kjh2064
5e50ec6991
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>
49 lines
2.1 KiB
Markdown
49 lines
2.1 KiB
Markdown
# 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)
|