---
name: documentation-and-adrs
description: Record architecture decision records, inline documentation, API docs, READMEs, and changelogs that capture why decisions were made. Use when making an architectural choice, changing a public API, shipping a feature, or when the same explanation keeps getting repeated. Not for deciding whether to remove a system: use deprecation-and-migration. Not for adversarial review of the decision itself: use doubt-driven-development.
license: MIT
metadata:
  author: TechTide AI (Alex Cinovoj)
  provenance: rewritten from patterns in Addy Osmani's agent-skills (MIT)
  category: Architecture
---

# 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

| Situation | Write |
|---|---|
| Significant architectural choice, expensive to reverse | ADR in `docs/decisions/` |
| Non-obvious intent in code | Inline comment on the why |
| Known trap near a function or module | Gotcha doc-comment, link the ADR |
| Public API added or changed | Typed doc-comments, OpenAPI for REST |
| New project or missing onboarding | README |
| Shipped user-facing change | Changelog entry |
| Project conventions agents keep violating | CLAUDE.md / rules file update |

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.