Claude Code 모범 사례

Claude Code는 에이전트 코딩 환경입니다. 질문에 답하고 기다리는 챗봇과 달리 Claude Code는 파일을 읽고, 명령을 실행하고, 변경을 수행하며, 당신이 지켜보거나 방향을 바꾸거나 완전히 떠나 있는 동안에도 자율적으로 문제를 해결할 수 있습니다.

이는 작업 방식을 바꿉니다. 직접 코드를 작성하고 Claude에게 검토를 요청하는 대신, 원하는 것을 설명하면 Claude가 어떻게 구축할지 파악합니다. Claude는 탐색하고, 계획하고, 구현합니다.

하지만 이러한 자율성에도 학습 곡선이 있습니다. Claude는 이해해야 할 특정 제약 조건 내에서 작동합니다.

이 가이드는 Anthropic의 내부 팀과 다양한 코드베이스, 언어, 환경에서 Claude Code를 사용하는 엔지니어들 사이에서 효과적으로 입증된 패턴을 다룹니다. 에이전트 루프가 내부적으로 어떻게 작동하는지에 대해서는 Claude Code 작동 방식을 참조하십시오.

대부분의 모범 사례는 하나의 제약 조건을 기반으로 합니다: Claude의 context window가 빠르게 채워지고, 채워질수록 성능이 저하됩니다.

Claude의 context window는 모든 메시지, Claude가 읽은 모든 파일, 모든 명령 출력을 포함한 전체 대화를 보유합니다. 그러나 이는 빠르게 채워질 수 있습니다. 단일 디버깅 세션이나 코드베이스 탐색만으로도 수만 개의 토큰을 생성하고 소비할 수 있습니다.

LLM 성능이 context가 채워질수록 저하되기 때문에 이는 중요합니다. context window가 거의 가득 차면 Claude는 이전 지시사항을 "잊기" 시작하거나 더 많은 실수를 할 수 있습니다. context window는 관리해야 할 가장 중요한 리소스입니다. 세션이 실제로 어떻게 채워지는지 보려면 대화형 연습을 시청하여 시작 시 로드되는 것과 각 파일 읽기의 비용을 확인하십시오. 사용자 정의 상태 줄로 context 사용량을 지속적으로 추적하고, 토큰 사용량 감소에서 토큰 사용량을 줄이기 위한 전략을 참조하십시오.

Claude에게 작업을 검증할 방법 제공하기

Claude가 자신의 작업을 확인할 수 있도록 테스트, 스크린샷 또는 예상 출력을 포함하십시오. 이것이 할 수 있는 가장 높은 영향력의 단일 작업입니다.

Claude는 테스트를 실행하고, 스크린샷을 비교하고, 출력을 검증하는 등 자신의 작업을 검증할 수 있을 때 훨씬 더 잘 수행합니다.

명확한 성공 기준이 없으면 올바르게 보이지만 실제로는 작동하지 않는 것을 생성할 수 있습니다. 당신이 유일한 피드백 루프가 되고, 모든 실수가 당신의 주의를 필요로 합니다.

UI 변경 사항은 Chrome 확장 프로그램의 Claude를 사용하여 검증할 수 있습니다. 브라우저에서 새 탭을 열고, UI를 테스트하고, 코드가 작동할 때까지 반복합니다.

검증은 테스트 스위트, linter 또는 출력을 확인하는 Bash 명령일 수도 있습니다. 검증을 견고하게 만드는 데 투자하십시오.

먼저 탐색하고, 그 다음 계획하고, 그 다음 코드 작성하기

연구 및 계획을 구현과 분리하여 잘못된 문제를 해결하는 것을 피하십시오.

Claude가 바로 코딩으로 뛰어들도록 하면 잘못된 문제를 해결하는 코드가 생성될 수 있습니다. Plan Mode를 사용하여 탐색을 실행과 분리하십시오.

