# Claude Code 마스터리 워크북 — 학습자용

실습 루트: [`starter/`](starter/) 디렉터리. 각 미션은 **같은 6블록**으로 진행합니다.

---

## 사용법: 6블록 템플릿

1. **한 줄 목표** + **이 장이 끝나면 할 수 있는 것**
2. **준비물**
3. **예상 시간**
4. **단계(Step)** — 각 Step 끝 **Verify** 한 줄
5. **성공 기준(Checklist)**
6. **막혔을 때(Troubleshooting)**

---

## Mission 1 — 나의 첫 에이전트와 프로젝트 헌법 (`CLAUDE.md`, Plan Mode)

### 한 줄 목표

자동완성을 넘어 **에이전트 루프**와 **프로젝트 헌법**, **계획 모드**의 차이를 체감한다.

### 이 장이 끝나면 할 수 있는 것

- `/init`로 `CLAUDE.md` 초안을 만들고, 팀 규칙을 한두 줄 보강할 수 있다.
- Plan Mode에서 **승인 전** 과도한 코드 변경이 없음을 확인할 수 있다.

### 준비물

- Node.js 18+, Claude Code CLI, 계정/API 키
- [`starter/`](starter/) 클론 또는 복사본을 연 상태에서 `claude` 실행

### 예상 시간

25~40분

### 단계

**Step 1 — `/init`으로 헌법 기초**

1. 터미널에서 `starter/`로 이동한 뒤 Claude Code를 연다.
2. `/init` 입력. 에이전트가 프로젝트 구조를 스캔하며 `CLAUDE.md` 초안을 만드는 과정을 관찰한다.
3. **Verify:** 루트(또는 문서에 적힌 경로)에 `CLAUDE.md`가 생겼는지 확인한다.

**Step 2 — 나만의 코딩 규칙 주입**

1. `CLAUDE.md`를 연다.
2. 예: `변수명과 파일명에는 snake_case를 사용한다.` / `공개 함수에는 한 줄 docstring을 단다.` 처럼 **명시적 제약**을 1~2줄 추가한다.
3. **Verify:** 저장 후 파일에 규칙이 그대로 남아 있는지 확인한다.

**Step 3 — Plan Mode**

1. **Shift+Tab을 두 번** 눌러 Plan Mode로 진입한다(제품 UI가 다르면 치트시트·공식 안내 참고).
2. 다음 요청을 입력하기 **전에** Plan Mode인지 확인한다: *「간단한 To-Do 리스트 CLI를 파이썬으로 만들어줘」*.
3. 에이전트가 **즉시 대량 편집**하기보다 **아키텍처·구현 계획**을 먼저 제시하고 **승인(Approve)** 을 요구하는지 본다.
4. **Verify:** 승인 전에는 계획 중심 응답이고, 승인 후에만 본격 구현으로 넘어가는지 확인한다. (이미 `starter`에 `todo_cli`가 있으므로, 「기존 `todo_cli`에 항목 추가 명령만 넣는 계획」처럼 **범위를 줄여**도 된다.)

### 성공 기준(Checklist)

- [ ] `CLAUDE.md` 존재 + 본인이 추가한 규칙 1~2줄 포함
- [ ] Plan Mode에서 **계획 → 승인** 흐름을 눈으로 확인
- [ ] (선택) 승인 후에만 파일 편집이 진행됨

### 막혔을 때(Troubleshooting)

- **`/init`이 인식 안 됨:** Slash 명령이 막혀 있으면 설정·버전 확인.
- **Plan Mode 진입이 다름:** IDE/CLI 버전별 단축키는 공식 문서 우선.

### 심화 읽기 (선택)

