Claude Code는 에이전트 코딩을 위한 명령줄 도구입니다. 이 글은 다양한 코드베이스, 언어, 환경에서 Claude Code를 효과적으로 사용하는 것으로 입증된 팁과 요령을 다룹니다.
2025년 4월 18일 게시
우리는 최근 에이전트 코딩을 위한 명령줄 도구인 Claude Code를 출시했습니다. 연구 프로젝트로 개발된 Claude Code는 Anthropic 엔지니어와 연구자들에게 Claude를 코딩 워크플로우에 통합할 수 있는 더 네이티브한 방법을 제공합니다.
Claude Code는 의도적으로 저수준이고 편견이 없도록 설계되어, 특정 워크플로우를 강요하지 않고 원시 모델 액세스에 가까운 기능을 제공합니다. 이러한 설계 철학은 유연하고 사용자 정의 가능하며 스크립트 작성이 가능하고 안전한 파워 툴을 만듭니다. 강력하지만, 이러한 유연성은 에이전트 코딩 도구를 처음 접하는 엔지니어들에게 학습 곡선을 제시합니다—적어도 그들이 자신만의 모범 사례를 개발할 때까지는 말입니다.
이 글은 Anthropic의 내부 팀과 다양한 코드베이스, 언어, 환경에서 Claude Code를 사용하는 외부 엔지니어들 모두에게 효과적으로 입증된 일반적인 패턴을 설명합니다. 이 목록의 어떤 것도 돌에 새겨진 것이거나 범용적으로 적용되는 것은 아닙니다. 이러한 제안을 시작점으로 여기시기 바랍니다. 실험해보고 자신에게 가장 잘 맞는 것을 찾으시기를 권합니다!
더 자세한 정보를 원하시나요? claude.ai/code의 포괄적인 문서에서 이 글에서 언급된 모든 기능을 다루고 추가 예제, 구현 세부사항, 고급 기법을 제공합니다.
Claude Code는 자동으로 컨텍스트를 프롬프트에 가져오는 에이전트 코딩 어시스턴트입니다. 이 컨텍스트 수집은 시간과 토큰을 소비하지만, 환경 튜닝을 통해 최적화할 수 있습니다.
CLAUDE.md는 Claude가 대화를 시작할 때 자동으로 컨텍스트에 가져오는 특별한 파일입니다. 다음을 문서화하기에 이상적인 장소입니다:
CLAUDE.md 파일에는 필수 형식이 없습니다. 간결하고 사람이 읽기 쉽게 유지하는 것을 권장합니다. 예를 들어:
# Bash 명령어
- npm run build: 프로젝트 빌드
- npm run typecheck: 타입체커 실행
# 코드 스타일
- ES 모듈 (import/export) 구문 사용, CommonJS (require) 사용 안 함
- 가능할 때 destructure import 사용 (예: import { foo } from 'bar')
# 워크플로우
- 일련의 코드 변경을 완료했을 때 타입체크 실행
- 성능상 전체 테스트 스위트가 아닌 단일 테스트 실행 선호CLAUDE.md 파일을 여러 위치에 배치할 수 있습니다:
CLAUDE.md로 명명하고 git에 체크인하여 세션 간에 공유하고 팀과 공유할 수 있습니다 (권장), 또는 CLAUDE.local.md로 명명하고 .gitignore에 추가root/foo에서 claude를 실행하고 root/CLAUDE.md와 root/foo/CLAUDE.md 모두에 CLAUDE.md 파일이 있을 수 있습니다. 둘 다 자동으로 컨텍스트에 가져옵니다.CLAUDE.md 파일을 가져옵니다.~/.claude/CLAUDE.md), 모든 claude 세션에 적용됩니다./init 명령을 실행하면 Claude가 자동으로 CLAUDE.md를 생성합니다.
CLAUDE.md 파일은 Claude의 프롬프트의 일부가 되므로, 자주 사용하는 프롬프트처럼 개선되어야 합니다. 흔한 실수는 효과성을 반복하지 않고 광범위한 콘텐츠를 추가하는 것입니다. 시간을 내어 실험하고 모델에서 최상의 지시 준수를 생성하는 것이 무엇인지 확인하세요.
CLAUDE.md에 수동으로 콘텐츠를 추가하거나 # 키를 눌러 Claude에게 관련 CLAUDE.md에 자동으로 통합할 지시사항을 줄 수 있습니다. 많은 엔지니어들이 코딩하면서 명령어, 파일, 스타일 가이드라인을 문서화하기 위해 #을 자주 사용한 다음, 팀원들도 혜택을 받을 수 있도록 커밋에 CLAUDE.md 변경사항을 포함시킵니다.
Anthropic에서는 때때로 CLAUDE.md 파일을 프롬프트 개선기를 통해 실행하고 종종 지시사항을 튜닝합니다 (예: "중요" 또는 "반드시"로 강조 추가).
기본적으로 Claude Code는 시스템을 수정할 수 있는 모든 작업에 대해 권한을 요청합니다: 파일 쓰기, 많은 bash 명령어, MCP 도구 등. 우리는 안전을 우선시하기 위해 이러한 의도적으로 보수적인 접근 방식으로 Claude Code를 설계했습니다.
안전하다고 알고 있는 추가 도구를 허용하거나 실행 취소하기 쉬운 잠재적으로 안전하지 않은 도구(예: 파일 편집, git commit)를 허용하도록 허용 목록을 사용자 정의할 수 있습니다.
허용된 도구를 관리하는 네 가지 방법이 있습니다:
/permissions 명령 사용하여 허용 목록에서 도구를 추가하거나 제거합니다. 예를 들어, 파일 편집을 항상 허용하기 위해 Edit를, git 커밋을 허용하기 위해 Bash(git commit:*)를, Puppeteer MCP 서버와의 탐색을 허용하기 위해 mcp__puppeteer__puppeteer_navigate를 추가할 수 있습니다..claude/settings.json 또는 ~/.claude.json 수동 편집 (팀과 공유하기 위해 전자를 소스 제어에 체크인하는 것을 권장)--allowedTools CLI 플래그 사용Claude는 gh CLI를 사용하여 이슈 생성, 풀 리퀘스트 열기, 댓글 읽기 등을 위해 GitHub와 상호작용하는 방법을 알고 있습니다. gh가 설치되지 않은 경우에도 Claude는 GitHub API나 MCP 서버(설치된 경우)를 계속 사용할 수 있습니다.
Claude는 사용자와 마찬가지로 편의 스크립트와 함수 세트를 구축할 수 있는 셸 환경에 액세스할 수 있습니다. 또한 MCP와 REST API를 통해 더 복잡한 도구를 활용할 수 있습니다.
Claude Code는 bash 환경을 상속받아 모든 도구에 액세스할 수 있습니다. Claude는 unix tools와 gh와 같은 일반적인 유틸리티를 알고 있지만, 지시사항 없이는 사용자 정의 bash 도구에 대해 알지 못합니다:
--help를 실행하라고 Claude에게 말하세요CLAUDE.md에 문서화하세요Claude Code는 MCP 서버와 클라이언트 모두로 작동합니다. 클라이언트로서 세 가지 방법으로 MCP 서버에 연결하여 도구에 액세스할 수 있습니다:
.mcp.json 파일에서 (코드베이스에서 작업하는 모든 사람이 사용 가능). 예를 들어, .mcp.json에 Puppeteer와 Sentry 서버를 추가하여 저장소에서 작업하는 모든 엔지니어가 즉시 사용할 수 있도록 할 수 있습니다.MCP와 작업할 때 구성 문제를 식별하는 데 도움이 되도록 --mcp-debug 플래그로 Claude를 시작하는 것도 도움이 될 수 있습니다.
반복되는 워크플로우(디버깅 루프, 로그 분석 등)의 경우, .claude/commands 폴더 내의 마크다운 파일에 프롬프트 템플릿을 저장하세요. 이들은 /를 입력할 때 슬래시 명령어 메뉴를 통해 사용할 수 있게 됩니다. 이러한 명령어를 git에 체크인하여 팀의 나머지 구성원들이 사용할 수 있도록 할 수 있습니다.
사용자 정의 슬래시 명령어는 명령어 호출에서 매개변수를 전달하기 위해 특수 키워드 $ARGUMENTS를 포함할 수 있습니다.
예를 들어, GitHub 이슈를 자동으로 가져와서 수정하는 데 사용할 수 있는 슬래시 명령어는 다음과 같습니다:
GitHub 이슈를 분석하고 수정해주세요: $ARGUMENTS.
다음 단계를 따르세요:
1. gh issue view를 사용하여 이슈 세부사항 가져오기
2. 이슈에서 설명된 문제 이해하기
3. 관련 파일에 대한 코드베이스 검색
4. 이슈를 수정하기 위한 필요한 변경사항 구현
5. 수정을 확인하기 위한 테스트 작성 및 실행
6. 코드가 린팅과 타입 체킹을 통과하는지 확인
7. 설명적인 커밋 메시지 작성
8. 푸시하고 PR 생성
모든 GitHub 관련 작업에는 GitHub CLI `gh`를 사용하는 것을 기억하세요.위 내용을 .claude/commands/fix-github-issue.md에 넣으면 Claude Code에서 /project:fix-github-issue 명령어로 사용할 수 있습니다. 그러면 예를 들어 /project:fix-github-issue 1234를 사용하여 Claude가 이슈 #1234를 수정하도록 할 수 있습니다. 마찬가지로, 모든 세션에서 사용 가능한 명령어를 위해 ~/.claude/commands 폴더에 개인 명령어를 추가할 수 있습니다.
Claude Code는 특정 워크플로우를 강요하지 않고 원하는 방식으로 사용할 수 있는 유연성을 제공합니다. 이 유연성이 제공하는 공간 내에서 Claude Code를 효과적으로 사용하기 위한 여러 성공적인 패턴이 사용자 커뮤니티에서 나타났습니다:
이 다재다능한 워크플로우는 많은 문제에 적합합니다:
1-2단계는 중요합니다—이것들 없이는 Claude가 솔루션을 코딩하는 것으로 바로 건너뛰는 경향이 있습니다. 때로는 그것이 원하는 것이지만, Claude에게 먼저 연구하고 계획하도록 요청하는 것은 사전에 더 깊은 사고가 필요한 문제의 성능을 크게 향상시킵니다.
이것은 단위, 통합 또는 엔드투엔드 테스트로 쉽게 검증할 수 있는 변경사항에 대한 Anthropic이 선호하는 워크플로우입니다. 테스트 주도 개발(TDD)은 에이전트 코딩과 함께 더욱 강력해집니다:
Claude는 반복할 명확한 목표가 있을 때 최상의 성능을 발휘합니다—시각적 모의, 테스트 케이스 또는 다른 종류의 출력. 테스트와 같은 예상 출력을 제공함으로써 Claude는 변경사항을 만들고, 결과를 평가하고, 성공할 때까지 점진적으로 개선할 수 있습니다.
테스팅 워크플로우와 유사하게, Claude에게 시각적 목표를 제공할 수 있습니다:
인간과 마찬가지로 Claude의 출력은 반복을 통해 크게 향상되는 경향이 있습니다. 첫 번째 버전이 좋을 수 있지만, 2-3번의 반복 후에는 일반적으로 훨씬 더 좋아 보입니다. 최상의 결과를 위해 Claude에게 출력을 볼 수 있는 도구를 제공하세요.
Claude를 감독하는 대신, claude --dangerously-skip-permissions를 사용하여 모든 권한 검사를 우회하고 Claude가 완료될 때까지 중단 없이 작업하도록 할 수 있습니다. 이는 린트 오류 수정이나 보일러플레이트 코드 생성과 같은 워크플로우에 잘 작동합니다.
Claude가 임의 명령을 실행하도록 하는 것은 위험하며 데이터 손실, 시스템 손상 또는 데이터 유출(예: 프롬프트 인젝션 공격을 통해)을 초래할 수 있습니다. 이러한 위험을 최소화하려면 인터넷 액세스 없이 컨테이너에서 --dangerously-skip-permissions를 사용하세요. Docker Dev Containers를 사용한 이 참조 구현을 따를 수 있습니다.
새로운 코드베이스에 온보딩할 때 학습과 탐색을 위해 Claude Code를 사용하세요. 페어 프로그래밍할 때 프로젝트의 다른 엔지니어에게 묻는 것과 같은 종류의 질문을 Claude에게 할 수 있습니다. Claude는 다음과 같은 일반적인 질문에 답하기 위해 코드베이스를 에이전트적으로 검색할 수 있습니다:
foo.rs의 134줄에서 async move { ... }는 무엇을 하나요?CustomerOnboardingFlowImpl은 어떤 엣지 케이스를 처리하나요?bar 대신 foo를 호출하는 이유는 무엇인가요?baz.py의 334줄과 Java에서 동등한 것은 무엇인가요?Anthropic에서는 이런 방식으로 Claude Code를 사용하는 것이 우리의 핵심 온보딩 워크플로우가 되어 있으며, 램프업 시간을 크게 개선하고 다른 엔지니어들의 부담을 줄이고 있습니다. 특별한 프롬프트는 필요하지 않습니다! 단순히 질문하면 Claude가 코드를 탐색하여 답을 찾습니다.
Claude는 많은 git 작업을 효과적으로 처리할 수 있습니다. 많은 Anthropic 엔지니어들이 git 상호작용의 90% 이상을 Claude를 사용합니다:
Claude Code는 많은 GitHub 상호작용을 관리할 수 있습니다:
이는 gh 명령줄 구문을 기억할 필요를 없애면서 루틴 작업을 자동화합니다.
Anthropic의 연구자와 데이터 사이언티스트들은 Claude Code를 사용하여 Jupyter 노트북을 읽고 씁니다. Claude는 이미지를 포함한 출력을 해석할 수 있어 데이터를 탐색하고 상호작용하는 빠른 방법을 제공합니다. 필수 프롬프트나 워크플로우는 없지만, 권장하는 워크플로우는 VS Code에서 Claude Code와 .ipynb 파일을 나란히 열어두는 것입니다.
동료들에게 보여주기 전에 Jupyter 노트북을 정리하거나 미적 개선을 하도록 Claude에게 요청할 수도 있습니다. 노트북이나 데이터 시각화를 "미적으로 보기 좋게" 만들라고 구체적으로 지시하는 것은 인간의 시청 경험을 위해 최적화하고 있다는 것을 상기시키는 데 도움이 되는 경향이 있습니다.
아래 제안사항들은 모든 워크플로우에 적용됩니다:
Claude Code의 성공률은 더 구체적인 지시사항, 특히 첫 번째 시도에서 크게 향상됩니다. 사전에 명확한 방향을 제시하면 나중에 과정 수정의 필요성이 줄어듭니다.
예를 들어:
| 나쁨 | 좋음 |
|---|---|
| foo.py에 테스트 추가 | foo.py에 대한 새 테스트 케이스 작성, 사용자가 로그아웃된 엣지 케이스 커버. 모의 사용 피하기 |
| ExecutionFactory가 왜 이렇게 이상한 API를 가지고 있나요? | ExecutionFactory의 git 히스토리를 살펴보고 API가 어떻게 만들어졌는지 요약하기 |
| 캘린더 위젯 추가 | 홈페이지에서 기존 위젯이 어떻게 구현되어 있는지 살펴보고 패턴과 특히 코드와 인터페이스가 어떻게 분리되어 있는지 이해하기. HotDogWidget.php가 시작하기에 좋은 예제입니다. 그런 다음 패턴을 따라서 사용자가 월을 선택하고 앞뒤로 페이지를 넘기며 연도를 선택할 수 있는 새 캘린더 위젯을 구현하세요. 코드베이스의 나머지 부분에서 이미 사용된 것 외의 라이브러리 없이 처음부터 구축하세요. |
Claude는 의도를 추론할 수 있지만 마음을 읽을 수는 없습니다. 구체성은 기대와의 더 나은 일치로 이어집니다.
Claude는 여러 방법을 통해 이미지와 다이어그램에서 뛰어난 성능을 발휘합니다:
cmd+ctrl+shift+4로 클립보드에 스크린샷을 찍고 ctrl+v로 붙여넣기. 이는 맥에서 보통 사용하는 cmd+v가 아니며 원격으로는 작동하지 않습니다)이는 UI 개발을 위한 디자인 모의를 참조 포인트로 사용할 때와 분석 및 디버깅을 위한 시각적 차트 작업할 때 특히 유용합니다. 컨텍스트에 시각적 요소를 추가하지 않더라도 결과가 시각적으로 매력적이어야 한다는 것이 얼마나 중요한지 Claude에게 명확히 하는 것이 여전히 도움이 될 수 있습니다.
저장소 어디서든 파일이나 폴더를 빠르게 참조하기 위해 탭 완성을 사용하여 Claude가 올바른 리소스를 찾거나 업데이트하는 데 도움을 주세요.
Claude가 가져와서 읽을 수 있도록 프롬프트와 함께 특정 URL을 붙여넣으세요. 동일한 도메인(예: docs.foo.com)에 대한 권한 프롬프트를 피하려면 /permissions를 사용하여 허용 목록에 도메인을 추가하세요.
자동 수락 모드(shift+tab으로 토글)는 Claude가 자율적으로 작업할 수 있게 하지만, 일반적으로 적극적인 협력자가 되어 Claude의 접근 방식을 안내함으로써 더 나은 결과를 얻을 수 있습니다. 처음에 Claude에게 작업을 철저히 설명함으로써 최상의 결과를 얻을 수 있지만, 언제든지 Claude를 과정 수정할 수도 있습니다.
이 네 가지 도구가 과정 수정에 도움이 됩니다:
Claude Code가 때때로 첫 번째 시도에서 문제를 완벽하게 해결하기도 하지만, 이러한 수정 도구를 사용하는 것이 일반적으로 더 빠르게 더 나은 솔루션을 생산합니다.
/clear 사용긴 세션 동안 Claude의 컨텍스트 창이 관련 없는 대화, 파일 내용, 명령어로 채워질 수 있습니다. 이는 성능을 저하시키고 때로는 Claude를 산만하게 할 수 있습니다. 작업 사이에 /clear 명령어를 자주 사용하여 컨텍스트 창을 재설정하세요.
코드 마이그레이션, 수많은 린트 오류 수정, 복잡한 빌드 스크립트 실행과 같은 여러 단계나 철저한 솔루션이 필요한 대규모 작업의 경우, Claude가 마크다운 파일이나 심지어 GitHub 이슈를 체크리스트와 작업 스크래치패드로 사용하도록 하여 성능을 향상시키세요:
예를 들어, 많은 수의 린트 이슈를 수정하려면 다음을 수행할 수 있습니다:
Claude에게 데이터를 제공하는 여러 방법이 있습니다:
cat foo.txt | claude), 로그, CSV, 대용량 데이터에 특히 유용대부분의 세션은 이러한 접근법의 조합을 포함합니다. 예를 들어, 로그 파일을 파이프로 넣은 다음 Claude에게 도구를 사용하여 로그를 디버그하기 위한 추가 컨텍스트를 가져오도록 지시할 수 있습니다.
Claude Code는 CI, 사전 커밋 후크, 빌드 스크립트 및 자동화와 같은 비대화형 컨텍스트를 위한 헤드리스 모드를 포함합니다. 프롬프트와 함께 -p 플래그를 사용하여 헤드리스 모드를 활성화하고, 스트리밍 JSON 출력을 위해 --output-format stream-json을 사용합니다.
헤드리스 모드는 세션 간에 지속되지 않습니다. 각 세션마다 트리거해야 합니다.
헤드리스 모드는 저장소에 새 이슈가 생성될 때와 같은 GitHub 이벤트에 의해 트리거되는 자동화를 지원할 수 있습니다. 예를 들어, 공개 Claude Code 저장소는 새 이슈가 들어올 때 Claude를 사용하여 검사하고 적절한 라벨을 할당합니다.
Claude Code는 기존 린팅 도구가 감지하지 못하는 주관적 코드 리뷰를 제공할 수 있으며, 오타, 오래된 댓글, 오해의 소지가 있는 함수나 변수 이름 등의 문제를 식별합니다.
단독 사용을 넘어서, 가장 강력한 애플리케이션 중 일부는 병렬로 여러 Claude 인스턴스를 실행하는 것을 포함합니다:
간단하지만 효과적인 접근법은 한 Claude가 코드를 작성하게 하는 동안 다른 Claude가 검토하거나 테스트하게 하는 것입니다. 여러 엔지니어와 작업하는 것과 유사하게, 때로는 별도의 컨텍스트를 갖는 것이 유익합니다:
/clear를 실행하거나 다른 터미널에서 두 번째 Claude 시작/clear를 다시) 코드와 검토 피드백을 모두 읽게 함테스트와 비슷한 것을 할 수 있습니다: 한 Claude가 테스트를 작성하게 한 다음, 다른 Claude가 테스트를 통과하는 코드를 작성하게 합니다. Claude 인스턴스들이 별도의 작업 스크래치패드를 제공하고 어느 것에 쓰고 어느 것에서 읽을지 지시하여 서로 소통하게 할 수도 있습니다.
이러한 분리는 종종 단일 Claude가 모든 것을 처리하는 것보다 더 나은 결과를 가져옵니다.
Claude가 각 단계를 완료하기를 기다리는 대신, Anthropic의 많은 엔지니어들이 하는 것은:
이 접근법은 여러 독립적인 작업에 빛나며, 여러 체크아웃에 대한 더 가벼운 대안을 제공합니다. Git 워크트리를 사용하면 동일한 저장소에서 여러 브랜치를 별도 디렉토리로 체크아웃할 수 있습니다. 각 워크트리는 격리된 파일과 함께 자체 작업 디렉토리를 가지면서 동일한 Git 히스토리와 reflog를 공유합니다.
git 워크트리를 사용하면 프로젝트의 서로 다른 부분에서 여러 Claude 세션을 동시에 실행할 수 있으며, 각각은 자체 독립적인 작업에 집중합니다. 예를 들어, 한 Claude가 인증 시스템을 리팩터링하는 동안 다른 Claude는 완전히 관련 없는 데이터 시각화 구성 요소를 구축할 수 있습니다. 작업이 겹치지 않으므로 각 Claude는 다른 Claude의 변경사항을 기다리거나 병합 충돌을 처리하지 않고 전속력으로 작업할 수 있습니다:
git worktree add ../project-feature-a feature-acd ../project-feature-a && claude몇 가지 팁:
git worktree remove ../project-feature-aclaude -p (헤드리스 모드)는 내장 도구와 시스템 프롬프트를 활용하면서 Claude Code를 더 큰 워크플로우에 프로그래밍 방식으로 통합합니다. 헤드리스 모드를 사용하는 두 가지 주요 패턴이 있습니다:
1. 팬아웃은 대규모 마이그레이션이나 분석을 처리합니다 (예: 수백 개의 로그에서 감정 분석 또는 수천 개의 CSV 분석):
claude -p "foo.py를 React에서 Vue로 마이그레이션하세요. 완료되면 성공했으면 OK 문자열을, 작업이 실패했으면 FAIL을 반환해야 합니다." --allowedTools Edit Bash(git commit:*)2. 파이프라이닝은 Claude를 기존 데이터 처리 파이프라인에 통합합니다:
claude -p "<your prompt>" --json | your_command를 호출합니다. 여기서 your_command는 처리 파이프라인의 다음 단계입니다.두 사용 사례 모두에서 Claude 호출을 디버깅하기 위해 --verbose 플래그를 사용하는 것이 도움이 될 수 있습니다. 일반적으로 더 깔끔한 출력을 위해 프로덕션에서는 verbose 모드를 끄는 것을 권장합니다.
Claude Code와 함께 작업하는 팁과 모범 사례는 무엇인가요? @AnthropicAI를 태그해서 무엇을 구축하고 있는지 보여주세요!
Boris Cherny가 작성했습니다. 이 작업은 창의적인 접근법과 워크플로우로 계속해서 우리에게 영감을 주는 더 넓은 Claude Code 사용자 커뮤니티의 모범 사례를 바탕으로 합니다. 또한 Claude Code에 대한 귀중한 통찰력과 실무 경험으로 이러한 권장사항을 형성하는 데 도움을 준 Daisy Hollman, Ashwin Bhat, Cat Wu, Sid Bidasaria, Cal Rueb, Nodir Turakulov, Barry Zhang, Drew Hodun 및 기타 많은 Anthropic 엔지니어들에게 특별히 감사드립니다.