Claude Code 모범 사례

📄 원문: Claude Code Best Practices

• 출처: Claude Code Best Practices
• 저자: Anthropic
• 원문 발행일: 2025년 4월 18일
• 라이선스: 저작권 Anthropic
• 번역일: 2025년 6월 26일
• 번역 및 감수: Claude and 공부하우
• 참고: 이 번역은 교육 목적으로 작성되었으며, Anthropic의 공식 번역이 아닙니다.

⚖️ 저작권 안내

이 번역문은 교육 및 정보 제공 목적으로 작성되었습니다. 원문의 저작권은 Anthropic에 있으며, 이 번역은 Anthropic의 공식 번역이 아닙니다.

본 번역은 다음과 같은 교육적 공정 사용(Fair Use) 원칙에 따라 제공됩니다:

- 비영리 교육 목적

- 원문 출처의 명확한 표시

- 한국어 사용자의 기술 이해 증진을 위한 변형적 사용

- 원저작물의 시장 가치에 부정적 영향을 미치지 않음

저작권 관련 문제가 제기될 경우, 즉시 적절한 조치를 취하겠습니다. 상업적 사용이나 재배포 전에 원저작권자의 허가를 받으시기 바랍니다.

문의사항이나 우려사항이 있으시면 오른쪽 템플릿 복사를 클릭 하신 뒤, 연락 페이지를 통해 알려 주시기 바랍니다.

Anthropic 엔지니어링

🏷️ 태그: Claude Code, AI 코딩, 개발 도구, 베스트 프랙티스, 에이전틱 코딩

우리는 최근 에이전틱 코딩 (agentic coding)을 위한 명령줄 도구인 Claude Code를 출시했습니다. 연구 프로젝트로 개발된 Claude Code는 Anthropic 엔지니어와 연구원들이 Claude를 코딩 워크플로우에 더 자연스럽게 통합할 수 있는 방법을 제공합니다.

Claude Code는 의도적으로 저수준이고 특정 견해를 강요하지 않으며, 특정 워크플로우를 강제하지 않고 거의 원시 모델 접근을 제공합니다. 이러한 설계 철학은 유연하고, 사용자 정의 가능하며, 스크립트화 가능하고, 안전한 강력한 도구를 만들어냅니다. 강력하지만, 이러한 유연성은 에이전틱 코딩 도구를 처음 사용하는 엔지니어들에게 학습 곡선을 제시합니다 - 적어도 그들이 자신만의 모범 사례를 개발하기 전까지는 말이죠.

이 게시물은 Anthropic의 내부 팀과 다양한 코드베이스, 언어, 환경에서 Claude Code를 사용하는 외부 엔지니어들 모두에게 효과적인 것으로 입증된 일반적인 패턴을 설명합니다. 이 목록의 어떤 것도 확정적이거나 보편적으로 적용 가능한 것은 아닙니다. 이러한 제안사항들을 시작점으로 고려하세요. 여러분이 실험하고 가장 잘 맞는 것을 찾기를 권장합니다!

더 자세한 정보를 찾고 계신가요? claude.ai/code의 포괄적인 문서는 이 게시물에서 언급된 모든 기능을 다루고 추가 예제, 구현 세부사항, 고급 기술을 제공합니다.

1. 설정 사용자 정의하기

Claude Code는 프롬프트에 컨텍스트를 자동으로 가져오는 에이전틱 코딩 어시스턴트입니다. 이 컨텍스트 수집은 시간과 토큰을 소비하지만, 환경 조정을 통해 최적화할 수 있습니다.

a. CLAUDE.md 파일 만들기

CLAUDE.md는 Claude가 대화를 시작할 때 자동으로 컨텍스트에 가져오는 특별한 파일입니다. 이것은 다음을 문서화하는 이상적인 장소입니다:

• 일반적인 bash 명령어
• 핵심 파일과 유틸리티 함수
• 코드 스타일 가이드라인
• 테스트 지침
• 저장소 에티켓 (예: 브랜치 명명, merge vs. rebase 등)
• 개발자 환경 설정 (예: pyenv 사용, 어떤 컴파일러가 작동하는지)
• 프로젝트 특유의 예상치 못한 동작이나 경고
• Claude가 기억하기를 원하는 다른 정보

CLAUDE.md 파일에 필요한 형식은 없습니다. 간결하고 인간이 읽을 수 있도록 유지하는 것을 권장합니다. 예를 들어:

# Bash 명령어
- npm run build: 프로젝트 빌드
- npm run typecheck: 타입 체커 실행

# 코드 스타일
- CommonJS (require)가 아닌 ES 모듈 (import/export) 구문 사용
- 가능한 경우 import를 구조 분해하여 사용 (예: import { foo } from 'bar')

# 워크플로우
- 일련의 코드 변경을 완료한 후에는 반드시 타입 체크 수행
- 성능을 위해 전체 테스트 스위트가 아닌 단일 테스트 실행을 선호

원본 코드:

# Bash commands
- npm run build: Build the project
- npm run typecheck: Run the typechecker

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

CLAUDE.md 파일은 여러 위치에 배치할 수 있습니다:

