# Claude Code Playbook

실전에서 검증된 Claude Code 활용 패턴 정리.

---

## Part 1: 핵심 워크플로우

### 1. CLAUDE.md에 투자하라

- 실수할 때마다 CLAUDE.md `## 실수 방지` 섹션에 추가
- PR 리뷰에서 `@.claude` 태그 → CLAUDE.md 자동 업데이트 (복리 엔지니어링)
- 프로젝트별 노트 디렉토리를 유지하고 CLAUDE.md에서 참조

### 2. Plan 모드부터 시작

- 대부분의 세션을 Plan 모드(Shift+Tab 두 번)로 시작
- 계획을 충분히 다듬은 후 Auto-accept 모드로 전환하여 구현
- 복잡한 작업은 반드시 Plan 모드 — 원샷 구현을 노린다
- 문제가 생기면 다시 Plan 모드로 전환

### 3. 슬래시 명령어로 반복 자동화

- 하루에 여러 번 반복하는 "내부 루프" 워크플로우마다 명령어 생성
- `.claude/commands/`에 저장, Git에 커밋
- 이 프로젝트의 명령어:
  - `/simplify` — 변경 코드 리뷰 및 단순화
  - `/verify` — 전체 검증 (docker, env, sql, 헬스체크)
  - `/status` — 프로젝트 상태 확인

### 4. 서브에이전트로 워크플로우 분담

- 요청에 "서브에이전트를 사용해"를 추가하면 분산 처리
- 메인 에이전트의 컨텍스트가 깨끗하게 유지됨
- 활용 패턴:
  - code-simplifier: 작업 후 코드 단순화
  - build-validator: 빌드 확인
  - code-architect: 아키텍처 설계

### 5. 검증 피드백 루프 (가장 중요)

> "Claude에게 작업을 검증할 방법을 주면 최종 결과물의 품질이 2-3배 올라간다."

- Claude가 모든 변경사항을 테스트하도록 한다
- `/verify` 명령어로 자동 검증
- UI 변경 시 스크린샷 기반 확인

---

## Part 2: 고급 패턴

### 6. 병렬 워크트리

- 3-5개 Git 워크트리를 동시에 띄우고, 각각 전용 Claude 세션
- 셸 별칭(za, zb, zc)으로 한 키로 이동
- 독립적인 기능/버그를 동시에 진행 가능

### 7. PostToolUse 훅으로 자동 포맷

- Claude가 생성한 코드를 자동 포맷팅
- CI에서 포맷팅 에러 발생 방지
- 나머지 10%를 훅이 처리

### 8. 안전한 명령어 사전 승인

- `--dangerously-skip-permissions`는 사용하지 않음
- `/permissions`로 안전한 Bash 명령어를 미리 허용
- `.claude/settings.json`에 체크인하여 공유

### 9. 도구 통합 (MCP)

- Slack 검색 및 메시지 전송
- CLI로 분석 쿼리 실행
- 에러 로그 조회
- `.mcp.json`에 체크인하여 공유

### 10. 프롬프팅 레벨업

- PR 제출 전 Claude에게 변경사항 리뷰 요청
- 수정 후: "지금까지 알게 된 모든 것을 바탕으로, 이걸 버리고 우아한 솔루션을 구현해."
- 모호함을 줄이는 상세한 스펙 작성

### 11. 터미널 & 환경

- `/statusline`으로 컨텍스트 사용량과 Git 브랜치 표시
- 음성 입력 (fn x 2, macOS)으로 상세한 프롬프트 작성

### 12. Claude로 학습하기

- `/config`에서 "Explanatory" 또는 "Learning" 출력 스타일 활성화
- 익숙하지 않은 코드를 설명하는 HTML 프레젠테이션 생성
- 프로토콜과 코드베이스의 ASCII 다이어그램 요청

---

## 이 프로젝트에 적용된 패턴

| 패턴 | 적용 방법 |
|------|----------|
| CLAUDE.md 투자 | 실수 발생 시 `## 실수 방지` 섹션에 누적 |
| 슬래시 명령어 | `/simplify`, `/verify`, `/status` |
| 검증 루프 | `/verify`로 docker, env, sql, 헬스체크 자동 검증 |
| 안전한 명령어 | DB 포트 localhost 바인딩, .env git 제외 |