1탄 1장
1탄 — 메타 매뉴얼 · 1장
5파일+의 정체성: 표준 흡수 + 5확장 결합
5개 마크다운 파일이 9개 표준을 흡수하고 미점유 영역을 메우는 방식을 살펴봅니다
📑 이 챕터에서 다룰 내용

0장에서 우리는 SDD 9개 도구의 풍경을 보고, 그 안에서 5파일+의 자리를 한 문장으로 좌표화했습니다.

📘 좌표 한 문장 (복기)

"이 책의 5파일+ 사이클은 SDD 9개 표준의 단순화가 아니라, 표준이 다루지 못하는 5개 영역을 다루기 위한 학습용 + 운영용 + 한국어 솔로용 형식이다."

이 문장은 좌표입니다. 좌표만으로는 작업을 시작할 수 없습니다. 좌표를 5개의 마크다운 파일에 박아 넣어야 손에 잡히는 형식이 됩니다. 이 장의 일이 그것입니다.

💡 비개발자 동업자께 — 마크다운이 무엇인지부터

마크다운(Markdown) = 글에 굵기·제목·목록을 표시할 수 있는 가장 단순한 형식. 워드 문서처럼 메뉴를 누르지 않고, 특수 기호(#·**·- 같은)만으로 형식을 표시합니다.

💻 마크다운 예시
# 큰 제목
## 작은 제목
**굵은 글씨**
- 목록 항목 1
- 목록 항목 2

마크다운으로 적은 파일은 .md 확장자를 가집니다. 메모장으로 열 수 있고, AI에게 그대로 보내도 AI가 이해합니다.

이 장에서 5파일 각각을 다음 4단계로 풉니다.

1
무엇을 하는 파일인가

1탄 v1.0에서 정의된 역할 (이미 익숙하시면 빠르게 패스 가능)

2
9개 표준 도구의 무엇과 무엇에 매핑되는가

표준 흡수 부분

3
5개 확장(E1~E5) 중 어느 것이 그 파일에 결합되는가

표준 미점유 부분

4
줍줍(2탄) + TotalSportsView(3탄) 두 프로젝트에서 구체적으로 어떻게 보이는가

실제 예시

1-1 5파일의 출처 — 1탄 v1.0 짧은 복습 🔗

1탄 v1.0의 핵심 메시지는 "진짜 프로젝트를 시작할 때 처음 만들어야 할 다섯 개의 마크다운 파일"이었습니다.

파일역할만드는 시점
SPEC.md무엇을 만들 것인가프로젝트 시작 초반
PLAN.md언제·어떤 순서로 만들 것인가시작 중반
REVIEW.md코드 작업 시작 준비가 됐는가시작 후반
BUILD.md매일 무엇을 했는가진행 중 매일 갱신
CLAUDE.mdClaude Code가 매번 읽을 컨텍스트 가이드시작 끝 + 진행 중 갱신
📘 v2에서 변하는 것

이 5파일에 +를 붙입니다. "5파일 + 5확장"의 줄임말로 "5파일+"입니다.

5파일 자체는 v1.0과 같습니다. 다만 각 파일이 9개 표준 도구의 어디에 매핑되는지(표준 흡수)와 5개 확장 중 어느 것이 결합되는지(표준 미점유)가 명시적으로 박힙니다. 이게 v2의 본질 변화입니다.

1-2 SPEC.md — 무엇을 만들 것인가 + 회색지대 결정 (E1) 🔗

SPEC.md의 역할

SPEC.md는 "무엇"의 자리입니다. 프로젝트가 무엇이고, 누구를 위해 만들고, 어떤 기능과 제약과 성공 기준을 가지는지 — 모든 "무엇"의 결정이 여기 박힙니다.

1탄 v1.0에서 정의된 7항목 형식:

  • §1 한 줄 정의
  • §2 타겟 사용자
  • §3 핵심 기능
  • §4 비기능 요구사항 (성능·보안·확장성)
  • §5 제약·금지 사항
  • §6 성공 기준
  • §7 수익화

표준 매핑 — SPEC.md는 9개 도구의 어디에 해당하는가

도구해당 산출물
GSDPROJECT.md (비전·목표) + REQUIREMENTS.md (v1/v2/out-of-scope 분리)
Spec-Kit/speckit.constitution (헌법) + /speckit.specify 결과
OpenSpecopenspec/changes/{change}/proposal.md + openspec/specs/
BMADMary(분석가)의 requirements.md + Preston(PM)의 PRD
TaskmasterPRD 입력 (도구가 분해 대상으로 받는 시작점)
Intentliving spec의 "intent" 정의 부분
Kiro/AI-DLCAWS-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 안에 명시적 섹션으로 들어옵니다.

💻 줍줍(2탄)의 E1 적용 — SPEC.md 발췌
## ⚖️ 회색지대 결정 — "줍줍" 표현과 개인정보

[1] "줍줍" 표현의 정직한 위치
- "공짜로 줍는다"는 표현은 정부 지원금 공식 신청 절차와 거리가 있음
- 본 서비스가 약속하는 것: 정보 격차를 줄인다
- 본 서비스가 약속하지 않는 것: 무조건 받게 해준다, 신청 보장

[2] 개인정보 처리 위치
- IDFA (광고 식별자) 미수집 — 애플 심사 통과 가속
- 익명 닉네임 자동 부여 — 실명 노출 차단
- "개인정보 판매 없음" 정체성 명시
💻 TotalSportsView(3탄)의 E1 적용 — SPEC.md 발췌
## ⚖️ Position C 채택의 법적 근거

한국 사행행위등 규제 및 처벌특례법은 "도박을 조장하는 행위"를
처벌한다. "조장"의 핵심 요건:
① 인지 — 도박 목적임을 알고
② 설계 — 도박을 돕도록 의도적으로 만들었다

본 SPEC은 이 두 요건이 동시 성립하지 않는 포지션을 명시적으로
채택한다:

> "TotalSportsView는 스포츠 분석 미디어다. 콘텐츠를 누가 어떻게
> 사용하는지 묻지 않는다. 다만 베팅 사이트로 연결하지 않고,
> 베팅을 권유하는 콘텐츠를 만들지 않는다."
⚠️ 이 두 섹션은 9개 표준 도구의 어디에도 없습니다

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 + 다중 페르소나)미디어 플랫폼, 복잡한 콘텐츠 시스템
1-3 PLAN.md — 언제 만들 것인가 + 1인 12개월 페이스 (E2) 🔗

