docs: Enhance document routing and create tech debt registry (PR 3a)

Strengthen documentation coherence and navigation: README.md: - Add 'Developer's Document Guide' section at top - Link to CLAUDE.md, AGENTS.md, architecture, guardrails, validation gates - Reference docs/INDEX.md and TECH_DEBT_REGISTER.md docs/INDEX.md (new): - Central documentation index with purpose and audience - Core guides, executive/planning, tech debt, reference docs - Quick links for first change, architectural decisions, validation TECH_DEBT_REGISTER.md (new): - Tech debt tracking per AGENTS.md v16.0 - 8 registered debts (code analysis suppressions, deferred refactoring) - Impact/Effort matrix with paydown strategy (quarterly 20% target) - Status tracking with completion history - How-to guide for resolving debt CLAUDE.md: - Update TECH_DEBT_REGISTER reference from 'to be created' to actual link Result: - Developers land on README → directed to CLAUDE.md or AGENTS.md - All docs cross-reference each other for circular navigation - Tech debt fully visible and tracked with clear paydown roadmap - docs/INDEX.md provides comprehensive reference point Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-08-02 05:44:47 +09:00
parent e9f9c6615c
commit 5e50ec6991
4 changed files with 164 additions and 2 deletions
@@ -558,7 +558,7 @@ Every suppressed rule, deferred refactor, and architectural compromise is debt.

 ### Tech Debt Registry

