frd)¶

Context¶

이전 라운드(Track E, 2026-05-20)에서 사고력 답변구조 + 챌린지식 풀이의 Backend FRD를 wiki/concepts/*.md §4 안에 작성했음
결과: 각 concept 페이지가 ~150줄로 비대해짐. 추상 개념(왜·누가·원칙)과 구체 구현 명세(API 스키마·Flyway 번호·엔티티 필드·서비스 클래스명)가 한 파일에 섞임
사용자 의문 (2026-05-21): "FRD를 wiki 계층에 뽑아? 실제 백엔드 적용할 FRD는 따로 빼는 거야? 앤드류 카파시 어떻게 하는지 제대로 조사"

조사 결과¶

Karpathy 원의도 (Gist 2026-04-03): raw/ immutable + wiki/ 갱신 가능한 개념·결정·도메인 인덱스 + CLAUDE.md 스키마. "FRD" "spec" "implementation detail" 단어는 본문에 등장하지 않음 — wiki는 "개념의 인덱스이자 상호 참조 구조"
Karpathy 본인 적용 (nanochat): wiki/, docs/, specs/ 디렉토리 없음. 문서 = README + GitHub Discussions. 실제 구현부는 코드 폴더(nanochat/, scripts/) 가까이
업계 합의 (Google Design Doc, Spec-Driven Development): "specs belong in your repository, not in a wiki or a separate documentation system" (David Lapsley 2026-01)
운영 부담: wiki/concepts에 FRD를 두면 PR 작성 시 wiki + 코드를 동시에 갱신해야 하고, FRD가 stale인지 알아채기 어려움. code review 게이트도 wiki 분리되어 누락 가능성↑

Decision¶

Backend 구현 명세를 wiki 밖, 코드 옆으로 분리한다.

구분	위치	책임
추상 개념·원칙	`wiki/concepts/*.md`	"왜 이 기능? 누가 쓰나? 어떤 원칙?" — 추상, LLM이 매번 로드 (100k token 한도)
결정 사유	`wiki/decisions/ADR-NNNN-*.md`	Context·Decision·Consequences·Alternatives — 누적, supersedes로만 무효화
Backend 구현 명세	`mvp-back/docs/frd/*.md`	API 스키마·Flyway V번호·엔티티 필드·서비스 클래스명·권한 분기 — 구현자가 코드 옆에서 직접 참조
Frontend 구현 명세	`mvp-front/docs/frd/*.md` (subtree 연결 후)	화면·플로우·컴포넌트·route
도메인 인덱스	`wiki/domains/*.md`	도메인 한 줄 정의 + 코드 위치 링크 + FRD 역링크 — 컨텍스트 navigation 허브

구체 액션 (본 PR)¶

mvp-back/docs/frd/ 신설 — README + 사고력-답변구조.md + 챌린지식-풀이.md (8~11 sections 풀버전)
wiki/concepts/{사고력-답변구조,챌린지식-풀이}.md §4 슬림화 — 요약 5~10줄 + mvp-back:docs/frd/... 링크
wiki/domains/{qna,challenge}.md §3·§4 슬림화 — FRD 역링크
README.md "LLM wiki" 섹션의 FRD 위치 정책 명시

Consequences¶

긍정: - 구현자가 코드 옆에서 spec 직접 참조 → 코드 ↔ 명세 불일치 발견 즉시 - git blame / git log -- mvp-back/docs/frd/X.md 로 명세 변화 추적 - wiki는 100k token 한도 안에서 안정 (concept 페이지 ~30줄 수준 유지) - PR review에 FRD 갱신을 게이트로 강제 가능 (향후 hook) - Karpathy 원의도 + 업계 표준에 부합

부정: - frontmatter가 없는 코드 옆 spec은 wiki의 frontmatter validator/wiki-link 그래프 도구의 혜택 못 받음 (단 d-edu 규모에선 손실 미미) - 사람이 FRD 위치를 알아야 함 — README.md "LLM wiki" 섹션 + wiki/domains 역링크로 발견 가능성 확보 - 백엔드만 mvp-back/docs/frd, 프론트는 mvp-front/docs/frd 로 두 곳 → 모노레포 단일 spec 디렉토리(docs/specs/)보다 분산. 단 백/프 독립 구현 + 두 도메인 모델 다름이라 분산이 자연스러움

Alternatives¶

wiki/concepts §4 통합 유지 — 채택 X. Karpathy 원의도(wiki = 추상)와 어긋남. 비대화 가속화
루트 docs/specs/ 단일 디렉토리 — 채택 X. 모노레포라 백/프 분리가 자연스럽고, 두 모듈이 spec 형식·도구도 다름
wiki/spec/ 신설 (wiki 안에 별도 페이지 타입 추가) — 채택 X. wiki는 LLM이 갱신하지만 구현 명세는 사람·LLM 공동 갱신 + git review 게이트가 필요. 코드 옆이 자연스러움
mvp-back/src/main/.../docs/ (구현 디렉토리 안) — 채택 X. spec은 패키지 단위가 아니라 feature 단위 → 패키지 트리에 묻히면 발견성↓

Status¶

2026-05-21: accepted

Date¶

2026-05-21