Claude Code: 에이전트 코딩을 위한 모범 사례

대부분의 모범 사례는 하나의 제약 조건에 기반합니다. 바로 Claude의 컨텍스트 창(context window)이 빠르게 채워지고, 채워질수록 성능이 저하된다는 것입니다. Claude의 컨텍스트 창은 모든 메시지, Claude가 읽는 모든 파일, 그리고 모든 명령어 출력을 포함하여 전체 대화를 담고 있습니다. 하지만 이것은 빠르게 가득 찰 수 있습니다. 단 한 번의 디버깅 세션이나 코드베이스 탐색만으로도 수만 개의 토큰을 생성하고 소비할 수 있습니다. 이는 LLM 성능이 컨텍스트가 채워짐에 따라 저하된다는 점에서 중요합니다. 컨텍스트 창이 거의 가득 차면, Claude는 이전 지침을 '잊기' 시작하거나 더 많은 실수를 할 수 있습니다. 따라서 컨텍스트 창 관리가 가장 중요한 자원입니다. 세션이 실제로 어떻게 채워지는지 확인하려면, 시작 시 로드되는 내용과 각 파일 읽기가 얼마의 비용이 드는지 보여주는 대화형 워크스루를 시청하십시오. 사용자 지정 상태 표시줄로 컨텍스트 사용량을 지속적으로 추적하고, 토큰 사용량을 줄이는 전략을 통해 토큰 사용량 감소 방법을 확인해 보십시오.

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

Claude는 작업이 끝났다고 판단하면 멈춥니다. 검사 과정 없이는 실행할 수 있으며, '끝났다'는 것이 유일한 신호가 되고, 사용자 자신이 검증 루프(verification loop)가 됩니다. 즉, 모든 실수는 사용자가 알아차릴 때까지 기다립니다. Claude에게 통과 또는 실패를 반환하는 무언가를 제공하면, 이 루프가 스스로 닫힙니다. Claude는 작업을 수행하고, 검사를 실행하며, 결과를 읽고, 검사가 통과할 때까지 반복합니다. 여기서 '검사'란 대화에서 Claude가 읽을 수 있는 신호를 반환하는 모든 것을 의미합니다: 테스트 스위트(test suite), 빌드 종료 코드(build exit code), 린터(linter), 출력을 고정된 값(fixture)과 비교하여 차이점을 보여주는 스크립트, 또는 디자인과 비교되는 브라우저 스크린샷 등이 있습니다. Claude의 검사가 통과한 후에는 실행 중인 애플리케이션에 대해 변경 사항을 확인하기 위해 직접 /verify를 실행하십시오.

하나의 프롬프트에서: Claude에게 같은 메시지 내에서 검사를 실행하고 반복하도록 요청하십시오 (위 표와 같이). 세션 전체에 걸쳐: 목표(goal)를 설정하여 검사 과정을 지정하십시오.

condition. 별도의 평가자(evaluator)가 매 턴마다 이를 재검사하고, Claude는 목표(goal)가 해결될 때까지 계속 작업합니다. 만약 Claude가 정체되면, Claude Code는 목표가 여전히 설정된 상태에서 결국 실행을 중단합니다. /goal 평가가 어떻게 작동하는지 확인해 보세요.결정론적 게이트(deterministic gate)로서: Stop hook은 스크립트로 사용자의 검사를 실행하고, 통과할 때까지 턴이 종료되는 것을 차단합니다. Stop input은 연속 블록의 제한을 다룹니다.제2의 의견으로서: 자체 발견 사항을 확인하는 검증 서브 에이전트(verification subagent)나 동적 워크플로우가 신선한 모델로 결과를 반박하려고 시도하여, 작업을 수행하는 에이전트가 평가를 내리는 주체가 아니게 합니다.

/goal

그리고 Stop hook 버전은 사용자가 지켜보지 않아도 무인 실행(unattended run)을 올바르게 완료할 수 있게 해줍니다. Claude에게 성공을 단언하기보다 증거를 보여주도록 하세요: 테스트 출력, 실행한 명령어와 그 반환 값, 또는 결과 스크린샷 등이 될 수 있습니다. 증거를 검토하는 것이 직접 검증을 다시 실행하는 것보다 빠르며, 사용자가 지켜보지 않은 세션에서도 작동합니다.

먼저 탐색하고, 계획한 다음, 코딩하기