• 저장소의 루트 또는 claude를 실행하는 위치 (가장 일반적인 사용법). CLAUDE.md로 이름을 지정하고 git에 체크인하여 세션과 팀 전체에서 공유할 수 있도록 하거나 (권장), CLAUDE.local.md로 이름을 지정하고 .gitignore에 추가
• 디렉토리의 부모 claude를 실행하는 위치. 이는 모노레포에 가장 유용하며, root/foo에서 claude를 실행하고 root/CLAUDE.md와 root/foo/CLAUDE.md 모두에 CLAUDE.md 파일이 있을 수 있습니다. 이 두 파일은 모두 자동으로 컨텍스트에 포함됩니다
• 디렉토리의 자식 claude를 실행하는 위치. 이는 위의 반대이며, 이 경우 Claude는 자식 디렉토리의 파일을 작업할 때 필요에 따라 CLAUDE.md 파일을 가져옵니다
• 홈 폴더 (~/.claude/CLAUDE.md), 모든 claude 세션에 적용됩니다

/init 명령을 실행하면 Claude가 자동으로 CLAUDE.md를 생성합니다.

b. CLAUDE.md 파일 조정하기

CLAUDE.md 파일은 Claude의 프롬프트의 일부가 되므로, 자주 사용하는 프롬프트처럼 다듬어져야 합니다. 일반적인 실수는 효과성을 반복하지 않고 광범위한 콘텐츠를 추가하는 것입니다. 시간을 내어 실험하고 모델에서 최상의 지시 따르기를 생성하는 것이 무엇인지 결정하세요.

CLAUDE.md에 수동으로 콘텐츠를 추가하거나 # 키를 눌러 Claude에게 관련 CLAUDE.md에 자동으로 통합할 지침을 제공할 수 있습니다. 많은 엔지니어가 코딩하는 동안 명령, 파일 및 스타일 가이드라인을 문서화하기 위해 #를 자주 사용한 다음, 팀 구성원도 혜택을 받을 수 있도록 커밋에 CLAUDE.md 변경 사항을 포함합니다.

Anthropic에서는 때때로 CLAUDE.md 파일을 프롬프트 개선기를 통해 실행하고 준수를 개선하기 위해 지침을 조정합니다 (예: "IMPORTANT" 또는 "YOU MUST"로 강조 추가).

c. Claude의 허용된 도구 목록 관리하기

기본적으로 Claude Code는 시스템을 수정할 수 있는 모든 작업에 대해 권한을 요청합니다: 파일 쓰기, 많은 bash 명령, MCP 도구 등. 우리는 안전을 우선시하기 위해 의도적으로 보수적인 접근 방식으로 Claude Code를 설계했습니다. 안전하다고 알고 있는 추가 도구를 허용하거나 취소하기 쉬운 잠재적으로 안전하지 않은 도구를 허용하도록 허용 목록을 사용자 정의할 수 있습니다 (예: 파일 편집, git commit).

허용된 도구를 관리하는 네 가지 방법이 있습니다:

• "항상 허용" 선택 세션 중 프롬프트가 표시될 때.
• /permissions 명령 사용 Claude Code를 시작한 후 허용 목록에서 도구를 추가하거나 제거합니다. 예를 들어, 파일 편집을 항상 허용하려면 Edit를 추가하고, git 커밋을 허용하려면 Bash(git commit:*)를 추가하거나, Puppeteer MCP 서버로 탐색을 허용하려면 mcp__puppeteer__puppeteer_navigate를 추가할 수 있습니다.
• 수동으로 편집 .claude/settings.json 또는 ~/.claude.json (전자를 소스 제어에 체크인하여 팀과 공유하는 것을 권장합니다).
• --allowedTools CLI 플래그 사용 세션별 권한을 위해.

d. GitHub를 사용하는 경우 gh CLI 설치

Claude는 gh CLI를 사용하여 GitHub와 상호 작용하는 방법을 알고 있습니다: 이슈 생성, 풀 리퀘스트 열기, 댓글 읽기 등. gh가 설치되지 않은 경우에도 Claude는 여전히 GitHub API 또는 MCP 서버(설치한 경우)를 사용할 수 있습니다.

2. Claude에게 더 많은 도구 제공하기

Claude는 셸 환경에 액세스할 수 있으며, 여기서 자신을 위해 하는 것처럼 편의 스크립트와 함수 세트를 구축할 수 있습니다. 또한 MCP 및 REST API를 통해 더 복잡한 도구를 활용할 수 있습니다.

a. bash 도구와 함께 Claude 사용하기

Claude Code는 bash 환경을 상속하여 모든 도구에 액세스할 수 있습니다. Claude는 unix 도구 및 gh와 같은 일반적인 유틸리티를 알고 있지만, 지침 없이는 사용자 정의 bash 도구를 알지 못합니다:

1. 사용 예제와 함께 Claude에게 도구 이름 알려주기
2. Claude에게 --help를 실행하여 도구 문서를 보도록 지시
3. 자주 사용하는 도구를 CLAUDE.md에 문서화

b. MCP와 함께 Claude 사용하기

Claude Code는 MCP 서버와 클라이언트 역할을 모두 수행합니다. 클라이언트로서 세 가지 방법으로 여러 MCP 서버에 연결하여 도구에 액세스할 수 있습니다:

• 프로젝트 구성에서 (해당 디렉토리에서 Claude Code를 실행할 때 사용 가능)
• 전역 구성에서 (모든 프로젝트에서 사용 가능)
• 체크인된 .mcp.json 파일에서 (코드베이스에서 작업하는 모든 사람이 사용 가능). 예를 들어, .mcp.json에 Puppeteer와 Sentry 서버를 추가하여 저장소에서 작업하는 모든 엔지니어가 즉시 사용할 수 있도록 할 수 있습니다.

