docs: 문서 재정리 — historical 223개 압축/삭제 + DOCS.md SoT 지도 (md 268→66) #225
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: altair823-org/kebab#225
Reference in New Issue
Block a user
Delete Branch "docs/reorg"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
요약
여러 세션 누적으로 ~268개 md 로 불어난 문서를 재구조화·압축해, "현재 코드베이스의 진실(SoT)이 뭔지, 어느 문서가 최신인지"를 즉시 알 수 있게 한다. 사용자 지침: stale·outdated 정보 최대한 감축, diverged 과거 문서 destructive 허용, durable 내용은 삭제 전 living 문서로 흡수(안전망), 원본은 git history 보존.
5-에이전트 전수 분석 → 방안 C(max-compress) 승인 → 7-phase 실행. md 문서 268 → 66 (−202), −81,677줄.
설계:
docs/superpowers/specs/2026-06-27-doc-reorg-design.md무엇이 바뀌나
신규 (SoT 명확화)
DOCS.md(root) — 문서 지도: "알고 싶은 것 → 어느 문서가 진실" 표 + 구역(living/계약/증거) 맵. 사용자 1순위 pain 직접 해소.CHANGELOG.md(root) — release 변경 이력 인덱스.삭제 (223개, git history 보존)
docs/superpowers/plans/(64) ·handoffs/(8) ·poc/+research/(3) — 머지 완료 작업의 실행/측정 스캐폴딩 (durable 0 또는 HOTFIXES 에 이미 있음).tasks/p0..p10/(86) ·docs/superpowers/specs/feature specs (55) — 작업/feature 설계, 코드+HOTFIXES+ARCHITECTURE 가 대체.docs/spec/스텁 (7) — 오펀 포인터(inbound 0).durable 보존 (삭제 전 흡수 — 안전망)
슬림 (stale 제거)
HANDOFF.md181→45줄 (한 줄 요약이 v0.18.0 이었음 → 현재 v0.32.0 phase 대시보드).tasks/INDEX.md185→40줄 (삭제될 spec 으로 82 링크 → per-component 상태 표).유지
2026-04-27-final-form-design.md(frozen, 유일 계약) + 본 doc-reorg spec.검증
docs/superpowers/= specs 2개,tasks/p*/없음, 스텁 없음.git log --all -- <path>/git checkout <sha> -- <path>.비범위
시험 항목 (Test Plan)
DOCS.md하나로 "현재 진실/최신/계약/증거" 식별 가능.git log --all -- docs/superpowers/plans/로 삭제 원본 복구 가능.Assisted-by: Claude Code
초안의 archive-이동 안은 폐기(frozen 끼리 결합도 높아 이동이 무결성 깸). 사용자 지침("stale 최대한 줄이기, diverged 과거 문서 destructive 허용, durable 은 삭제 전 living 흡수")을 반영. 5-에이전트 전수 분석 근거로 확정 범위(C): - 삭제(~220, git 보존): plans 64 + handoffs 8 + 스텁 7 + tasks/p* 86 + feature specs 55 - 유지: 설계 계약(2026-04-27) + 본 spec + 모든 living + release-notes + 증거 - 추출(안전망): durable 4건(LanceDB upsert/RAG score-gate/PDF chunk_id 충돌/ heading 우선순위) → ARCHITECTURE, 의존성 경계표 → CLAUDE.md - DOCS.md(SoT 지도)·CHANGELOG.md 신설, HANDOFF/INDEX/HOTFIXES/components 슬림 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8Ladoc-reorg(C) Phase 2: - DOCS.md (root): "알고 싶은 것 → SoT" 표 + 구역(living/계약/증거) 맵 + "삭제된 historical = git history, durable 은 living 흡수" 선언 + 재발방지 원칙. → 사용자 1순위 pain("뭐가 최신/진실인지") 직접 해소. - CHANGELOG.md (root): release-notes 9개 역순 인덱스 + gitea 링크, 미문서화 구간(v0.1~v0.19/v0.21~v0.27)은 Gitea releases 참조 명시. - README 상단에 DOCS.md 포인터 1줄. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8Ladoc-reorg(C) Phase 6: 사용자 지침("stale 최대한 줄이기, diverged 과거 문서 destructive 허용")에 따라 머지 완료 작업의 historical 스캐폴딩 제거. 삭제 (git rm, history 보존): - docs/superpowers/plans/ (64) — worker 실행 스캐폴딩, durable 0 - docs/superpowers/handoffs/ (8) — 측정 기록, durable 은 HOTFIXES 에 있음 - docs/superpowers/{poc,research}/ (3) — OCR PoC 비교 + 제거된 expansion 연구 - docs/spec/ (7) — 설계 계약으로 향하는 오펀 스텁(inbound 0) - tasks/p0..p10/ (86) — 작업별 frozen 계약, 코드+HOTFIXES 가 대체 - docs/superpowers/specs/ feature specs (55) — feature 설계, 코드+ARCHITECTURE 대체 유지: - docs/superpowers/specs/ = 설계 계약(2026-04-27) + 본 doc-reorg spec 2개만 - tasks/ = INDEX/HOTFIXES/_template/phase-* (living) - durable invariant 4건 → ARCHITECTURE, 의존성 경계표 → CLAUDE (Phase 1 에서 흡수 완료) 복구: git log --all -- <path> / git checkout <sha> -- <path>. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012Mc6W1fgsrbFKTsqA6P8La