TL;DR
- Anthropic 엔지니어들이 공개한 Claude Code 실전 사용법의 핵심은 단 하나: 컨텍스트 창이 가장 중요한 자원이며, 모든 패턴이 여기서 출발한다.
- 검증 수단(테스트·스크린샷) 제공, Explore→Plan→Implement→Commit 4단계 분리,
/clear·서브에이전트 활용이 성능 차이를 만드는 세 가지 핵심이다. - 병렬 세션, 비대화형 모드(
claude -p), Writer/Reviewer 패턴으로 단일 세션의 한계를 넘는다.
Claude Code는 챗봇이 아니다
Claude Code는 파일을 읽고, 명령을 실행하고, 코드를 수정하고, 문제를 자율적으로 해결하는 에이전트다. 질문에 답하고 기다리는 챗봇과 근본적으로 다르다.
그래서 사용법도 다르다. Anthropic 엔지니어들이 공개한 내부 사용 패턴은 이 차이에서 출발한다.
모든 패턴의 출발점: 컨텍스트 창
Anthropic이 공식 가이드에서 제일 먼저 강조하는 것은 기능이 아니라 제약이다.
> 컨텍스트 창이 가장 중요하게 관리해야 할 자원이다.
Claude의 컨텍스트 창에는 대화 전체, Claude가 읽은 모든 파일, 실행한 명령의 출력이 쌓인다. 디버깅 세션 하나가 수만 토큰을 소비한다. 그리고 컨텍스트가 가득 찰수록 성능이 떨어진다. 초기 지시를 “잊거나” 실수가 늘어난다.
이후 소개하는 모든 패턴은 이 제약에서 파생된다.
패턴 1: 검증 수단을 먼저 제공하라
Anthropic이 “단일 최고 레버리지”라고 부르는 것이 있다. Claude가 스스로 검증할 수 있게 하는 것이다.
테스트, 스크린샷, 예상 출력 중 하나라도 없으면 Claude는 “그럴듯해 보이지만 실제로 동작하지 않는” 결과를 낼 수 있다.
| 전략 | ❌ Before | ✅ After |
| 검증 기준 제공 | 이메일 검증 함수 구현해줘 |
validateEmail 함수 작성. 테스트 케이스: user@example.com → true, invalid → false. 구현 후 테스트 실행해줘 |
| UI 시각 검증 | 대시보드 더 보기 좋게 만들어줘 |
[스크린샷 첨부] 이 디자인으로 구현하고, 결과 스크린샷을 원본과 비교해서 차이점 수정해줘 |
| 근본 원인 수정 | 빌드가 실패해 |
이 에러로 빌드 실패: [에러 붙여넣기]. 수정 후 빌드 성공 확인. 에러를 억제하지 말고 근본 원인을 해결해줘 |
검증이 테스트 스위트, 린터, Bash 명령이어도 된다. 검증 수단에 투자하는 것이 후속 수정 시간을 줄인다.
패턴 2: Explore → Plan → Implement → Commit
Claude를 바로 코딩에 투입하면 잘못된 문제를 해결하는 코드가 나올 수 있다. Anthropic이 권장하는 4단계 워크플로우다.
1단계: Explore (플랜 모드)
claude (plan mode): "src/auth를 읽고 세션과 로그인 처리 방식을 파악해줘"2단계: Plan (플랜 모드)
claude (plan mode): "Google OAuth를 추가하려면 어떤 파일이 바뀌어야 해?
세션 흐름은? 구현 계획 만들어줘"
→ Ctrl+G: 플랜을 텍스트 에디터에서 직접 편집 가능
3단계: Implement (기본 모드)
claude: "플랜대로 OAuth 흐름 구현해줘. 콜백 핸들러 테스트 작성하고,
실패하면 수정해줘"
4단계: Commit
claude: "변경 내용을 설명적인 커밋 메시지로 커밋하고 PR 열어줘"
플랜 모드가 항상 필요한 건 아니다. 오타 수정, 로그 한 줄 추가처럼 명확한 소규모 작업은 바로 실행한다. 계획은 접근법이 불확실하거나, 여러 파일을 수정하거나, 코드베이스가 낯설 때 유효하다.
패턴 3: 구체적인 컨텍스트가 재작업을 줄인다
Claude는 의도를 추론할 수 있지만 마음을 읽지는 못한다.
| 전략 | ❌ Before | ✅ After |
| 작업 범위 지정 | foo.py에 테스트 추가해줘 |
foo.py에 로그아웃 상태 엣지 케이스 테스트 작성. mock 사용 금지 |
| 출처 지정 | ExecutionFactory API가 왜 이렇게 이상해? |
ExecutionFactory의 git 히스토리를 보고 API가 이렇게 된 경위를 요약해줘 |
| 기존 패턴 참조 | 캘린더 위젯 추가해줘 |
홈페이지 HotDogWidget.php 패턴을 참고해서 월 선택·년도 페이지네이션 캘린더 위젯 구현. 기존에 사용 중인 라이브러리만 써줘 |
| 증상 설명 | 로그인 버그 고쳐줘 |
세션 만료 후 로그인 실패 보고. src/auth/ 토큰 갱신 확인. 재현 실패 테스트 작성 후 수정해줘 |
@로 파일 직접 참조, 스크린샷 붙여넣기, cat error.log | claude로 데이터 파이프 — 설명 대신 실제 파일을 주면 컨텍스트가 정확해진다.
막연한 프롬프트가 유효한 경우도 있다. "이 파일에서 개선할 점이 뭐야?" 같은 개방형 질문은 미처 생각 못했던 문제를 발굴할 때 유용하다.
패턴 4: CLAUDE.md — 팀의 영구 컨텍스트
CLAUDE.md는 Claude가 매 세션 시작 시 자동으로 읽는 파일이다. /init 명령으로 프로젝트 구조 기반의 초안을 생성하고, 팀이 함께 다듬어간다.
포함할 것:
# CLAUDE.md# 코드 스타일
- ES 모듈(import/export) 사용, CommonJS(require) 금지
- 가능하면 destructure import 사용
# 워크플로우
- 코드 변경 완료 후 반드시 타입 체크
- 전체 테스트 스위트 대신 단일 테스트 실행 선호 (성능)
# 프로젝트 특이사항
- 내부 API 인증은 X-Service-Token 헤더 필수
- DB 마이그레이션은 migrations/ 디렉터리 외 절대 금지
| ✅ 포함 | ❌ 제외 |
| Claude가 추론할 수 없는 Bash 명령 | 코드를 읽으면 알 수 있는 것 |
| 기본값과 다른 코드 스타일 규칙 | Claude가 이미 아는 표준 관례 |
| 테스트 방법·선호 테스트 러너 | 자주 바뀌는 정보 |
| 브랜치 명명·PR 규칙 | 자명한 관행(“클린 코드 작성”) |
| 프로젝트 고유 아키텍처 결정 | 파일별 코드베이스 설명 |
중요한 경고: CLAUDE.md가 너무 길면 Claude가 절반을 무시한다. 각 줄마다 “이걸 제거하면 Claude가 실수할까?” 물어보고, 아니라면 삭제한다. Git에 커밋해 팀이 함께 관리하면 시간이 지날수록 가치가 복리로 쌓인다.
패턴 5: 서브에이전트로 컨텍스트를 보호하라
코드베이스 탐색은 컨텍스트를 빠르게 잠식한다. 수백 개 파일을 읽으면 메인 대화창이 가득 찬다.
서브에이전트는 별도 컨텍스트 창에서 실행되고 요약만 돌려준다.
# 탐색을 서브에이전트에 위임
"서브에이전트를 사용해서 우리 인증 시스템의 토큰 갱신 처리와
재사용 가능한 OAuth 유틸리티가 있는지 조사해줘"# 구현 후 검증도 서브에이전트로
"서브에이전트를 사용해서 이 코드의 엣지 케이스를 리뷰해줘"
프로젝트 전용 서브에이전트를 .claude/agents/에 정의해두면 재사용된다.
# .claude/agents/security-reviewer.md
name: security-reviewer
description: 보안 취약점 코드 리뷰
tools: Read, Grep, Glob, Bash
model: opus
시니어 보안 엔지니어로 다음을 검토:
- SQL/XSS/명령어 인젝션 취약점
- 인증·인가 결함
- 코드 내 시크릿 노출
- 안전하지 않은 데이터 처리
구체적인 라인 번호와 수정 방안 제시.
패턴 6: 세션 관리 — 빠르게 방향을 수정하라
Esc # 실행 중단 (컨텍스트 유지, 재지시 가능)
Esc + Esc # 체크포인트 메뉴 (대화·코드 이전 상태로 복원)
/clear # 관련 없는 작업 사이에 컨텍스트 초기화
/compact # 컨텍스트 압축 (핵심 정보만 유지)
/rewind # 특정 메시지부터 요약 또는 복원
/btw "질문" # 오버레이로 답변 (컨텍스트에 남지 않음)
같은 문제를 두 번 이상 수정했다면: 컨텍스트가 실패한 시도로 오염된 상태다. /clear 후 배운 점을 반영해 더 구체적인 프롬프트로 새 세션을 시작하는 것이 낫다.
카카오·토스 같은 팀 환경에서는 세션에 의미 있는 이름을 붙이는 것이 중요하다. claude --continue로 최근 세션을 재개하거나 claude --resume으로 목록에서 선택할 수 있다. oauth-migration, db-refactor 같은 이름으로 작업별 세션을 브랜치처럼 관리한다.
패턴 7: 병렬 세션과 비대화형 모드
단일 세션의 한계를 넘는 두 가지 방법이다.
Writer / Reviewer 패턴
세션 A (Writer) 세션 B (Reviewer)
─────────────────────────────────────────────────────
API 레이트 리미터 구현
@src/middleware/rateLimiter.ts
엣지 케이스, 레이스 컨디션,
기존 미들웨어 패턴 일관성 리뷰[세션 B 리뷰 반영하여 수정]
구현한 코드를 직접 리뷰하면 편향이 생긴다. 별도 세션은 방금 쓴 코드에 대한 편향 없이 독립적인 시각을 제공한다.
비대화형 모드 — CI/CD 통합
# 단일 쿼리
claude -p "이 프로젝트가 무엇을 하는지 설명해줘"# JSON 출력 (스크립트 파싱용)
claude -p "모든 API 엔드포인트 나열" --output-format json
# 대규모 마이그레이션 — 파일별 병렬 처리
for file in $(cat files.txt); do
claude -p "$file을 React에서 Vue로 마이그레이션. OK 또는 FAIL 반환" \
--allowedTools "Edit,Bash(git commit *)" &
done
# 자율 실행 (auto 모드 — 분류기가 위험 명령 차단)
claude --permission-mode auto -p "모든 lint 에러 수정"
Anthropic 내부 실태
Claude Code 창시자 Boris Chernyi의 발언이 공개됐다.
> “Anthropic 내부에서는 수동으로 작성된 코드가 문자 그대로 없다. Claude들이 Slack에서 서로 조율하고, 루프 안에서 코드를 짜고, 코드베이스 전반의 이슈를 해결한다.”
이 구조가 가능한 건 CLAUDE.md·서브에이전트·병렬 세션이 팀 규모에서도 동작하도록 설계돼 있어서다.
피해야 할 실패 패턴
| 패턴 | 증상 | 처방 |
| 주방 세트 세션 | 무관한 작업을 한 세션에서 처리 | 작업 사이마다 /clear |
| 반복 수정 | 같은 문제를 두 번 이상 수정 | /clear 후 더 나은 프롬프트로 재시작 |
| 과다 CLAUDE.md | Claude가 지시 절반을 무시 | 가차 없이 삭제, 필요하면 훅으로 전환 |
| 검증 없는 신뢰 | 그럴듯하지만 엣지 케이스 미처리 | 항상 테스트·스크립트·스크린샷으로 검증 |
| 무한 탐색 | 범위 없이 “조사해줘” → 파일 수백 개 읽음 | 탐색 범위 좁히거나 서브에이전트로 위임 |
결론: 에이전트를 에이전트처럼 써라
Claude Code를 “자동완성이 잘 되는 챗봇”으로 쓰면 잠재력의 10%를 쓰는 것이다. Anthropic 엔지니어들이 공개한 패턴의 공통점은 에이전트의 자율성을 믿되, 컨텍스트·검증·방향을 사람이 관리한다는 구조다.
컨텍스트 창을 의식하고, 검증 수단을 준비하고, 탐색과 구현을 분리하면 Claude Code는 단순 도구가 아니라 팀의 연장선으로 작동한다.
참고 자료