PLAN.md의 역할

PLAN.md는 "언제 · 어떤 순서로 · 얼마나"의 자리입니다. SPEC의 결정을 캘린더에 올려놓는 작업입니다.

1탄 v1.0에서 정의된 4가지 골격: ① SPEC 분해(양방향 추적 가능) ② 시간 단위 쪼개기(1시간 단위) ③ 게이트 명시(측정 가능 통과 조건) ④ 리스크 등록부(영향·확률·완화책·트리거)

표준 매핑

도구해당 산출물
GSDROADMAP.md (phases) + phase별 {N}-{M}-PLAN.md
Spec-Kitphase tasks (구조화된 implementation steps)
OpenSpecproposal.md"tasks" 섹션
BMADSally(제품 오너)의 story breakdown + Simon(스크럼 마스터)의 sprint plan
Taskmastertask decomposition + dependency graph (가장 강한 영역)

확장 결합 — PLAN.md + E2 1인 12개월 페이스

E2: 1인 12개월 페이스 게이트가 PLAN.md에 박힙니다. 표준이 다루지 못하는 "사람이 12개월 동안 무너지지 않을 페이스인가"의 메타 결정입니다.

💻 TSV 예시 — 시간 갭 흡수 옵션
## 시간 갭 흡수 옵션 — 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탄)약 18KB2KB (게이트 + 휴식 + R4)10주 (1.5~2개월)
TotalSportsView (3탄)28KB4KB (시간 갭 산식 + 14게이트 + 14리스크)12개월
1-4 REVIEW.md — 들어갈 준비가 됐는가 + 두 검토자 (E3) 🔗

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
OpenSpecproposal-implementation gap 추적 (자동)
BMADQuinn(QA Engineer)의 test strategy 검증

