ADR-0005 — FRD 폴더 구조 + 8단계 워크플로 + Versioning¶

Context¶

ADR-0004 (2026-05-21)에서 Backend FRD를 wiki에서 mvp-back/docs/frd/X.md 로 분리했다. 다만 세 가지 후속 질문이 미해결로 남았다:

Frontend FRD 는 어떤 위치·형식인가? — mvp-front/docs/frd/ 신설 시 Backend와 같은 구조인가?
단일 파일 vs 폴더 — frd/사고력-답변구조.md 한 파일에 API/엔티티/Flyway 다 때려박는 구조 맞는가?
기획 변경·버전업 처리 — 중간에 기획이 바뀌거나 v2가 나올 때 FRD를 어떻게 다루는가?

사용자가 (2026-05-21) "잘나가는 스타트업이 어떻게 하는지 super hard thinking" 으로 정밀 조사를 요청.

조사 결과¶

5가지 업계 패턴:

패턴	대표	d-edu 적합도
Full Design Doc (20+ pages)	Stripe, Google	❌ 과함
Spec-Driven Dev (per-feature spec.md)	GitHub Spec Kit, Anthropic, OpenAI	✅ 채택
Lightweight RFC	Linear, GitLab	△ 토론 위주, 구현 명세 부족
Code-First / No spec	Karpathy nanochat	❌ LLM hallucination 위험
Component-Driven (PRD + Tech spec 분리)	Notion, Figma	△ 큰 팀용

합의 (2025-2026): - 팀 ≤ 5명 → 단일 파일 OK (Linear, Notion) - 팀 ≥ 10명·큰 기능 → 폴더 + index (GitHub Spec-Kit specs/{번호}-{이름}/) - API versioning 복잡 → 버전 폴더 (Stripe /latest/ + /preview/, Shopify 12개월 후방 호환) - LLM 시대 → spec-driven dev로 AI hallucination 40~50% 감소 (Thoughtworks 2025)

Decision¶

1. FRD 폴더 구조 (Backend·Frontend 동일)¶

{mvp-back,mvp-front}/docs/frd/
├── README.md              # 인덱스 + 작성 규약 + versioning 정책
├── <기능 슬러그>/
│   ├── spec.md            # 메인 명세
│   └── archive/           # v0.X 보관용 (versioning 시나리오 2/3 대비, .gitkeep)
└── (다음 기능 폴더)

한 기능 = 한 폴더 = 한 spec.md
평소 단일 파일 ROI 유지
향후 sub-spec 필요 시 같은 폴더에 자연스럽게 추가 (api-contract.md, state-machine.md)
백/프 동일 구조 — 사람·LLM 인지 부담 최소

2. Frontend FRD 형식 — Spec-Driven Dev 변형 (8 sections, 60~100줄)¶

§	섹션	목적
1	Problem / Goal	2~3 sentences. 사용자 pain + 비즈니스 의도 + Success 정의
2	User Scenarios	3~5 concrete flows (페르소나 명시)
3	Data Contract	Backend FRD §2 API 매칭, request/response JSON shape
4	FSD Mapping	features/widgets/entities/shared 어느 slice
5	Edge Cases / Defer	1차 MVP에서 안 하는 것 (refactor 방지)
6	Success Metrics	analytics 이벤트명 + funnel
7	Related Specs	Backend FRD + Figma + E2E spec path
8	Open Questions	코드 들어가기 전 합의 미해결

Skip: 전체 route list (app router 자체가 명세) · Zustand store shape (TanStack DevTools) · 스타일 가이드 (tailwind.config) · 컴포넌트 prop types (TS 자동완성).

Backend FRD는 더 풀버전 (8~11 sections — Flyway·서비스 클래스명·권한 분기 등 추가).

3. 신규 기능 개발 워크플로 (8단계)¶

1. /sync-notion <page-id>                → raw/notion/<page>.md
2. wiki/concepts/X.md                    → 추상 (9 sections: 왜·누가·원칙)
3. wiki/decisions/ADR-NNNN.md            → 결정 사유 (필요 시)
4. mvp-back/docs/frd/<X>/spec.md         → Backend 구현 명세
5. mvp-front/docs/frd/<X>/spec.md        → Frontend 구현 명세
6. 코드 구현 (Track F)                   → 백 → 프, spec.md를 LLM/사람 input으로
7. wiki/domains/{관련}.md                → navigation 허브 (FRD 역링크)
8. /log-append <type> "<요약>"           → wiki/log.md

4. Versioning 정책 (3 시나리오)¶

시나리오	절차
v0.1 → v0.2 (소소한 수정, breaking 아님)	`spec.md` overwrite + frontmatter `version: v0.2` + 변경 이력 표에 1줄. git log로 추적
v0.X → v0.2 (breaking change)	새 ADR 작성 → 기존 `spec.md`를 `archive/spec-v0.X-YYYY-MM-DD.md`로 mv → 새 `spec.md` 작성. 코드는 `/api/v2/` 새 path 도입
v0.2 신규 서비스 (완전 병행)	별도 기능 폴더 신설. 기존 기능 그대로 유지 (둘 다 ACTIVE 상태로 동시 지원)

5. spec.md frontmatter 표준¶

---
feature: 사고력-답변구조
version: v0.1
status: drafted          # drafted | active | superseded | archived
updated: 2026-05-21
related_wiki_concept: "[[wiki/concepts/사고력-답변구조]]"
related_frontend_frd: "[[mvp-front:docs/frd/사고력-답변구조/spec]]"   # frontend FRD에서만 backend 링크
related_adr: [ADR-0004, ADR-0005]
---

Consequences¶

긍정: - 백/프 동일 구조 → 일관성 + 인지 부담 최소 - archive/ 폴더로 versioning 시나리오 2/3 깔끔 처리 - 폴더 단위라 sub-spec 추가가 자연스러움 (over-engineering 없이 확장) - spec-driven dev → LLM 코드 생성 hallucination 40~50% 감소

부정: - 디렉토리 깊이 1 단계 증가 (frd/X.md → frd/X/spec.md) - archive/ 폴더가 초반 빈 채로 — 단 .gitkeep으로 명시

Alternatives 평가¶

옵션	평가
단일 파일 유지 (ADR-0004 그대로)	❌ 사용자 의도("폴더 분리") 미충족. 향후 sub-spec/versioning 어색
API/엔티티/상태 각 sub-spec 강제 분리	❌ 작은 기능엔 over-engineering. 매번 5개 파일 갱신 비용
백 = 단일 파일, 프 = 폴더 (비대칭)	❌ 일관성 깨짐, 사람·LLM 혼란
루트 `docs/specs/` 통합	❌ 모노레포라 백/프 분리가 자연스러움

Status¶

2026-05-21: accepted

Date¶

2026-05-21