MCP 작업 시 구성 문제를 식별하는 데 도움이 되도록 --mcp-debug 플래그로 Claude를 시작하는 것도 도움이 될 수 있습니다.

c. 사용자 정의 슬래시 명령 사용

반복되는 워크플로우(디버깅 루프, 로그 분석 등)의 경우 .claude/commands 폴더 내의 마크다운 파일에 프롬프트 템플릿을 저장합니다. 이들은 /를 입력할 때 슬래시 명령 메뉴를 통해 사용할 수 있습니다. 이러한 명령을 git에 체크인하여 나머지 팀에서 사용할 수 있도록 할 수 있습니다.

사용자 정의 슬래시 명령은 명령 호출에서 매개변수를 전달하기 위한 특수 키워드 $ARGUMENTS를 포함할 수 있습니다.

예를 들어, GitHub 이슈를 자동으로 가져와서 수정하는 데 사용할 수 있는 슬래시 명령은 다음과 같습니다:

다음 GitHub 이슈를 분석하고 수정해 주세요: $ARGUMENTS.

다음 단계를 따르세요:

1. `gh issue view`를 사용하여 이슈 세부 정보 가져오기
2. 이슈에 설명된 문제 이해하기
3. 관련 파일을 위해 코드베이스 검색
4. 이슈를 수정하기 위한 필요한 변경 사항 구현
5. 수정 사항을 확인하기 위한 테스트 작성 및 실행
6. 코드가 린팅과 타입 체크를 통과하는지 확인
7. 설명적인 커밋 메시지 작성
8. 푸시하고 PR 생성

모든 GitHub 관련 작업에는 GitHub CLI (`gh`)를 사용하는 것을 잊지 마세요.

원본 코드:

Please analyze and fix the GitHub issue: $ARGUMENTS.

Follow these steps:

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.

위 내용을 .claude/commands/fix-github-issue.md에 넣으면 Claude Code에서 /project:fix-github-issue 명령으로 사용할 수 있습니다. 그런 다음 예를 들어 /project:fix-github-issue 1234를 사용하여 Claude가 이슈 #1234를 수정하도록 할 수 있습니다. 마찬가지로, 모든 세션에서 사용하고 싶은 명령을 위해 ~/.claude/commands 폴더에 개인 명령을 추가할 수 있습니다.

3. 일반적인 워크플로우 시도하기

Claude Code는 특정 워크플로우를 강요하지 않으므로 원하는 방식으로 사용할 수 있는 유연성을 제공합니다. 이러한 유연성이 제공하는 공간 내에서 Claude Code를 효과적으로 사용하기 위한 몇 가지 성공적인 패턴이 사용자 커뮤니티에서 나타났습니다:

a. 탐색, 계획, 코드, 커밋

이 다재다능한 워크플로우는 많은 문제에 적합합니다:

1. Claude에게 관련 파일, 이미지 또는 URL 읽기 요청, 일반적인 포인터("로깅을 처리하는 파일 읽기") 또는 특정 파일 이름("logging.py 읽기")을 제공하되, 아직 코드를 작성하지 말라고 명시적으로 지시합니다.

   • 이는 특히 복잡한 문제의 경우 하위 에이전트의 강력한 사용을 고려해야 하는 워크플로우의 부분입니다. Claude에게 세부 사항을 확인하거나 가질 수 있는 특정 질문을 조사하기 위해 하위 에이전트를 사용하도록 지시하는 것은, 특히 대화나 작업 초기에, 효율성 측면에서 큰 손실 없이 컨텍스트 가용성을 보존하는 경향이 있습니다.

2. Claude에게 특정 문제에 접근하는 방법에 대한 계획을 세우도록 요청. 우리는 "think"라는 단어를 사용하여 확장된 사고 모드를 트리거하는 것을 권장합니다. 이는 Claude에게 대안을 더 철저히 평가할 수 있는 추가 계산 시간을 제공합니다. 이러한 특정 구문은 시스템에서 증가하는 사고 예산 수준에 직접 매핑됩니다: "think" < "think hard" < "think harder" < "ultrathink". 각 수준은 Claude가 사용할 수 있도록 점진적으로 더 많은 사고 예산을 할당합니다.

   • 이 단계의 결과가 합리적으로 보이면, Claude가 계획이 포함된 문서나 GitHub 이슈를 생성하도록 하여 구현(3단계)이 원하는 것이 아닌 경우 이 지점으로 재설정할 수 있습니다.

3. Claude에게 솔루션을 코드로 구현하도록 요청. 또한 솔루션의 일부를 구현할 때 솔루션의 합리성을 명시적으로 확인하도록 요청하는 것도 좋은 시점입니다.

4. Claude에게 결과를 커밋하고 풀 리퀘스트를 생성하도록 요청. 관련이 있다면, Claude가 방금 한 일에 대한 설명으로 README나 변경 로그를 업데이트하는 것도 좋은 시기입니다.

1~2단계는 중요합니다. 이 단계가 없으면 Claude는 솔루션을 코딩하는 것으로 바로 뛰어드는 경향이 있습니다. 때로는 그것이 원하는 것일 수도 있지만, Claude에게 먼저 연구하고 계획하도록 요청하면 미리 더 깊은 사고가 필요한 문제에 대한 성능이 크게 향상됩니다.

