adrlisted

# Architecture Decision Records (ADRs) An ADR is a short document that captures a significant technical decision — why it was made, what alternatives were weighed, and what consequences to expect. Its value is institutional memory: future contributors (and future Claude sessions) don't re-litigate settled questions, and the reasoning doesn't disappear as the decision fades into obvious-seeming background. **Write one when the decision:** - is hard to reverse or expensive to undo - cost real deliberation (alternatives existed) - will surprise someone reading the code later - defines a constraint that future decisions must respect Don't write one for every choice — only the ones worth recording. ## Format Use the lightweight Nygard format — context + decision + consequences, in a short Markdown file. ```markdown # NNNN — Title in plain words **Date:** YYYY-MM-DD **Status:** Accepted | Deprecated | Superseded by [ADR-MMMM](MMMM-title.md) ## Context What situation prompted this decision? What constraints, requirements, or pressures existed? What were the realistic alternatives and their trade-offs? ## Decision The choice made. One or two sentences, stated directly. ## Consequences What becomes easier, harder, or required as a result? Downstream impacts, known limitations, things to watch for. ``` ## Where to store them Place ADRs in `docs/decisions/` (create it if absent), named `NNNN-short-title.md` — sequential, lowercase, hyphens. Keep a `docs/decisions/README