What it does
Writes an ADR to docs/DECISIONS.md, or retrieves existing ADRs. Every ADR captures:
- Context — the problem and forces at play
- Decision — what was chosen
- Alternatives considered — what else was looked at, and why rejected
- Consequences — trade-offs, what to revisit later
- Decider(s) — who made the call
When to log one
- You picked a library over alternatives
- You chose a pattern (e.g. composition vs inheritance, service vs hook)
- You scoped out a feature deliberately
- You accepted a trade-off (e.g. speed over flexibility)
Rule of thumb: if a future session might ask “why did we do it this way?”, log it.
Usage
/decision Use Zod over Yup for validation
/decision list # show ADR index
/decision auth # search ADRs by topicLogging a new ADR
Claude asks you to answer:
- Context — the problem
- Decision — what we’re choosing
- Alternatives considered — at least two, each with why rejected
- Consequences — positive, negative, revisit-if condition
- Decider(s) — names
Then writes the new ADR at the top of DECISIONS.md (newest first), auto-numbered as ADR-NNN.
Supersession
If a decision is reversed later, log a new ADR that supersedes the old. In the new ADR, add “Supersedes ADR-MMM”. In the old ADR, change Status: accepted to Status: superseded by ADR-NNN (YYYY-MM-DD).
Never delete an ADR. The superseded record is part of the history.