b. 테스트 작성, 커밋; 코드 작성, 반복, 커밋

이것은 단위, 통합 또는 엔드 투 엔드 테스트로 쉽게 확인할 수 있는 변경 사항에 대한 Anthropic이 선호하는 워크플로우입니다. 테스트 주도 개발 (Test-driven development, TDD)은 에이전틱 코딩과 함께 더욱 강력해집니다:

1. 예상 입력/출력 쌍을 기반으로 테스트를 작성하도록 Claude에게 요청. 테스트 주도 개발을 하고 있다는 사실을 명시적으로 알려서 코드베이스에 아직 존재하지 않는 기능이라도 모의 구현을 만들지 않도록 합니다.

2. Claude에게 테스트를 실행하고 실패하는지 확인하도록 지시. 이 단계에서 구현 코드를 작성하지 말라고 명시적으로 지시하는 것이 종종 도움이 됩니다.

3. 만족스러우면 Claude에게 테스트를 커밋하도록 요청.

4. Claude에게 테스트를 통과하는 코드를 작성하도록 요청, 테스트를 수정하지 말라고 지시합니다. Claude에게 모든 테스트가 통과할 때까지 계속하라고 지시합니다. Claude가 코드를 작성하고, 테스트를 실행하고, 코드를 조정하고, 테스트를 다시 실행하는 데 일반적으로 몇 번의 반복이 필요합니다.

   • 이 단계에서는 구현이 테스트에 과적합되지 않았는지 독립적인 하위 에이전트로 확인하도록 요청하는 것이 도움이 될 수 있습니다

5. 변경 사항에 만족하면 Claude에게 코드를 커밋하도록 요청.

Claude는 명확한 목표에 대해 반복할 때 가장 잘 수행됩니다. 시각적 모형, 테스트 케이스 또는 다른 종류의 출력. 테스트와 같은 예상 출력을 제공함으로써 Claude는 변경을 하고, 결과를 평가하고, 성공할 때까지 점진적으로 개선할 수 있습니다.

c. 코드 작성, 스크린샷 결과, 반복

테스트 워크플로우와 유사하게 Claude에게 시각적 목표를 제공할 수 있습니다:

1. Claude에게 브라우저 스크린샷을 찍을 수 있는 방법 제공 (예: Puppeteer MCP 서버, iOS 시뮬레이터 MCP 서버 또는 수동으로 스크린샷을 복사/붙여넣기).
2. Claude에게 시각적 모형 제공 이미지를 복사/붙여넣기 또는 드래그 앤 드롭하거나 Claude에게 이미지 파일 경로를 제공합니다.
3. Claude에게 디자인을 코드로 구현하도록 요청, 결과의 스크린샷을 찍고 결과가 모형과 일치할 때까지 반복합니다.
4. 만족하면 Claude에게 커밋하도록 요청.

인간과 마찬가지로 Claude의 출력은 반복을 통해 크게 향상되는 경향이 있습니다. 첫 번째 버전이 좋을 수도 있지만, 2-3번의 반복 후에는 일반적으로 훨씬 더 좋아 보일 것입니다. 최상의 결과를 위해 Claude에게 출력을 볼 수 있는 도구를 제공하세요.

d. 안전한 YOLO 모드

Claude를 감독하는 대신 claude --dangerously-skip-permissions를 사용하여 모든 권한 확인을 우회하고 Claude가 완료될 때까지 방해받지 않고 작업하도록 할 수 있습니다. 이는 린트 오류 수정이나 보일러플레이트 코드 생성과 같은 워크플로우에 잘 작동합니다.

Claude가 임의의 명령을 실행하도록 하는 것은 위험하며 데이터 손실, 시스템 손상 또는 데이터 유출(예: 프롬프트 주입 공격을 통해)을 초래할 수 있습니다. 이러한 위험을 최소화하려면 인터넷 액세스가 없는 컨테이너에서 --dangerously-skip-permissions를 사용하세요. Docker Dev Containers를 사용한 이 참조 구현을 따를 수 있습니다.

e. 코드베이스 Q&A

새로운 코드베이스에 온보딩할 때 학습 및 탐색을 위해 Claude Code를 사용하세요. 페어 프로그래밍을 할 때 프로젝트의 다른 엔지니어에게 물어볼 것과 같은 종류의 질문을 Claude에게 할 수 있습니다. Claude는 다음과 같은 일반적인 질문에 답하기 위해 에이전틱하게 코드베이스를 검색할 수 있습니다:

• 로깅은 어떻게 작동하나요?
• 새 API 엔드포인트를 어떻게 만드나요?
• foo.rs의 134번째 줄에서 async move { ... }는 무엇을 하나요?
• CustomerOnboardingFlowImpl은 어떤 엣지 케이스를 처리하나요?
• 333번째 줄에서 bar() 대신 foo()를 호출하는 이유는 무엇인가요?
• baz.py의 334번째 줄과 동등한 Java 코드는 무엇인가요?

Anthropic에서는 이러한 방식으로 Claude Code를 사용하는 것이 핵심 온보딩 워크플로우가 되어 램프업 시간을 크게 개선하고 다른 엔지니어의 부담을 줄였습니다. 특별한 프롬프팅이 필요하지 않습니다! 단순히 질문하면 Claude가 답을 찾기 위해 코드를 탐색할 것입니다.

f. git와 상호 작용하기 위해 Claude 사용

