Living Documentation

In one line: Document at build time, not retroactively — docs are a deliverable on the same tier as code and tests, and they double as AI context.

What: Every architectural decision and capability is documented in a structured Docusaurus site as it is built. A feature is not complete until its documentation exists.

Why: Documentation debt compounds faster than technical debt. Code can still be read; the reasons behind it — why this approach over alternatives, what constraint shaped this API — are invisible in the code and gone once they leave working memory.

Documentation also serves the AI directly: it reads CLAUDE.md, memory files, and linked docs at session start. Narrative understanding of why the architecture is shaped this way produces measurably better proposals than what-only knowledge — the AI aligns with the design philosophy instead of generating locally reasonable, globally incoherent solutions.

This creates a compounding knowledge flywheel:

1. The architect writes a design specification.
2. Claude reads the specification and produces aligned implementation.
3. The implementation is documented (API contracts, architectural diagrams, decision records).
4. Future Claude sessions read the accumulated documentation and produce even more aligned output.
5. Each cycle adds context that makes the next cycle faster and more accurate.

Stale documentation is worse than none: it misleads the AI into producing code for a system state that no longer exists. Currency is therefore enforced structurally (the documentation commit pattern), never via periodic "doc sprints" that lag the code.

The five audiences for documentation:

Audience	What they need	How the docs serve them
Prospects and partners	Credibility at first glance	Architecture depth and evidence-backed claims demonstrate engineering capability
AI agents	Narrative context beyond code	Specifications, ADRs, and analysis provide the "why" raw code cannot convey
Developers	Architecture truth	API references, data-flow diagrams, and component registries for onboarding and navigation
Regulators	Compliance depth	Traceability, data-processing records, and audit-trail documentation
Team	Alignment as the system grows	ADRs prevent re-litigating decisions; pillar docs prevent scope ambiguity

Evidence: Enforced by the documentation commit pattern (Section 11.4) — the review stage treats a code change without its doc update as incomplete, the same way it treats code without tests. The result is a roughly 1:1 code-to-docs commit cadence: an approximate outcome of the mechanism, not a mandated metric. Docs lag during intensive sprints and catch up during consolidation; the claim is structural incentive, not perfect sync.

How: Four mechanisms, detailed in Section 11:

1. The documentation commit pattern — every architecture-changing branch ships code + ADR (if applicable) + doc page update + build verification, enforced at review.
2. Same-repo Docusaurus deployment — docs live beside the code so they are always at the same commit; no separate-repo drift.
3. Structured content organization — navbar sections by audience, so no flat undifferentiated wiki.
4. The AI context loop — memory → design specs → ADRs → architecture pages cross-reference into a navigable knowledge graph for humans and AI alike.

Architecture-as-Code (extension). Living documentation becomes infrastructure when it is machine-readable. The methodology extends the living documentation principle with five practices:

1. Structured frontmatter — every architecture page has machine-readable metadata (components, tests, data_flow, depends_on, last_verified, status). AI agents parse this to understand which docs are relevant to the files they're modifying.

2. Auto-generated architecture index — a build plugin scans all pages and generates docs/architecture-index.json mapping source files to their documentation pages. AI agents read this index before modifying code.

3. Sync surfacing — an advisory staleness check warns when documentation is stale (last_verified > 30 days for modified files), surfacing the stale pages for a review pass. It is a nudge, not a build-breaker.

4. Documentation-first development — the brainstorming skill creates a Docusaurus placeholder page (status: planned) before any code exists. The page tracks the feature lifecycle: planned → in-progress → implemented.

5. Test mapping — the tests: frontmatter field maps components to their test files. The Stop hook verifies that the RIGHT tests were run, not just "some tests."

The result: documentation drift is structurally discouraged for new features — the page exists before the code, the staleness check surfaces stale docs at review (advisory), and AI agents consult docs before modifying code.

Evidence: Surfaced by the advisory staleness check (templates/hooks/check-doc-staleness.sh — stale last_verified emits a WARN line, exits 0, never blocks) and the build plugin that regenerates the architecture index. Reproducible: touch a documented file, let last_verified age past the threshold, and watch the check warn about the stale page. See appendix-h-architecture-as-code.md.

---