권장 워크플로우에는 4가지 단계가 있습니다:

탐색

Plan Mode를 입력하십시오. Claude는 파일을 읽고 변경을 수행하지 않고 질문에 답합니다.

read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

계획

Claude에게 상세한 구현 계획을 작성하도록 요청하십시오.

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

Ctrl+G를 눌러 Claude가 진행하기 전에 텍스트 편집기에서 계획을 열어 직접 편집하십시오.

구현

Plan Mode를 종료하고 Claude가 코드를 작성하도록 하여 계획에 대해 검증하십시오.

implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

커밋

Claude에게 설명적인 메시지로 커밋하고 PR을 생성하도록 요청하십시오.

commit with a descriptive message and open a PR

Plan Mode는 유용하지만 오버헤드도 추가합니다.

범위가 명확하고 수정이 작은 작업(예: 오타 수정, 로그 줄 추가 또는 변수 이름 바꾸기)의 경우 Claude에게 직접 수행하도록 요청하십시오.

계획은 접근 방식이 불확실할 때, 변경이 여러 파일을 수정할 때, 또는 수정 중인 코드에 익숙하지 않을 때 가장 유용합니다. diff를 한 문장으로 설명할 수 있다면 계획을 건너뛰십시오.

프롬프트에서 구체적인 컨텍스트 제공하기

지시사항이 정확할수록 필요한 수정이 적습니다.

Claude는 의도를 추론할 수 있지만 마음을 읽을 수는 없습니다. 특정 파일을 참조하고, 제약 조건을 언급하고, 예제 패턴을 지적하십시오.

모호한 프롬프트는 탐색 중이고 과정을 수정할 여유가 있을 때 유용할 수 있습니다. "이 파일에서 무엇을 개선하시겠습니까?"와 같은 프롬프트는 당신이 생각하지 못했을 것들을 드러낼 수 있습니다.

풍부한 콘텐츠 제공하기

@를 사용하여 파일을 참조하거나, 스크린샷/이미지를 붙여넣거나, 데이터를 직접 파이프하십시오.

여러 가지 방법으로 Claude에게 풍부한 데이터를 제공할 수 있습니다:

• @로 파일 참조 코드가 어디에 있는지 설명하는 대신. Claude는 응답하기 전에 파일을 읽습니다.
• 이미지를 직접 붙여넣기. 프롬프트에 이미지를 복사/붙여넣기 또는 드래그 앤 드롭하십시오.
• 문서 및 API 참조에 URL 제공. /permissions를 사용하여 자주 사용되는 도메인을 허용 목록에 추가하십시오.
• 데이터 파이프 cat error.log | claude를 실행하여 파일 내용을 직접 전송하십시오.
• Claude가 필요한 것을 가져오도록 하기. Bash 명령, MCP 도구 또는 파일 읽기를 사용하여 Claude가 자체적으로 컨텍스트를 가져오도록 하십시오.

환경 구성하기

CLAUDE.md, 권한, CLI 도구, MCP 서버, hooks, skills, subagents, plugins를 설정하는 방법은 Claude Code 확장하기의 환경 구성하기 섹션을 참조하십시오.

효과적으로 소통하기

Claude Code와의 소통 방식은 결과의 품질에 크게 영향을 미칩니다.

코드베이스 질문 하기

선임 엔지니어에게 물어볼 질문을 Claude에게 하십시오.

새로운 코드베이스에 온보딩할 때 Claude Code를 학습 및 탐색에 사용하십시오. Claude에게 다른 엔지니어에게 물어볼 것과 같은 종류의 질문을 할 수 있습니다:

• 로깅은 어떻게 작동합니까?
• 새로운 API 엔드포인트를 어떻게 만듭니까?
• foo.rs의 134번 줄에서 async move { ... }는 무엇을 합니까?
• CustomerOnboardingFlowImpl은 어떤 엣지 케이스를 처리합니까?
• 이 코드가 333번 줄에서 bar() 대신 foo()를 호출하는 이유는 무엇입니까?

