Initial commit without large binary files.

Add workbook and starter project sources while excluding slide/document binaries to avoid oversized pushes.

Made-with: Cursor

.gitignore

+*.pptx
+*.pdf

README.md

+# Claude Code 마스터리 워크북 — 자료 모음
+
+이 저장소는 **Claude Code** 실습용 워크북과 **Starter** 프로젝트를 담습니다. 슬라이드를 암기하는 대신, 미션별 **행동·검증·의도적 실패**로 익힙니다.
+
+## 문서
+
+| 파일 | 대상 |
+|------|------|
+| [workbook-learner.md](workbook-learner.md) | 실습자 — Mission 1~5 절차·체크리스트 |
+| [workbook-instructor.md](workbook-instructor.md) | 강사 — 타이밍, 분기, 토큰·비용 가드 |
+| [cheat-sheet-one-pager.md](cheat-sheet-one-pager.md) | 공통 — 명령어·설정 템플릿 1장 |
+
+## Starter Repo
+
+실습은 [`starter/`](starter/) 디렉터리를 프로젝트 루트로 사용합니다.
+
+```bash
+cd starter
+# 필요 시 가상환경
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python -m todo_cli --help
+```
+
+자세한 미션 순서는 `starter/README.md`와 `workbook-learner.md`를 따릅니다.
+
+## 준비물
+
+- Node.js 18 이상 및 **Claude Code CLI** 설치
+- Claude Pro/Max 또는 Anthropic API 키(제품 정책에 맞게)
+- (Mission 3) GitHub MCP 사용 시 `GITHUB_PERSONAL_ACCESS_TOKEN` 등 [GitHub MCP 서버](https://github.com/modelcontextprotocol/servers) 문서 참고
+
+## 저비용 실습 팁
+
+긴 대화·멀티 에이전트는 토큰을 많이 씁니다. 제품 CLI에서 지원하는 경우 저비용 모델 플래그를 사용하고, `starter` 코드는 **500줄 이하**로 유지합니다.

cheat-sheet-one-pager.md

+# Claude Code 핵심 치트시트 (1장)
+
+> UI·CLI는 버전에 따라 다를 수 있음. 최종 동작은 **공식 Claude Code 문서**를 확인하세요.
+
+## 제품 구분 (혼동 방지)
+
+- **본 워크북 / Starter** = **Claude Code** (`claude` CLI, `CLAUDE.md`, Plan Mode, MCP, Hooks, `claude -p`).
+- **[anthropics/claude-cookbooks](https://github.com/anthropics/claude-cookbooks)** = 주로 **Claude API + Python/Jupyter** 레시피. **필수 실습 경로가 아님** — 개념 심화·숙제용.
+
+## 자주 쓰는 명령·기능
+
+| 동작 | 메모 |
+|------|------|
+| `/init` | 프로젝트 스캔 후 `CLAUDE.md` 초안 생성 |
+| `/compact` | 컨텍스트 압축. 예: `/compact Keep: 인증 아키텍처 결정, 미해결 순환참조 스택트레이스` |
+| Plan Mode | **계획 승인 후** 구현. IDE에서는 `Shift+Tab` 두 번(제품 기준) |
+| MCP 추가 | 예: `claude mcp add github -- npx -y @modelcontextprotocol/server-github` |
+| 헤드리스 | `claude -p "프롬프트"` — 파이프와 CI에 끼워 넣기 |
+
+## `.claude/settings.json` — PreToolUse 훅 스켈레톤
+
+필드 이름은 설치된 CLI/버전 문서에 맞게 조정하세요. 아래는 **예시 구조**입니다.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${workspaceFolder}/scripts/protect-files.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- `protect-files.sh`가 대상 파일(예: `.env`)에 대한 편집을 감지하면 **exit code 2**로 차단하도록 구현합니다.
+
+## `claude -p` 파이프 예시
+
+```bash
+cat sample-error.log | claude -p "이 로그의 원인을 한 줄로 요약해"
+```
+
+CI에서: 로그/테스트 출력을 파이프로 넘겨 짧은 요약·분류만 받아 **아티팩트**로 저장.
+
+## 저비용 모델 (예시)
+
+플래그 이름·모델 ID는 **현재 CLI 도움말** 기준. 예: 경량 모델 옵션이 있으면 실습 중 멀티 에이전트·긴 맥락 구간에만 제한 사용.
+
+## `/compact` Keep 패턴
+
+- `Keep: [아키텍처 결정 1문장] + [열려 있는 이슈] + [재현 커맨드]`
+- 압축 후 **같은 세션에서** `현재 프로젝트 상태를 요약해`로 보존 여부 확인.

starter/.claude/settings.json

+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/protect-files.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

starter/.env.example

+# 예시 — 실제 비밀 금지
+DATABASE_URL=postgresql://user:changeme@localhost:5432/todoapp

starter/.gitignore

+.venv/
+__pycache__/
+*.pyc
+.env
+.claude/settings.local.json

starter/CLAUDE.md

+# Claude Code — 프로젝트 헌법 (초안)
+
+이 파일은 `/init`으로 덮어쓰거나 보강할 수 있습니다. 워크북 Mission 1에서는 **규칙을 1~2줄 추가**해 보세요.
+
+## 프로젝트 요약
+
+- Python 패키지 `todo_cli`: 할 일 CLI.
+- 실습용 데이터: `data/todos.json`.
+
+## 작업 시 지침 (예시 — 학습자가 수정)
+
+- (여기에 본인 팀 규칙을 추가하세요.)

starter/README.md

+# Claude Code 워크북 — Starter Repo
+
+경량 파이썬 CLI 예제(실습 목표: **500줄 이하** 유지). 워크북: 상위 디렉터리의 [workbook-learner.md](../workbook-learner.md).
+
+## 빠른 시작
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+python -m todo_cli --help
+python -m todo_cli list
+```
+
+## 디렉터리 안내
+
+| 경로 | 용도 |
+|------|------|
+| `Spec.md` | Mission 2 — 인수 테스트·요구사항 |
+| `CLAUDE.md` | Mission 1 — `/init` 후 여기에 헌법 보강 |
+| `sample-error.log` | Mission 5 — `claude -p` 파이프용 |
+| `scripts/protect-files.sh` | Mission 5 — `.env` 등 편집 차단 |
+| `scripts/budget_api.py` | Mission 3 — PTC용 50명 스텁 데이터 |
+| `docs/ptc-exercise.md` | PTC 설명·도구 제약 메모 |
+| `.claude/settings.json` | Mission 5 — PreToolUse 훅 (환경에 맞게 수정) |
+
+## 미션 순서
+
+1. **M1**: `/init`, `CLAUDE.md` 편집, Plan Mode
+2. **M2**: `Spec.md` → IT1만 구현, `/compact`
+3. **M3**: GitHub MCP, `budget_api.py` + PTC 관찰
+4. **M4**: `todo_cli.py` 리뷰 프롬프트
+5. **M5**: 훅 차단 + `claude -p`
+
+## 보안
+
+- `.env`는 저장소에 커밋하지 않는다. 예시는 `.env.example` — 로컬 실습 시 복사해 `cp .env.example .env` 후 사용.
+- `protect-files.sh`는 실습용 — 프로덕션 정책은 별도 검토.
+
+## 저비용 실습
+
+멀티 에이전트·긴 맥락 구간은 비용이 큼. CLI에서 지원 시 경량 모델을 제한적으로 사용.

starter/Spec.md

+# To-Do CLI — 스펙 (워크북 Mission 2)
+
+## 목표
+
+터미널에서 할 일条目을 추가·목록·완료 처리할 수 있는 최소 CLI.
+
+## 요구사항
+
+- 데이터는 프로젝트 루트의 `data/todos.json` (JSON 배열)에 저장한다.
+
+## 예외·경계
+
+- 빈 문자열 추가는 거부하고 exit code 1과 메시지를 출력한다.
+
+## 인수 테스트
+
+| ID | 설명 | 검증 방법 |
+|----|------|-----------|
+| IT1 | `--help` 시 사용법과 하위 명령 요약이 출력된다 | `python -m todo_cli --help`에 `add`, `list` 문자열 포함 |
+| IT2 | `add "할 일"` 후 `list`에 동일 문자열이 보인다 | 수동 |
+| IT3 | 빈 문자열 add 시 비정상 종료 코드 1 | `python -m todo_cli add ""` → exit 1 |
+
+> Mission 2에서는 **IT1만** 구현하도록 지시한다.

starter/docs/ptc-exercise.md

+# Mission 3 — PTC(Programmatic Tool Calling) 체감용 메모
+
+## 시나리오
+
+50명의 직원에 대해 **예산 초과 여부**를 알고 싶다. 도구가 `employee_record(id)` 하나뿐이라면, **도구를 50번 호출**하면 지연·토큰·비용이 커진다.
+
+## 기대 패턴
+
+모델이 **코드 실행(또는 단일 스크립트)** 으로 `scripts/budget_api.py` 또는 `budget_api.all_summaries()`를 한 번에 호출한 뒤, **요약만** 답변으로 돌려주는 방식을 택하는지 관찰한다.
+
+로컬 확인:
+
+```bash
+cd starter
+python scripts/budget_api.py | head
+```
+
+## `allowed_callers` 메모
+
+일부 제품/도구 정의에서는 특정 호출자(예: `code_execution_20250825`)만이 대량 데이터 도구를 직접 반복 호출할 수 있게 제한한다. **정확한 키와 JSON 스키마는 사용 중인 Claude Code / MCP 문서**를 따른다. 강사가 제공하는 스니펫이 있으면 그대로 등록하고, 없으면 이 파일의 **관찰 포인트**만으로 실습해도 된다.
+
+## 과제 질문 예시
+
+> 「`starter/scripts/budget_api.py`의 데이터로 50명의 예산 초과 여부를 확인하고, 초과한 사람 수와 이름 최대 5명만 요약해 줘.」

starter/requirements.txt

+# Starter: 표준 라이브러리만 사용 (실습 단순화)
+# 필요 시 여기에 의존성 추가

starter/sample-error.log

+Traceback (most recent call last):
+  File "/app/todo_cli/cli.py", line 42, in add_item
+    store.append(normalize(text))
+  File "/app/todo_cli/store.py", line 18, in append
+    from app.db import session  # ImportError: cannot import name 'session' from partially initialized module 'app.db' (most likely due to a circular import)
+
+ImportError: cannot import name 'session' from partially initialized module 'app.db' (most likely due to a circular import)

starter/scripts/budget_api.py

+#!/usr/bin/env python3
+"""Mission 3 — 가상 예산 API 스텁. PTC 실습: 50명 일괄 조회는 루프 한 번으로 처리."""
+
+from __future__ import annotations
+
+# 직원 id 1..50: (이름, 지출, 한도)
+_STAFF: list[tuple[str, float, float]] = [
+    (f"emp_{i:02d}", float(800 + (i * 13) % 400), 1000.0 + (i % 5) * 50)
+    for i in range(1, 51)
+]
+
+
+def employee_record(employee_id: int) -> dict[str, float | str | bool]:
+    if not 1 <= employee_id <= len(_STAFF):
+        raise ValueError("employee_id out of range")
+    name, spent, limit = _STAFF[employee_id - 1]
+    over = spent > limit
+    return {
+        "id": employee_id,
+        "name": name,
+        "spent": spent,
+        "limit": limit,
+        "over_budget": over,
+    }
+
+
+def all_summaries() -> list[dict[str, float | str | bool]]:
+    return [employee_record(i) for i in range(1, 51)]
+
+
+if __name__ == "__main__":
+    import json
+
+    print(json.dumps(all_summaries(), indent=2))

starter/scripts/protect-files.sh

+#!/usr/bin/env bash
+# Mission 5 — 민감 파일 편집 차단 (실습용).
+# Claude Code PreToolUse 훅이 stdin으로 도구/파일 메타데이터(JSON 등)를 넘길 수 있다고 가정하고,
+# 그 내용에 .env 경로가 보이면 exit 2로 차단한다.
+
+set -euo pipefail
+
+payload="$(cat || true)"
+
+if echo "$payload" | grep -qiE '(\.env\b|"file_path"[[:space:]]*:[[:space:]]*"[^"]*\.env|/\.env"|\\\.env)'; then
+  echo "workbook hook: blocked edit/write targeting .env" >&2
+  exit 2
+fi
+
+exit 0

starter/todo_cli/__init__.py

+"""최소 To-Do CLI (워크북 Starter)."""
+
+__version__ = "0.1.0"

starter/todo_cli/__main__.py

+from todo_cli.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

starter/todo_cli/cli.py

+"""CLI 진입점."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+_DATA = Path(__file__).resolve().parent.parent / "data" / "todos.json"
+
+
+def _load() -> list[str]:
+    if not _DATA.exists():
+        return []
+    raw = _DATA.read_text(encoding="utf-8").strip()
+    if not raw:
+        return []
+    return json.loads(raw)
+
+
+def _save(items: list[str]) -> None:
+    _DATA.parent.mkdir(parents=True, exist_ok=True)
+    _DATA.write_text(json.dumps(items, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="todo_cli",
+        description="Minimal todo list CLI for Claude Code workbook.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("list", help="Show all todos")
+
+    p_add = sub.add_parser("add", help="Add a todo")
+    p_add.add_argument("text", help="Todo text")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "list":
+        for i, item in enumerate(_load(), start=1):
+            print(f"{i}. {item}")
+        return 0
+
+    if args.cmd == "add":
+        text = (args.text or "").strip()
+        if not text:
+            print("empty item rejected", file=sys.stderr)
+            return 1
+        items = _load()
+        items.append(text)
+        _save(items)
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

workbook-instructor.md

+# 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 매뉴얼** (치트시트와 동일 문구).

workbook-learner.md

+# 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시간 압축 분기를 따른다.
+
+수고했습니다.