Claude Code 모범 사례

Claude Code는 질문에 답하고 기다리는 챗봇과 달리, 파일을 읽고 명령을 실행하고 변경을 가하며 자율적으로 문제를 풀어나가는 에이전트형 코딩 환경입니다. 이 글은 Anthropic 내부 팀과 다양한 코드베이스에서 검증된 패턴을 정리한 것으로, 환경 구성부터 병렬 세션으로 확장하는 법까지 다룹니다. 대부분의 모범 사례는 한 가지 제약에서 출발합니다: Claude의 컨텍스트 창은 빨리 차오르고, 차오를수록 성능이 떨어진다. 컨텍스트 창이 가장 중요한 관리 자원입니다.

출처: 공식문서

본문

Claude가 스스로 검증할 방법을 주세요

Claude는 작업이 "완료된 것처럼 보일 때" 멈춥니다. 검증할 체크(테스트, 빌드, 비교용 스크린샷)를 주면 검증 루프가 닫힙니다. 체크는 대화에서 Claude가 읽을 신호를 주는 무엇이든 됩니다: 테스트 스위트, 빌드 exit code, 린터, fixture 대비 diff 스크립트, 디자인과 비교하는 브라우저 스크린샷 등.

한 프롬프트로: 같은 메시지에서 체크 실행·반복을 지시 (예: "validateEmail 함수를 작성해. 예제 테스트: [email protected]은 true, invalid는 false. 구현 후 테스트 실행해")
세션 전반으로: 체크를 /goal 조건으로 설정 → 별도 평가자가 매 턴 재확인. Claude가 막히면 8회 연속 블록 후 훅이 턴 종료를 강제
결정적 게이트로: Stop 훅이 체크를 스크립트로 실행해 통과할 때까지 턴 종료 차단
제2의 의견으로: 검증 서브에이전트가 새 모델로 결과를 반박 시도 (작업한 에이전트가 채점하지 않도록)

Claude에게 성공을 주장만 하지 말고 증거(테스트 출력, 실행한 명령과 결과, 결과 스크린샷)를 보여 달라고 하세요.

먼저 탐색, 그다음 계획, 마지막에 코드

탐색과 실행을 분리하면 잘못된 문제를 푸는 것을 피할 수 있습니다. 권장 4단계:

탐색(Explore): Shift+Tab으로 ⏸ plan mode on 표시가 나올 때까지 누르거나 claude --permission-mode plan으로 시작. Claude가 변경 없이 파일을 읽고 질문에 답함
계획(Plan): 상세 구현 계획 요청. Ctrl+G로 에디터에서 직접 편집 가능
구현(Implement): 계획 승인 또는 Shift+Tab으로 plan 모드 해제 후 코드 작성
커밋(Commit): 설명 메시지와 함께 커밋·PR 생성 요청

plan 모드는 오버헤드도 있으므로, 범위가 명확하고 수정이 작은 작업(오타 수정, 로그 한 줄 추가, 변수 이름 변경)은 직접 시키는 게 낫습니다. 한 문장으로 diff를 설명할 수 있다면 계획은 건너뛰세요.

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

Claude는 의도를 유추하지만 마음을 읽지는 못합니다. 특정 파일·제약·예시 패턴을 지목하세요.

작업 범위 지정: "foo.py에 로그아웃 상태 사용자 엣지 케이스를 다루는 테스트를 작성해. mocks는 피해."
소스 지목: "ExecutionFactory의 git 히스토리를 훑고 api가 어떻게 생겼는지 요약해."
기존 패턴 참조: "홈 페이지의 기존 위젯 구현 패턴(HotDogWidget.php 등)을 따라 새 달력 위젯을 만들되, 코드베이스에 이미 쓰는 라이브러리 외에는 쓰지 마."
증상 설명: "세션 타임아웃 후 로그인이 실패한다고 사용자가 보고합니다. src/auth/의 인증 흐름(특히 token refresh)을 확인하고, 재현하는 실패 테스트를 먼저 써."

풍부한 콘텐츠 제공: @로 파일 참조, 이미지 붙여넣기, 문서 URL 제공(/permissions로 자주 쓰는 도메인 허용), cat error.log | claude로 데이터 파이프, 필요한 내용을 Claude가 스스로 가져오게 지시.

환경 구성하기

