kimtth Goal: a durable, searchable record of why a decision was made.
Use for:
- capturing significant or hard-to-reverse decisions
- preserving context for future maintainers
- aligning a team on a chosen direction
Workflow:
- Trigger an ADR when a decision is significant or contested.
- State the context and the forces driving the decision.
- Record the decision in one clear statement.
- List the options considered and why they were rejected.
- Capture the consequences, trade-offs, and follow-ups.
- Store it in-repo, numbered and immutable once accepted.
ADR sections:
- title and status (proposed, accepted, superseded)
- context and problem
- decision
- alternatives considered
- consequences
Rules:
- one decision per record; keep it short
- record the why, not just the what
- do not edit accepted ADRs; supersede with a new one
- link related and superseding ADRs