Writing Decision Records
also called ADR
Recording a decision so the next person understands why — including the options rejected and the conditions that would reverse it.
Definition
An architecture decision record captures one decision: the context, the options considered, the choice, and the consequences. One page, written when the decision is made.
The structure that works
Context. What forced a decision now. The constraints and the drivers, stated so a reader in two years understands the situation without asking anyone.
Options considered. At least two real ones. This is the valuable section — without it the next person re-litigates every settled question and frequently re-makes an avoided mistake.
Decision. What was chosen, stated plainly.
Consequences. What gets better, what gets worse, and what new obligations this creates. A decision with no stated downside has not been understood.
Revisit conditions. What would make this the wrong choice. This is the section most often missing and the most valuable over time:
"Revisit if the average service has fewer than two committers, if cross-service changes exceed a third of our features, or if operational overhead per service exceeds X engineer-days per quarter."
Written that way, the revisit is triggered by evidence rather than by an outage or a new CTO.
What makes them work
- Written at the time. Reconstructed afterwards they are rationalisation.
- Short. One page. A long record is not written and not read.
- Immutable. A superseded decision is not edited; a new record supersedes it, so the history of reasoning is preserved.
- Stored with the code, so they are found by people working on the system rather than in a wiki nobody visits.
- Numbered and listed, so the set is navigable.
What deserves one
Decisions that are expensive to reverse, that people will question later, or where the reasoning is not obvious from the outcome. Not every technical choice — a record for every library selection devalues the whole set.
Failure scenarios
- Only the chosen option recorded, so the reasoning is unrecoverable.
- No consequences section, so the trade is invisible.
- No revisit conditions, so a decision that has become wrong stays in force.
- Written for governance rather than for the next engineer.
- Edited in place, destroying the history.
Interview question
"What section is missing from most architecture decision records, and why does it matter?"