02-구조

02. 구조 — 4단계 사이클과 강제 메커니즘

4단계 사이클

       ┌──────────────────────────────────┐
       │ 1. 실패하는 테스트 작성            │
       └──────────────┬───────────────────┘
                      │
                      ▼
       ┌──────────────────────────────────┐
       │ 2. 모델이 최소 변경으로 통과 시도   │
       └──────────────┬───────────────────┘
                      │
                      ▼
       ┌──────────────────────────────────┐
       │ 3. 자동 검증 (lint·typecheck·test)  │
       └──────────────┬───────────────────┘
                      │ 실패
                      ▼
       ┌──────────────────────────────────┐
       │ 4. 에러를 컨텍스트에 넣고 재시도    │
       └──────────────────────────────────┘

이 사이클의 1, 4가 사람의 시간을 가장 많이 절약한다.

강제 메커니즘 (모델이 사이클을 지키게)

A. CLAUDE.md 가드레일

## TDD 규칙 (강제)
- 새 함수에는 vitest 단위 테스트를 먼저 작성한다.
- 모든 PR은 `pnpm test` 통과.
- 실패하는 테스트 없이 구현 코드를 commit하지 않는다.

B. PostToolUse hook

Edit|Write 매처로 매 편집 후 관련 테스트 자동 실행. 실패하면 모델에게 stderr로 에러 전달, exit 2로 다음 단계 차단.

C. Stop hook

응답 종료 시 한 번 더 전체 검증. (07장 run-tests.sh)

D. PreCommit hook (선택)

git pre-commit 훅과 통합 — 사람이 직접 커밋하든 에이전트가 하든 동일한 게이트.

컨텍스트 선택이 곧 정확도

에어비앤비의 두 번째 핵심:

“Rich context expansion: prompts grew to 40k–100k tokens, including related files, sibling test examples, the component source, and team-specific patterns.”
의역: “풍부한 컨텍스트 확장: 프롬프트가 40k~100k 토큰까지 자랐다 — 관련 파일, 형제 테스트 예시, 컴포넌트 소스, 팀 고유 패턴 포함.”

즉, 테스트 작성 또는 수정 단계에서는 인접 테스트 예시를 컨텍스트에 적극 포함한다. 모델은 “이 팀이 어떻게 테스트를 쓰는지” 한 두 개의 예시만으로 일관성을 유지한다.