이런 방식으로 Claude Code를 사용하는 것은 효과적인 온보딩 워크플로우이며, 램프업 시간을 개선하고 다른 엔지니어의 부담을 줄입니다. 특별한 프롬프팅이 필요하지 않습니다: 직접 질문하십시오.

Claude가 당신을 인터뷰하도록 하기

더 큰 기능의 경우 Claude가 먼저 당신을 인터뷰하도록 하십시오. 최소한의 프롬프트로 시작하고 Claude에게 AskUserQuestion 도구를 사용하여 당신을 인터뷰하도록 요청하십시오.

Claude는 기술 구현, UI/UX, 엣지 케이스, 트레이드오프를 포함하여 아직 고려하지 않은 것들에 대해 질문합니다.

[간단한 설명]을 빌드하고 싶습니다. AskUserQuestion 도구를 사용하여 자세히 인터뷰해주세요.

기술 구현, UI/UX, 엣지 케이스, 우려 사항, 트레이드오프에 대해 질문하세요. 명백한 질문을 하지 마세요, 당신이 고려하지 않았을 수 있는 어려운 부분을 파고드세요.

모든 것을 다룰 때까지 인터뷰를 계속한 다음 SPEC.md에 완전한 사양을 작성하세요.

사양이 완료되면 새 세션을 시작하여 실행하십시오. 새 세션은 구현에만 집중하는 깨끗한 context를 가지고 있으며, 참조할 수 있는 작성된 사양이 있습니다.

세션 관리하기

대화는 지속적이고 되돌릴 수 있습니다. 이를 활용하십시오!

조기에 자주 방향 수정하기

Claude가 궤도를 벗어나는 것을 알아차리면 즉시 수정하십시오.

최고의 결과는 긴밀한 피드백 루프에서 나옵니다. Claude가 때때로 첫 시도에서 문제를 완벽하게 해결하지만, 빠르게 수정하면 일반적으로 더 빠르게 더 나은 솔루션을 생성합니다.

• Esc: Esc 키로 Claude의 작업을 중간에 중지하십시오. Context는 보존되므로 방향을 바꿀 수 있습니다.
• Esc + Esc 또는 /rewind: Esc를 두 번 누르거나 /rewind를 실행하여 rewind 메뉴를 열고 이전 대화 및 코드 상태를 복원하거나 선택한 메시지에서 요약하십시오.
• "Undo that": Claude에게 변경 사항을 되돌리도록 하십시오.
• /clear: 관련 없는 작업 간에 context를 재설정하십시오. 관련 없는 context가 있는 긴 세션은 성능을 줄일 수 있습니다.

한 세션에서 같은 문제에 대해 Claude를 두 번 이상 수정했다면 context는 실패한 접근 방식으로 복잡해져 있습니다. /clear를 실행하고 배운 내용을 통합하는 더 구체적인 프롬프트로 새로 시작하십시오. 누적된 수정이 있는 긴 세션보다 더 나은 프롬프트가 있는 깨끗한 세션이 거의 항상 더 나은 성능을 발휘합니다.

context 적극적으로 관리하기

관련 없는 작업 간에 /clear를 자주 실행하여 context window를 재설정하십시오.

Claude Code는 context 제한에 접근할 때 대화 기록을 자동으로 압축하여 중요한 코드와 결정을 보존하면서 공간을 확보합니다.

긴 세션 동안 Claude의 context window는 관련 없는 대화, 파일 내용, 명령으로 채워질 수 있습니다. 이는 성능을 줄이고 때때로 Claude를 산만하게 할 수 있습니다.