Claude가 바로 코딩으로 점프하게 두면 잘못된 문제를 해결하는 코드를 생성할 수 있습니다. 계획 모드(plan mode)를 사용하여 탐색과 실행을 분리하세요. 권장되는 워크플로우는 네 단계로 구성됩니다:탐색(Explore)

Shift+Tab

버튼 상태 표시줄에 ⏸ plan mode on이 나타날 때까지 사용하거나, claude --permission-mode plan으로 세션을 시작합니다. Claude는 파일을 읽고 변경 사항을 만들지 않으면서 질문에 답합니다.계획(Plan)

Ctrl+G

Claude가 진행하기 전에 텍스트 편집기에서 계획을 열어 직접 수정할 수 있습니다.구현(Implement)

Shift+Tab

그런 다음 Claude에게 코딩하도록 하고, 그 계획에 따라 검증합니다.커밋(Commit)

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

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

Claude에게 풍부한 데이터를 여러 방식으로 제공할 수 있습니다: 코드 위치를 설명하는 대신 참조 파일을 사용하세요. Claude는 응답하기 전에 해당 파일을 읽습니다. [IMG:N]

이미지를 직접 붙여넣으세요. 이미지를 프롬프트에 복사/붙여넣기하거나 드래그 앤 드롭하세요.
문서 및 API 참조를 위한 URL을 제공하세요. 자주 사용되는 도메인을 허용 목록으로 지정하려면 /permissions를 사용하세요.
데이터를 파이프(Pipe)로 전달하세요. cat error.log | claude -p "explain this error"와 같이 실행하여 파일 내용을 직접 전송할 수 있습니다.
Claude가 필요한 것을 가져오게 하세요. Bash 명령어, MCP 도구 또는 파일을 읽어 컨텍스트를 스스로 가져오도록 Claude에게 지시하세요.

환경 설정하기

몇 가지 설정 단계만으로도 모든 세션에서 Claude Code의 효과를 크게 높일 수 있습니다. 확장 기능의 전체 개요와 각 기능을 언제 사용해야 하는지는 Extend Claude Code를 참고하세요.

효과적인 CLAUDE.md 작성하기

CLAUDE.md는 Claude가 모든 대화 시작 시 읽는 특별한 파일입니다. Bash 명령어, 코드 스타일, 워크플로우 규칙 등을 포함하세요. 이는 Claude가 코드만으로는 추론할 수 없는 영구적인 컨텍스트를 제공합니다. CLAUDE.md 파일에 필수적인 형식은 없지만, 간결하고 사람이 읽기 쉬운 형태로 유지해야 합니다. 예를 들어, /context를 사용하여 Claude가 파일을 로드했는지 확인할 수 있습니다. CLAUDE.md는 매 세션마다 로드되므로, 광범위하게 적용되는 내용만 포함하세요. 도메인 지식이나 때때로만 관련되는 워크플로우의 경우 대신 스킬(skills)을 사용하세요. Claude는 이를 요청에 따라 로드하여 모든 대화를 부풀리지 않습니다.

간결하게 유지하세요. 각 줄마다 다음 질문을 하세요: “이것을 제거해도 Claude가 실수하는 원인이 될까?” 그렇지 않다면, 삭제하세요. 내용이 과도하게 많은 CLAUDE.md 파일은 Claude가 실제 지침을 무시하게 만듭니다!

/doctor는 Claude가 코드베이스에서 파생할 수 있는 내용을 잘라내도록 제안합니다.
만약 Claude가 특정 지침을 계속 건너뛴다면, 해당 줄에만 “IMPORTANT”와 같은 강조 표시를 추가하세요. 여러 줄을 강조하면 아무것도 눈에 띄지 않습니다. 팀이 기여할 수 있도록 CLAUDE.md 파일을 git에 커밋하세요. 이 파일은 시간이 지남에 따라 가치가 쌓입니다.
CLAUDE.md 파일은 @path/to/import를 사용하여 추가 파일을 가져올 수 있습니다.

구문 (syntax). import 규칙 및 CLAUDE.md 파일이 위치할 수 있는 곳은 CLAUDE.md 파일을 참조하세요.

권한 설정

