0003. 모든 문서를 허브 한 곳에서 관리한다 (스포크 docs 폐지)
맥락 (Context)
hub-and-spoke(핸드오프 2.1)는 구현 심화 문서를 코드 레포에 두어 “코드 PR에 문서 포함” 결합을 확보하는 설계였다. 그러나 실제 운영에서 문서가 3레포에 흩어져 “한 곳에서 한번에 보고 관리”가 어려웠고, 읽기 통합(Quartz aggregate)만으로는 부족하다는 판단이 나왔다. 결정적으로 문서 갱신 주체가 사람 단독이 아니라 AI 에이전트다 — 에이전트는 레포 경계와 무관하게 코드 변경 시 허브 문서를 함께 갱신할 수 있으므로, “같은 레포여야 결합이 성립한다”는 전제가 약해졌다.
고려한 옵션 (Considered Options)
- 옵션 A: hub-and-spoke 유지 + Quartz aggregate — 저장 분산, 읽기만 통합. (AI 추천안)
- 옵션 B: 전면 중앙화 — 모든 문서를 허브
docs/로, 스포크엔 포인터만. - 옵션 C: 미러 동기화 — 원본 스포크, 허브에 복사본. (두 사본 = 최악의 부패, 즉시 기각)
결정 (Decision)
옵션 B, 단 “지식 문서”에 한정. 문서 부패 위험을 알고 감수한다 — 흩어진 문서의 관리 비용이 부패 위험보다 크다고 판단. 팀이 같이 보는 지식(명세·as-built·API 맥락·기획·정책·감사 기록)은 BE docs/be/, FE docs/fe/로 허브에 모은다.
예외 — 그 레포에서 일할 때만 쓰는 문서는 코드 옆 유지:
tapple-be/openapi/openapi.yaml— 계약 원본. CI가 코드와 diff 검증해야 하므로 코드 옆 (ADR-0002 불변).- 각 레포
CLAUDE.md— AI 진입점은 레포마다. - 레포 작업 문서: 구현 규칙, 테스트 작성 가이드, 온보딩, 서비스 계획, 레포-로컬 ADR(
docs/adr/) — 순수 그 레포 작업자용. - 내부 작업물(
superpowers/등) — 문서 아님.
판정 한 줄: “상대 직군/레포가 볼 일이 있나?” 있으면 허브, 없으면 코드 옆.
결과 (Consequences)
- 좋아지는 것: 한 레포에서 전 문서 관리·검색·그래프. Quartz가 크로스레포 checkout 없이 전체 렌더(aggregate 파이프라인 제거). 링크가 전부 상대경로 — 도구 무관.
- 감수하는 것: 코드 변경과 문서 갱신이 다른 레포로 갈라짐 — 부패 방지선이 사라짐.
- 부패 완화 장치: FE/BE
CLAUDE.md에 “API·동작 변경 시 tapple-docs의 해당 문서를 같은 작업에서 갱신” 규칙 명시. AI 에이전트 워크플로우가 이를 수행한다.
재검토 조건
문서와 코드의 불일치가 실제 사고(잘못된 계약 참조로 인한 재작업)를 2회 만들면, 해당 문서 유형을 다시 코드 레포로 되돌리는 부분 롤백을 검토한다.