📑 이 챕터에서 다룰 내용
새 7장에서 Phase 분리를 마쳤고, PLAN.md v2.1이 손에 있습니다. 이제 BUILD 시작 전 최후의 관문 — REVIEW.md입니다.
REVIEW.md는 "BUILD 진입 준비가 됐는가"의 자기 검증 자리입니다. SPEC.md는 외부 검토(Gemini 1차) + 두 검토자(단계 ⑤)를 받았지만, 외부 검토가 잡지 못하는 영역이 있습니다 — SPEC↔PLAN 정합성, 시간 산식 현실성, 롤백 전략 가능성. 이게 REVIEW의 영역입니다.
이 장은 v1.0 6장(REVIEW.md + READY 판정)의 보강 버전입니다. 핵심 추가 사항은 다음과 같습니다.
v1.0 10개 항목 + 게이트 / 리스크 / E3 추가 항목
v1.0의 YES/NO 이진 판정에서 진화했습니다
12건 발견 패턴 (Claude만 4 + Gemini만 6 + 둘 다 2) 데이터 입증
줍줍·TSV 두 사례로 실제 처리 과정을 봅니다
| 📚 사전 지식 체크 | 🎯 이 장의 목적 | ✅ 완료 후 결과물 |
|---|---|---|
| SPEC.md v4 + PLAN.md v2.1 완성 | REVIEW.md를 10가지 체크 + 3단계 판정으로 완성 + READY: YES 받기 + E3 두 검토자 사각지대 패턴 적용 | REVIEW.md (FAIL 0 + WITH-CONDITIONS ≤ 3) + READY: YES + git commit |
5파일 중 REVIEW.md를 완성하는 단계입니다.
| SPEC.md (새 5장) | PLAN.md (새 6장) | REVIEW.md ◀ 지금 여기 | BUILD.md (새 9장) | CLAUDE.md (새 11장) |
|---|---|---|---|---|
| 완성 | 완성 | 작성 중 | 미작성 | 미작성 |
소프트웨어 공학자 배리 봄이 IBM 프로젝트 데이터를 분석해 측정한 결과입니다.
- 요구사항(Spec) 단계 결함 발견·수정 비용 = 1
- 설계 단계 = 6배
- 코딩 중 = 10배
- 테스트 중 = 15배
- 출시 후 = 100배
REVIEW는 코딩 전(6배 단계)에서 결함을 잡습니다. BUILD 시작 후 방향이 틀렸다는 것을 알면 이미 만든 코드를 모두 버려야 합니다.
REVIEW 30분이 BUILD 후 50시간 재작업을 막습니다.
조종사가 아무리 경험이 많아도 이륙 전 체크리스트를 생략하지 않습니다. 항공기 사고의 70%는 이 절차를 건너뛸 때 발생합니다. 체크리스트는 "나를 믿지 못해서"가 아니라 "인간은 잊어버리기 때문에" 만들어진 것입니다.
REVIEW의 10가지 항목은 Claude Code 개발의 이륙 전 체크리스트예요. 30분의 확인이 50시간의 재작업을 막습니다.
| 도구 | 매핑 |
|---|---|
| GSD | {N}-VERIFICATION.md (자동 검증) + {N}-UAT.md (수동 검증) + /gsd-verify-work |
| Spec-Kit | /speckit.analyze (cross-artifact 일관성) + /speckit.checklist |
| OpenSpec | proposal-implementation gap 추적 |
| BMAD | Quinn(QA)의 test strategy 검증 |
자세한 매핑은 새 1장 1.7 표 또는 부록 H를 참조하세요.
REVIEW.md는 SPEC.md + PLAN.md 두 파일을 모두 읽은 후 작성합니다. Claude Code에 두 파일을 참조하게 하고 15가지를 점검해달라고 요청합니다.
STEP 1 — 두 파일 기반 REVIEW.md 작성 요청
/model claude-opus-4-6 # REVIEW도 Opus 사용 SPEC.md와 PLAN.md를 읽고 REVIEW.md를 작성해줘. 아래 10가지 항목을 각각 PASS / WITH-CONDITIONS / FAIL 로 판정하고 이유를 써줘: [기본 10가지] 1. Phase 1에 수익화 경로가 1개 이상 있다 (또는 의도적 무수익 명시) 2. Phase 1만으로 실제 배포·공개가 가능하다 3. 모든 DB 테이블에 RLS 설정 계획이 있다 4. API 비밀 키가 프론트엔드 코드에 노출될 구조가 없다 5. 기술 스택이 일관된다 (혼용 없음) 6. DB 설계에 N+1 쿼리 위험이 없다 7. Phase 1 변경 파일이 10개 이하다 8. 외부 서비스 연동 위치가 명확하다 (Edge Function 등) 9. 에러 처리 계획이 있다 10. 배포 환경변수 분리 계획이 있다 [1탄 v2 추가 — 게이트 + 리스크] 11. 각 Phase에 측정 가능 게이트가 있다 12. 리스크 등록부가 R1~RN 영향·확률·완화·트리거 모두 갖춤 13. R4 (1인 번아웃) 가 등록부에 포함됐다 — E2 [1탄 v2 추가 — E3 두 검토자] 14. SPEC v4가 두 검토자 (Claude 시뮬 + Gemini) 검토를 받았다 15. 두 검토자 발견 12건이 SPEC v4에 모두 반영됐다 마지막에 종합 판정: - FAIL 0건 + WITH-CONDITIONS ≤ 3건 → READY: YES - 그 외 → READY: NO + WITH-CONDITIONS 항목 패치 후 재검토
총 15가지 항목입니다. v1.0 10개에 5개(★ 11~15)가 추가됐습니다.
STEP 2 — 결과 확인
cat REVIEW.md # 15가지 항목 모두 판정됐는지 확인 # WITH-CONDITIONS 항목별 조건이 명확한지 확인 # 종합 판정 (READY: YES/NO) 확인
v1.0의 "YES/NO 이진 판정"에서 v2는 3단계 판정으로 진화했습니다.
이진 판정(YES/NO)의 한계: "95% 충족됐는데 한 작은 항목이 빠졌다" 같은 상황에서 NO 판정이 나옵니다. 그러면 "패치"와 "전면 재작업"의 차이가 표시되지 않아요.
3단계 판정은 "부분 충족 + 명시 조건 만족 시 자동 PASS 전환"의 중간 단계를 일급 객체로 둡니다. 이게 표준 도구가 다루지 않는 정직성입니다.
판정 정의
| 판정 | 정의 | 처리 |
|---|---|---|
| PASS | 명확히 통과. 수정 불필요 | 그대로 유지 |
| WITH-CONDITIONS | 부분 충족. 명시 조건 만족 시 PASS 전환 | 조건 명시 + 패치 후 자동 PASS |
| FAIL | 미통과. SPEC 또는 PLAN 수정 필요 | SPEC/PLAN 수정 후 재 REVIEW |
READY 진입 기준
READY: YES 조건
- FAIL 0건
- WITH-CONDITIONS ≤ 3건
- 모든 WITH-CONDITIONS의 조건이 명시됨
READY: NO 조건
- FAIL ≥ 1건, 또는
- WITH-CONDITIONS ≥ 4건
3건 한도가 핵심입니다. 4건 이상이면 "전반적 점검 필요"의 신호예요. 3건 이하면 "가벼운 패치로 충분"합니다.
GSD의 /gsd-verify-work는 PASS / FAIL 이진입니다. "부분 충족 명시 + 자동 PASS 전환"의 3단계는 표준에 없어요. 5파일+의 정직성입니다.
여기가 새 1장에서 정의한 E3가 데이터로 입증되는 자리입니다.
"검토자 한 명에 의존하지 말라" — 두 다른 AI 모델 또는 두 사람의 사각지대가 다르므로 통합해야 입체적 검증이 됩니다.
9개 표준 도구의 자리:
- Spec-Kit
/speckit.analyze— 단일 모델 검증 - BMAD Quinn — 단일 페르소나 검토
- GSD plan-checker — 단일 모델
"두 다른 모델의 사각지대 차이"를 명시적으로 다루는 도구는 없습니다.
E3는 두 단계에서 작동합니다
새 4장 7단계 사이클에서 본 것처럼, E3는 두 단계에서 작동합니다.
| 라운드 | 시점 | 주체 | 발견 건수 |
|---|---|---|---|
| 1라운드 | SPEC v1 → v2 | Gemini 외부 검토 | 5~7건 |
| 2라운드 | SPEC v3 → v4 | Claude 시뮬레이션 + Gemini | 12건 |
1라운드는 새 5장 SPEC.md 작성에서 다뤘습니다. 2라운드가 이 장의 핵심입니다.
2라운드 — Claude Code 프롬프트
# Claude 시뮬레이션 검토 — Claude Code 안에서 /model claude-opus-4-6 /effort high SPEC.md v3을 다른 시뮬레이션 검토자가 본다고 가정하고 약점을 5건 이상 찾아줘. 사용자가 못 본 것, 외부 검토자가 못 본 것을 중심으로. # 외부 Gemini 검토 — gemini.google.com [Gemini에게 SPEC v3 + "5가지 관점 검토" 프롬프트]
두 검토자 발견 12건 — TSV 사례
| # | 발견 | Claude만 | Gemini만 | 둘 다 |
|---|---|---|---|---|
| 1 | Day 14 다관점 가설 검증 측정 기준 부재 | ✅ | ||
| 2 | 페르소나 SEO 키워드 cannibalization | ✅ | ||
| 3 | 운영자 패널 "전체 정지" 30초 명시 부재 | ✅ | ||
| 4 | 다관점 클릭률 임계값(15% vs 10%) 근거 약함 | ✅ | ||
| 5 | About 페이지 외부 노출 시점(Day 1 게이트) | ✅ | ||
| 6 | 페르소나 시스템 프롬프트 환각 방지 명세 부재 | ✅ | ||
| 7 | API 비용 폭주 방어(Cloudflare WAF) 부재 | ✅ | ||
| 8 | 분 단위 스케줄링 (시간 단위 이상) | ✅ | ||
| 9 | DB 복합 인덱스(league_code + match_date) | ✅ | ||
| 10 | 자동 일관성 테스트 5/5 통과 게이트 | ✅ | ||
| 11 | Phase 1.0 실패 신호(Day 14 게이트 fail 시) | ✅ | ||
| 12 | 페르소나 system prompt cache_control | ✅ | ||
| 합계 | 4 | 6 | 2 |
만약 Claude만 받았다면 5·6·7·8·9·10번(6건)을 놓칩니다. 만약 Gemini만 받았다면 1·2·3·4번(4건)을 놓칩니다. 둘 다 받아야 12건 모두 포착됩니다.
두 검토자 발견 12건 — 줍줍 사례
| # | 발견 | Claude만 | Gemini만 | 둘 다 |
|---|---|---|---|---|
| 1 | 단계적 기여 시스템 부담 곡선 측정 부재 | ✅ | ||
| 2 | 닉네임 자동 부여 형용사 풀 20개 — 충돌 가능성 | ✅ | ||
| 3 | 운영자 검수 큐(LLM confidence 0.7 미만) 부재 | ✅ | ||
| 4 | 후기 신고 처리 SLA 부재(7일 내?) | ✅ | ||
| 5 | LLM 분류 프롬프트 — JSON 외 출력 fallback | ✅ | ||
| 6 | source_url null 처리(LLM 추출 실패 시) | ✅ | ||
| 7 | benefits.is_active 트리거(deadline 경과 자동) | ✅ | ||
| 8 | 행정구역 코드 변경(지자체 통폐합) 처리 | ✅ | ||
| 9 | 카카오 로그인 토큰 갱신 주기 명시 부재 | ✅ | ||
| 10 | FCM 토큰 만료 처리 | ✅ | ||
| 11 | UNIQUE (user_id, benefit_id) 제약 — 통계 조작 차단 | ✅ | ||
| 12 | Satori 한글 폰트 사전 검증 | ✅ | ||
| 합계 | 4 | 6 | 2 |
두 프로젝트가 다른 도메인(미디어 vs B2C 앱)인데도 같은 "4 + 6 + 2" 패턴이 나옵니다. 이게 E3가 데이터로 입증된 모습입니다.
Claude와 Gemini의 사각지대 차이 — 관찰된 패턴
| 영역 | Claude 더 잘 잡음 | Gemini 더 잘 잡음 |
|---|---|---|
| 측정 가능 임계값 | ✅ (Day 14 가설 검증 측정) | |
| SEO 키워드 분리 | ✅ (페르소나 cannibalization) | |
| 사용자 행동 패턴 | ✅ (단계적 기여 부담 곡선) | |
| 인프라·기술 디테일 | ✅ (WAF·복합 인덱스·캐시) | |
| Edge case 처리 | ✅ (LLM JSON fallback·null 처리) | |
| 외부 의존성 변경 | ✅ (행정 코드 변경·토큰 만료) |
Claude는 "비즈니스 로직과 사용자 경험"에 강하고, Gemini는 "인프라와 edge case"에 강합니다. 두 사각지대가 의도적으로 다릅니다 — 같은 회사 모델이면 같은 약점을 가져요.
이 두 사각지대 차이가 "의사의 두 번째 의견"의 핵심 가치입니다.
REVIEW.md 작성 시 자주 보는 결과: PASS 5~6건 + WITH-CONDITIONS 4~5건. 이게 "결함이 아니라 그물이 작동했다는 증거"입니다.
TSV 1차 REVIEW 결과 (15항목)
| 항목 | 판정 | 조건 (WITH-CONDITIONS인 경우) |
|---|---|---|
| 1. Phase 1 수익화 | PASS | (Phase 1.0 의도적 무수익 명시됨) |
| 2. Phase 1 배포 가능 | PASS | |
| 3. RLS 설정 | PASS | |
| 4. API 키 노출 | PASS | |
| 5. 기술 스택 일관 | PASS | |
| 6. N+1 쿼리 위험 | W-C | 복합 인덱스 (league_code + match_date) 추가 시 PASS 전환 |
| 7. 변경 파일 10개 이하 | PASS | |
| 8. 외부 연동 위치 | PASS | |
| 9. 에러 처리 | W-C | Sentry 통합 시 PASS 전환 (Day 15~18) |
| 10. 환경변수 분리 | PASS | |
| 11. 게이트 측정 가능 | PASS | |
| 12. 리스크 등록부 R1~R14 | PASS | |
| 13. R4 1인 번아웃 등록 | PASS | |
| 14. SPEC v4 두 검토자 | PASS | |
| 15. 12건 모두 반영 | W-C | P1+P2+P3 패치(75분) 후 PASS 전환 |
| 합계 | PASS 12 + W-C 3 |
종합 판정: WITH-CONDITIONS 3건(한도 = 3) → READY: YES (조건부).
75분 패치 사례 — 어떻게 처리되는가
# P1 — 항목 6: 복합 인덱스 추가 (15분) [Claude Code에서] PLAN.md에 Day 8 작업으로 "복합 인덱스 추가 (league_code + match_date) — 15분" 명시. # P2 — 항목 9: Sentry 통합 게이트 (5분) [Claude Code에서] PLAN.md G4 (Day 18) 통과 조건에 "Sentry 통합 + 7일 무장애 관측" 추가. # P3 — 항목 15: SPEC v4 → v4.1 (55분) [Claude Code에서] SPEC.md v4의 12건 발견 중 미반영 3건 추가 반영: - 페르소나 system prompt cache_control 명시 - 자동 일관성 테스트 fail 시 cron/publish.ts 정지 명시 - 분 단위 스케줄링 (시간 단위에서 갱신) # 모두 처리 후 재 REVIEW REVIEW.md 다시 작성해줘. 이번엔 P1·P2·P3 패치 반영 결과로.
2차 REVIEW 결과
| 항목 | 1차 → 2차 |
|---|---|
| 6 | W-C → PASS |
| 9 | W-C → PASS |
| 15 | W-C → PASS |
| 그 외 | 변동 없음 |
| 합계 | PASS 14 + W-C 1 + FAIL 0 |
READY: YES (FAIL 0 + W-C 1). 남은 W-C 1건은 "BUILD 진행 중 자연 해결되는 항목" — READY 진입을 막지 않습니다.
1차 REVIEW에서 "PASS 5건 + WITH-CONDITIONS 5건" 같은 결과가 나오면, 비개발자 동업자는 "내 SPEC + PLAN 부실"로 받아들이기 쉽습니다.
그러나 정확한 해석은 정반대입니다: REVIEW가 5건의 미세한 누락을 잡았어요. 이걸 BUILD 시작 후 발견했다면(배리 봄의 결함 비용 법칙 — 10배~100배 비용) 50시간 재작업이 됐을 것을, REVIEW가 75분 패치로 막은 것입니다.
"REVIEW에서 발견 = 75분" vs "BUILD에서 발견 = 50시간". 40배 절약. 이게 REVIEW의 본질 가치입니다.
READY: YES — BUILD 시작 가능
# 모든 항목 PASS 또는 ≤3건 WITH-CONDITIONS cat REVIEW.md | tail -10 # READY: YES 확인 git add REVIEW.md SPEC.md PLAN.md git commit -m "REVIEW.md: READY YES (PASS 14 + W-C 1) + 75분 패치"
READY: NO — 패치 후 재 REVIEW
[FAIL 항목이 있는 경우] NO인 항목만 수정합니다. 수정 중 새 기능 추가 금지. SPEC.md나 PLAN.md를 수정해야 한다면 먼저 수정 후 REVIEW 재실행. REVIEW.md의 3번 (RLS) 이 FAIL이야. SPEC.md의 DB 스키마에 RLS 계획을 추가해줘. 그 후 REVIEW.md를 다시 작성해줘.
FAIL 항목이 있는 상태에서 BUILD를 시작하면 반드시 나중에 처음부터 다시 만들어야 하는 상황이 옵니다.
특히 RLS 미설정(3번)과 API 키 노출 구조(4번)는 배포 후 발견 시 보안 사고로 이어집니다. 귀찮더라도 READY: YES 받을 때까지 기다립니다.
cat REVIEW.md | tail -10 # READY: YES 확인 # 5파일 현재 상태 cat SPEC.md | head -5 # ← 완성 (v4 또는 v4.1) cat PLAN.md | head -5 # ← 완성 (v2.1) cat REVIEW.md # ← 완성 (READY: YES) cat BUILD.md # ← 아직 비어있음 (새 9장) cat CLAUDE.md # ← 기본 내용 (새 11장에서 완성)
- 1️⃣ 핵심 한 줄: REVIEW.md = 15가지 체크(10 + 게이트 + 리스크 + E3) × 3단계 판정(PASS/W-C/FAIL). FAIL 0 + W-C ≤ 3 → READY: YES.
- 2️⃣ 15가지 체크리스트: 기본 10개(수익화·배포 가능·RLS·API 키·기술 스택·N+1·10파일·외부 연동·에러 처리·환경변수) + v2 추가 5개(게이트·리스크 등록부·R4·두 검토자·12건 반영)
- 3️⃣ E3 패턴 — 데이터 입증: 줍줍·TSV 모두 같은 12건 = Claude만 4 + Gemini만 6 + 둘 다 2. 한 검토자만 받으면 6건 또는 4건을 놓칩니다.
- 4️⃣ Claude 강점: 비즈니스 로직·사용자 행동·측정 임계값
- 5️⃣ Gemini 강점: 인프라·edge case·외부 의존성 변경
- 6️⃣ 75분 패치 사례(TSV): 1차 PASS 12 + W-C 3 → 75분 패치(P1+P2+P3) → 2차 PASS 14 + W-C 1
- 7️⃣ 메타 교훈: WITH-CONDITIONS = "그물이 작동한 증거"(결함 아님). REVIEW에서 발견 75분 vs BUILD에서 발견 50시간 — 40배 절약.
이제 코드를 써도 방향이 틀릴 가능성이 거의 없습니다. "두 검토자 + 자기 검증 + 75분 패치"의 그물이 작동했습니다.
다음 장에서 드디어 BUILD.md를 만들고 첫 코드를 작성합니다. E4(LogOnTable 실황 보존)의 첫 등장이 여기서 시작됩니다.