ADR-0011 — LLM wiki 중간 레이어 역할 재정의¶

Context¶

사용자 깊은 의문 (2026-05-22):

"노션에서 화면 흐름 정의하고 frontend docs에 FRD를 놓는다. 그럼 중간 wiki에선 뭘 해야 하는가? 만약 기획이 바뀌면 노션에서 업데이트를 하는 것인가? 애초에 LLM wiki 중간 레이어 존재 목적은? LLM wiki 중간 레이어가 업데이트되면 자연스럽게 FRD도 업데이트되어야 하는 것 아닌가? 그럼 개발은 LLM wiki 중간 레이어를 바라봐야 하는가? 잘나가는 스타트업은 어떻게 하고 있지?"

이전 조사의 시정¶

이전 Explore agent (2026-05-22)가 "잘나가는 스타트업 대부분 wiki 중간 레이어 미사용 → d-edu도 폐기 권장"으로 결론. 사용자 정당히 반박:

"Karpathy의 LLM wiki는 3단 레이어가 생명인데"

Karpathy Gist 원문 재확인 (WebFetch 2026-05-22): - "The wiki is a persistent, compounding artifact" — 핵심 가설 - 3계층 (raw + wiki + schema) = 본질 - "The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping" - LLM = cross-referencing·consistency update 담당. 사람 = sourcing·questions 담당 - "Cross-references are already there" — wiki는 prebuilt 인덱스

정확한 해석¶

사실	의미
잘나가는 스타트업 wiki 미사용 (Linear·Notion·Anthropic·Stripe·GitHub Spec-Kit·Karpathy nanochat)	그 회사들은 다른 패턴 (Notion-first / Spec-first / CLAUDE.md-centric) 채택
d-edu는 ADR-0002 Karpathy LLM wiki 패턴 채택	3단 레이어 유지가 일관성
Tom Nguyen 6개월 실운영 보고 — "wiki는 명시적 프롬프트 없이 참조 안 됨"	Karpathy 패턴 약점 — d-edu가 LLM에 명시적 프롬프트로 wiki 로드 필요

Decision¶

wiki 중간 레이어 유지 + 각 sub-디렉토리 책임 명확화.

각 sub-디렉토리 책임¶

위치	역할	갱신 주체
`wiki/concepts/<X>.md`	추상 합의 — "왜 이 기능? 누가 쓰나? 어떤 원칙?". FRD가 "무엇·어떻게"라면 concept은 "왜·누가"	LLM 갱신, 사람 review
`wiki/decisions/ADR-NNNN.md`	결정 사유 누적 — Context·Decision·Consequences·Alternatives. 코드 옆 spec엔 안 들어감	사람·LLM 공동 작성
`wiki/domains/<X>.md`	navigation 허브 — 도메인별 모든 wiki·spec·코드 link 모음	LLM 갱신, 사람 review
`wiki/log.md`	append-only 변경 이력 — 사람·LLM 친화 요약. git history와 별도 의미 (시간·actor·type 메타)	슬래시 명령 `/log-append`
`wiki/index.md`	wiki 카탈로그 — LLM 진입 시 첫 페이지. 모든 wiki 페이지 list	슬래시 명령 `/wiki-ingest` 자동

레이어 간 흐름¶

┌─────────────────┐
│  Notion (PRD)   │ ← 기획자가 직접 작성
└────────┬────────┘
         │ /sync-notion (수동, 향후 자동 검토)
         ▼
┌─────────────────┐
│  raw/notion/    │ ← immutable, LLM 읽기만 (hook 차단)
└────────┬────────┘
         │ LLM이 bookkeeping (wiki librarian)
         ▼
┌──────────────────────────────────┐
│  wiki/ (LLM 갱신, 사람 review)    │ ← 컴파일된 LLM 컨텍스트
│  - concepts (추상)               │
│  - decisions (ADR)               │
│  - domains (navigation)          │
│  - log (시계열 변경)             │
└────────┬─────────────────────────┘
         │ 사람이 spec 작성 (LLM 보조)
         ▼
┌─────────────────────────────────┐
│  mvp-{back,front}/docs/frd/     │ ← 코드 구현 명세
│    <X>/spec.md (per-feature)    │
└────────┬────────────────────────┘
         │ 사람·LLM 코드 작성
         ▼
┌─────────────────────────────────┐
│  코드 (mvp-back/src, mvp-front) │
└─────────────────────────────────┘

중요한 분업: - 개발자는 spec.md만 본다. wiki는 LLM이 자동 로드 (Karpathy: "LLM은 사서, 사람은 큐레이터") - 기획자는 Notion만 갱신. wiki·spec은 LLM/개발자가 단계별 propagation - 자동 propagation은 미도입 (사용자 결정 "나중에. 자동 시기 애매함")

Consequences¶

긍정¶

Bookkeeping 자동화: LLM이 cross-reference + consistency 관리 → 사람 부담 ↓
결정 누적 (ADR): 다른 패턴에선 결정 사유가 PR 코멘트에 흩어짐. wiki/decisions는 영구 누적
LLM 컨텍스트 효율: raw 1MB → wiki 100KB로 압축. 매 질문마다 wiki만 로드해도 충분
Karpathy 패턴 일관성: ADR-0002 채택 결정과 정합

부정¶

Sync 비용: Notion → raw → wiki → spec → 코드 5단계 수동 (단 LLM이 wiki bookkeeping 자동화로 일부 상쇄)
작은 팀 운영 부담: 큰 팀에 최적화된 패턴을 작은 팀이 쓰면 over-engineering 위험 — d-edu는 Karpathy 본인 가설 검증 의미도 있음
명시적 프롬프트 필요: LLM이 wiki 참조하려면 사람이 "wiki/concepts 확인해줘" 같은 명시 필요 (Tom Nguyen 검증)

Alternatives 거부¶

옵션	평가
Notion-first (Linear, Notion 본인 패턴)	❌ ADR-0002 Karpathy 패턴 폐기. 결정 누적·LLM 컨텍스트 누적 가치 상실
Spec-first (GitHub Spec-Kit)	❌ 추상(concept)·결정(ADR) 위치 불명. 큰 결정이 spec에 묻혀 검색 어려움
CLAUDE.md-centric (Anthropic)	❌ 단일 파일로 추상·결정·도메인·로그 모두 → 비대화. 작은 팀에도 부적합
wiki 폐기	❌ 이미 작업한 wiki commit 38개 손실. Karpathy 패턴 채택 결정 (ADR-0002) 무효화

향후 검토 항목¶

자동 propagation (사용자 결정 "나중에"):
LLM agent가 raw/notion/ 변경 감지 → wiki/concepts·domains·log 자동 갱신 PR
Track F (코드 구현) 끝난 후 검토 (1~2주 후)
GitHub Spec-Kit 패턴 참고 가능
wiki 운영 비용 측정:
wiki 갱신에 들어가는 사람·LLM 시간 트래킹
6개월 후 ROI 평가 → 필요 시 슬림화 또는 자동화 강화
명시적 프롬프트 표준화:
LLM이 코드 작업 시 자동으로 wiki 진입하도록 CLAUDE.md "Reading order"에 강제

Status¶

2026-05-22: accepted

Date¶

2026-05-22