내 Claude Code 플레이북 — 설계・매뉴얼・팁
이 글은 내가 Claude Code를 어떻게 설계해서 쓰는지를 한곳에 모으는 살아있는 문서다. 한 번에 끝낼 가이드라기보다, 새로운 설계나 팁을 발견할 때마다 계속 덧붙여 나가는 개인 플레이북에 가깝다.
지금 정리된 첫 번째 주제는 CLAUDE.md와 docs/agent의 분리 구조다. 작업 매뉴얼이 늘어나면서 가장 먼저 부딪힌 문제와 그 해법이라, 이 글의 시작점으로 잡았다.
1. CLAUDE.md는 라우터, docs/agent는 매뉴얼
Claude Code로 작업하다 보면 CLAUDE.md 가 빠르게 비대해진다. 코드 리뷰 규칙, 테스트 작성 가이드, 배포 절차, 데이터베이스 마이그레이션 주의사항… 모든 걸 한 파일에 넣다 보면 어느 순간 컨텍스트 윈도우를 잡아먹는 거대한 매뉴얼이 된다.
해결은 단순하다. CLAUDE.md 는 라우터로 두고, 실제 매뉴얼은 docs/agent/ 디렉토리에 분리하는 것이다.
전체 구조
code-review.md
...
...
CLAUDE.md 는 매번 컨텍스트에 자동으로 로드되지만, docs/agent/ 아래 문서들은 필요한 상황에만 읽힌다. 평상시에는 라우팅 규칙만 메모리에 있고, 실제 상세 매뉴얼은 그 순간 호출된 것만 들어온다.
왜 분리하는가
한 파일에 다 적었을 때의 문제는 세 가지다.
분리하면 각 매뉴얼은 그 작업에 진짜 필요한 규칙들로만 채워진 작고 응집된 문서가 된다.
CLAUDE.md — 라우터로서의 역할
CLAUDE.md 에는 매뉴얼 자체가 아니라 "어떤 상황에 어떤 문서를 읽어라" 만 적는다. 예시는 이렇다.
## docs/agent 문서 사용 가이드
작업 상황에 따라 아래 문서를 먼저 읽고 규칙을 따른다.
- **코드 리뷰 / PR 검토 / 변경사항 점검** 요청을 받으면
→ `docs/agent/code-review.md` 를 먼저 읽는다.
- (앞으로 추가될 문서들도 동일한 패턴으로 등록)
이 한 블록이 핵심이다. Claude는 매 요청 시작 시 CLAUDE.md 를 통해 "이 요청에 해당하는 매뉴얼이 있는가?" 를 판단하고, 있으면 그 파일을 읽어들인 뒤 작업을 시작한다.
docs/agent/code-review.md — 첫 번째 매뉴얼
코드 리뷰는 가장 자주 반복되는 작업이라 첫 매뉴얼로 적합하다. 다루는 항목은 세 가지다.
- 범위 설정 —
origin/masterrebase 후 master 기준 diff만 본다 - 설계 원칙 — 가능한 한 간결하게, 재사용성 높게, 더 나은 설계가 있으면 적용
- 테스트 — pure function 단위로 쪼개고, 테스트를 작성하고, 전부 실행하고, 버그는 즉시 수정
실제 문서 전문은 별도 페이지로 호스팅한다 → docs/agent/code-review
이 문서가 코드 리뷰 요청이 들어왔을 때만 로드되기 때문에, 평소 일반 코딩 작업에는 영향을 주지 않는다. 그리고 리뷰가 시작되면 모델은 이 짧고 명확한 매뉴얼에 집중할 수 있다.
요청이 처리되는 흐름
내가 매번 "rebase부터 해", "pure function인지 확인해", "테스트 돌려봐" 라고 적을 필요가 없다. 한 줄짜리 요청에 docs/agent/code-review.md 가 정의한 4단계 절차가 자동으로 따라온다.
새 매뉴얼을 추가하는 패턴
앞으로 매뉴얼이 늘어날 텐데, 추가 방식은 항상 같다.
docs/agent/<작업명>.md파일 생성- 그 작업에 필요한 규칙만 응집해서 작성
CLAUDE.md의 라우팅 가이드에 한 줄 추가
후보들을 미리 적어두면 좋다.
| 파일명 | 트리거 | 내용 |
|---|---|---|
code-review.md | 코드 리뷰 / PR 검토 | 본문 참고 ✅ |
bug-fix.md | 버그 수정 | 재현 → 원인 → 최소 수정 → 회귀 테스트 |
refactor.md | 리팩토링 | 동작 보존 검증, 작은 커밋 단위 |
feature-add.md | 새 기능 추가 | 인터페이스 설계 → pure function 분리 → 테스트 |
매뉴얼이 늘어나도 CLAUDE.md 는 한 줄씩만 길어진다. 컨텍스트 부담은 라우팅 규칙 분량만큼만 늘어나고, 실제 매뉴얼 본문은 호출된 것만 로드된다.
1번 주제 정리
CLAUDE.md는 작업 매뉴얼이 아니라 매뉴얼 인덱스다. "무엇을 하라" 가 아니라 "어떤 문서를 읽으라" 를 적는다.docs/agent/<작업>.md는 그 작업의 SOP(표준 작업 절차)다. 짧고 응집되어 있고, 호출되었을 때만 로드된다.
코드를 모듈로 쪼개는 것과 같은 원리다. 한 파일에 다 욱여넣지 않고, 책임이 분명한 작은 문서들로 나누면 매뉴얼도 코드처럼 유지보수할 수 있게 된다.
앞으로 추가될 주제들
이 플레이북은 새로운 설계나 팁이 쌓일 때마다 항목을 더해나간다. 다음으로 정리할 후보들.
- 2. 슬래시 커맨드 설계 — 어떤 반복 작업을 커맨드로 박제할지 판단 기준
- 3. 에이전트 분리 전략 — sonnet vs haiku, 언제 별도 에이전트로 분리하는가
- 4. MCP 서버 활용 패턴 — 외부 시스템을 어디까지 끌어들일지
- 5. 자동 메모리 운용 — 무엇을 기억시키고 무엇을 기억시키지 말 것인가
- 6. 컨텍스트 다이어트 — 토큰을 의식한 프로젝트 문서 구조
각 항목은 충분히 익은 시점에 본문에 합류한다.