documentation-and-adrs

Documentation and ADRs

Document decisions, not code. Code shows what was built; only documentation captures why, what alternatives were rejected, and what constraints applied. That context is what future engineers and agents actually need.

Routing

Do not document the obvious, do not restate code in comments, do not write docs for throwaway prototypes.

ADRs

Write one for: framework or major dependency choices, data models and schemas, auth strategy, API architecture, infrastructure, anything expensive to reverse. Number them sequentially in docs/decisions/.

Every ADR carries: status (proposed, accepted, superseded, deprecated), date, context (requirements and constraints), the decision, alternatives considered with pros, cons, and the rejection reason for each, and consequences. The alternatives section is the payload: a decision with no rejected alternatives recorded is an announcement, not a record.

Lifecycle: never delete old ADRs. When a decision changes, write a new ADR that references and supersedes the old one. History is the point.

Read references/templates.md when writing: it has the full ADR template, README skeleton, changelog format, and API doc examples.

Inline Documentation Rules

• Comment the why, never the what. "Increment counter" is noise; "sliding window resets at the boundary to prevent burst attacks at window edges" is documentation.
• Document gotchas where they bite: ordering requirements, hydration timing, non-obvious failure modes. Link the relevant ADR.
• No TODO comments for things you should do now. Do them.
• No commented-out code, ever. Git has history; delete it.
• Public functions get parameter, return, throws, and one example in typed doc-comments.

Documentation for Agents

Agents read docs more reliably than humans do. Keep current: CLAUDE.md and rules files (conventions agents must follow), spec files (so agents build the right thing), ADRs (so agents stop re-litigating settled decisions), and inline gotchas (so agents avoid known traps). A stale rules file is worse than none; it teaches agents wrong things confidently.

Verification

Run grep -rn "TODO\|^\s*//.*const \|commented" --include="*.ts" src/ | head -20 (adapt to your language) and list docs/decisions/. Expect: no stale TODOs, no commented-out code blocks, and an ADR for each major dependency and schema in the project. For any significant decision with no ADR, write one now from memory and mark it accepted retroactively; a late record beats none. Then check the README quick start on a clean clone: expect a new engineer reaches a running dev server using only its commands.

Good vs Bad

Judgment call: commenting a rate limiter.

Bad: // increment the counter by 1 above counter += 1. Restates code, rots instantly.

Good: // Sliding window, not fixed schedule: reset at the window boundary so bursts at window edges cannot double-spend the limit. See ADR-007. Explains intent, links the decision.

Footguns

• "The code is self-documenting." It documents what, never why or what was rejected. Fix: ADR for the decision, comments for non-obvious intent.
• Deferring docs until "the API stabilizes". APIs stabilize faster when documented; the doc is the first test of the design. Fix: write docs with the API, not after.
• Comments that describe behavior. Behavior changes, comments rot, readers get lied to. Fix: comment intent and constraints, which are stable.
• Deleting superseded ADRs. The next team re-runs the same two-hour debate. Fix: mark superseded, link forward, keep the file.

Completion Checklist

• [ ] ADRs exist for all significant decisions, each with alternatives and rejection reasons
• [ ] README covers quick start, commands, architecture pointer
• [ ] Public APIs have typed doc-comments with examples
• [ ] Gotchas documented at the point of danger
• [ ] No commented-out code or stale TODOs introduced
• [ ] Rules files current with actual conventions

Any box unchecked: not done. Fix or say so.