Claude는 많은 git 작업을 효과적으로 처리할 수 있습니다. 많은 Anthropic 엔지니어는 git 상호 작용의 90% 이상을 Claude를 사용합니다:

• git 히스토리 검색 "v1.2.3에 어떤 변경 사항이 포함되었나요?", "이 특정 기능의 소유자는 누구인가요?" 또는 "이 API가 이런 식으로 설계된 이유는 무엇인가요?"와 같은 질문에 답하기 위해. 이러한 쿼리에 답하기 위해 git 히스토리를 살펴보도록 Claude에게 명시적으로 프롬프트하는 것이 도움이 됩니다.
• 커밋 메시지 작성. Claude는 변경 사항과 최근 히스토리를 자동으로 보고 모든 관련 컨텍스트를 고려하여 메시지를 작성합니다
• 복잡한 git 작업 처리 파일 되돌리기, 리베이스 충돌 해결, 패치 비교 및 이식과 같은

g. GitHub와 상호 작용하기 위해 Claude 사용

Claude Code는 많은 GitHub 상호 작용을 관리할 수 있습니다:

• 풀 리퀘스트 생성: Claude는 약어 "pr"을 이해하고 diff와 주변 컨텍스트를 기반으로 적절한 커밋 메시지를 생성합니다.
• 간단한 코드 리뷰 댓글에 대한 원샷 해결 구현: PR에 대한 댓글을 수정하라고 지시하고 (선택적으로 더 구체적인 지침을 제공) 완료되면 PR 브랜치로 다시 푸시합니다.
• 실패한 빌드 수정 또는 린터 경고
• 오픈 이슈 분류 및 우선순위 지정 Claude에게 오픈 GitHub 이슈를 반복하도록 요청하여

이는 gh 명령줄 구문을 기억할 필요성을 없애면서 일상적인 작업을 자동화합니다.

h. Jupyter 노트북 작업을 위해 Claude 사용

Anthropic의 연구원과 데이터 과학자들은 Jupyter 노트북을 읽고 쓰기 위해 Claude Code를 사용합니다. Claude는 이미지를 포함한 출력을 해석할 수 있어 데이터를 탐색하고 상호 작용하는 빠른 방법을 제공합니다. 필요한 프롬프트나 워크플로우는 없지만, 우리가 권장하는 워크플로우는 VS Code에서 Claude Code와 .ipynb 파일을 나란히 열어두는 것입니다.

또한 동료에게 보여주기 전에 Jupyter 노트북을 정리하거나 미적 개선을 하도록 Claude에게 요청할 수 있습니다. 노트북이나 데이터 시각화를 "미적으로 만족스럽게" 만들도록 구체적으로 지시하면 인간의 시청 경험을 최적화하고 있음을 상기시키는 데 도움이 됩니다.

4. 워크플로우 최적화

아래 제안 사항은 모든 워크플로우에 적용됩니다:

a. 지침에서 구체적이 되세요

Claude Code의 성공률은 특히 첫 번째 시도에서 더 구체적인 지침으로 크게 향상됩니다. 처음부터 명확한 지시를 제공하면 나중에 방향 수정이 필요성이 줄어듭니다.

예를 들어:

좋지 않음	좋음
foo.py에 테스트 추가	foo.py에 대한 새 테스트 케이스를 작성하고, 사용자가 로그아웃된 엣지 케이스를 다루세요. 모의 객체는 피하세요
ExecutionFactory가 왜 이상한 API를 가지고 있나요?	ExecutionFactory의 git 히스토리를 살펴보고 API가 어떻게 만들어졌는지 요약해 주세요
캘린더 위젯 추가	홈페이지에서 기존 위젯이 어떻게 구현되었는지 살펴보고 패턴을 이해하고 특히 코드와 인터페이스가 어떻게 분리되는지 이해하세요. HotDogWidget.php가 시작하기 좋은 예입니다. 그런 다음 패턴을 따라 사용자가 월을 선택하고 앞뒤로 페이지를 넘겨 연도를 선택할 수 있는 새 캘린더 위젯을 구현하세요. 코드베이스의 나머지 부분에서 이미 사용된 것 이외의 라이브러리 없이 처음부터 빌드하세요.

원본 테이블:

Poor	Good
add tests for foo.py	write a new test case for foo.py, covering the edge case where the user is logged out. avoid mocks
why does ExecutionFactory have such a weird api?	look through ExecutionFactory's git history and summarize how its api came to be
add a calendar widget	look at how existing widgets are implemented on the home page to understand the patterns and specifically how code and interfaces are separated out. HotDogWidget.php is a good example to start with. then, follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. Build from scratch without libraries other than the ones already used in the rest of the codebase.

Claude는 의도를 추론할 수 있지만 마음을 읽을 수는 없습니다. 구체성은 기대와 더 나은 일치로 이어집니다.

b. Claude에게 이미지 제공

Claude는 여러 방법을 통해 이미지와 다이어그램에 뛰어납니다:

• 스크린샷 붙여넣기 (프로 팁: macOS에서 _cmd+ctrl+shift+4_를 눌러 클립보드에 스크린샷을 찍고 _ctrl+v_로 붙여넣기. 이것은 mac에서 일반적으로 붙여넣기에 사용하는 cmd+v가 아니며 원격으로 작동하지 않습니다.)
• 드래그 앤 드롭 프롬프트 입력에 직접 이미지
• 파일 경로 제공 이미지용

