개요

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개 서브에이전트)나 claude -p 루프에 --allowedTools와 --permission-mode dontAsk를 조합해 처리한다. 23개 파일로 먼저 시험한다.
  • 끝내기 전에 적대적 리뷰를 넣는다. /code-review나 PLAN.md 대비 diff 검토를 서브에이전트에 맡긴다. 다만 리뷰어는 늘 뭔가를 찾아내므로, 정확성과 요구사항에 영향을 주는 갭만 보고하게 해 과잉 설계를 막는다.

흔한 실패 패턴

패턴처방
잡탕 세션작업 사이 /clear
반복 교정두 번 실패하면 /clear 후 더 나은 첫 프롬프트
비대한 CLAUDE.md과감히 가지치기하거나 훅으로 전환
믿고 나서 검증항상 검증 수단 제공. 검증할 수 없으면 배포하지 않는다
끝없는 탐색조사 범위를 좁히거나 서브에이전트 사용

마지막으로, 이 패턴들은 출발점일 뿐이라고 강조한다. 맥락을 쌓아 두는 게 나을 때도, 계획 없이 탐색하는 게 나을 때도 있다. 무엇이 통했는지 관찰하며 감을 기르라는 것이 결론이다.

관련