Claude Code v2.1.283 이상 버전에서는 자동 모드(auto mode)가 대화형 터미널 및 VS Code 세션의 기본 시작 권한 모드입니다. 별도의 분류기 모델(classifier model)이 사용자 대신 대부분의 작업을 검토하고, 범위 상승(scope escalation), 알 수 없는 인프라(unknown infrastructure), 또는 적대적 콘텐츠 기반 작업과 같이 위험해 보이는 경우에만 차단합니다. 이전 버전에서는 자동 모드가 Pro, Max 및 Team 플랜에서만 기본 시작 권한 모드였습니다. 수동 모드(Manual mode)에서는 Claude Code가 시스템을 수정할 수 있는 작업(파일 쓰기, Bash 명령어, MCP 도구 등) 전에 사용자에게 요청합니다. 이는 안전하지만 번거롭습니다. 열 번째 승인 이후에는 검토하기보다는 클릭하는 경향이 생깁니다. 다음 두 가지 도구가 수동 모드의 이러한 중단을 줄이고 자동 모드에서도 적용됩니다:
권한 허용 목록(Permission allowlists): npm run lint 또는 git commit과 같이 안전하다고 아는 특정 도구를 허용합니다.

샌드박싱(Sandboxing): 파일 시스템 및 네트워크 액세스를 제한하는 OS 수준 격리 기능을 활성화하여 Claude가 정의된 경계 내에서 더 자유롭게 작업할 수 있도록 합니다.

CLI 도구 사용하기

CLI 도구는 외부 서비스와 상호 작용하는 가장 컨텍스트 효율적인 방법입니다. GitHub를 사용하는 경우, gh CLI를 설치하세요. Claude는 이를 사용하여 이슈 생성, 풀 리퀘스트 열기 및 댓글 읽기를 하는 방법을 알고 있습니다. gh가 없더라도 Claude는 여전히 GitHub API를 사용할 수 있지만, 인증되지 않은 요청은 종종 속도 제한(rate limits)에 걸립니다.
Claude는 또한 자신이 이미 알고 있는 CLI 도구 외의 도구를 학습하는 데 효과적입니다. Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.와 같은 프롬프트를 시도해 보세요.

MCP 서버 연결하기

MCP 서버를 사용하면 Claude에게 이슈 트래커의 기능 구현 요청, 데이터베이스 쿼리, 모니터링 데이터 분석, Figma 디자인 통합, 워크플로우 자동화 등을 요청할 수 있습니다.

후크 설정하기

훅(Hooks)은 Claude의 워크플로우 내 특정 지점에서 스크립트를 자동으로 실행합니다. 권고 사항인 CLAUDE.md 지침과 달리, 훅은 결정론적(deterministic)이며 해당 액션이 발생하도록 보장합니다. Claude가 직접 훅을 작성해 줄 수 있습니다. 예를 들어 “파일 편집 후마다 eslint를 실행하는 훅을 작성해 줘” 또는 *“migrations 폴더에 대한 쓰기를 차단하는 훅을 작성해 줘”*와 같은 프롬프트를 사용하거나, .claude/settings.json 파일을 직접 편집하여 수동으로 훅을 구성하고 /hooks를 실행하여 설정된 내용을 확인할 수 있습니다.

스킬(Skills) 생성하기

스킬은 프로젝트, 팀 또는 도메인에 특화된 정보로 Claude의 지식을 확장합니다. Claude는 관련성이 있을 때 자동으로 이를 적용하며, 필요하다면 /skill-name으로 직접 호출할 수도 있습니다. .claude/skills/ 디렉토리에 SKILL.md 파일을 추가하여 스킬을 생성하고, /fix-issue 1234와 같이 호출합니다. 사이드 이펙트(side effects)가 있어 수동으로 트리거하려는 워크플로우의 경우 disable-model-invocation: true를 사용하세요.

커스텀 서브 에이전트(Subagents) 생성하기

서브 에이전트는 자체 컨텍스트와 허용된 도구 세트를 가지고 실행됩니다. 이들은 많은 파일을 읽거나 메인 대화를 복잡하게 만들지 않으면서 전문적인 집중이 필요한 작업에 유용합니다. “보안 문제를 검토하기 위해 서브 에이전트를 사용해 줘.”

플러그인(Plugins) 설치하기

플러그인은 커뮤니티와 Anthropic에서 제공하는 스킬, 훅, 서브 에이전트 및 MCP 서버를 단일 설치 가능한 단위로 묶어줍니다. 만약 타입 언어(typed language)를 사용한다면, 코드 인텔리전스 플러그인을 설치하여 Claude가 편집 후 정확한 심볼 탐색과 자동 오류 감지 기능을 갖도록 하세요. 스킬, 서브 에이전트, 훅, MCP 중 무엇을 선택해야 할지에 대한 지침은 Extend Claude Code를 참고하세요.

