Documentation and ADRs
Overview
Document decisions, not just code. The most valuable documentation captures the why: the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.
When to Use
- Making a significant architectural decision
- Choosing between competing approaches
- Adding or changing a public API
- Shipping a feature that changes user-facing behavior
- Onboarding new team members (or agents) to the project
- When you find yourself explaining the same thing repeatedly
When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.
Architecture Decision Records (ADRs)
Read references/adrs.md when making a significant architectural decision (framework/library choice, data model, auth strategy, API architecture, or any expensive-to-reverse choice) — it has the "When to Write an ADR" checklist, the ADR template, and the lifecycle states.
Inline Documentation
Read references/inline-comments.md when writing or reviewing inline code comments — it has the why-not-what rule with before/after examples and the gotcha-documentation pattern.
API Documentation
Read references/api-documentation.md when adding or changing a public API — it has the TypeScript JSDoc pattern and the OpenAPI/Swagger REST pattern.
README Structure
Read references/readme-structure.md when a project lacks a README or its README is stale — it has the section skeleton (quick start, commands, architecture, contributing).
Changelog Maintenance
Read references/changelog.md when shipping a feature that changes user-facing behavior — it has the Keep-a-Changelog-style entry format.
Documentation for Agents
Special consideration for AI agent context:
- Agent rules files (
CLAUDE,AGENTS): Document project conventions so agents follow them - Spec files: Keep specs updated so agents build the right thing
- ADRs: Help agents understand why past decisions were made (prevents re-deciding)
- Inline gotchas: Prevent agents from falling into known traps
Common Rationalizations
| Rationalization | Reality | |---|---| | "The code is self-documenting" | Code shows what. It doesn't show why, what alternatives were rejected, or what constraints apply. | | "We'll write docs when the API stabilizes" | APIs stabilize faster when you document them. The doc is the first test of the design. | | "Nobody reads docs" | Agents do. Future engineers do. Your 3-months-later self does. | | "ADRs are overhead" | A 10-minute ADR prevents a 2-hour debate about the same decision six months later. | | "Comments get outdated" | Comments on why are stable. Comments on what get outdated. That's why you only write the former. |
Red Flags
- TODO comments that have been there for weeks
Verification
After documenting:
- [ ] ADRs exist for all significant architectural decisions
- [ ] README covers quick start, commands, and architecture overview
- [ ] API functions have parameter and return type documentation
- [ ] Known gotchas are documented inline where they matter
- [ ] No commented-out code remains
- [ ] Agent rules files (
CLAUDE,AGENTS) are current and accurate