Burt.K

Awesome Discovery

Claude Code 모범 사례

작성일 — 2025년 6월 28일

Table of Contents

https://www.anthropic.com/engineering/claude-code-best-practices

최근 Claude Code를 출시했다. 이 커맨드라인 도구는 에이전트 기반 코딩을 지원한다. 연구 프로젝트로 개발된 Claude Code는 Anthropic 엔지니어와 연구원들이 코딩 워크플로우에 Claude를 더 자연스럽게 통합할 수 있게 해준다.

Claude Code는 의도적으로 저수준이며 특정 워크플로우를 강제하지 않는다. 이 도구는 원시 모델에 가까운 접근을 제공하면서도 유연하고 커스터마이즈 가능하며 스크립팅이 가능한 안전한 강력한 도구로 설계되었다. 하지만 이러한 유연성은 에이전트 기반 코딩 도구를 처음 사용하는 엔지니어들에게는 학습 곡선을 요구한다. 적어도 자신만의 모범 사례를 개발할 때까지는 말이다.

이 글에서는 Anthropic 내부 팀과 다양한 코드베이스, 언어, 환경에서 Claude Code를 사용하는 외부 엔지니어들에게 효과적인 것으로 입증된 일반적인 패턴들을 소개한다. 이 목록에 있는 내용은 절대적이거나 보편적으로 적용 가능한 것은 아니다. 이 제안들은 시작점으로 생각하고, 여러분에게 맞는 방법을 실험해보길 권한다.

더 자세한 정보를 원한다면 claude.ai/code에서 제공하는 포괄적인 문서를 참고하라. 이 문서는 이 글에서 언급한 모든 기능을 다루며 추가 예제, 구현 세부 사항, 고급 기법을 제공한다.

1. 설정 커스터마이징

Claude Code는 자동으로 컨텍스트를 프롬프트에 포함하는 에이전트형 코딩 어시스턴트다. 컨텍스트 수집은 시간과 토큰을 소모하지만, 환경을 튜닝하여 최적화할 수 있다.

a. CLAUDE.md 파일 생성하기

CLAUDE.md는 Claude가 대화를 시작할 때 자동으로 참조하는 특별한 파일이다. 이 파일은 다음과 같은 내용을 문서화하기에 이상적이다:

CLAUDE.md 파일은 특별한 형식을 요구하지 않는다. 간결하고 사람이 읽기 쉬운 형태로 작성하는 것을 권장한다. 예를 들어:

# Bash 명령어

- npm run build: 프로젝트 빌드
- npm run typecheck: 타입 체크 실행

# 코드 스타일

- CommonJS(require) 대신 ES 모듈(import/export) 문법 사용
- 가능한 경우 import를 구조 분해 (예: import { foo } from 'bar')

# 작업 흐름

- 코드 변경을 마친 후 반드시 타입 체크 실행
- 성능을 위해 전체 테스트 대신 단일 테스트 실행 권장

CLAUDE.md 파일은 다음과 같은 위치에 배치할 수 있다:

/init 명령어를 실행하면 Claude가 자동으로 CLAUDE.md 파일을 생성한다.

b. CLAUDE.md 파일 튜닝하기

CLAUDE.md 파일은 Claude의 프롬프트에 포함되므로, 자주 사용하는 프롬프트처럼 꾸준히 다듬어야 한다. 흔히 하는 실수는 효과를 검증하지 않고 지나치게 많은 내용을 추가하는 것이다. 시간을 들여 실험하면서 모델이 가장 잘 따르는 지침을 찾아내는 것이 중요하다.

CLAUDE.md에 내용을 직접 추가하거나 # 키를 눌러 Claude에게 지시를 내릴 수 있다. 이 지시는 자동으로 관련 CLAUDE.md에 반영된다. 많은 엔지니어들은 코딩 중에 커맨드, 파일, 스타일 가이드라인을 기록하기 위해 #를 자주 사용하고, CLAUDE.md 변경 사항을 커밋에 포함시켜 팀원들도 함께 활용할 수 있게 한다.

Anthropic에서는 때때로 프롬프트 개선 도구를 통해 CLAUDE.md 파일을 검토하고, “IMPORTANT”나 “YOU MUST”와 같은 강조 표현을 추가해 지침의 준수도를 높인다.

Claude Code tool allowlist

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

