ADR-0010 — 통합 개발 라이프사이클 확장 + 버전 통일¶

Context¶

ADR-0005에서 정한 신규 기능 8단계 워크플로는 wiki·FRD 중심으로, 다음 영역의 통합이 미흡: - 디자인 (Figma) — FRD §7에 "Figma TBD"만 있고 게이트 없음 - QA (E2E 시나리오·테스트 케이스) — FRD에 path만 있고 작성 시점·게이트 없음 - 마케팅 (카피·랜딩·SEO) — 6모 시즌 오픈챌린지 출시인데 협업 흐름 없음 - 운영 (CS·feature flag·롤아웃·모니터링) - 버전 통일 — Notion v0.x ↔ spec vY.Z 불일치 (사고력 v0.2 → spec v0.2, 챌린지 v0.2 → spec v0.2)

사용자 의문 (2026-05-21): 1. "spec.md 넣고 바로 개발 진행하는 게 맞아? 기획-프론트-백-디자인-마케팅 작업 흐름은?" 2. "버전을 맞춰야 될 거 같은데 — 노션 기획 v0.1이면 spec FRD wiki 등 0.1, 업데이트된 v0.2이면 그에 맞게 0.2"

잘나가는 스타트업 조사 (2025-2026)¶

회사	패턴	시사점
Linear	Issue 내 PRD + 디자인 + spec 병렬	게이트는 issue status로
Notion	Product spec template (PRD + Design + Spec 탭)	통합 페이지로 단일 진실원천
Stripe	Spec → Design → Verify → Dev	spec versioning은 OpenAPI
Figma Dev Mode	디자인 → Code Connect 컴포넌트 매핑	디자인-spec 단방향
Vercel v0	Figma wireframe → AI 컴포넌트 자동 생성	spec이 코드 input
Toss	Figma 컴포넌트 기반 + 마크다운 wiki	한국 작은 팀 패턴

합의: 1. 디자인·spec 병렬, waterfall X 2. 단계별 게이트 (다음 단계 진입 조건 명시) 3. 작은 팀(2~3명) 최소 필수 = spec.md + qa-plan.md + CHANGELOG.md + wiki/log.md 4. 마케팅·CS·운영은 외부 Notion (코드 리포 밖) 5. 버전은 PRD(Notion) 버전과 1:1 매칭 (Stripe·Notion API 패턴)

Decision¶

1. 통합 개발 라이프사이클 — 12단계 (필수 8 + 선택 4)¶

필수 8단계 (ADR-0005 그대로)¶

#	산출물	위치
1	Notion 기획 raw sync	`raw/notion/<page>.md`
2	추상 concept	`wiki/concepts/<X>.md`
3	결정 사유 ADR	`wiki/decisions/ADR-NNNN.md` (필요 시)
4	Backend 구현 명세	`mvp-back/docs/frd/<X>/spec.md`
5	Frontend 구현 명세	`mvp-front/docs/frd/<X>/spec.md`
6	코드 구현	백 → 프 순서
7	도메인 인덱스 갱신	`wiki/domains/<X>.md`
8	변경 이력 append	`/log-append` → `wiki/log.md`

선택 4단계 (작은 팀 우선순위 낮음, 기능 규모에 따라)¶

#	산출물	위치	게이트
9	디자인 게이트	Figma 파일 (외부)	"Ready for dev" 마크 → 단계 4·5 진입 가능
10	QA 게이트	`<X>/qa-plan.md` (FRD 폴더 내)	E2E 시나리오 작성 → 단계 6 진입
11	마케팅·CS 산출물	외부 Notion `marketing/<slug>`, `operations/<slug>`	출시 1주 전
12	변경 이력 압축	`<X>/CHANGELOG.md` (FRD 폴더 내)	매 버전 신규 후

1.5. wiki/concept 페이지 v 단위 분리 정책 (사용자 추가 요청 2026-05-22)¶

모든 concept 페이지는 v 단위로 분리 (Minor·Breaking 무관 일관 분리):

시점	처리
v0.1 최초 작성	`wiki/concepts/<X>.md` 신규, `status: drafted`
v0.2 갱신	`wiki/concepts/<X>.md` → `status: superseded` + `supersedes_by: <X>-v0.2` (본문 보존) + 신규 `wiki/concepts/<X>-v0.2.md` (`status: drafted`, `supersedes: <X>`)
v0.3 이상	동일 패턴 — 매 v 단위마다 새 페이지 + 이전 페이지 superseded