이는 특히 UI 개발을 위한 참조점으로 디자인 모형을 작업할 때와 분석 및 디버깅을 위한 시각적 차트에 유용합니다. 컨텍스트에 시각적 요소를 추가하지 않는 경우에도 결과가 시각적으로 매력적인 것이 얼마나 중요한지 Claude에게 명확히 하는 것이 도움이 될 수 있습니다.

c. Claude가 보거나 작업하기를 원하는 파일 언급

저장소의 어디에서나 파일이나 폴더를 빠르게 참조하려면 탭 완성을 사용하여 Claude가 올바른 리소스를 찾거나 업데이트하는 데 도움을 줍니다.

d. Claude에게 URL 제공

Claude가 가져와서 읽을 수 있도록 프롬프트와 함께 특정 URL을 붙여넣으세요. 동일한 도메인(예: docs.foo.com)에 대한 권한 프롬프트를 피하려면 /permissions를 사용하여 허용 목록에 도메인을 추가하세요.

e. 일찍 그리고 자주 방향 수정

자동 수락 모드(shift+tab으로 전환)를 사용하면 Claude가 자율적으로 작업할 수 있지만, 일반적으로 능동적인 협력자가 되어 Claude의 접근 방식을 안내함으로써 더 나은 결과를 얻을 수 있습니다. 처음에 Claude에게 작업을 철저히 설명하면 최상의 결과를 얻을 수 있지만, 언제든지 Claude의 방향을 수정할 수도 있습니다.

이 네 가지 도구는 방향 수정에 도움이 됩니다:

• 코딩 전에 Claude에게 계획을 세우도록 요청. 계획이 좋아 보일 때까지 코드를 작성하지 말라고 명시적으로 지시하세요.
• Escape를 눌러 중단 모든 단계(사고, 도구 호출, 파일 편집) 중 Claude를 중단시켜 컨텍스트를 보존하여 지침을 리디렉션하거나 확장할 수 있습니다.
• Escape를 두 번 탭하여 히스토리로 돌아가기, 이전 프롬프트를 편집하고 다른 방향을 탐색합니다. 원하는 결과를 얻을 때까지 프롬프트를 편집하고 반복할 수 있습니다.
• Claude에게 변경 사항을 취소하도록 요청, 종종 다른 접근 방식을 취하기 위해 옵션 2와 함께 사용됩니다.

Claude Code가 가끔 첫 번째 시도에서 문제를 완벽하게 해결하지만, 이러한 수정 도구를 사용하면 일반적으로 더 나은 솔루션을 더 빨리 생성합니다.

f. /clear를 사용하여 컨텍스트를 집중적으로 유지

긴 세션 동안 Claude의 컨텍스트 창은 관련 없는 대화, 파일 내용 및 명령으로 채워질 수 있습니다. 이는 성능을 저하시키고 때로는 Claude를 산만하게 할 수 있습니다. 작업 간에 /clear 명령을 자주 사용하여 컨텍스트 창을 재설정하세요.

g. 복잡한 워크플로우를 위해 체크리스트와 스크래치패드 사용

여러 단계가 있거나 철저한 솔루션이 필요한 대규모 작업(코드 마이그레이션, 수많은 린트 오류 수정 또는 복잡한 빌드 스크립트 실행과 같은)의 경우 Claude가 마크다운 파일(또는 GitHub 이슈!)을 체크리스트 및 작업 스크래치패드로 사용하도록 하여 성능을 향상시킵니다:

예를 들어, 많은 수의 린트 문제를 수정하려면 다음을 수행할 수 있습니다:

1. Claude에게 린트 명령을 실행하도록 지시하고 모든 결과 오류(파일 이름과 줄 번호 포함)를 마크다운 체크리스트에 작성
2. Claude에게 각 문제를 하나씩 해결하도록 지시, 수정하고 확인한 후 체크하고 다음으로 이동

h. Claude에게 데이터 전달

Claude에 데이터를 제공하는 여러 방법이 있습니다:

• 복사 및 붙여넣기 프롬프트에 직접 (가장 일반적인 접근 방식)
• Claude Code로 파이프 (예: cat foo.txt | claude), 특히 로그, CSV 및 대용량 데이터에 유용
• Claude에게 데이터를 가져오도록 지시 bash 명령, MCP 도구 또는 사용자 정의 슬래시 명령을 통해
• Claude에게 파일을 읽거나 URL을 가져오도록 요청 (이미지에도 작동)

대부분의 세션에는 이러한 접근 방식의 조합이 포함됩니다. 예를 들어, 로그 파일을 파이프한 다음 Claude에게 도구를 사용하여 로그를 디버그하기 위한 추가 컨텍스트를 가져오도록 지시할 수 있습니다.

5. 인프라 자동화를 위해 헤드리스 모드 사용

Claude Code에는 CI, 사전 커밋 후크, 빌드 스크립트 및 자동화와 같은 비대화형 컨텍스트를 위한 헤드리스 모드가 포함되어 있습니다. 헤드리스 모드를 활성화하려면 프롬프트와 함께 -p 플래그를 사용하고, 스트리밍 JSON 출력을 위해 --output-format stream-json을 사용하세요.

헤드리스 모드는 세션 간에 지속되지 않습니다. 각 세션마다 트리거해야 합니다.

a. 이슈 분류를 위해 Claude 사용