기본적으로 Claude Code는 시스템을 수정할 가능성이 있는 모든 작업에 대해 권한 요청을 한다. 파일 쓰기, 다양한 bash 명령, MCP 도구 등이 이에 해당한다. Claude Code는 안전을 최우선으로 고려해 의도적으로 보수적인 접근 방식을 채택했다. 여러분은 안전하다고 판단되는 추가 도구를 허용하거나, 되돌리기 쉬운 잠재적으로 안전하지 않은 도구(예: 파일 편집, git commit)를 허용하도록 허용 목록을 커스터마이즈할 수 있다.

허용 도구를 관리하는 방법은 네 가지가 있다:

d. GitHub 사용 시 gh CLI 설치하기

Claude는 gh CLI를 활용해 GitHub과 상호작용할 수 있다. 이를 통해 이슈 생성, 풀 리퀘스트 오픈, 코멘트 읽기 등 다양한 작업을 수행할 수 있다. 만약 gh가 설치되어 있지 않더라도, Claude는 GitHub API나 MCP 서버(설치된 경우)를 사용할 수 있다.

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

Claude는 여러분의 셸 환경에 접근할 수 있다. 이를 통해 여러분이 직접 사용하는 편의 스크립트와 함수를 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 서버와 클라이언트 역할을 동시에 수행한다. 클라이언트로서, Claude Code는 여러 MCP 서버에 연결해 다양한 도구를 활용할 수 있다. 이 연결은 세 가지 방식으로 설정할 수 있다:

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`)를 사용하세요.

위 내용을 .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를 읽어라”)을 제공할 수 있다. 하지만 아직 코드를 작성하지 말라고 명시적으로 지시한다.
    1. 이 단계에서는 특히 복잡한 문제의 경우 하위 에이전트(subagents)를 적극적으로 활용하는 것을 고려해야 한다. Claude에게 하위 에이전트를 사용해 세부 사항을 검증하거나 특정 질문을 조사하라고 요청하면, 초기 단계에서 컨텍스트 가용성을 유지하는 데 도움이 된다. 이는 효율성 저하 없이 문제를 더 깊이 이해할 수 있게 한다.
  2. Claude에게 특정 문제를 해결하기 위한 계획을 세우도록 요청한다. “생각해봐”라는 단어를 사용해 확장된 사고 모드를 트리거하는 것을 권장한다. 이 모드는 Claude가 대안을 더 철저히 평가할 수 있도록 추가적인 계산 시간을 제공한다. 시스템 내에서 이러한 구체적인 문구는 점진적으로 증가하는 사고 예산에 직접 매핑된다: “생각해봐” < “열심히 생각해봐” < “더 열심히 생각해봐” < “초고속 사고.” 각 단계는 Claude가 사용할 수 있는 사고 예산을 점진적으로 늘린다.
    1. 이 단계의 결과가 합리적으로 보이면, Claude에게 계획을 문서나 GitHub 이슈로 작성하도록 요청할 수 있다. 이렇게 하면 구현 단계(3단계)에서 원하는 결과가 나오지 않을 경우 이 지점으로 돌아갈 수 있다.
  3. Claude에게 코드로 해결책을 구현하도록 요청한다. 이 단계에서는 해결책의 각 부분을 구현하면서 그 합리성을 명시적으로 검증하도록 요청하는 것도 좋다.
  4. Claude에게 결과를 커밋하고 풀 리퀘스트를 생성하도록 요청한다. 관련이 있다면, Claude에게 README나 변경 로그를 업데이트하여 방금 수행한 작업을 설명하도록 요청할 수도 있다.

1단계와 2단계는 매우 중요하다. 이 단계 없이 Claude는 바로 코딩을 시작하려는 경향이 있다. 때로는 이것이 원하는 결과일 수 있지만, Claude에게 먼저 조사하고 계획을 세우도록 요청하면 초기에 깊은 사고가 필요한 문제에서 성능이 크게 향상된다.

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

이 워크플로우는 단위 테스트, 통합 테스트, 또는 엔드투엔드 테스트로 쉽게 검증할 수 있는 변경 사항에 적합한 Anthropic의 선호 방식이다. 에이전트 기반 코딩과 결합하면 테스트 주도 개발(TDD)이 더욱 강력해진다:

  1. Claude에게 예상 입력/출력 쌍을 기반으로 테스트를 작성하도록 요청한다. 테스트 주도 개발을 진행 중임을 명확히 알려서, 코드베이스에 아직 존재하지 않는 기능에 대한 모의 구현을 만들지 않도록 한다.
  2. Claude에게 테스트를 실행하고 실패하는지 확인하도록 지시한다. 이 단계에서는 구현 코드를 작성하지 않도록 명시적으로 알리는 것이 도움이 된다.
  3. 테스트에 만족하면 Claude에게 커밋하도록 요청한다.
  4. Claude에게 테스트를 통과하는 코드를 작성하도록 요청한다. 테스트를 수정하지 말고, 모든 테스트가 통과할 때까지 계속하도록 지시한다. Claude가 코드를 작성하고, 테스트를 실행하고, 코드를 조정하고, 다시 테스트를 실행하는 과정을 몇 번 반복해야 할 수 있다.
    1. 이 단계에서는 구현이 테스트에 과적합되지 않았는지 독립적인 하위 에이전트로 검증하도록 요청하는 것이 도움이 된다.
  5. 변경 사항에 만족하면 Claude에게 코드를 커밋하도록 요청한다.

Claude는 시각적 목업, 테스트 케이스, 또는 다른 종류의 출력과 같은 명확한 목표가 있을 때 가장 잘 작동한다. 테스트와 같은 예상 출력을 제공하면 Claude는 변경을 수행하고 결과를 평가하며 성공할 때까지 점진적으로 개선할 수 있다.

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

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

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

인간과 마찬가지로, Claude의 출력물도 반복 작업을 통해 크게 개선된다. 첫 번째 버전이 괜찮을 수 있지만, 2-3번 반복 후에는 훨씬 더 나은 결과를 얻을 수 있다. 최상의 결과를 위해 Claude가 자신의 출력물을 확인할 수 있는 도구를 제공한다.

Safe yolo mode

d. 안전한 YOLO 모드

Claude를 감독하는 대신 claude --dangerously-skip-permissions 명령어를 사용해 모든 권한 검사를 우회하고 작업이 완료될 때까지 방해받지 않게 할 수 있다. 이 방법은 린트 오류 수정이나 보일러플레이트 코드 생성과 같은 워크플로우에 적합하다. 하지만 Claude에게 임의의 명령어를 실행하게 하는 것은 위험하며, 데이터 손실, 시스템 오류, 또는 데이터 유출(예: 프롬프트 삽입 공격)을 초래할 수 있다. 이러한 위험을 최소화하려면 인터넷 접근이 차단된 컨테이너 내에서 --dangerously-skip-permissions를 사용한다. Docker Dev Containers를 사용한 참조 구현을 따라할 수 있다.

e. 코드베이스 Q&A

새로운 코드베이스에 적응할 때, 학습과 탐색을 위해 Claude Code를 활용한다. 프로젝트에서 페어 프로그래밍을 하면서 다른 엔지니어에게 물어보는 것과 같은 질문을 Claude에게 할 수 있다. Claude는 코드베이스를 능동적으로 탐색하여 다음과 같은 일반적인 질문에 답할 수 있다:

Anthropic에서는 이러한 방식으로 Claude Code를 사용하는 것이 핵심 온보딩 워크플로우가 되었다. 이는 적응 시간을 크게 단축시키고 다른 엔지니어들의 부담을 줄이는 데 기여했다. 특별한 프롬프트가 필요하지 않다! 단순히 질문을 하면, Claude가 코드를 탐색하여 답을 찾아준다.

Git과 상호작용하는 Claude 사용 예시

f. git과 상호작용하는 Claude 활용법

Claude는 다양한 git 작업을 효율적으로 처리할 수 있다. Anthropic 엔지니어들의 90% 이상이 git 관련 상호작용에 Claude를 활용하고 있다:

g. Claude를 활용한 GitHub 상호작용

Claude Code는 다양한 GitHub 작업을 관리할 수 있다:

이를 통해 gh 커맨드라인 구문을 외울 필요 없이 일상적인 작업을 자동화할 수 있다.

h. Jupyter 노트북 작업에 Claude 활용하기

Anthropic의 연구원과 데이터 과학자들은 Claude Code를 사용해 Jupyter 노트북을 읽고 작성한다. Claude는 이미지를 포함한 출력을 해석할 수 있어 데이터를 빠르게 탐색하고 상호작용할 수 있는 방법을 제공한다. 특별히 필요한 프롬프트나 워크플로우는 없지만, VS Code에서 Claude Code와 .ipynb 파일을 나란히 열어 작업하는 것을 추천한다.

또한 동료에게 노트북을 보여주기 전에 Claude에게 정리하거나 미적으로 개선하도록 요청할 수 있다. 특히 노트북이나 데이터 시각화를 “미적으로 매력적”으로 만들라고 명시적으로 지시하면, 인간의 시각적 경험을 최적화하도록 상기시키는 데 도움이 된다.

4. 워크플로우 최적화

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

a. 명확한 지침을 제공한다

Claude Code의 성공률은 첫 시도에서 더 구체적인 지침을 제공할 때 크게 향상된다. 처음부터 명확한 방향을 제시하면 나중에 수정할 필요가 줄어든다.

예를 들어:

부적절한 지침 | 적절한 지침 – | – foo.py에 테스트를 추가한다 | foo.py에 새로운 테스트 케이스를 작성한다. 사용자가 로그아웃된 상황과 같은 예외 사항을 다룬다. 모의 객체(mock)는 사용하지 않는다 ExecutionFactory의 API가 왜 이렇게 이상한가? | ExecutionFactory의 git 기록을 살펴보고 API가 어떻게 만들어졌는지 요약한다 캘린더 위젯을 추가한다 | 홈페이지에 구현된 기존 위젯을 살펴보고 패턴을 이해한다. 특히 코드와 인터페이스가 어떻게 분리되어 있는지 확인한다. HotDogWidget.php가 좋은 예제다. 그런 다음, 이 패턴을 따라 새로운 캘린더 위젯을 구현한다. 사용자가 월을 선택하고 앞뒤로 페이지를 넘기며 연도를 선택할 수 있도록 한다. 이미 코드베이스에서 사용 중인 라이브러리 외에는 새 라이브러리를 사용하지 않고 처음부터 구현한다

Claude는 의도를 추론할 수 있지만 마음을 읽지는 못한다. 명확한 지침은 기대치와의 일치를 더 잘 이끌어낸다.

Claude에게 이미지 제공

b. Claude에게 이미지 제공하기

Claude는 이미지와 다이어그램을 다루는 데 뛰어난 능력을 보인다. 이를 활용하는 주요 방법은 다음과 같다:

이 기능은 UI 개발을 위한 디자인 목업 참조나, 분석 및 디버깅을 위한 시각적 차트 작업에 특히 유용하다. 시각적 자료를 추가하지 않더라도, 결과물의 시각적 매력이 얼마나 중요한지 Claude에게 명확히 알려주는 것이 도움이 된다.

Claude가 참고하거나 작업할 파일을 언급하세요

c. Claude가 참고하거나 작업할 파일 지정하기

저장소 내 어디에 위치한 파일이나 폴더든지 탭 완성 기능을 활용해 빠르게 참조할 수 있다. 이를 통해 Claude가 적절한 리소스를 찾거나 업데이트하는 데 도움을 줄 수 있다.

Claude에게 URL 제공

d. Claude에게 URL 제공하기

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

e. 초기에 자주 방향을 수정한다

자동 수락 모드(shift+tab으로 전환)는 Claude가 자율적으로 작업할 수 있게 해주지만, 일반적으로 적극적으로 협력하고 Claude의 접근 방식을 안내하는 것이 더 나은 결과를 얻을 수 있다. 처음에 작업을 철저히 설명하는 것이 가장 좋은 결과를 얻는 방법이지만, 언제든지 Claude의 방향을 수정할 수도 있다.

다음 네 가지 도구가 방향 수정에 도움을 준다:

Claude Code가 가끔 첫 시도에서 문제를 완벽하게 해결하기도 하지만, 이러한 수정 도구를 사용하는 것이 일반적으로 더 빠르고 나은 솔루션을 제공한다.

f. /clear 명령으로 컨텍스트를 집중적으로 유지하기

긴 대화를 나누는 동안 Claude의 컨텍스트 윈도우에는 관련 없는 대화 내용, 파일 내용, 명령어 등이 쌓일 수 있다. 이는 성능을 저하시키고 때로는 Claude의 집중력을 흐릴 수 있다. 작업 간에 /clear 명령을 자주 사용하여 컨텍스트 윈도우를 초기화하면 이러한 문제를 방지할 수 있다.

g. 복잡한 워크플로우에서 체크리스트와 스크래치패드 활용하기

여러 단계로 구성되거나 철저한 해결책이 필요한 대규모 작업(예: 코드 마이그레이션, 수많은 린트 오류 수정, 복잡한 빌드 스크립트 실행 등)의 경우, Claude가 체크리스트와 작업용 스크래치패드로 Markdown 파일(또는 GitHub 이슈)을 사용하도록 하여 성능을 향상시킬 수 있다.

예를 들어, 대량의 린트 오류를 수정하려면 다음과 같이 진행한다:

  1. Claude에게 린트 명령어를 실행하도록 지시하고, 발생한 모든 오류(파일명과 줄 번호 포함)를 Markdown 체크리스트로 작성한다.
  2. Claude에게 각 문제를 하나씩 해결하도록 지시하고, 수정 및 검증 후 체크하고 다음으로 넘어간다.

h. 클로드에 데이터 전달하기

클로드에 데이터를 전달하는 방법은 여러 가지가 있다:

대부분의 작업에서는 이러한 방법들을 조합해서 사용한다. 예를 들어, 로그 파일을 파이프로 전달한 후, 클로드에게 추가 컨텍스트를 가져오도록 도구를 사용하도록 지시해 로그를 디버깅할 수 있다.

5. 헤드리스 모드로 인프라 자동화하기

Claude Code는 CI, pre-commit 훅, 빌드 스크립트, 자동화와 같은 비대화형 환경을 위한 헤드리스 모드를 제공한다. 헤드리스 모드를 활성화하려면 -p 플래그와 함께 프롬프트를 사용하고, 스트리밍 JSON 출력을 원할 경우 --output-format stream-json 옵션을 추가한다.

단, 헤드리스 모드는 세션 간에 지속되지 않는다. 각 세션마다 다시 활성화해야 한다.

a. GitHub 이슈 트라이지에 Claude 활용하기

헤드리스 모드는 GitHub 이벤트에 의해 트리거되는 자동화 작업을 실행할 수 있다. 예를 들어, 레포지토리에 새로운 이슈가 생성될 때 이를 처리할 수 있다. 공개된 Claude Code 레포지토리는 Claude를 사용해 새로운 이슈를 검토하고 적절한 라벨을 할당하는 방식을 보여준다.

b. Claude를 린터로 활용하기

Claude Code는 주관적인 코드 리뷰를 제공하여 전통적인 린팅 도구가 감지하지 못하는 문제를 식별할 수 있다. 예를 들어, 오타, 오래된 주석, 혼동을 줄 수 있는 함수나 변수명 등을 찾아낼 수 있다.

6. 다중 클로드 워크플로로 업그레이드

독립적으로 사용하는 것 외에도, 여러 클로드 인스턴스를 병렬로 실행하는 방식으로 더 강력한 활용이 가능하다:

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 worktrees 활용하기

이 방법은 여러 독립적인 작업을 수행할 때 특히 유용하며, 여러 체크아웃보다 가볍고 효율적인 대안을 제공한다. git worktrees를 사용하면 동일한 저장소에서 여러 브랜치를 별도의 디렉토리로 체크아웃할 수 있다. 각 worktree는 고유한 작업 디렉토리를 가지며 파일이 격리되어 있지만, 동일한 Git 히스토리와 reflog를 공유한다.

git worktrees를 사용하면 프로젝트의 다른 부분에서 여러 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단계 반복)

유용한 팁:

d. 커스텀 하네스와 함께 헤드리스 모드 사용하기

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

  1. 확장 작업(Fanning out): 대규모 마이그레이션이나 분석 작업을 처리한다. 예를 들어, 수백 개의 로그 파일에서 감정 분석을 수행하거나 수천 개의 CSV 파일을 분석하는 작업이 여기에 해당한다.

    1. Claude가 작업 목록을 생성하는 스크립트를 작성하도록 한다. 예를 들어, 프레임워크 A에서 프레임워크 B로 마이그레이션해야 하는 2,000개의 파일 목록을 생성한다.
    2. 각 작업을 반복하면서 Claude를 프로그램적으로 호출하고, 작업과 사용 가능한 도구 세트를 제공한다. 예: claude -p "React에서 Vue로 foo.py 마이그레이션. 작업이 완료되면 성공 시 OK, 실패 시 FAIL 문자열을 반드시 반환해야 한다." --allowedTools Edit Bash(git commit:*)
    3. 스크립트를 여러 번 실행하고 프롬프트를 수정하여 원하는 결과를 얻는다.

  2. 파이프라이닝(Pipelining): 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을 비롯한 Anthropic 엔지니어들에게 특별한 감사를 표한다. 이들의 유용한 통찰과 Claude Code에 대한 실무 경험은 이 가이드라인을 만드는 데 큰 도움을 주었다.