Example: when to write an architecture decision record

A decision framework for ADRs—when they earn their keep and when a comment or ticket is enough.

06 February 2026 · Archive

Example content

Sample guidance article; not a formal policy for any organisation.

Architecture Decision Records shine when the choice is costly to reverse or surprising to a newcomer. They are poor value when the answer is obvious and stable.

Write an ADR when

You reject a popular default for a specific reason.
Multiple teams will rely on the decision for years.
You need a dated snapshot of context that Slack will bury.

Skip the ADR when

The experiment will be thrown away in a week.
The decision is fully captured by types, tests, and naming.

Keep ADRs short: context, decision, consequences. Link to code and dashboards instead of duplicating them.