📑 이 챕터에서 다룰 내용
- 들어가며 — 좌표에서 형식으로
- 1.1 5파일의 출처 — 1탄 v1.0 짧은 복습
- 1.2 SPEC.md — 무엇을 만들 것인가 + 회색지대 결정 (E1)
- 1.3 PLAN.md — 언제 만들 것인가 + 1인 12개월 페이스 (E2)
- 1.4 REVIEW.md — 들어갈 준비가 됐는가 + 두 검토자 (E3)
- 1.5 BUILD.md — 매일 무엇을 했는가 + LogOnTable (E4)
- 1.6 CLAUDE.md — Claude에게 어떤 컨텍스트 + 콘텐츠 SSOT (E5)
- 1.7 5파일+가 한 번에 작동하는 모습
- 1.8 다음 장 — Claude Code 환경 만들기
- 📌 1장 정리
0장에서 우리는 SDD 9개 도구의 풍경을 보고, 그 안에서 5파일+의 자리를 한 문장으로 좌표화했습니다.
"이 책의 5파일+ 사이클은 SDD 9개 표준의 단순화가 아니라, 표준이 다루지 못하는 5개 영역을 다루기 위한 학습용 + 운영용 + 한국어 솔로용 형식이다."
이 문장은 좌표입니다. 좌표만으로는 작업을 시작할 수 없습니다. 좌표를 5개의 마크다운 파일에 박아 넣어야 손에 잡히는 형식이 됩니다. 이 장의 일이 그것입니다.
마크다운(Markdown) = 글에 굵기·제목·목록을 표시할 수 있는 가장 단순한 형식. 워드 문서처럼 메뉴를 누르지 않고, 특수 기호(#·**·- 같은)만으로 형식을 표시합니다.
# 큰 제목 ## 작은 제목 **굵은 글씨** - 목록 항목 1 - 목록 항목 2
마크다운으로 적은 파일은 .md 확장자를 가집니다. 메모장으로 열 수 있고, AI에게 그대로 보내도 AI가 이해합니다.
이 장에서 5파일 각각을 다음 4단계로 풉니다.
1탄 v1.0에서 정의된 역할 (이미 익숙하시면 빠르게 패스 가능)
표준 흡수 부분
표준 미점유 부분
실제 예시
1탄 v1.0의 핵심 메시지는 "진짜 프로젝트를 시작할 때 처음 만들어야 할 다섯 개의 마크다운 파일"이었습니다.
| 파일 | 역할 | 만드는 시점 |
|---|---|---|
| SPEC.md | 무엇을 만들 것인가 | 프로젝트 시작 초반 |
| PLAN.md | 언제·어떤 순서로 만들 것인가 | 시작 중반 |
| REVIEW.md | 코드 작업 시작 준비가 됐는가 | 시작 후반 |
| BUILD.md | 매일 무엇을 했는가 | 진행 중 매일 갱신 |
| CLAUDE.md | Claude Code가 매번 읽을 컨텍스트 가이드 | 시작 끝 + 진행 중 갱신 |
이 5파일에 +를 붙입니다. "5파일 + 5확장"의 줄임말로 "5파일+"입니다.
5파일 자체는 v1.0과 같습니다. 다만 각 파일이 9개 표준 도구의 어디에 매핑되는지(표준 흡수)와 5개 확장 중 어느 것이 결합되는지(표준 미점유)가 명시적으로 박힙니다. 이게 v2의 본질 변화입니다.
SPEC.md의 역할
SPEC.md는 "무엇"의 자리입니다. 프로젝트가 무엇이고, 누구를 위해 만들고, 어떤 기능과 제약과 성공 기준을 가지는지 — 모든 "무엇"의 결정이 여기 박힙니다.
1탄 v1.0에서 정의된 7항목 형식:
- §1 한 줄 정의
- §2 타겟 사용자
- §3 핵심 기능
- §4 비기능 요구사항 (성능·보안·확장성)
- §5 제약·금지 사항
- §6 성공 기준
- §7 수익화
표준 매핑 — SPEC.md는 9개 도구의 어디에 해당하는가
| 도구 | 해당 산출물 |
|---|---|
| GSD | PROJECT.md (비전·목표) + REQUIREMENTS.md (v1/v2/out-of-scope 분리) |
| Spec-Kit | /speckit.constitution (헌법) + /speckit.specify 결과 |
| OpenSpec | openspec/changes/{change}/proposal.md + openspec/specs/ |
| BMAD | Mary(분석가)의 requirements.md + Preston(PM)의 PRD |
| Taskmaster | PRD 입력 (도구가 분해 대상으로 받는 시작점) |
| Intent | living spec의 "intent" 정의 부분 |
| Kiro/AI-DLC | AWS-DLC의 "requirements phase" 산출물 |
SPEC.md 항목별 표준 매핑
| SPEC.md 항목 | 표준 매핑 |
|---|---|
| §1 한 줄 정의 | GSD PROJECT.md의 "vision", Spec-Kit /speckit.specify 도입부 |
| §2 타겟 사용자 | BMAD Mary의 페르소나 정의 |
| §3 핵심 기능 | GSD REQUIREMENTS.md (v1/v2 분리), OpenSpec proposal의 "what" |
| §4 비기능 요구사항 | Spec-Kit /speckit.constitution의 architectural rules |
| §5 제약·금지 사항 | Spec-Kit /speckit.constitution의 constraints |
| §6 성공 기준 | GSD ROADMAP.md의 milestone definition of done |
| §7 수익화 | (대부분 표준이 다루지 않음 — 비즈니스 결정으로 분류) |
확장 결합 — SPEC.md + E1 회색지대 결정
여기가 5파일+의 "+"가 SPEC.md에 박히는 자리입니다. E1: 회색지대 결정 프레임이 SPEC.md 안에 명시적 섹션으로 들어옵니다.
## ⚖️ 회색지대 결정 — "줍줍" 표현과 개인정보 [1] "줍줍" 표현의 정직한 위치 - "공짜로 줍는다"는 표현은 정부 지원금 공식 신청 절차와 거리가 있음 - 본 서비스가 약속하는 것: 정보 격차를 줄인다 - 본 서비스가 약속하지 않는 것: 무조건 받게 해준다, 신청 보장 [2] 개인정보 처리 위치 - IDFA (광고 식별자) 미수집 — 애플 심사 통과 가속 - 익명 닉네임 자동 부여 — 실명 노출 차단 - "개인정보 판매 없음" 정체성 명시
## ⚖️ Position C 채택의 법적 근거 한국 사행행위등 규제 및 처벌특례법은 "도박을 조장하는 행위"를 처벌한다. "조장"의 핵심 요건: ① 인지 — 도박 목적임을 알고 ② 설계 — 도박을 돕도록 의도적으로 만들었다 본 SPEC은 이 두 요건이 동시 성립하지 않는 포지션을 명시적으로 채택한다: > "TotalSportsView는 스포츠 분석 미디어다. 콘텐츠를 누가 어떻게 > 사용하는지 묻지 않는다. 다만 베팅 사이트로 연결하지 않고, > 베팅을 권유하는 콘텐츠를 만들지 않는다."
GSD의 "security enforcement"는 코드 보안이고, Spec-Kit의 "constitution"은 architectural rules입니다. "법적·윤리적 회색지대에서 안전한 사업 포지션을 명세적으로 결정"은 표준 도구가 "비즈니스 요구사항"으로 받아두고 사용자에게 떠넘기는 영역입니다.
5파일+의 SPEC.md는 이 영역을 본문에 명시적으로 흡수합니다.
두 프로젝트의 SPEC 분량 비교
| 프로젝트 | SPEC 분량 | 회색지대 분량 | 비고 |
|---|---|---|---|
| 줍줍 (2탄) | 약 12KB / 280줄 | 1KB (개인정보 + 표현) | B2C 앱, 명확한 사용자 유형 |
| TotalSportsView (3탄) | 24KB / 451줄 | 2KB (Position C + 다중 페르소나) | 미디어 플랫폼, 복잡한 콘텐츠 시스템 |
PLAN.md의 역할
PLAN.md는 "언제 · 어떤 순서로 · 얼마나"의 자리입니다. SPEC의 결정을 캘린더에 올려놓는 작업입니다.
1탄 v1.0에서 정의된 4가지 골격: ① SPEC 분해(양방향 추적 가능) ② 시간 단위 쪼개기(1시간 단위) ③ 게이트 명시(측정 가능 통과 조건) ④ 리스크 등록부(영향·확률·완화책·트리거)
표준 매핑
| 도구 | 해당 산출물 |
|---|---|
| GSD | ROADMAP.md (phases) + phase별 {N}-{M}-PLAN.md |
| Spec-Kit | phase tasks (구조화된 implementation steps) |
| OpenSpec | proposal.md의 "tasks" 섹션 |
| BMAD | Sally(제품 오너)의 story breakdown + Simon(스크럼 마스터)의 sprint plan |
| Taskmaster | task decomposition + dependency graph (가장 강한 영역) |
확장 결합 — PLAN.md + E2 1인 12개월 페이스
E2: 1인 12개월 페이스 게이트가 PLAN.md에 박힙니다. 표준이 다루지 못하는 "사람이 12개월 동안 무너지지 않을 페이스인가"의 메타 결정입니다.
## 시간 갭 흡수 옵션 — Phase 1.0 (Day 1~30 → 33일) PLAN v1 → v2 변환 시 +29h 추가 작업 발생. 가용 120h. 흡수 방법 3가지 옵션: 옵션 A — 부가 기능 축소 (-16h) 옵션 B — 모니터링 축소 (-8h) 옵션 C — 일정 3일 연장 (+12h 가용) ← 채택 채택 근거: Phase 1.0의 본질은 "5리그 × 2 페르소나 안정 가동 + 7일 무장애 입증"이지 30일이라는 캘린더가 아니다. 검증이 본질이고 캘린더는 도구다.
## G2 — 4주차 게이트 (DB·인증 완성) [ ] users / benefits / jupjups / reports 테이블 생성 [ ] 집계 트리거 정상 동작 [ ] 카카오 로그인 + 닉네임 자동 부여 [ ] pg_cron API 호출 매일 03:00 정상 실행 [ ] 어드민 기초 페이지 (LLM 분류 검수용) [ ] 운영자 페이스 점검: 3~4주차 누적 60h 초과 시 5주차 1일 휴식
"이 사람이 무너지기 전에 멈추는 트리거"가 PLAN의 일부입니다. 표준 도구의 리스크 등록부에는 기술 리스크와 외부 의존성 리스크만 있습니다. R4 — 1인 운영 번아웃은 5파일+만 다루는 항목입니다.
두 프로젝트의 PLAN 분량 비교
| 프로젝트 | PLAN 분량 | E2 분량 | 일정 |
|---|---|---|---|
| 줍줍 (2탄) | 약 18KB | 2KB (게이트 + 휴식 + R4) | 10주 (1.5~2개월) |
| TotalSportsView (3탄) | 28KB | 4KB (시간 갭 산식 + 14게이트 + 14리스크) | 12개월 |
REVIEW.md의 역할
REVIEW.md는 "코드 작업 시작 준비가 됐는가"의 자기 검증 자리입니다. 1탄 v1.0에서 정의된 10가지 체크 + 3단계 판정(PASS / WITH-CONDITIONS / FAIL) + READY 진입 기준(FAIL 0건 + WITH-CONDITIONS ≤ 3건).
표준 매핑
| 도구 | 해당 산출물 |
|---|---|
| GSD | {N}-VERIFICATION.md (자동 검증) + /gsd-verify-work |
| Spec-Kit | /speckit.analyze (cross-artifact 일관성) + /speckit.checklist |
| OpenSpec | proposal-implementation gap 추적 (자동) |
| BMAD | Quinn(QA Engineer)의 test strategy 검증 |
확장 결합 — REVIEW.md + E3 두 검토자 사각지대
E3: 두 검토자 사각지대 패턴이 REVIEW.md에 박힙니다. E3는 SPEC 단계 외부 검토에서 먼저 등장하고, REVIEW 단계에서 다시 작동하는 "두 단계에 걸친 패턴"입니다.
3탄에서 SPEC v3에 대해:
- Claude 시뮬레이션 검토: 5건 발견
- 실제 외부 Gemini 검토: 7건 발견
- 합계 12건 중 둘 다 잡은 것 2건, Claude만 4건, Gemini만 6건
한 검토자만 받으면 6개 또는 4개를 놓칩니다. 표준 도구는 단일 검증 도구만 있습니다. "두 다른 모델의 사각지대 차이"를 명시적으로 다루는 도구는 없습니다.
REVIEW의 가장 중요한 메타 교훈: "WITH-CONDITIONS는 결함이 아니라 그물이 작동했다는 증거"입니다.
1차 REVIEW에서 "PASS 5건 + WITH-CONDITIONS 5건"이 나오면, 이걸 "내 SPEC + PLAN이 부실"로 받지 않고 "REVIEW가 5건의 미세한 누락을 잡았다"로 받습니다.
GSD의 /gsd-verify-work는 PASS / FAIL 이진 판정입니다. "부분 충족 + 명시 조건 만족 시 자동 PASS 전환"의 3단계 판정은 표준에 없습니다.
두 프로젝트의 REVIEW 사례
| 프로젝트 | REVIEW 분량 | 1차 결과 | 2차 결과 (패치 후) |
|---|---|---|---|
| 줍줍 (2탄) | 약 12KB | PASS 6 + WITH-CONDITIONS 4 | PASS 9 + WITH-CONDITIONS 1 |
| TotalSportsView (3탄) | 17KB | PASS 5 + WITH-CONDITIONS 5 | PASS 9 + WITH-CONDITIONS 1 |
BUILD.md의 역할
BUILD.md는 "BUILD 단계의 일자별 로그" 자리입니다. Day 1부터 Phase 종료까지 매일의 작업·산출물·이슈·회고를 기록합니다. 매일 5분에 끝나는 양식입니다.
확장 결합 — BUILD.md + E4 LogOnTable 실황 보존
E4: LogOnTable 실황 보존이 BUILD.md(그리고 책 본문 자체)에 박힙니다.
"왜 그 결정을 내렸는가"의 사용자-AI 대화 트레이스를 보존하는 패턴입니다.
단순 결정 결과(예: "Position C 채택")가 아니라, 결정에 도달하는 과정(예: "Junho의 시장 직관 → Claude의 법적 정제 → 명시적 경계 설정"의 3단계 대화) 자체를 본문에 남기는 형식입니다.
### [3주차 화요일 14:00] LLM confidence 임계값 결정 > Junho: API 응답 → LLM 분류 → DB 저장 흐름에서 confidence가 > 0.5 정도면 어떻게 처리할까? 자동 저장? 어드민 검수 큐로? > Claude: 두 옵션의 트레이드오프를 봅시다: > > 옵션 A — 자동 저장 (모든 결과) > - 장점: 어드민 부담 0, 데이터 풍부 > - 단점: 잘못된 분류가 사용자에게 노출, 신뢰 손상 > > 옵션 C — 임계값 0.7 + null 필드 처리 > - 자동 저장하되, confidence 0.7 미만 *필드*는 NULL > - 사용자 노출 시 "정보 부족 (원문 링크)"으로 표시 > - 어드민 부담 거의 0, 사용자 신뢰 보존 > - 1인 운영 환경에서 옵션 C 권장. > Junho: 옵션 C로 가자. SPEC §3에 명시.
이 트레이스가 6개월 후 동업자가 "왜 0.7인가, 0.6도 가능했나" 펼쳤을 때의 답입니다. 결과만 적힌 SPEC만으로는 답이 없습니다.
BUILD.md만이 아니라, 1탄·2탄·3탄 책 본문 자체가 큰 LogOnTable입니다. "LogOnTable 실황"이라고 명시적으로 표시된 절들이 책에 여러 번 등장합니다.
표준 도구의 매뉴얼이 "이 명령을 입력하세요"를 가르친다면, 5파일+의 본문은 "이런 대화로 이런 결정에 도달하세요"를 가르칩니다.
CLAUDE.md의 역할
CLAUDE.md는 "Claude Code가 매 세션 자동으로 읽을 컨텍스트 가이드" 자리입니다. 200줄 이하, 약 7KB. 매 chat 시작 시 자동 입력되므로, 매번 컨텍스트를 다시 설명할 필요가 없습니다.
SSOT = Single Source of Truth = 단일 진실 출처.
"같은 정보가 여러 곳에 흩어져 있으면 어디가 맞는지 모른다"는 문제의 해결책. 정보를 한 곳에만 두고(출처), 다른 곳들은 그 출처를 참조하게 합니다.
비유: 회사의 "오늘의 휴무일" 정보가 사장님 메모지·HR 문서·게시판·카톡에 모두 있다면 어느 게 맞는지 모릅니다. SSOT는 "공식 사내 캘린더 한 곳"만 진실이고, 나머지는 거기서 가져오게 하는 패턴입니다.
확장 결합 — CLAUDE.md + E5 콘텐츠 SSOT
## Content SSOT — 소상공인 / 개인 두 탭 원칙: 같은 "지원금 정보"를 두 탭이 다르게 노출하되, 사실 자체는 동일한 출처 (DB의 benefits 테이블) 에서 받는다. 규칙: 1. benefits 테이블의 모든 사실 (마감일·금액·자격 요건) 은 두 탭이 동일하게 표시. 변형 금지. 2. summary와 key_requirements 텍스트는 톤에 따라 다를 수 있음. 다만 사실은 동일. 4. 자동 검증: 같은 benefit_id에 대해 두 탭 노출 시 사실 일치 테스트 (마감일·금액 같음).
## Persona System Rules
Phase 1.0 핵심 규칙:
1. 2종 페르소나만 활성: STAT (통계학자) + OBSERVER (신중한 관찰자)
2. SSOT 의무: 모든 페르소나는 lib/match_facts.ts의 MatchFacts
인터페이스를 단일 입력으로 받음
3. 사실 자체 변경 금지: 페르소나는 해석·표현·강조점만 다름
4. 자동 일관성 테스트 통과 의무: tests/persona_consistency.test.ts
가 fail하면 cron/publish.ts 정지
5. prompt caching 적용 의무: 페르소나 system prompt는
cache_control: { type: 'ephemeral' }콘텐츠 SSOT는 "사실 환각(factual hallucination)"이라는 LLM 시대 고유 문제를 다룹니다. AI가 "분석가니까 통계가 있어야 한다"는 압박으로 사실을 추정하면(입력에 없는 수치 만들어냄), 같은 경기에 대해 페르소나마다 다른 사실이 출력됩니다. 사용자 신뢰가 즉시 깨집니다.
해결: SSOT 인터페이스 + 시스템 프롬프트 환각 방지 + 자동 일관성 테스트의 삼중 안전장치. CLAUDE.md에 이 안전장치가 명시됩니다.
5파일과 5확장이 어떻게 한 시스템으로 작동하는지 한 표로 정리합니다.
| 파일 | v1.0 역할 | 표준 흡수 (대표 매핑) | 확장 결합 |
|---|---|---|---|
| SPEC.md | 무엇을 만들 것인가 | GSD PROJECT.md + REQUIREMENTS.md / Spec-Kit /speckit.specify + constitution | E1: 회색지대 결정 |
| PLAN.md | 언제·어떤 순서로 만들 것인가 | GSD ROADMAP.md + phase plans / Taskmaster decomposition | E2: 1인 12개월 페이스 |
| REVIEW.md | BUILD 진입 준비가 됐는가 | GSD VERIFICATION.md + UAT.md / Spec-Kit /speckit.analyze | E3: 두 검토자 사각지대 |
| BUILD.md | 매일 무엇을 했는가 | GSD SUMMARY.md (per task) + atomic commits | E4: LogOnTable 실황 보존 |
| CLAUDE.md | Claude에게 어떤 컨텍스트 | GSD STATE.md + .clinerules / Spec-Kit constitution | E5: 콘텐츠 SSOT |
각 파일이 표준 흡수 + 확장 결합을 동시에 한다는 점이 핵심입니다. "표준의 단순화"가 아니라 "표준 흡수 + 표준 미점유 영역의 명시적 추가"가 5파일+의 정체성입니다.
두 프로젝트의 5파일 현황
jupjup/ ├── SPEC.md (12KB) — 7항목 + 회색지대 (표현·개인정보) 섹션 ├── PLAN.md (18KB) — 10주 일정 + 8개 게이트 + 12개 리스크 ├── REVIEW.md (12KB) — 10가지 체크 + WITH-CONDITIONS 처리 ├── BUILD.md ( 4KB) — placeholder, 3주차부터 채워질 양식 ├── CLAUDE.md ( 7KB) — 200줄 + Two-Tab Content SSOT 7개 규칙 └── (3주차부터의 코드)
5파일 합계 약 53KB.
totalsportsview/ ├── SPEC.md (24KB) — 7항목 + Position C 섹션 ├── PLAN.md (28KB) — 33일 일정 + 5게이트 + 14리스크 ├── REVIEW.md (17KB) — 10가지 체크 + WITH-CONDITIONS 처리 ├── BUILD.md ( 4KB) — placeholder, Day 1부터 채워질 양식 ├── CLAUDE.md ( 7KB) — 200줄 + Persona System Rules 7개 └── (Day 1부터의 코드)
5파일 합계 약 80KB.
두 프로젝트의 5파일이 "같은 형식"으로 "다른 도메인"에서 작동합니다. 도메인이 달라도 형식은 같습니다. 이게 5파일+의 본질입니다.
좌표축이 명확해졌고(0장), 형식이 정의됐습니다(이 장). 이제 실제로 Claude Code를 컴퓨터에 설치하고, 5파일을 만들 환경을 준비하는 단계로 들어갑니다.
| 장 | 핵심 |
|---|---|
| 새 2장 | 프로젝트 시작 30분 — 폴더 + 5파일 + git init |
| 새 3장 | Claude Code 설치 |
| 새 4장 | 5파일+ 사이클 + 9개 도구 매핑 (전면 학습) |
| 새 5~11장 | 5파일 각각 깊은 작성 + 5확장 결합 |
| 새 12~30장 | AI 협업·수익화·운영·고급 기능 |
| 새 31~33장 | 기존 프로젝트 적용 + 팀 협업 + 자유 창작 준비 |
- 1️⃣ 5파일+ = 5파일(SPEC·PLAN·REVIEW·BUILD·CLAUDE) + 5확장(E1~E5). 각 파일이 표준 흡수 + 확장 결합을 동시에 합니다.
- 2️⃣ SPEC.md + E1: 회색지대(법적·윤리적 안전 위치) 결정을 명세 안에 명시합니다.
- 3️⃣ PLAN.md + E2: 1인 12개월 페이스 게이트 — 운영자 번아웃 리스크(R4)를 PLAN에 박습니다.
- 4️⃣ REVIEW.md + E3: 두 검토자의 사각지대를 통합해 PASS/WITH-CONDITIONS/FAIL 3단계 판정을 합니다.
- 5️⃣ BUILD.md + E4: LogOnTable — 결정 결과뿐 아니라 결정 과정의 대화를 보존합니다.
- 6️⃣ CLAUDE.md + E5: 콘텐츠 SSOT — 다중 페르소나가 단일 진실 출처에서 사실을 받도록 규칙화합니다.
- 7️⃣ 마크다운 풀이: 글에 형식을 표시하는 가장 단순한 방식. .md 확장자. 메모장으로 열림. AI가 그대로 이해합니다.