확장 결합 — REVIEW.md + E3 두 검토자 사각지대

E3: 두 검토자 사각지대 패턴이 REVIEW.md에 박힙니다. E3는 SPEC 단계 외부 검토에서 먼저 등장하고, REVIEW 단계에서 다시 작동하는 "두 단계에 걸친 패턴"입니다.

⚠️ TSV 예시 — 한 검토자만 받으면 절반을 놓칩니다

3탄에서 SPEC v3에 대해:

  • Claude 시뮬레이션 검토: 5건 발견
  • 실제 외부 Gemini 검토: 7건 발견
  • 합계 12건 중 둘 다 잡은 것 2건, Claude만 4건, Gemini만 6건

한 검토자만 받으면 6개 또는 4개를 놓칩니다. 표준 도구는 단일 검증 도구만 있습니다. "두 다른 모델의 사각지대 차이"를 명시적으로 다루는 도구는 없습니다.

💡 WITH-CONDITIONS 처리의 정직성

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탄)약 12KBPASS 6 + WITH-CONDITIONS 4PASS 9 + WITH-CONDITIONS 1
TotalSportsView (3탄)17KBPASS 5 + WITH-CONDITIONS 5PASS 9 + WITH-CONDITIONS 1
1-5 BUILD.md — 매일 무엇을 했는가 + LogOnTable (E4) 🔗

BUILD.md의 역할

BUILD.md는 "BUILD 단계의 일자별 로그" 자리입니다. Day 1부터 Phase 종료까지 매일의 작업·산출물·이슈·회고를 기록합니다. 매일 5분에 끝나는 양식입니다.

확장 결합 — BUILD.md + E4 LogOnTable 실황 보존

E4: LogOnTable 실황 보존이 BUILD.md(그리고 책 본문 자체)에 박힙니다.

📘 LogOnTable의 정의

"왜 그 결정을 내렸는가"의 사용자-AI 대화 트레이스를 보존하는 패턴입니다.

단순 결정 결과(예: "Position C 채택")가 아니라, 결정에 도달하는 과정(예: "Junho의 시장 직관 → Claude의 법적 정제 → 명시적 경계 설정"의 3단계 대화) 자체를 본문에 남기는 형식입니다.

💻 줍줍 예시 — LLM 분류 신뢰성 결정 LogOnTable
### [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만으로는 답이 없습니다.

💡 책 본문 자체가 큰 LogOnTable입니다

BUILD.md만이 아니라, 1탄·2탄·3탄 책 본문 자체가 큰 LogOnTable입니다. "LogOnTable 실황"이라고 명시적으로 표시된 절들이 책에 여러 번 등장합니다.

표준 도구의 매뉴얼이 "이 명령을 입력하세요"를 가르친다면, 5파일+의 본문은 "이런 대화로 이런 결정에 도달하세요"를 가르칩니다.

1-6 CLAUDE.md — Claude에게 어떤 컨텍스트 + 콘텐츠 SSOT (E5) 🔗

CLAUDE.md의 역할

CLAUDE.md는 "Claude Code가 매 세션 자동으로 읽을 컨텍스트 가이드" 자리입니다. 200줄 이하, 약 7KB. 매 chat 시작 시 자동 입력되므로, 매번 컨텍스트를 다시 설명할 필요가 없습니다.

📘 SSOT 풀이 — 비개발자께

SSOT = Single Source of Truth = 단일 진실 출처.

