개요
Anthropic 내부 팀과 여러 엔지니어가 효과를 본 Claude Code 사용 패턴을 모은 공식 문서다. 거의 모든 권고는 **“컨텍스트 창은 빨리 차고, 찰수록 성능이 떨어진다”**는 한 가지 제약에서 나온다. 대화, 읽은 파일, 명령 출력이 모두 컨텍스트를 차지하므로, 컨텍스트를 가장 중요한 자원으로 관리해야 한다. 에이전트 루프 자체의 동작은 2026-04-04-how-claude-code-works 참고.
확인 시점
Telegram 저장일은 2026-06-14이지만, 문서는 계속 갱신된다. 본문은 2026-10-04에 가져온 버전이며 v2.1.283의 auto mode 기본값,
/goal,/btw, agent view 같은 최신 기능이 반영되어 있다.
1. 스스로 검증할 수단을 준다
가장 먼저 나오는 권고다. Claude는 일이 “끝난 것처럼 보이면” 멈춘다. 돌려 볼 검사가 없으면 사람이 검증 루프가 된다. 테스트, 빌드 종료 코드, 린터, 픽스처 diff, 디자인과 비교할 스크린샷처럼 통과/실패를 돌려주는 신호를 주면 Claude가 스스로 반복한다.
| 전략 | 나쁜 예 | 좋은 예 |
|---|---|---|
| 검증 기준 제시 | ”이메일 검증 함수 구현해” | 예시 케이스를 주고 “구현 후 테스트 실행해” |
| UI 시각 검증 | ”대시보드 예쁘게” | 스크린샷을 주고 “결과를 캡처해 원본과 비교, 차이 나열 후 수정” |
| 근본 원인 | ”빌드 실패해” | 에러를 붙이고 “근본 원인을 고쳐, 에러를 억누르지 말고” |
검증을 얼마나 강하게 걸지는 단계별로 고른다.
- 한 프롬프트 안: 검사하고 반복하라고 같은 메시지에서 지시한다.
- 세션 전체:
/goal조건으로 걸면 별도 평가자가 매 턴 다시 확인한다. - 결정적 게이트: Stop hook이 검사 스크립트를 돌려 통과할 때까지 턴 종료를 막는다.
- 제2의 의견: 검증 서브에이전트나 워크플로가 새 컨텍스트에서 결과를 반박해 본다.
“성공했다”는 주장 대신 테스트 출력, 실행한 명령, 스크린샷 같은 증거를 보여 달라고 한다.
2. 탐색 → 계획 → 구현 → 커밋
Plan mode(Shift+Tab 또는 --permission-mode plan)에서 코드를 읽고 계획을 세운다. Ctrl+G로 계획을 편집기에서 직접 고칠 수 있다. 그다음 구현하고 테스트하고 커밋·PR까지 간다. diff를 한 문장으로 설명할 수 있는 작은 수정이라면 계획은 건너뛴다.
3. 프롬프트에 구체적 맥락을 준다
범위(어떤 파일, 어떤 시나리오, 목 사용 여부), 답을 찾을 출처(git 히스토리 등), 따라 할 기존 패턴(예시 위젯 파일), 증상과 위치와 “고쳐진 상태”의 정의를 준다. @ 파일 참조, 이미지 붙여넣기, 파이프 입력을 쓴다. 탐색 단계에서는 오히려 모호한 질문이 쓸모 있을 때도 있다.
4. 환경 구성
- CLAUDE.md:
/init으로 시작해 짧게 유지한다. 줄마다 “이걸 지우면 Claude가 실수할까?”를 묻고 아니면 지운다. 길어지면 정작 중요한 규칙이 묻힌다.- 넣을 것: 추측할 수 없는 명령, 기본값과 다른 스타일, 테스트 방법, 저장소 관례, 프로젝트 고유의 아키텍처 결정, 함정
- 뺄 것: 코드만 읽어도 알 수 있는 것, 표준 관례, 자주 바뀌는 정보, 파일별 설명
- 가끔만 필요한 지식은 스킬로 옮긴다. 체크인된 CLAUDE.md는
/doctor로 줄일 곳을 제안받을 수 있다.
- 권한: v2.1.283 이상에서는 auto mode가 기본 시작 모드다. 분류 모델이 위험해 보이는 동작만 막는다. Manual 모드에서는
/permissions허용 목록과/sandbox로 승인 피로를 줄인다. - CLI 도구:
gh,aws,gcloud같은 CLI가 외부 서비스와 상호작용하는 가장 컨텍스트 효율적인 방법이다. - mcp 서버, 훅, 스킬, 서브에이전트, 플러그인: 훅은 권고에 그치는 CLAUDE.md와 달리 결정적으로 실행된다. 부작용이 있는 워크플로 스킬에는
disable-model-invocation: true를 건다.
5. 소통
- 시니어 엔지니어에게 하듯 코드베이스에 대해 질문한다. 온보딩에 효과적이다.
- 큰 기능은 Claude가
AskUserQuestion으로 사용자를 인터뷰하게 해 SPEC.md를 쓰게 한다. 구현은 깨끗한 새 세션에서 시작한다. 좋은 스펙은 관련 파일과 인터페이스, 범위 밖 항목, 끝에서 끝까지의 검증 단계를 명시한다.
6. 세션 관리
Esc로 중단하고Esc Esc나/rewind로 되돌린다. 같은 문제를 두 번 넘게 고쳐도 안 되면/clear후 더 나은 프롬프트로 다시 시작한다.- 관련 없는 작업 사이에는
/clear를 쓴다. 압축 방향은/compact <지시>로 정하고, 일부만 요약하려면 rewind 메뉴의 Summarize from/up to here를 쓴다. 컨텍스트에 남길 필요 없는 질문은/btw로 묻는다. - 조사는 서브에이전트에 맡겨 메인 컨텍스트를 깨끗하게 지킨다.
- 체크포인트는 Claude의 편집 도구로 바꾼 내용만 추적한다. Bash로 바꾼 것은 잡지 못하므로 git을 대신하지 못한다.
/rename으로 세션에 이름을 붙이고--continue,--resume으로 이어 간다.
7. 자동화와 확장
claude -p로 CI, pre-commit, 스크립트에 넣는다(--output-format json/stream-json).- 병렬 실행 수단은 worktree, 세션 간 메시징, 데스크톱 앱, 클라우드, agent view(
claude agents), 실험적 agent teams가 있다. Writer/Reviewer 패턴처럼 새 컨텍스트로 리뷰를 맡긴다. - 대량 마이그레이션은
/batch(530개 서브에이전트)나3개 파일로 먼저 시험한다.claude -p루프에--allowedTools와--permission-mode dontAsk를 조합해 처리한다. 2 - 끝내기 전에 적대적 리뷰를 넣는다.
/code-review나 PLAN.md 대비 diff 검토를 서브에이전트에 맡긴다. 다만 리뷰어는 늘 뭔가를 찾아내므로, 정확성과 요구사항에 영향을 주는 갭만 보고하게 해 과잉 설계를 막는다.
흔한 실패 패턴
| 패턴 | 처방 |
|---|---|
| 잡탕 세션 | 작업 사이 /clear |
| 반복 교정 | 두 번 실패하면 /clear 후 더 나은 첫 프롬프트 |
| 비대한 CLAUDE.md | 과감히 가지치기하거나 훅으로 전환 |
| 믿고 나서 검증 | 항상 검증 수단 제공. 검증할 수 없으면 배포하지 않는다 |
| 끝없는 탐색 | 조사 범위를 좁히거나 서브에이전트 사용 |
마지막으로, 이 패턴들은 출발점일 뿐이라고 강조한다. 맥락을 쌓아 두는 게 나을 때도, 계획 없이 탐색하는 게 나을 때도 있다. 무엇이 통했는지 관찰하며 감을 기르라는 것이 결론이다.
관련
- moc-claude-code
- 2026-05-20-claude-code-large-codebases-best-practices: 대형 코드베이스용 실전 팁
- 2026-07-11-chatgpt-prompting-overview-docs: OpenAI 쪽 공식 프롬프팅 가이드