근거: - 사용자 의도 "v0.1·v0.2 업데이트 과정이 보이도록" - Karpathy LLM wiki "decisions are forever" — concept도 역사 보존 - 사고력·챌린지 모두 동일 패턴 → 사람·LLM 인지 부담 최소

⚠ FRD spec.md와 다른 정책: - FRD spec.md: 활성 spec은 <X>/spec.md (frontmatter version) + archive에 v0.X 보관 - wiki/concept: 모든 버전을 페이지로 공존 (Karpathy 원칙 강화)

2. 버전 통일 정책 (Notion v0.x ↔ spec v0.x 1:1)¶

파일	표기
`mvp-back/docs/frd/<X>/spec.md` frontmatter `version`	Notion 페이지 버전 (`v0.1`, `v0.2`, ...)
`mvp-front/docs/frd/<X>/spec.md` frontmatter `version`	동상
`wiki/concepts/<X>.md` frontmatter `version`	동상
`archive/spec-vX.Y-YYYY-MM-DD.md` 파일명	Notion 버전 명시
`wiki/concepts/<X>-v0.Y.md` (신규 v 페이지)	Notion 버전 명시

원칙: - version 필드 = Notion 페이지 버전 (Notion이 source of truth) - breaking/minor 구분은 CHANGELOG + 변경 이력 표 "내용" 컬럼에서 표기 ("v0.2 — Breaking" / "v0.2 — Minor") - 신규 notion_version frontmatter 필드 추가 (Notion 페이지와의 매칭 명시) - API path versioning은 별도 (/api/v1/, /api/v2/ ...) — Notion 버전과 무관

3. CHANGELOG.md per feature¶

FRD 폴더에 단순 changelog. v0.1 ↔ v0.2 변경 trace를 git history 외 한 페이지에 압축.

포맷:

# <기능명> Changelog

## v0.2 (YYYY-MM-DD) — Breaking / Minor
- **Notion**: [v0.2 페이지](url)
- **ADR**: [[ADR-NNNN]]
- **변경**: 항목 나열
- **PR**: #NNN
- **Archived spec**: archive/spec-v0.1-YYYY-MM-DD.md (있을 때만)

## v0.1 (YYYY-MM-DD) — Initial
- **Notion**: [v0.1 페이지](url)
- **변경**: 최초 작성

4. 게이트 정책 (작은 팀 최소 운영)¶

게이트	진입 조건	게이트 위치
spec 확정	단계 4·5 완료 + 변경 이력 표 갱신	spec.md frontmatter `status: drafted → active` 시
코드 진입 (단계 6)	spec 확정 + (선택) Figma "Ready for dev" + (선택) qa-plan 작성	PR review 시 spec.md 갱신 동반
머지	단계 6 + 단계 7·8 완료	GitHub PR review + log.md append
출시	(선택) 단계 11 마케팅·CS 준비 완료	feature flag rollout 직전

작은 팀은 디자인 게이트·QA 게이트를 선택사항으로 운영. 기능 규모가 커지면 게이트를 강제로 격상.

Consequences¶

긍정: - 디자인·QA·마케팅 통합 흐름 명문화 → 큰 기능 출시 시 누락 방지 - 버전 통일 → Notion ↔ spec ↔ wiki ↔ archive 추적성 ↑ - CHANGELOG.md per feature → 사람·LLM이 한 페이지에서 변경 trace 확인 - 작은 팀 최소 필수와 풀 워크플로 분리 → 단계 가감 자유

부정: - 단계 수 증가 (8 → 12) → 인지 부담 - 버전 통일 작업 1회 (기존 spec v0.1/v0.2/v0.2 → v0.1/v0.2) — 본 PR에 포함 - 외부 Notion과 코드 리포 양쪽 관리 → 동기화 부담 (단 명확한 분리로 충돌 X)

Alternatives¶

옵션	평가
8단계 그대로 유지 (선택사항 없음)	❌ 디자인·QA·마케팅 흐름 누락
모든 게이트를 필수화 (12단계 의무)	❌ 작은 팀 over-engineering, 속도 저하
외부 Notion에 모든 단계 통합 (코드 리포 spec 제거)	❌ ADR-0004 (spec은 코드 옆) 위반, LLM 접근성 ↓
버전 semver (v0.1.0/v0.2.0) — 코드 버전 따로	❌ Notion ↔ spec ↔ wiki 매칭 어려움, 사용자 의도와 어긋남
✅ 채택: 12단계 (필수 8 + 선택 4) + Notion v0.x 매칭	작은 팀 최소 + 풀 워크플로 모두 지원

Status¶

2026-05-21: accepted

Date¶

2026-05-21