효과적인 CLAUDE.md 작성: 빌드 명령·코드 스타일·워크플로우 규칙 포함. 구체적·간결하게. "이 줄을 지우면 Claude가 실수할까?"로 판단해 비대한 파일은 정리. ✅ 포함: Claude가 못 짐작하는 Bash 명령, 기본값과 다른 스타일 규칙, 테스트 지침, 저장소 에티켓, 프로젝트 아키텍처 결정, 환경 특이사항, 비직관적 동작 / ❌ 제외: 코드 읽으면 아는 것, 표준 관례, 상세 API 문서, 자주 변하는 정보. @path/to/import 문법으로 추가 파일 가져오기 가능.
권한 구성: 신뢰하는 도구를 /permissions로 사전 승인하고 /sandbox로 샌드박스 실행. Pro/Max/Team에서는 auto mode가 기본 시작 모드(분류 모델이 위험한 것만 차단). 수동 모드에서는 permission allowlists와 샌드박싱으로 중단을 줄임.
CLI 도구 사용: gh, aws, gcloud, sentry-cli 같은 CLI를 쓰라고 지시 (컨텍스트 효율 최고). 모르는 CLI는 'foo-cli-tool --help'로 배우게 시킬 수 있음.
MCP 서버 연결: claude mcp add --transport http notion https://mcp.notion.com/mcp처럼 연결.
훅 설정: 반드시 매번 일어나야 하는 행동은 훅으로 (결정적, 보장). "편집 후 eslint를 실행하는 훅을 작성해"처럼 Claude가 직접 쓸 수도 있음.
스킬 생성: .claude/skills/<name>/SKILL.md로 도메인 지식·재사용 워크플로우. disable-model-invocation: true로 부작용 워크플로우는 수동만 허용.
커스텀 서브에이전트: .claude/agents/에 자체 도구·모델을 가진 전담 어시스턴트 정의.
플러그인 설치: /plugin으로 마켓플레이스 탐색. 타입 언어면 code intelligence 플러그인 추천.

효과적으로 소통하기

코드베이스 질문: "로깅은 어떻게 동작하나요?", "새 API 엔드포인트는 어떻게 만들죠?", "foo.rs 134번 줄의 async move { ... }는 무엇을 하나요?" — 선임 엔지니어에게 묻듯 직접 질문.
Claude에게 인터뷰 시키기: 큰 기능은 AskUserQuestion 도구로 인터뷰하게 하고 SPEC.md에 명세 작성. 구현은 완전한 명세 후 새 세션에서 (깨끗한 컨텍스트). 유용한 스펙은 자족적여야 함: 관련 파일·인터페이스, 범위 외 항목, end-to-end 검증 단계 포함.

세션 관리하기

일찍·자주 코스 수정: Esc로 중단(컨텍스트 보존), Esc+Esc 또는 /rewind로 되감기 메뉴, "Undo that", /clear로 정리. 같은 문제로 두 번 이상 수정했다면 /clear 후 배운 것을 반영한 더 구체적 프롬프트로 시작.
컨텍스트 적극 관리: 작업 사이 /clear, /compact <지시어>(예: /compact Focus on the API changes)로 제어, /rewind에서 부분 요약, /btw로 컨텍스트에 남기지 않는 곁가지 질문.
조사엔 서브에이전트: "서브에이전트로 X를 조사해" — 별도 컨텍스트에서 탐색해 메인 대화를 깨끗하게 유지.
체크포인트로 되감기: 매 턴이 체크포인트를 만들고 파일을 자동 스냅샷. Esc 두 번 또는 /rewind. 주의: Bash나 외부 프로세스 변경은 추적 안 됨(git 대체 아님).
대화 재개: /rename으로 이름 짓고 브랜치처럼 취급. claude --continue 또는 claude --resume으로 이어가기.

자동화와 확장

비대화형 모드: CI·pre-commit·스크립트에서 claude -p "your prompt". --output-format json/stream-json로 파싱 가능한 출력:

claude -p "Explain what this project does"
claude -p "List all API endpoints" --output-format json
claude -p "Analyze this log file" --output-format stream-json --verbose

여러 세션 병렬 실행: worktrees(격리 git 체크아웃), 크로스 세션 메시징, 데스크톱 앱, 클라우드, agent view, agent teams. Writer/Reviewer 패턴(한 세션이 구현, 다른 세션이 리뷰)으로 품질 중심 워크플로우.
파일 간 팬아웃(Fan out): /batch <지시어>로 5~30개 서브에이전트에 분산(각자 워크트리에서 PR)하거나 claude -p 루프:

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

auto mode로 자율 실행: claude --permission-mode auto -p "fix all lint errors" — 분류 모델이 위험(스코프 확장·미지의 인프라·적대적 콘텐츠)만 차단.
적대적 리뷰 단계: 완료로 치기 전 새 컨텍스트의 서브에이전트가 diff를 리뷰. /code-review 스킬로 버그를, 직접 프롬프트로 계획 대조. 리뷰어는 correctness·명시된 요건에만 영향을 주는 gap만 지적하라고 지시(과잉 엔지니어링 방지).

흔한 실패 패턴 피하기

주방 싱크 세션 — 무관한 작업을 섞지 말고 /clear로 분리
반복 수정 — 두 번 실패 수정 후엔 /clear + 개선된 프롬프트
과도하게 지정된 CLAUDE.md — 너무 길면 절반 무시. 없어도 되는 규칙은 삭제하거나 훅으로 변환
신뢰-검증 격차 — 그럴듯해 보이는 구현이 엣지 케이스를 안 다룸. 항상 검증 제공
무한 탐색 — 범위 없는 "조사" 지시는 수백 파일을 읽음. 좁게 범위 지정하거나 서브에이전트 사용

직관 키우기

이 가이드의 패턴은 절대적이지 않습니다. 때로 컨텍스트를 쌓아 두는 게 맞고(깊은 문제), 때로 계획 없이 탐색적으로, 때로 모호한 프롬프트가 정답일 때가 있습니다. 잘 될 때·안 될 때의 프롬프트 구조·컨텍스트·모드를 관찰하고 이유를 되짚으며 자신만의 직관을 키우세요.

Claude Code 모범 사례