• 작업 간에 자주 /clear를 사용하여 context window를 완전히 재설정하십시오
• 자동 압축이 트리거되면 Claude는 코드 패턴, 파일 상태, 주요 결정을 포함하여 가장 중요한 것을 요약합니다
• 더 많은 제어를 위해 /compact <instructions>를 실행하십시오(예: /compact Focus on the API changes)
• 대화의 일부만 압축하려면 Esc + Esc 또는 /rewind를 사용하고, 메시지 체크포인트를 선택하고, Summarize from here 또는 Summarize up to here 를 선택하십시오. 첫 번째는 해당 지점부터의 메시지를 압축하면서 이전 context를 유지하고, 두 번째는 이전 메시지를 압축하면서 최근 메시지를 완전히 유지합니다. Restore vs. summarize를 참조하십시오.
• CLAUDE.md에서 "When compacting, always preserve the full list of modified files and any test commands"와 같은 지시사항으로 압축 동작을 사용자 정의하여 중요한 context가 요약을 통해 유지되도록 하십시오
• 빠른 질문의 경우 context에 들어가지 않아야 하므로 /btw를 사용하십시오. 답변은 해제 가능한 오버레이에 나타나고 대화 기록에 들어가지 않으므로 context를 증가시키지 않고 세부 정보를 확인할 수 있습니다.

subagents를 사용하여 조사하기

"use subagents to investigate X"로 연구를 위임하십시오. 그들은 별도의 context에서 탐색하여 구현을 위해 주요 대화를 깨끗하게 유지합니다.

context가 기본 제약 조건이므로 subagents는 사용 가능한 가장 강력한 도구 중 하나입니다. Claude가 코드베이스를 연구할 때 많은 파일을 읽으며, 모두 context를 소비합니다. Subagents는 별도의 context window에서 실행되고 요약을 보고합니다:

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

subagent는 코드베이스를 탐색하고, 관련 파일을 읽고, 주요 대화를 복잡하게 하지 않고 발견 사항을 보고합니다.

Claude가 구현한 후 검증을 위해 subagents를 사용할 수도 있습니다:

use a subagent to review this code for edge cases

체크포인트로 rewind하기

Claude가 수행하는 모든 프롬프트는 체크포인트를 생성합니다. 이전 체크포인트로 대화, 코드 또는 둘 다를 복원할 수 있습니다.

Claude는 각 변경 전에 자동으로 파일을 스냅샷하므로 체크포인트가 파일을 복원할 수 있습니다. Escape를 두 번 누르거나 /rewind를 실행하여 rewind 메뉴를 열기. 대화만 복원하거나, 코드만 복원하거나, 둘 다 복원하거나, 선택한 메시지에서 요약할 수 있습니다. 자세한 내용은 Checkpointing을 참조하십시오.

모든 움직임을 신중하게 계획하는 대신 Claude에게 위험한 것을 시도하도록 할 수 있습니다. 작동하지 않으면 rewind하고 다른 접근 방식을 시도하십시오. 체크포인트는 세션 간에 유지되므로 터미널을 닫아도 나중에 rewind할 수 있습니다.

체크포인트는 Claude가 수행한 변경만 추적하며, 외부 프로세스는 추적하지 않습니다. 이는 git의 대체품이 아닙니다.

대화 재개하기

/rename으로 세션에 이름을 지정하고 분기처럼 취급하십시오: 각 작업 스트림은 자체 지속적인 context를 가집니다.

Claude Code는 대화를 로컬로 저장하므로 작업이 여러 세션에 걸쳐 있을 때 context를 다시 설명할 필요가 없습니다. claude --continue를 실행하여 가장 최근 세션을 선택하거나, claude --resume을 실행하여 목록에서 선택하십시오. oauth-migration과 같은 설명적인 이름으로 세션에 이름을 지정하여 나중에 찾을 수 있도록 하십시오. Manage sessions에서 전체 resume, branch, naming 제어 집합을 참조하십시오.

자동화 및 확장하기

한 Claude로 효과적이 되면 병렬 세션, 비대화형 모드, fan-out 패턴으로 출력을 곱하십시오.