헤드리스 모드는 저장소에 새 이슈가 생성될 때와 같이 GitHub 이벤트로 트리거되는 자동화를 구동할 수 있습니다. 예를 들어, 공개 Claude Code 저장소는 Claude를 사용하여 들어오는 새 이슈를 검사하고 적절한 레이블을 할당합니다.

b. Claude를 린터로 사용

Claude Code는 기존 린팅 도구가 감지하는 것 이상의 주관적인 코드 리뷰를 제공하여 오타, 오래된 주석, 오해의 소지가 있는 함수 또는 변수 이름 등과 같은 문제를 식별할 수 있습니다.

6. 멀티 Claude 워크플로우로 레벨업

독립형 사용을 넘어, 가장 강력한 애플리케이션 중 일부는 여러 Claude 인스턴스를 병렬로 실행하는 것을 포함합니다:

a. 한 Claude가 코드를 작성하고, 다른 Claude를 사용하여 확인

간단하지만 효과적인 접근 방식은 한 Claude가 코드를 작성하는 동안 다른 Claude가 검토하거나 테스트하는 것입니다. 여러 엔지니어와 작업하는 것과 유사하게, 때로는 별도의 컨텍스트를 갖는 것이 유익합니다:

1. Claude를 사용하여 코드 작성
2. /clear를 실행하거나 다른 터미널에서 두 번째 Claude 시작
3. 두 번째 Claude가 첫 번째 Claude의 작업을 검토하도록 함
4. 다른 Claude를 시작하거나 (또는 다시 /clear) 코드와 리뷰 피드백을 모두 읽음
5. 이 Claude가 피드백을 기반으로 코드를 편집하도록 함

테스트와 유사한 작업을 수행할 수 있습니다: 한 Claude가 테스트를 작성한 다음 다른 Claude가 테스트를 통과하는 코드를 작성하도록 합니다. Claude 인스턴스가 별도의 작업 스크래치패드를 제공하고 어느 것에 쓰고 어느 것에서 읽을지 알려줌으로써 서로 통신하도록 할 수도 있습니다.

이러한 분리는 종종 단일 Claude가 모든 것을 처리하는 것보다 더 나은 결과를 산출합니다.

b. 저장소의 여러 체크아웃 보유

각 단계가 완료될 때까지 기다리는 대신, Anthropic의 많은 엔지니어가 하는 일은:

1. 별도의 폴더에 3-4개의 git 체크아웃 생성
2. 각 폴더를 별도의 터미널 탭에서 열기
3. 각 폴더에서 Claude를 시작하여 다른 작업 수행
4. 순환하며 진행 상황을 확인하고 권한 요청을 승인/거부

c. git worktree 사용

이 접근 방식은 여러 독립 작업에 빛을 발하며 여러 체크아웃에 대한 더 가벼운 대안을 제공합니다. Git worktree를 사용하면 동일한 저장소에서 여러 브랜치를 별도의 디렉토리로 체크아웃할 수 있습니다. 각 worktree에는 동일한 Git 히스토리와 reflog를 공유하면서 격리된 파일이 있는 자체 작업 디렉토리가 있습니다.

git worktree를 사용하면 프로젝트의 다른 부분에서 동시에 여러 Claude 세션을 실행할 수 있으며, 각각은 자체 독립 작업에 집중합니다. 예를 들어, 한 Claude가 인증 시스템을 리팩토링하는 동안 다른 Claude가 완전히 관련 없는 데이터 시각화 구성 요소를 구축할 수 있습니다. 작업이 겹치지 않으므로 각 Claude는 다른 Claude의 변경을 기다리거나 병합 충돌을 처리하지 않고 최고 속도로 작업할 수 있습니다:

1. worktree 생성: git worktree add ../project-feature-a feature-a
2. 각 worktree에서 Claude 시작: cd ../project-feature-a && claude
3. 필요에 따라 추가 worktree 생성 (새 터미널 탭에서 1-2단계 반복)

몇 가지 팁:

• 일관된 명명 규칙 사용
• worktree당 하나의 터미널 탭 유지
• Mac에서 iTerm2를 사용하는 경우 Claude가 주의가 필요할 때를 위해 알림 설정
• 다른 worktree에 대해 별도의 IDE 창 사용
• 완료되면 정리: git worktree remove ../project-feature-a

d. 사용자 정의 하네스와 함께 헤드리스 모드 사용

claude -p (헤드리스 모드)는 내장 도구와 시스템 프롬프트를 활용하면서 Claude Code를 더 큰 워크플로우에 프로그래밍 방식으로 통합합니다. 헤드리스 모드를 사용하는 두 가지 주요 패턴이 있습니다:

1. 팬 아웃은 대규모 마이그레이션 또는 분석을 처리합니다 (예: 수백 개의 로그에서 감정 분석 또는 수천 개의 CSV 분석):

   1. Claude가 작업 목록을 생성하는 스크립트를 작성하도록 합니다. 예를 들어, 프레임워크 A에서 프레임워크 B로 마이그레이션해야 하는 2k 파일 목록을 생성합니다.
   2. 작업을 반복하면서 각각에 대해 Claude를 프로그래밍 방식으로 호출하고 작업과 사용할 수 있는 도구 세트를 제공합니다. 예: claude -p "foo.py를 React에서 Vue로 마이그레이션하세요. 완료되면 성공한 경우 OK 문자열을, 작업이 실패한 경우 FAIL을 반환해야 합니다." --allowedTools Edit Bash(git commit:*)
   3. 스크립트를 여러 번 실행하고 원하는 결과를 얻기 위해 프롬프트를 다듬습니다.