- [anthropics/claude-cookbooks](https://github.com/anthropics/claude-cookbooks) — **API·노트북** 트랙. Claude Code 실습과 **동일 제품이 아님**.

---

## Mission 2 — 스펙 주도 개발과 `/compact`

### 한 줄 목표

긴 채팅 대신 **`Spec.md`로 범위를 고정**하고, 맥락이 길어졌을 때 **`/compact` + Keep**으로 중요 정보를 남긴다.

### 이 장이 끝나면 할 수 있는 것

- 인수 테스트 번호 단위로 구현 범위를 지시할 수 있다.
- `/compact` 후에도 **보존 지침에 넣은 키워드**가 요약에 남는지 검증할 수 있다.

### 준비물

- Mission 1과 동일
- `starter/Spec.md` 템플릿(필요 시 채움)

### 예상 시간

35~50분 (의도적으로 대화를 길게 하면 더 늘어남)

### 단계

**Step 1 — Spec.md 기반 지시**

1. `starter/Spec.md`를 연다. 요구사항·예외·**인수 테스트** 번호를 채우거나 강사가 준 예시를 붙여넣는다.
2. 채팅에 길게 적지 않고, 파일을 저장한 뒤 에이전트에게 예를 들어 말한다: *「이 Spec.md의 인수 테스트 1번만 구현해」*.
3. **Verify:** 코드/테스트 변경이 **테스트 1번 범위**에 머무는지 확인한다.

**Step 2 — 토큰 60% 근처 + `/compact`**

1. 여러 번 수정·에러 로그를 붙여 **상태 표시줄 토큰 게이지가 대략 60%**에 가깝도록 한다(과금·한도에 주의).
2. 다음과 같이 **Keep** 문구를 넣어 압축한다:

   ```text
   /compact Keep: 방금 작성한 인증 로직의 아키텍처 결정 사항과 아직 해결되지 않은 순환 참조 에러 로그
   ```

   (실제 프로젝트에 맞게 한 줄로 바꿔도 됨. 핵심은 **특정 키워드**를 Keep에 넣는 것.)

3. 압축 직후 질문: *「현재 프로젝트 상태를 요약해 봐」*.
4. **Verify (의도적 성공 기준):** 답변에 Keep에 넣은 **아키텍처 결정**·**순환 참조**(또는 대체 키워드)가 **그대로 또는 의미상 유지**되는지 확인한다. 사라지면 Keep 문구를 더 구체적으로 조정해 재시도.

### 성공 기준(Checklist)

- [ ] `Spec.md` 기반으로 **인수 테스트 1번만** 구현 지시 완료
- [ ] `/compact Keep: ...` 실행 후 **요약 질문**으로 중요 정보 잔존 확인
- [ ] (의도적 학습) 토큰 게이지와 비용 한도를 인지했음

### 막혔을 때(Troubleshooting)

- **압축 후 정보 유실:** Keep에 파일명·에러 한 줄·결정 문장을 **직접 인용** 형태로 넣는다.
- **비용 부담:** 멀티턴을 줄이고, 저비용 모델·새 세션 옵션을 검토한다.

### 심화 읽기 (선택)

- Cookbooks의 요약·분류 패턴은 **개념**만 참고. 실행 환경은 API·노트북.

---

## Mission 3 — 터미널 밖으로 (MCP + PTC)

### 한 줄 목표

**MCP**로 외부(GitHub 등)와 연결하고, **PTC**로 대량 도구 호출 대신 **루프 실행 + 요약**을 쓰는 이유를 본다.

### 이 장이 끝나면 할 수 있는 것

- GitHub MCP를 등록하고 이슈 요약을 **에이전트 대화 안에서** 받아본다.
- 50건 같은 반복 조회를 **50번 도구 핑퐁이 아닌** 배치/루프로 처리하는 흐름을 관찰한다.

### 준비물

- GitHub MCP: PAT 등 [서버 문서](https://github.com/modelcontextprotocol/servers/tree/main/src/github) 필요 여부 확인
- `starter/docs/ptc-exercise.md` 참고

### 예상 시간

40~55분

### 단계

**Step 1 — GitHub MCP**

1. 터미널 예시(제품 문서와 버전을 맞출 것):

   ```bash
   claude mcp add github -- npx -y @modelcontextprotocol/server-github
   ```

2. 환경 변수로 토큰 설정(문서 따름).

3. 에이전트에게: *「내 저장소의 최근 열린 이슈 3개를 읽고 요약해 줘」* (본인 저장소·권한에 맞게 수정).

4. **Verify:** 요약에 **이슈 번호·제목** 등 외부 근거가 드러나는지 확인한다.

**Step 2 — PTC 체감**

1. `starter/docs/ptc-exercise.md`를 연다. 스텁 API·`allowed_callers` 메모를 읽는다.
2. 에이전트에게: *「50명의 직원 예산 초과 여부를 확인해 줘」* (데이터는 `starter/scripts/budget_api.py` 또는 문서의 경로 사용).
3. **관찰:** 에이전트가 **도구를 50번** 부르기보다, **스크립트/루프로 일괄 처리 후 짧은 요약**을 제시하는지 본다.
4. **Verify:** 최종 답이 **전체 로그가 아닌 요약**(예: 초과 인원 수·이름 목록 일부) 위주인지 확인한다.

### 성공 기준(Checklist)

- [ ] MCP 등록 후 GitHub(또는 대체) **외부 데이터**가 대화에 반영됨
- [ ] PTC 연습에서 **배치 처리 vs 반복 도구 호출** 차이를 메모했음

### 막혔을 때(Troubleshooting)

- **MCP 인증 실패:** PAT 스코프, `HTTPS_PROXY`, `npx` 캐시 확인.
- **GitHub 없음:** 강사 제공 public 저장소 이슈 URL로 범위 축소.

---

## Mission 4 — 적대적 QA와 다중 에이전트

### 한 줄 목표

자기 리뷰 편향을 줄이기 위해 **비판자(Critic)** / **수정자(Fixer)** / **Fresh-context** 루프를 쓴다.

### 이 장이 끝나면 할 수 있는 것

- 같은 코드에 대해 「스스로 리뷰」와 「역할 분리 리뷰」출력 차이를 비교한다.
- 맥락 없는 에이전트에게 **코드만** 주고 취약점을 묻는다.

### 준비물

- Mission 1~3과 동일. **토큰 많이 씀** — 짧은 파일 하나로 고정 권장 (`starter/src/todo_cli.py` 등).

### 예상 시간

45~60분

### 단계

**Step 1 — 자기 평가 vs 역할 분리**

1. 최근 작성/수정한 코드 파일 하나를 고른다.
2. 지시: *「이 코드를 스스로 리뷰해 봐」*. 출력을 메모.
3. 지시를 바꾼다: *「독립된 비판자(Critic) 에이전트를 가정해. 읽기 권한만 있고 공격적으로 비판해. 그 다음 수정자(Fixer)가 그 피드백으로 패치를 제안해」*.
4. **Verify:** 두 출력의 **비판 깊이·구체성**이 다른지 확인한다.

**Step 2 — Fresh-context critique**

1. 지시: *「지금까지의 대화를 볼 수 없는 새 에이전트라고 가정하고, 아래 파일만 보고 취약점 3가지를 말해」* + 코드 붙여넣기 또는 파일 경로.
2. **Verify:** 취약점이 **이전 대화의 요약에만 의존**하지 않고, **코드 인용/줄 근거**가 있는지 확인한다.

### 성공 기준(Checklist)

- [ ] 자기 리뷰 vs Critic/Fixer 프롬프트 **출력 차이** 메모
- [ ] Fresh-context 지시에서 **근거 3건** 확보

### 막혔을 때(Troubleshooting)

- **비판이 여전히 뻔함:** Critic 프롬프트에 *「동의하지 말 것. TODO/에러 처리/경계조건을 집어낼 것」* 추가.
- **비용:** 한 파일·한 함수로 축소.

---

## Mission 5 — Hooks와 Headless (`claude -p`)

### 한 줄 목표

**PreToolUse 훅**으로 민감 파일 편집을 막고, **`claude -p`**로 CI에 끼워 넣는다.

### 이 장이 끝나면 할 수 있는 것

- `.env` 수정 시도가 **exit code 2**로 차단되는 것을 본다.
- 로그를 파이프로 넘겨 **한 줄 요약**을 받는다.

### 준비물

- `starter/scripts/protect-files.sh` 실행 권한: `chmod +x scripts/protect-files.sh`
- `starter/.claude/settings.json`을 [치트시트](cheat-sheet-one-pager.md)에 맞게 조정(경로 일치)

### 예상 시간

30~45분

### 단계

**Step 1 — 민감 파일 훅**

1. `starter/.claude/settings.json`에서 훅이 `protect-files.sh`를 호출하는지 확인한다.
2. 에이전트에게 **의도적으로 실패할 요청**을 한다: *「`.env` 파일의 DB 비밀번호를 admin123으로 바꿔줘」*.
3. **Verify (의도적 실패 = Pass):** 훅이 **차단(예: exit code 2)** 하고, 에이전트가 그 사실을 **인지**하는지 확인한다. 차단 없이 수정되면 `settings.json` 경로·matcher·스크립트를 점검한다.

**Step 2 — `claude -p` 파이프**

1. 실행 예:

   ```bash
   cd starter
   cat sample-error.log | claude -p "이 에러 로그의 원인을 한 줄로 요약해"
   ```

2. **Verify:** 대화형 없이 **한 줄(또는 짧은 문단)** 출력이 나온다.

### 성공 기준(Checklist)

- [ ] `.env` 수정 시도가 훅으로 **차단**됨 (**❌가 떠야 Pass**)
- [ ] `sample-error.log` 파이프 + `claude -p` 동작 확인

### 막혔을 때(Troubleshooting)

- **훅 미작동:** JSON 스키마가 CLI 버전과 맞는지, `workspaceFolder` 치환 지원 여부 확인. 필요 시 절대 경로 사용.
- **Windows:** WSL 또는 Git Bash에서 `bash scripts/protect-files.sh` 검증.

---

## 전체 진행 순서

Mission 1 → 2 → 3 → 4 → 5 권장. 시간이 짧으면 강사 안내에 따라 3시간 압축 분기를 따른다.

수고했습니다.