AI 지식 / / 2025. 6. 18. 07:00

Claude Code 베스트 프랙티스

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

Claude Code는 에이전틱 코딩을 위한 명령줄 도구입니다. 이 글은 다양한 코드베이스, 언어, 환경에서 Claude Code를 효과적으로 사용하기 위해 입증된 팁과 트릭을 다룹니다.

최근 저희는 에이전틱 코딩을 위한 명령줄 도구인 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 use, 작동하는 컴파일러)
  • 프로젝트 특유의 예상치 못한 동작이나 경고
  • Claude가 기억했으면 하는 기타 정보

CLAUDE.md 파일에는 필수 형식이 없습니다. 간결하고 사람이 읽기 쉽게 유지하는 것을 권장합니다. 예를 들어:

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

# 코드 스타일
- CommonJS(require)가 아닌 ES modules(import/export) 문법 사용
- 가능할 때 imports 구조화 (예: import { foo } from 'bar')

# 워크플로우
- 일련의 코드 변경을 마쳤을 때 타입체크를 꼭 하기
- 성능을 위해 전체 테스트 스위트가 아닌 단일 테스트 실행 선호

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 파일을 프롬프트 개선기를 통해 실행하고 준수를 개선하기 위해 지침을 조정합니다 (예: "중요" 또는 "반드시 해야 함"으로 강조 추가).

c. Claude의 허용된 도구 목록 큐레이션

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

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

  1. 세션 중 프롬프트가 나타날 때 "항상 허용" 선택
  2. Claude Code를 시작한 후 /permissions 명령어를 사용하여 허용 목록에서 도구를 추가하거나 제거. 예를 들어, 파일 편집을 항상 허용하려면 Edit를, git 커밋을 허용하려면 Bash(git commit:*), Puppeteer MCP 서버로 탐색을 허용하려면 mcp__puppeteer__puppeteer_navigate를 추가할 수 있습니다
  3. .claude/settings.json 또는 ~/.claude.json을 수동으로 편집 (전자를 소스 컨트롤에 체크인하여 팀과 공유하는 것을 권장)
  4. 세션별 권한을 위해 --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는 유닉스 도구와 gh 같은 일반적인 유틸리티들을 알고 있지만, 지침 없이는 여러분의 사용자 정의 bash 도구에 대해 알지 못할 것입니다:

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

b. MCP와 함께 Claude 사용

Claude Code는 MCP 서버와 클라이언트 모두로 기능합니다. 클라이언트로서, 세 가지 방법으로 도구에 접근하기 위해 임의의 수의 MCP 서버에 연결할 수 있습니다:

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

MCP로 작업할 때, 설정 문제를 식별하는 데 도움이 되도록 --mcp-debug 플래그로 Claude를 실행하는 것도 도움이 될 수 있습니다.

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

반복되는 워크플로우—디버깅 루프, 로그 분석 등—의 경우, .claude/commands 폴더 내의 Markdown 파일에 프롬프트 템플릿을 저장하세요. /를 입력할 때 슬래시 명령어 메뉴를 통해 사용할 수 있게 됩니다. 이러한 명령어들을 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를 읽어줘")을 제공하되, 아직 코드를 작성하지 말라고 명시적으로 말하세요.

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

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

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

  4. Claude에게 솔루션을 코드로 구현하도록 요청하세요. 이는 또한 솔루션의 조각들을 구현하면서 솔루션의 합리성을 명시적으로 검증하도록 요청하기 좋은 장소입니다.

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

1-2단계는 중요합니다—이것들 없이는 Claude가 솔루션을 코딩하는 것으로 바로 점프하는 경향이 있습니다. 때로는 그것이 원하는 것이지만, Claude에게 먼저 연구하고 계획하도록 요청하는 것은 사전에 더 깊은 사고가 필요한 문제들에 대한 성능을 크게 향상시킵니다.

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

이는 단위, 통합, 또는 end-to-end 테스트로 쉽게 검증할 수 있는 변경사항에 대한 Anthropic이 선호하는 워크플로우입니다. 테스트 주도 개발 (TDD)은 에이전틱 코딩과 함께 훨씬 더 강력해집니다:

  1. Claude에게 예상 입력/출력 쌍을 기반으로 테스트를 작성하도록 요청하세요. 테스트 주도 개발을 하고 있다는 사실을 명시하여 코드베이스에 아직 존재하지 않는 기능에 대해서도 목 구현을 생성하지 않도록 하세요.

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

  3. 테스트에 만족할 때 Claude에게 테스트를 커밋하도록 요청하세요.

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

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

  6. 변경사항에 만족할 때 Claude에게 코드를 커밋하도록 요청하세요.

