docs/ 폴더 최적화 + broken ref 부채 일괄 해소
요약docs/ 루트에 산재한 23 파일을 의미 단위 서브디렉토리로 정리하여 트리 깊이 1단계 일관성 회복
구현 Phase
루트 단발 sprint 노트 3 (sprint-{40,48,51}-*.md) → adr/sprints/sprint-{NN}.md + Sprint 62+ frontmatter 컨벤션 보정
runbook 14개 → docs/runbook/ + 영역별 인덱스 README. 단, sed 결과 19개 cross-ref가 staging 누락으로 commit에서 제외
sprint-95-programmers-dataset.md → docs/adr/topics/ (5 cross-ref 갱신: sprint-95 ADR + gateway TS JSDoc + 2 README)
broken ref 5종 23회 참조 일괄 정리 — 3 신규 작성(monitoring-logging.md §1~§11 / ci-cd.md §1~§7 / annotation-dictionary.md 13 guard + 10 event + 16 domain) + 24 sed + 1 ref 제거
주요 결정
Phase A/D/E/F
위치 이동 (git mv) + 본문 불변 + Phase D 카테고리(conventions/ / patterns/) 일관성 적용
Phase B
정리본 .md만 영구 보존, 원시 .jsonl은 비보존 — docs/audits/README.md에 SSOT 명문화
Phase C
신규 진입자 navigation을 위해 docs/README.md + docs/adr/README.md 인덱스 신규
Phase G
broken ref 5종 부채를 본 sprint 범위에 포함 — 코드 주석에 박힌 monitoring-log-rules §섹션 13개를 정확히 매칭하는 stub 작성으로 해소
목표
- docs/ 루트에 산재한 23 파일을 의미 단위 서브디렉토리로 정리하여 트리 깊이 1단계 일관성 회복
- audit 산출물 보존 정책 명문화 + raw jsonl 부피 제거
- 검증 중 발견한 미작성 문서 5종(23회 broken ref) 일괄 해소
결정
- Phase A/D/E/F: 위치 이동 (
git mv) + 본문 불변 + Phase D 카테고리(conventions//patterns/) 일관성 적용 - Phase B: 정리본
.md만 영구 보존, 원시.jsonl은 비보존 —docs/audits/README.md에 SSOT 명문화 - Phase C: 신규 진입자 navigation을 위해
docs/README.md+docs/adr/README.md인덱스 신규 - Phase G: broken ref 5종 부채를 본 sprint 범위에 포함 — 코드 주석에 박힌
monitoring-log-rules §섹션13개를 정확히 매칭하는 stub 작성으로 해소 - 모든 phase 독립 PR + Squash merge — 변경 범위/위험도 분리
구현 (8 PR squash merge, origin/main 3873f6d → 661cd59)
사고 1건 + 복구 1건
- 사고: Phase E PR #240에서
git mv+ 신규 README는 commit됐으나 sed로 처리한 cross-ref 갱신 19 파일이 staged area 누락으로 commit에서 제외 → main에 broken link 19건 노출 - 부수 사고: 머지 전 워킹트리 변경 분리를 위해
git stash push -u했다가 hotfix 직후git stash drop으로 stash 제거 → 함께 stashed된 untracked sprint-149/150/151/152.md ADR 4건이 손실 - 복구:
- PR #241로 cross-ref 19건 일괄 복원 (CI green merge)
- 손실 ADR 4건은
git fsck --no-reflogs --unreachable→ stash commit792f75bd의 3rd parent tree에서 4 blob 모두 100% 복구
Phase G 부채 해소 상세
| 슬러그 (미작성) | 해소 방식 | 영향 파일 |
|---|---|---|
monitoring-log-rules.md | conventions/monitoring-logging.md 신규 작성 — 코드 주석 §1~§11-2 13개 §섹션 정확히 매칭 (구조화 로깅 / sanitize / Saga / MQ / 에러 코드 / slow query / 메트릭 / Prometheus alert) | 15 |
ci-cd-rules.md | conventions/ci-cd.md 신규 작성 — Conventional Commits + 브랜치/PR/CI/보안/의존성/배포 (§7-2 Layer 순차) | 3 |
annotation-dictionary.md | conventions/annotation-dictionary.md 신규 작성 — @guard 13 + @event 10 + @domain 16 catalog | 3 |
migration-rules.md | conventions/migration-naming.md로 ref 갱신 (Phase D conventions/ 활용) | 1 |
work-progress-guide.md | scribe.md ref 제거 (단일 참조 + 미작성 문서) | 1 |
| 합계 | 3 신규 + 24 sed + 1 ref 제거 | 23회 broken link 해소 |
검증
- 8 PR 모두 CI fail 0, mergeStateStatus CLEAN ✅
- 4 슬러그 broken ref grep: 0건 (
monitoring-log-rules/ci-cd-rules/migration-rules/work-progress-guide) - docs/ 루트 파일 수: 23 → 1 (README.md만 잔존)
- docs/ 트리 깊이 1단계 일관성 회복 (
adr/audits/assets/conventions/patterns/runbook/모두 서브디렉토리) - docs/ 부피: 1.7M → 1.5M (audits raw 260K 제거)
- conventions 6개로 확장 (3개 신규 + 3개 기존)
브랜치 규율
✅ 19 스프린트 연속 준수 — 8 PR 모두 신규 브랜치 + Squash merge, main 직접 commit 0건 (Sprint 134 위반 이후)
신규 패턴
- 재검증으로 "범위 외" 평가 깨기 — 이전 plan에서 "cross-ref 영향 큼"으로 범위 외 처리한 컨벤션/패턴 6개를 Phase D 진입 전 재검증 → cross-ref 0건 확인 후 즉시 처리. 그동안 누적된 "안전한데 미해소" 부채 발굴 가능성
- 부채 발견 → 본 sprint 범위 확장 (Phase G) — 검증 중 broken ref 23건 발견 → 별도 sprint 이월하지 않고 즉시 처리. 단일 sprint 안에서 "정리 + 검증 + 추가 부채 해소" 사이클 완결
- 코드에 박힌 §섹션 번호로 stub 작성 가이드 —
monitoring-log-rules §1~§1113개 §섹션이 코드/인프라 주석에 박혀있어 stub 작성 시 정확한 섹션 번호 + 의미를 코드에서 역으로 추출 가능. "코드가 문서의 정의역을 강제한다" 패턴 git fsck --no-reflogs --unreachable로 stash drop 손실 복구 —git stash drop후에도 stash commit이 GC 전까지 unreachable 상태로 잔존. 3rd parent tree에서 untracked blob까지 100% 복구 가능- 단일 sprint 8 PR + 1 hotfix 묶음 — Sprint 150 (3 PR) / 152 (3 PR) 패턴 확장. 각 PR 영향 범위 분리 + CI green merge 순차 진행으로 위험 점진 흡수
관련 메모리
- sprint-window.md
- feedback-blog-workflow — 사용자 검증 사이클 패턴 직접 재확인