Architecture decision record

How to use it well

• →List the options you seriously considered, including the one you're doing today - a decision that never mentions the status quo reads as if no one checked whether change was worth it.
• →Write the consequence you don't like, not just the one you do. An ADR that only lists upside is a pitch deck, and the downside is exactly what the next engineer needs to plan around.
• →The revisit clause is what stops an ADR from calcifying into unquestionable law - give it a concrete trigger (a cost, a metric, a date) rather than "if it stops working."

Part by part

**Status:** {{status}}

Proposed, accepted, superseded. Status is what makes a directory of ADRs navigable — without it, every record reads as current.

## Options considered

Preserves the alternatives. Most of an ADR's later value is stopping someone re-proposing an option that was already examined and rejected.

## Consequences

Both directions. A consequences section listing only benefits is advocacy, and it fails the one job of telling a future reader what was traded away.

## Revisit when

The condition under which this should be reconsidered. It is the section that stops a decision outliving the constraints that produced it.

Common mistakes

• Editing an ADR when the decision changes.

  Destroys the history it exists to preserve. Supersede it with a new record that references the old one, so the sequence of decisions stays readable.

• A consequences section that is all upside.

  Every real decision costs something. A record without the costs cannot be reassessed later, because the reader cannot tell what was knowingly accepted.

• Writing the ADR months after the decision.

  The context is what fades first, and it is the most valuable part. A record written from memory contains the justification you now believe rather than the constraint you actually faced.

Questions