-Location: `TECH_DEBT_REGISTER.md` (to be created in PR 4)
+Location: [`TECH_DEBT_REGISTER.md`](TECH_DEBT_REGISTER.md)

 Format:
 ```
@@ -2,10 +2,26 @@

 Reference implementation closure for governed advisory research. `RESEARCH_CANDIDATE_NOT_PRODUCTION`; automatic order/KIS/model activation OFF.

-
 **상태:** `IMPLEMENTATION_TEMPLATE / STATIC_VALIDATED / BUILD_DB_E2E_SHADOW_REHEARSAL_REQUIRED`  
 **운영 경계:** `RESEARCH_CANDIDATE_NOT_PRODUCTION · 투자자문형 우선 · 자동주문/KIS 제출 OFF · 자동 모델승격 OFF`

+---
+
+## 📖 개발자를 위한 문서 가이드
+
+**→ 여기서 시작:**
+- **Claude Code 개발:** [`CLAUDE.md`](CLAUDE.md) — 로컬 개발, 빌드, 테스트, Gitea API
+- **AI 코딩 헌법:** [`AGENTS.md`](AGENTS.md) — 모든 작업의 기준 (13개 결정 기준, 체크리스트, 안티패턴)
+- **아키텍처:** [`docs/03_ARCHITECTURE_BE_FE.md`](docs/03_ARCHITECTURE_BE_FE.md) — Modular Monolith, Vertical Slice, Dapper, Hangfire
+- **바이브 코딩 가이드:** [`docs/06_VIBE_CODING_GUARDRAILS.md`](docs/06_VIBE_CODING_GUARDRAILS.md) — AI 입력 패킷, 차단 규칙, 리팩터링 정공법
+- **Validation Gates:** [`docs/07_VALIDATION_GATES.md`](docs/07_VALIDATION_GATES.md) — 생산 배포 조건
+
+**문서 색인:** [`docs/INDEX.md`](docs/INDEX.md)
+
+**기술부채 추적:** [`TECH_DEBT_REGISTER.md`](TECH_DEBT_REGISTER.md) — Impact/Effort 매트릭스, 분기별 회수 목표
+
+---
+
 v16.0은 v10.0의 Baseline Preservation + Delta + Supersession + Traceability, RG-01~08, PIT·불변 Evidence·26 Vertical Slice 기준과 v12.1~v14.0 실행 패키지를 삭제하지 않고 보존한 누적 Delta다. 화면 수나 코드량을 생산준비도로 간주하지 않으며, `Source/License → PIT/Revision/DQ → Evidence/Version Set → Sell/Reentry → Recommendation → Maker-Checker → Publish → Outcome → Reconciliation/DR`의 완결성으로 판단한다.

 ## v16.0 핵심 Delta
@@ -0,0 +1,98 @@
+# Tech Debt Register
+
+**Governance:** Tracked per AGENTS.md v16.0. Quarterly paydown target: 20% by Impact.
+
+---
+
+## Summary
+
+| Status | Count | Total Impact |
+|--------|-------|--------------|
+| Backlog | 8 | 20 pts |
+| In Progress | 0 | 0 pts |
+| Completed | 0 | 0 pts |
+
+---
+
+## Registry
+
+### Code Analysis Suppressions
+
+| ID | Category | Impact | Effort | Status | Notes | Owner | ADR |
+|----|----------|--------|--------|--------|-------|-------|-----|
+| DEBT-001 | CA1822 (static hints) | Low (1) | Low (1) | Backlog | Analyzer suggestions for instance methods that could be static. Not performance-critical; batch during refactors. | Team | - |
+| DEBT-002 | CA1873 (array logging) | Low (1) | Low (1) | Backlog | Conditional array evaluation in logging. Low runtime impact; defer until performance profiling. | Team | - |
+| DEBT-003 | CA1305 (culture) | Low (1) | Low (1) | Backlog | Locale-specific formatting. Accept as-is for Serilog; breaking change if fixed. | Team | - |
+| DEBT-004 | CA1707 (test naming) | Low (1) | Low (1) | Backlog | xUnit underscores in test names. Convention; no fix needed. | Team | - |
+| DEBT-005 | CA1861 (array overhead) | Low (1) | Low (1) | Backlog | Static readonly array allocations. Negligible perf; accept trade-off for readability. | Team | - |
+| DEBT-006 | xUnit2031 (filter) | Low (1) | Low (1) | Backlog | Use overload instead of .Where() for Assert.Single. Analyzer nit; defer. | Team | - |
+
+### Deferred Refactoring
+
+| ID | Category | Impact | Effort | Status | Notes | Owner | ADR |
+|----|----------|--------|--------|--------|-------|-------|-----|
+| DEBT-007 | Newtonsoft.Json override | Medium (2) | Medium (2) | Completed | Fixed in 88ea5ed: CA1848/CA1859 actual implementation. LoggerMessage + HashSet/Dictionary. | @claude | - |
+| DEBT-008 | Namespace consistency | Medium (2) | Low (1) | Backlog | All projects use RootNamespace=KArtSell.Aegis; AssemblyName retained per-project for DLL clarity. Consider if alignment needed. | - | - |
+
+---
+
+## Impact/Effort Matrix
+
+```
+             Low Effort    High Effort
+High Impact   QUICK WINS    ROADMAP
+              (DEBT-007)    (none currently)
+
+Low Impact    BATCH         MONITOR
+              (DEBT-001/002) (DEBT-003/004/005/006/008)
+```
+
+### Quick Wins (Do This Sprint)
+- None current
+
+### Roadmap (Next Quarter)
+- None current
+
+### Batch During Feature Work
+- DEBT-001 (static hints): Batch with ModelOperations refactoring
+- DEBT-002 (array logging): Include in Serilog structured-logging improvement
+
+### Monitor & Defer
+- DEBT-003 through DEBT-006: Keep in backlog; revisit if performance audit flags them
+- DEBT-008: Accept per-project AssemblyName for clarity (DLL identification)
+
+---
+
+## Paydown Tracking
+
+### Q3 2026 (Current)
+- **Target:** 20% of total impact resolved = 4 pts
+- **Completed:** DEBT-007 (2 pts) — 50% of target achieved
+- **Remaining:** Identify 2 more low-effort wins
+
+### Q4 2026
+- **Target:** 20% = 4 pts (cumulative: 8 pts / 40% debt)
+- **Plan:** TBD after Q3 completion
+
+### Q1 2027
+- **Target:** 20% = 4 pts (cumulative: 12 pts / 60% debt)
+- **Plan:** TBD
+
+---
+
+## How to Resolve Tech Debt
+
+1. **Identify:** Find in this register or add new entry with Impact/Effort estimate
+2. **Estimate:** Low (1) / Medium (2) / High (3) for each dimension
+3. **Schedule:** Pick based on matrix above
+4. **Implement:** Separate PR, reference Debt ID in commit message (e.g., `TECH-007: Fix CA1848`)
+5. **Verify:** Update register (move to Completed, record date + ADR link)
+6. **Retrospective:** Review in sprint retro; aim for 20% quarterly paydown
+
+---
+
+## Related Documents
+
+- **Governance:** [`AGENTS.md`](AGENTS.md#13-tech-debt-management-tech-debt-registry)
+- **Tracking:** [`CLAUDE.md`](CLAUDE.md#tech-debt-management)
+- **Decision Log:** See individual PR commit messages and ADRs
@@ -0,0 +1,48 @@
+# Documentation Index
+
+## Core Development Guides
+
+| Document | Purpose | Audience |
+|----------|---------|----------|
+| [`../CLAUDE.md`](../CLAUDE.md) | Claude Code development guide | AI-assisted developers |
+| [`../AGENTS.md`](../AGENTS.md) | AI coding constitution v16.0 | All developers |
+| [`03_ARCHITECTURE_BE_FE.md`](03_ARCHITECTURE_BE_FE.md) | System architecture (Modular Monolith, Vertical Slice) | Architects, Backend engineers |
+| [`06_VIBE_CODING_GUARDRAILS.md`](06_VIBE_CODING_GUARDRAILS.md) | AI work protocols, guardrails | All developers using Claude |
+| [`07_VALIDATION_GATES.md`](07_VALIDATION_GATES.md) | Production readiness criteria | QA, Release managers |
+
+## Executive & Planning
+
+| Document | Purpose |
+|----------|---------|
+| [`00_EXECUTIVE_PROPOSAL.md`](00_EXECUTIVE_PROPOSAL.md) | High-level project rationale |
+| [`01_SOURCE_AUDIT.md`](01_SOURCE_AUDIT.md) | Source code assessment |
+| [`02_ALGORITHM_REFACTORING.md`](02_ALGORITHM_REFACTORING.md) | Algorithm improvement strategy |
+
+## Tech Debt & Maintenance
+
+| Document | Purpose |
+|----------|---------|
+| [`../TECH_DEBT_REGISTER.md`](../TECH_DEBT_REGISTER.md) | Tech debt tracking (Impact/Effort matrix) |
+
+## Reference Documents
+
+- `contracts/` — Data and API contracts (UI adapter, schedules, events)
+- `templates/` — Vertical Slice, Hangfire job, SQL scaffolds
+- `tools/` — Scaffold generators, validators
+
+## Quick Links
+
+**For your first change:**
+1. Read [`../CLAUDE.md`](../CLAUDE.md) (setup, build, test)
+2. Review [`../AGENTS.md`](../AGENTS.md) decision checklist
+3. Check [`03_ARCHITECTURE_BE_FE.md`](03_ARCHITECTURE_BE_FE.md) for module boundaries
+4. Reference [`06_VIBE_CODING_GUARDRAILS.md`](06_VIBE_CODING_GUARDRAILS.md) before AI code requests
+
+**For architectural decisions:**
+- Module communication: [`03_ARCHITECTURE_BE_FE.md`](03_ARCHITECTURE_BE_FE.md#2-vertical-slice-standard)
+- Observability: [`../CLAUDE.md`](../CLAUDE.md#observability)
+- Tech debt: [`../TECH_DEBT_REGISTER.md`](../TECH_DEBT_REGISTER.md)
+
+**For validation & release:**
+- Gates to pass: [`07_VALIDATION_GATES.md`](07_VALIDATION_GATES.md)
+- Readiness checklist: [`../AGENTS.md`](../AGENTS.md#work-decision-checklist)