2. 파이프라이닝은 Claude를 기존 데이터/처리 파이프라인에 통합합니다:

   1. claude -p "<your prompt>" --json | your_command를 호출합니다. 여기서 your_command는 처리 파이프라인의 다음 단계입니다
   2. 그게 다입니다! JSON 출력(선택 사항)은 더 쉬운 자동 처리를 위한 구조를 제공하는 데 도움이 될 수 있습니다.

이 두 가지 사용 사례 모두에 대해 Claude 호출을 디버깅하는 데 --verbose 플래그를 사용하는 것이 도움이 될 수 있습니다. 일반적으로 더 깨끗한 출력을 위해 프로덕션에서 verbose 모드를 끄는 것을 권장합니다.

Claude Code 작업에 대한 팁과 모범 사례는 무엇인가요? @AnthropicAI를 태그하여 여러분이 무엇을 만들고 있는지 볼 수 있게 해주세요!

감사의 말

Boris Cherny가 작성했습니다. 이 작업은 창의적인 접근 방식과 워크플로우가 계속해서 우리에게 영감을 주는 더 넓은 Claude Code 사용자 커뮤니티의 모범 사례를 기반으로 합니다. 또한 Daisy Hollman, Ashwin Bhat, Cat Wu, Sid Bidasaria, Cal Rueb, Nodir Turakulov, Barry Zhang, Drew Hodun 및 Claude Code에 대한 귀중한 통찰력과 실제 경험이 이러한 권장 사항을 형성하는 데 도움을 준 다른 많은 Anthropic 엔지니어들에게 특별한 감사를 드립니다.

---

공부하우 추가 설명

아래 내용은 독자의 이해를 돕기 위해 공부하우가 추가한 설명입니다. 원문에는 없는 내용입니다.

주요 용어 설명

이 문서에서 사용된 주요 기술 용어들을 설명합니다:

개발 도구 관련 용어

에이전틱 코딩 (Agentic Coding)
AI가 단순히 코드를 제안하는 것을 넘어, 파일을 읽고 쓰고, 명령을 실행하고, 테스트를 수행하는 등 개발자처럼 능동적으로 행동하는 코딩 방식입니다. Claude Code는 이러한 에이전틱 접근 방식을 사용하여 개발자의 작업을 자동화합니다.

명령줄 도구 (Command Line Tool)
그래픽 사용자 인터페이스(GUI) 대신 텍스트 명령을 통해 컴퓨터와 상호작용하는 프로그램입니다. Claude Code는 터미널에서 claude 명령으로 실행되는 CLI 도구입니다.

컨텍스트 (Context)
Claude가 작업을 수행할 때 참조하는 모든 정보를 의미합니다. 파일 내용, 이전 대화, 프로젝트 설정 등이 포함되며, 더 많은 컨텍스트를 제공할수록 Claude가 더 정확한 작업을 수행할 수 있습니다.

토큰 (Token)
AI 모델이 텍스트를 처리하는 기본 단위입니다. 대략적으로 한 토큰은 4글자 정도에 해당합니다. Claude Code는 컨텍스트를 처리할 때 토큰을 소비하므로, 효율적인 토큰 사용이 중요합니다.

워크플로우 관련 용어

테스트 주도 개발 (Test-Driven Development, TDD)
실제 코드를 작성하기 전에 먼저 테스트를 작성하는 개발 방법론입니다. 테스트가 실패하는 것을 확인한 후, 테스트를 통과하는 최소한의 코드를 작성하고, 리팩토링하는 과정을 반복합니다.

풀 리퀘스트 (Pull Request, PR)
GitHub에서 코드 변경사항을 메인 브랜치에 병합하기 전에 검토를 요청하는 기능입니다. Claude Code는 자동으로 PR을 생성하고 관리할 수 있습니다.

모노레포 (Monorepo)
여러 프로젝트나 패키지를 하나의 저장소에서 관리하는 방식입니다. 대규모 조직에서 코드 공유와 일관성을 위해 사용합니다.

워크트리 (Worktree)
Git의 기능으로, 하나의 저장소에서 여러 브랜치를 동시에 다른 디렉토리에서 작업할 수 있게 해줍니다. 여러 기능을 병렬로 개발할 때 유용합니다.

기술 구성 관련 용어

MCP (Model Context Protocol)
Claude가 외부 도구나 서비스와 통신할 수 있게 해주는 프로토콜입니다. 데이터베이스, API, 브라우저 자동화 도구 등과 연결할 수 있습니다.

헤드리스 모드 (Headless Mode)
사용자 인터페이스 없이 백그라운드에서 실행되는 모드입니다. CI/CD 파이프라인이나 자동화 스크립트에서 Claude Code를 사용할 때 활용합니다.

린터 (Linter)
코드의 스타일, 문법 오류, 잠재적 버그 등을 자동으로 검사하는 도구입니다. Claude Code는 기존 린터보다 더 주관적이고 의미론적인 코드 리뷰를 제공할 수 있습니다.

하위 에이전트 (Subagent)
메인 Claude 인스턴스가 특정 작업을 위해 생성하는 별도의 Claude 인스턴스입니다. 복잡한 문제를 해결할 때 작업을 분할하여 처리하는 데 사용됩니다.

관련 글

관련 글을 불러오는 중...