효과적으로 소통하기

Claude에게 다른 엔지니어에게 물어볼 질문들을 던져보세요. 그리고 더 큰 기능을 위해서는 구현을 시작하기 전에 Claude가 당신과 인터뷰하고 명세서(spec)를 작성하도록 하세요.

코드베이스 관련 질문하기

새로운 코드베이스에 온보딩할 때는 학습과 탐색을 위해 Claude Code를 사용하세요. 다른 엔지니어에게 할 법한 질문들을 Claude에게도 할 수 있습니다:

• 로깅은 어떻게 작동하나요?
• 새로운 API 엔드포인트를 만들려면 어떻게 해야 하나요?
• foo.rs의 134번째 줄에 있는 async move { ... }는 무엇을 하나요?
• CustomerOnboardingFlowImpl은 어떤 예외 케이스를 처리하나요?
• 왜 이 코드는 333번째 줄에서 bar() 대신 foo()를 호출하나요?

Claude가 당신에게 인터뷰하게 하기

Claude는 기술적 구현, UI/UX, 예외 케이스, 트레이드오프(tradeoffs) 등 아직 고려하지 못했을 수도 있는 것들에 대해 질문합니다. 프롬프트를 보내기 전에 [간략한 설명]을 자신의 기능으로 대체하세요.

세션 관리

대화는 지속적이며 되돌릴 수 있습니다. 이를 유리하게 사용하세요!

일찍, 자주 방향 수정하기

최고의 결과는 긴 피드백 루프(feedback loops)에서 나옵니다. Claude가 가끔 첫 시도에 완벽하게 문제를 해결하더라도, 빠르게 교정하는 것이 일반적으로 더 빠르고 좋은 솔루션을 만들어냅니다.: Esc 키를 사용하여 Claude의 동작 중간을 멈추세요. 컨텍스트는 유지되므로 방향을 전환할 수 있습니다.: Esc + Esc 또는 /rewind를 실행하거나 두 번 Esc를 누르거나 /rewind를 실행하여 이전 대화 및 코드 상태를 열람하고 복원하거나, 선택된 메시지에서 요약할 수 있습니다.: Claude가 변경 사항을 되돌리게 하려면. "그거 취소해줘("Undo that")": 관련 없는 작업 간의 컨텍스트를 초기화합니다. 관련 없는 컨텍스트가 쌓인 긴 세션은 성능을 저하시킬 수 있습니다.: /clear

/clear를 사용하여 새로운 시작을 하고, 배운 내용을 통합한 더 구체적인 프롬프트를 사용하세요. 개선된 프롬프트로 깨끗하게 시작하는 것이 누적된 수정이 있는 긴 세션보다 거의 항상 우수합니다.

컨텍스트 적극적으로 관리하기

Claude Code는 컨텍스트 한계에 가까워지면 대화 기록을 자동으로 압축하여 중요한 코드와 결정 사항은 보존하면서 공간을 확보합니다. 긴 세션 동안 Claude의 컨텍스트 창은 관련 없는 대화, 파일 내용, 명령어로 채워질 수 있습니다. 이는 성능을 저하시키고 때로는 Claude를 산만하게 만들 수 있습니다.- /clear 사용하기

작업 간에 컨텍스트 창을 완전히 초기화하는 것이 좋습니다. 자동 압축(auto compaction)이 트리거되면 Claude는 코드 패턴, 파일 상태 및 주요 결정 사항을 포함하여 가장 중요한 내용을 요약합니다.

• 더 많은 제어를 위해 /compact <지침>과 같이 Focus on the API changes를 실행할 수 있습니다.

• 대화의 일부만 압축하려면 Esc + Esc 또는 /rewind를 사용하고 메시지 체크포인트를 선택한 다음 여기부터 요약(Summarize from here) 또는 **여태까지 요약(Summarize up to here)**을 선택합니다. 첫 번째는 해당 시점 이후의 메시지를 응축하면서 이전 컨텍스트를 유지하는 반면, 두 번째는 최근 내용을 온전히 유지하면서 이전 메시지를 응축합니다. 리와인드 메뉴의 요약 옵션을 참조하세요.

• 중요한 컨텍스트가 요약 과정에서 살아남도록 CLAUDE.md에서 다음과 같은 지침으로 압축 동작을 사용자 정의할 수 있습니다: `