# Claude Code 마스터리 워크북 — 강사용

학습자 문서: [workbook-learner.md](workbook-learner.md). 본 문서는 **타이밍**, **분기**, **리스크**, **데모 순서**만 담습니다.

---

## 코스 길이 분기

| 형태 | 권장 | 조정 |
|------|------|------|
| 전일 / 반일 | M1~M3 오전, M4~M5 오후 | GitHub MCP는 반드시, PTC는 라이브 |
| 3시간 압축 | **M1·M2 필수** | M3는 GitHub MCP만; **PTC는 강사 데모 영상** 또는 10분 라이브로 대체 |
| 기업 내부 (GitHub 제한) | M3-1 대체 | public 예제 저장소 + 읽기 전용 PAT, 또는 Issues 없이 “MCP 연결 확인”만 |

---

## 비용·토큰 가드 (반드시 시작 시 언급)

- **Mission 2**: `/compact` 실습을 위해 맥락을 부풀리면 비용이 급증. **60% 전후**에서 멈출 것, **과금 한도** 안내.
- **Mission 4**: Critic/Fixer·Fresh-context는 **턴 수 2배**. 파일 **하나(예: `todo_cli.py` ~80줄)** 로 고정하라.
- 저비용 모델: CLI가 지원하면 **긴 미션에만** 제한 적용하라고 안내(정확한 플래그는 제품 릴리스 노트에 따름).
- 실습 후 **새 세션**으로 리셋해도 된다고 말해 줌.

---

## 미션별 권장 시간·포인트

### Mission 1 (25~40분)

- `/init` 직후 **너무 긴 CLAUDE.md**가 나오면 학습자에게 “2줄만 추가”로 단순화.
- Plan Mode: **승인 전 편집 금지**가 핵심 메시지. 제품이 약간 다르게 동작하면 “계획 먼저”만 강조.

### Mission 2 (35~50분)

- **인수 테스트 1번만**: `Spec.md`에 이미 IT1을 “도움말 출력” 등 아주 작게 적어 두면 수업이 안정적.
- `/compact Keep`은 **미리 정한 키워드**(예: `Circular import in app/db.py line 12`)를 쓰게 하면 Verify가 쉬움.

### Mission 3 (40~55분)

- **GitHub MCP**: PAT는 사전 배포 또는 수업 전 10분에 발급. **classic PAT vs fine-grained** 혼란 대비 1슬라이드.
- **PTC**: 학습자가 50번 도구 호출을 보지 못하면, 강사가 로그/설명으로 “만약 매번 도구였다면…” 보완.

### Mission 4 (45~60분)

- “스스로 리뷰”가 빈약하면 정상 — 그 차이를 **판교육 포인트**로 삼음.
- Fresh-context: 대화 말고 **파일 첨부/경로**만 주도록 프롬프트를 통일.

### Mission 5 (30~45분)

- **차단이 성공**: ❌가 떠야 Pass임을 학습자에게 미리 말함(의도적 실패).
- `settings.json`의 `matcher`·`command` 경로가 틀리면 가장 흔한 실패 — 수업 전 `starter`에서 **dry-run** 할 것.
- Windows만 쓰는 반은 WSL 안내.

---

## 흔한 오류 → 조치

| 증상 | 조치 |
|------|------|
| MCP `npx` 타임아웃 | 캐시, 방화벽, `NODE_EXTRA_CA_CERTS` |
| 훅이 안 막음 | 편집 도구 이름이 matcher와 불일치; 스크립트에 실행 권한 |
| `claude -p` 대화형으로 빠짐 | CLI 버전·플래그 문서 확인 |

---

## debrief 질문 (선택)

1. Plan Mode 없이 같은 요청을 했을 때 무엇이 달라졌나?
2. `/compact` Keep 없이 압축했을 때 어떤 정보가 사라졌나?
3. MCP 없이 동일 작업을 하려면 어떤 수동 단계가 필요했나?
4. 훅 없이 `.env`를 LLM에게 맡기면 어떤 리스크가 있나?

---

## 보조 자료: [anthropics/claude-cookbooks](https://github.com/anthropics/claude-cookbooks)

- **용도**: 수료 후 **선택 심화** — `tool_use`, `patterns/agents` 등 **API·노트북** 환경.
- **강사 브릿지**: M3 직전 “도구 스키마 개념”, M4 직전 “서브에이전트 아이디어” 정도만 언급. **필수 경로에 넣지 말 것.**
- 한 줄 고정: **Cookbooks ≠ Claude Code CLI 매뉴얼** (치트시트와 동일 문구).