Guidelines for AI on how and when to generate Documentation

claude.md

Documentation Standards

Principle: Documentation That Ages Well

Documentation should focus on stable concepts rather than implementation details that change frequently.

DO Document (Low Maintenance)

• Architecture rationale - why decisions were made, not just what
• Concepts and patterns - multi-tenancy model, async patterns, state management
• Operational guidance - production checklists, troubleshooting steps
• Getting started - one minimal, tested example per feature
• Environment variables - reference tables (source of truth: Settings class)

AVOID Documenting (High Maintenance)

• Full code examples - one canonical example max, link to tests for more
• API references - use auto-generated docs (OpenAPI, docstrings)
• Data schemas - link to Pydantic models, don't duplicate JSON structures
• SQL/queries - keep in scripts or migrations, reference the script
• Implementation details - link to source code instead

Single Source of Truth Rule

Information Type	Source of Truth	Documentation Should
Database schemas/indexes	Migration scripts or setup scripts	Say "Run scripts/setup_*.py"
Data models	Pydantic/TypedDict definitions	Link to model file
API contracts	OpenAPI spec (auto-generated)	Link to /docs endpoint
Config options	Settings class	Reference the class
Code examples	Integration tests	Link to test file

Documentation Anti-Patterns

❌ Duplicating code in docs - Will drift from implementation

<!-- BAD: This SQL will get out of sync -->
CREATE INDEX idx_customer ON invoices(_customer_id);

✅ Reference the source

<!-- GOOD: Single source of truth -->
Run `python scripts/setup_db.py` to create required indexes.
See the script for current index definitions.

❌ Multiple code examples - More examples = more maintenance ✅ One minimal example + link - "See tests/integration/test_*.py for more examples"

❌ Hardcoded JSON schemas - Schema evolves with code ✅ Generated or linked - "Schema defined by Scenario model in src/models/customer.py"

When Writing Documentation

1. Ask: "Will this need updating when code changes?"
2. If yes: Link to source instead of duplicating
3. If no: Document it (concepts, rationale, checklists)