diff --git a/CLAUDE.md b/CLAUDE.md index 09eb8a01..b8d63260 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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: ``` diff --git a/README.md b/README.md index f55264d1..0f251ba9 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/TECH_DEBT_REGISTER.md b/TECH_DEBT_REGISTER.md new file mode 100644 index 00000000..b0079b47 --- /dev/null +++ b/TECH_DEBT_REGISTER.md @@ -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 diff --git a/docs/INDEX.md b/docs/INDEX.md new file mode 100644 index 00000000..510ee882 --- /dev/null +++ b/docs/INDEX.md @@ -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)