From 354c18b5b8709c39def3018bca913faf0b73ef0d Mon Sep 17 00:00:00 2001 From: Phil Skentelbery Date: Mon, 24 Nov 2025 10:28:55 -0700 Subject: [PATCH] docs: Add comprehensive documentation navigation guide to CLAUDE.md Added "Documentation Navigation" section with: - Clear explanation of docs/ folder structure and purpose of each subdirectory - Guidelines for finding existing documentation before implementing features - Practical rules for when to create ADRs, design docs, reports, or standards - File naming conventions for different document types This improves agent and developer ability to navigate the documentation system and maintain proper organization standards. Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index b8cf123..443f352 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,7 +29,54 @@ When invoking the agent-developer, always remind it to: - Create feature branches for non-trivial changes - Write clear commit messages -## Key Documentation References +## Documentation Navigation + +### Understanding the docs/ Structure + +The `docs/` folder is organized by document type and purpose: + +- **`docs/architecture/`** - System design overviews, component diagrams, architectural patterns +- **`docs/decisions/`** - Architecture Decision Records (ADRs), numbered sequentially (ADR-001, ADR-002, etc.) +- **`docs/deployment/`** - Deployment guides, infrastructure setup, operations documentation +- **`docs/design/`** - Detailed design documents, feature specifications, phase plans +- **`docs/examples/`** - Example implementations, code samples, usage patterns +- **`docs/projectplan/`** - Project roadmaps, implementation plans, feature scope definitions +- **`docs/reports/`** - Implementation reports from developers (dated: YYYY-MM-DD-description.md) +- **`docs/reviews/`** - Architectural reviews, design critiques, retrospectives +- **`docs/standards/`** - Coding standards, conventions, processes, workflows + +### Where to Find Documentation + +- **Before implementing a feature**: Check `docs/decisions/` for relevant ADRs and `docs/design/` for specifications +- **Understanding system architecture**: Start with `docs/architecture/overview.md` +- **Coding guidelines**: See `docs/standards/` for language-specific standards and best practices +- **Past implementation context**: Review `docs/reports/` for similar work (sorted by date) +- **Project roadmap and scope**: Refer to `docs/projectplan/` + +### Where to Create New Documentation + +**Create an ADR (`docs/decisions/`)** when: +- Making architectural decisions that affect system design +- Choosing between competing technical approaches +- Establishing patterns that others should follow +- Format: `ADR-NNN-brief-title.md` (find next number sequentially) + +**Create a design doc (`docs/design/`)** when: +- Planning a complex feature implementation +- Detailing technical specifications +- Documenting multi-phase development plans + +**Create an implementation report (`docs/reports/`)** when: +- Completing significant development work +- Documenting implementation details for architect review +- Format: `YYYY-MM-DD-brief-description.md` + +**Update standards (`docs/standards/`)** when: +- Establishing new coding conventions +- Documenting processes or workflows +- Creating checklists or guidelines + +### Key Documentation References - **Architecture**: See `docs/architecture/overview.md` - **Implementation Plan**: See `docs/projectplan/v1/implementation-plan.md`