Use an ADR for one architecturally significant choice that future people and agents will otherwise have to rediscover. Record the reason and consequences, not a complete project history.
Annotated example
This example preserves the hard-to-reverse choice and the proof that guards it. Implementation steps belong in a linked plan.
The ADR community defines an ADR as a record of an important architectural decision with its context and consequences. MADR offers fuller and smaller forms, while Michael Nygard’s well-known short form uses status, context, decision, and consequences. Our ADR formats profile explains the tradeoffs.
Review prompts
- Is this a genuine tradeoff with durable consequences?
- Does the context explain why the decision was necessary at the time?
- Are rejected options represented fairly?
- Can a test, lint rule, review check, or operational signal confirm the decision?
This template is Plannotator-authored and does not reproduce a third-party template verbatim.
Reviewed July 18, 2026. Written and maintained by the Plannotator documentation team. Last modified on July 19, 2026