지금까지 모든 것은 한 명의 인간, 한 명의 Claude, 한 개의 대화를 가정합니다. 하지만 Claude Code는 수평으로 확장됩니다. 이 섹션의 기술은 더 많은 작업을 수행하는 방법을 보여줍니다.

비대화형 모드 실행하기

CI, pre-commit hooks 또는 스크립트에서 claude -p "prompt"를 사용하십시오. 스트리밍 JSON 출력의 경우 --output-format stream-json을 추가하십시오.

claude -p "your prompt"를 사용하면 세션 없이 비대화형으로 Claude를 실행할 수 있습니다. 비대화형 모드는 Claude를 CI 파이프라인, pre-commit hooks 또는 자동화된 워크플로우에 통합하는 방법입니다. 출력 형식을 사용하면 결과를 프로그래밍 방식으로 구문 분석할 수 있습니다: 일반 텍스트, JSON 또는 스트리밍 JSON.

# 일회성 쿼리
claude -p "이 프로젝트가 무엇을 하는지 설명하세요"

# 스크립트를 위한 구조화된 출력
claude -p "모든 API 엔드포인트 나열" --output-format json

# 실시간 처리를 위한 스트리밍
claude -p "이 로그 파일 분석" --output-format stream-json

여러 Claude 세션 실행하기

개발 속도를 높이거나, 격리된 실험을 실행하거나, 복잡한 워크플로우를 시작하기 위해 여러 Claude 세션을 병렬로 실행하십시오.

조정하고 싶은 정도에 맞는 병렬 접근 방식을 선택하십시오:

• Worktrees: 격리된 git 체크아웃에서 별도의 CLI 세션을 실행하여 편집이 충돌하지 않도록 합니다
• 데스크톱 앱: 여러 로컬 세션을 시각적으로 관리하십시오. 각 세션은 자신의 worktree에 있습니다
• 웹의 Claude Code: Anthropic이 관리하는 클라우드 인프라의 격리된 VM에서 세션을 실행하십시오
• Agent teams: 공유 작업, 메시징, 팀 리더를 사용한 여러 세션의 자동 조정

작업을 병렬화하는 것 외에도 여러 세션은 품질 중심 워크플로우를 활성화합니다. 새로운 context는 Claude가 방금 작성한 코드에 편향되지 않으므로 코드 검토를 개선합니다.

예를 들어 Writer/Reviewer 패턴을 사용하십시오:

테스트로 비슷한 작업을 수행할 수 있습니다: 한 Claude가 테스트를 작성하고 다른 Claude가 테스트를 통과하는 코드를 작성합니다.

파일 전체에 fan out하기

각각에 대해 claude -p를 호출하는 루프를 통해 작업을 분배하십시오. 배치 작업의 경우 --allowedTools를 사용하여 권한을 범위 지정하십시오.

대규모 마이그레이션 또는 분석의 경우 많은 병렬 Claude 호출 전체에 작업을 분배할 수 있습니다:

작업 목록 생성

Claude가 마이그레이션이 필요한 모든 파일을 나열하도록 하십시오(예: 마이그레이션이 필요한 모든 2,000개의 Python 파일 나열)

목록을 통해 루프하는 스크립트 작성

for file in $(cat files.txt); do
  claude -p "React에서 Vue로 $file 마이그레이션. OK 또는 FAIL 반환." \
    --allowedTools "Edit,Bash(git commit *)"
done

몇 개 파일에서 테스트한 다음 규모에 맞게 실행

처음 2-3개 파일에서 잘못된 것을 기반으로 프롬프트를 개선한 다음 전체 집합에서 실행하십시오. --allowedTools 플래그는 Claude가 할 수 있는 작업을 제한하며, 이는 무인 상태에서 실행할 때 중요합니다.

Claude를 기존 데이터/처리 파이프라인에 통합할 수도 있습니다:

claude -p "<your prompt>" --output-format json | your_command

개발 중에 디버깅을 위해 --verbose를 사용하고 프로덕션에서는 끄십시오.

auto mode로 자율적으로 실행하기

중단 없는 실행과 백그라운드 안전 검사를 위해 auto mode를 사용하십시오. 분류기 모델이 명령을 실행하기 전에 검토하여 범위 확대, 알 수 없는 인프라, 적대적 콘텐츠 기반 작업을 차단하면서 일상적인 작업이 프롬프트 없이 진행되도록 합니다.

claude --permission-mode auto -p "fix all lint errors"

-p 플래그가 있는 비대화형 실행의 경우, 분류기가 반복적으로 작업을 차단하면 auto mode가 중단됩니다. 폴백할 사용자가 없기 때문입니다. auto mode가 폴백할 때의 임계값을 참조하십시오.

일반적인 실패 패턴 피하기

이는 일반적인 실수입니다. 조기에 인식하면 시간을 절약합니다:

• 주방 싱크 세션. 한 작업으로 시작한 다음 Claude에게 관련 없는 것을 물어본 다음 첫 번째 작업으로 돌아갑니다. Context는 관련 없는 정보로 가득 찹니다.

  수정: 관련 없는 작업 간에 /clear.

• 반복적으로 수정. Claude가 뭔가 잘못하고, 당신이 수정하고, 여전히 잘못되고, 다시 수정합니다. Context는 실패한 접근 방식으로 오염됩니다.

  수정: 두 번의 실패한 수정 후 /clear를 하고 배운 내용을 통합하는 더 나은 초기 프롬프트를 작성하십시오.

• 과도하게 지정된 CLAUDE.md. CLAUDE.md가 너무 길면 Claude는 중요한 규칙이 노이즈에 손실되기 때문에 절반을 무시합니다.

  수정: 무자비하게 정리하십시오. Claude가 지시사항 없이 이미 올바르게 수행하면 삭제하거나 hook으로 변환하십시오.

• 신뢰-검증 간격. Claude는 그럴듯해 보이지만 엣지 케이스를 처리하지 않는 구현을 생성합니다.

  수정: 항상 검증(테스트, 스크립트, 스크린샷)을 제공하십시오. 검증할 수 없으면 배포하지 마십시오.

• 무한 탐색. 범위를 지정하지 않고 Claude에게 뭔가를 "조사"하도록 요청합니다. Claude는 수백 개의 파일을 읽으며 context를 채웁니다.

  수정: 조사를 좁게 범위 지정하거나 subagents를 사용하여 탐색이 주요 context를 소비하지 않도록 하십시오.

직관 개발하기

이 가이드의 패턴은 정해진 것이 아닙니다. 일반적으로 잘 작동하지만 모든 상황에 최적일 수는 없는 시작점입니다.

때로는 복잡한 문제에 깊이 있고 기록이 가치 있기 때문에 context가 누적되도록 해야 합니다. 때로는 작업이 탐색적이기 때문에 계획을 건너뛰고 Claude가 파악하도록 해야 합니다. 때로는 모호한 프롬프트가 정확히 맞기 때문에 Claude가 문제를 해석하는 방식을 보고 싶을 때입니다.

작동하는 것에 주의를 기울이십시오. Claude가 훌륭한 출력을 생성할 때 당신이 한 것을 주목하십시오: 프롬프트 구조, 제공한 context, 당신이 있던 모드. Claude가 어려움을 겪을 때 왜인지 물어보십시오. Context가 너무 시끄러웠습니까? 프롬프트가 너무 모호했습니까? 작업이 한 번에 너무 컸습니까?

시간이 지남에 따라 어떤 가이드도 포착할 수 없는 직관을 개발할 것입니다. 구체적일 때와 개방적일 때, 계획할 때와 탐색할 때, context를 지울 때와 누적하도록 할 때를 알게 될 것입니다.