Claude는 반복할 명확한 목표가 있을 때—시각적 목업, 테스트 케이스, 또는 다른 종류의 출력—가장 좋은 성능을 발휘합니다. 테스트와 같은 예상 출력을 제공함으로써, Claude는 변경사항을 만들고, 결과를 평가하고, 성공할 때까지 점진적으로 개선할 수 있습니다.

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

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

  1. Claude에게 브라우저 스크린샷을 찍을 수 있는 방법을 제공하세요 (예: Puppeteer MCP 서버, iOS 시뮬레이터 MCP 서버, 또는 수동으로 Claude에 스크린샷을 복사/붙여넣기).

  2. 이미지를 복사/붙여넣기 또는 드래그 앤 드롭하거나, 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를 사용합니다:

  • "v1.2.3에 어떤 변경사항이 들어갔나?", "이 특정 기능을 누가 소유하나?", 또는 "이 API가 왜 이렇게 설계되었나?"와 같은 질문에 답하기 위한 git 히스토리 검색. 이런 쿼리에 답하기 위해 git 히스토리를 살펴보도록 Claude에게 명시적으로 프롬프트하는 것이 도움이 됩니다.

  • 커밋 메시지 작성. Claude는 모든 관련 컨텍스트를 고려하여 메시지를 구성하기 위해 변경사항과 최근 히스토리를 자동으로 살펴볼 것입니다.

  • 파일 되돌리기, 리베이스 충돌 해결, 패치 비교 및 이식과 같은 복잡한 git 작업 처리

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

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

  • 풀 리퀘스트 생성: Claude는 "pr" 약어를 이해하고 diff와 주변 컨텍스트를 기반으로 적절한 커밋 메시지를 생성할 것입니다.

  • 간단한 코드 리뷰 댓글에 대한 원샷 해결 구현: PR의 댓글을 수정하라고 말하기만 하면 됩니다 (선택적으로, 더 구체적인 지침을 제공) 그리고 완료되면 PR 브랜치로 다시 푸시합니다.

  • 실패한 빌드나 린터 경고 수정

  • 열린 GitHub 이슈들을 반복하도록 Claude에게 요청하여 열린 이슈들 분류 및 트리아지

이는 루틴 작업을 자동화하면서 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가 시작하기 좋은 예제. 그다음, 패턴을 따라 사용자가 월을 선택하고 앞뒤로 페이지네이션하여 연도를 선택할 수 있는 새로운 캘린더 위젯 구현. 코드베이스의 나머지 부분에서 이미 사용된 라이브러리 외에는 라이브러리 없이 처음부터 구축하기.

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에게 코딩하기 전에 계획을 세우도록 요청하세요. 계획이 좋아 보인다고 확인할 때까지 코딩하지 말라고 명시적으로 말하세요.
  • 어떤 단계에서든 (사고, 도구 호출, 파일 편집) Claude를 중단하기 위해 Escape를 누르세요. 컨텍스트를 보존하여 지침을 리디렉션하거나 확장할 수 있습니다.
  • 히스토리에서 뒤로 가기, 이전 프롬프트 편집하기, 다른 방향 탐색하기 위해 Escape를 두 번 누르세요. 원하는 결과를 얻을 때까지 프롬프트를 편집하고 반복할 수 있습니다.
  • 옵션 #2와 함께 다른 접근 방식을 취하기 위해 Claude에게 변경사항을 취소하도록 요청하세요.

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

f. 컨텍스트를 집중시키기 위해 /clear 사용

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

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

코드 마이그레이션, 수많은 린트 에러 수정, 복잡한 빌드 스크립트 실행과 같은 여러 단계가 있거나 철저한 솔루션이 필요한 큰 작업의 경우, Claude가 Markdown 파일 (또는 심지어 GitHub 이슈!)을 체크리스트와 작업 스크래치패드로 사용하도록 하여 성능을 향상시키세요:

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

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

h. Claude에 데이터 전달

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

  • 프롬프트에 직접 복사하여 붙여넣기 (가장 일반적인 접근법)
  • Claude Code로 파이프 (예: cat foo.txt | claude), 로그, CSV, 대용량 데이터에 특히 유용
  • bash 명령어, MCP 도구, 또는 사용자 정의 슬래시 명령어를 통해 데이터를 가져오도록 Claude에게 지시
  • 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가 코드를 작성하게 하면서 다른 하나가 리뷰하거나 테스트하게 하는 것입니다. 여러 엔지니어와 작업하는 것과 유사하게, 때로는 별도의 컨텍스트를 갖는 것이 유익합니다:

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

테스트와 유사한 것을 할 수 있습니다: 한 Claude가 테스트를 작성하게 하고, 다른 Claude가 테스트를 통과하는 코드를 작성하게 하세요. 심지어 Claude 인스턴스들이 별도의 작업 스크래치패드를 제공하고 어느 것에 쓰고 어느 것에서 읽을지 지시하여 서로 소통하게 할 수도 있습니다.

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

b. 리포지토리의 여러 체크아웃 가지기

Claude가 각 단계를 완료하기를 기다리는 대신, Anthropic의 많은 엔지니어들이 하는 것은:

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

c. git 워크트리 사용

이 접근법은 여러 독립적인 작업에 빛나며, 여러 체크아웃에 대한 더 가벼운 대안을 제공합니다. Git 워크트리는 동일한 리포지토리에서 여러 브랜치를 별도 디렉토리로 체크아웃할 수 있게 합니다. 각 워크트리는 격리된 파일과 함께 자체 작업 디렉토리를 가지면서, 동일한 Git 히스토리와 reflog를 공유합니다.

git 워크트리를 사용하면 프로젝트의 다른 부분에서 각각 자체 독립적인 작업에 집중하는 여러 Claude 세션을 동시에 실행할 수 있습니다. 예를 들어, 한 Claude가 인증 시스템을 리팩토링하는 동안 다른 하나는 완전히 관련 없는 데이터 시각화 컴포넌트를 구축할 수 있습니다. 작업들이 겹치지 않기 때문에, 각 Claude는 다른 것의 변경사항을 기다리거나 머지 충돌을 다루지 않고도 최대 속도로 작업할 수 있습니다:

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

몇 가지 팁:

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

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

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

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

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

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

  • claude -p "<당신의 프롬프트>" --json | your_command를 호출하세요. 여기서 your_command는 처리 파이프라인의 다음 단계입니다.
  • 그게 전부입니다! JSON 출력 (선택사항)은 더 쉬운 자동화된 처리를 위한 구조를 제공하는 데 도움이 될 수 있습니다.

이 두 사용 사례 모두에 대해, 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 엔지니어들에게 특별히 감사드립니다.

반응형
  • 네이버 블로그 공유
  • 네이버 밴드 공유
  • 페이스북 공유
  • 카카오스토리 공유