"같은 정보가 여러 곳에 흩어져 있으면 어디가 맞는지 모른다"는 문제의 해결책. 정보를 한 곳에만 두고(출처), 다른 곳들은 그 출처를 참조하게 합니다.

비유: 회사의 "오늘의 휴무일" 정보가 사장님 메모지·HR 문서·게시판·카톡에 모두 있다면 어느 게 맞는지 모릅니다. SSOT는 "공식 사내 캘린더 한 곳"만 진실이고, 나머지는 거기서 가져오게 하는 패턴입니다.

확장 결합 — CLAUDE.md + E5 콘텐츠 SSOT

💻 줍줍 예시 — 두 탭의 콘텐츠 SSOT
## Content SSOT — 소상공인 / 개인 두 탭

원칙: 같은 "지원금 정보"를 두 탭이 다르게 노출하되,
사실 자체는 동일한 출처 (DB의 benefits 테이블) 에서 받는다.

규칙:
1. benefits 테이블의 모든 사실 (마감일·금액·자격 요건) 은
   두 탭이 동일하게 표시. 변형 금지.
2. summary와 key_requirements 텍스트는 톤에 따라 다를 수 있음.
   다만 사실은 동일.
4. 자동 검증: 같은 benefit_id에 대해 두 탭 노출 시 사실 일치
   테스트 (마감일·금액 같음).
💻 TSV 예시 — 다중 페르소나 SSOT
## 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가 LLM 시대에 중요한 이유

콘텐츠 SSOT는 "사실 환각(factual hallucination)"이라는 LLM 시대 고유 문제를 다룹니다. AI가 "분석가니까 통계가 있어야 한다"는 압박으로 사실을 추정하면(입력에 없는 수치 만들어냄), 같은 경기에 대해 페르소나마다 다른 사실이 출력됩니다. 사용자 신뢰가 즉시 깨집니다.

해결: SSOT 인터페이스 + 시스템 프롬프트 환각 방지 + 자동 일관성 테스트의 삼중 안전장치. CLAUDE.md에 이 안전장치가 명시됩니다.

1-7 5파일+가 한 번에 작동하는 모습 🔗

5파일과 5확장이 어떻게 한 시스템으로 작동하는지 한 표로 정리합니다.

파일v1.0 역할표준 흡수 (대표 매핑)확장 결합
SPEC.md무엇을 만들 것인가GSD PROJECT.md + REQUIREMENTS.md / Spec-Kit /speckit.specify + constitutionE1: 회색지대 결정
PLAN.md언제·어떤 순서로 만들 것인가GSD ROADMAP.md + phase plans / Taskmaster decompositionE2: 1인 12개월 페이스
REVIEW.mdBUILD 진입 준비가 됐는가GSD VERIFICATION.md + UAT.md / Spec-Kit /speckit.analyzeE3: 두 검토자 사각지대
BUILD.md매일 무엇을 했는가GSD SUMMARY.md (per task) + atomic commitsE4: LogOnTable 실황 보존
CLAUDE.mdClaude에게 어떤 컨텍스트GSD STATE.md + .clinerules / Spec-Kit constitutionE5: 콘텐츠 SSOT
🎉 이 표가 5파일+의 정체성 한 페이지 요약입니다

각 파일이 표준 흡수 + 확장 결합을 동시에 한다는 점이 핵심입니다. "표준의 단순화"가 아니라 "표준 흡수 + 표준 미점유 영역의 명시적 추가"가 5파일+의 정체성입니다.

두 프로젝트의 5파일 현황

📘 줍줍 Phase 0 끝 시점 (2주차 끝)
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 Phase 0 끝 시점 (1~2주차 끝)
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파일+의 본질입니다.

1-8 다음 장 — Claude Code 환경 만들기 🔗

좌표축이 명확해졌고(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장 정리
  • 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가 그대로 이해합니다.
📘
1탄 도우미
질문하기 OK
안녕하세요! 5파일+의 정체성과 표준 매핑에 대해 무엇이든 물어보세요. 👇