Architecture decision records: better technology decisions

Published 6 October 2026 · Timcliffe

Most organisations do not lack technology decisions — they lack a record of why those decisions were made, what alternatives were considered, and what would need to change for the decision to be revisited. Six months later, the person who made the call has moved teams, the context has faded even for those who remain, and a new engineer proposes "simplifying" something that was actually a deliberate trade-off against a constraint that is no longer visible anywhere. An Architecture Decision Record, or ADR, is a short, durable, version-controlled document that captures exactly that context at the moment the decision is made, so it survives the people who made it.

The format is deliberately lightweight: a title, the status (proposed, accepted, superseded), the context and constraints that made a decision necessary, the decision itself, the alternatives genuinely considered and why they were not chosen, and the consequences — including the ones the team accepted as a trade-off rather than solved. What an ADR is not is a design document, a requirements specification, or a retrospective justification written after the fact to make a decision look more considered than it was.

Where ADR practice typically breaks down

The most common failure is writing ADRs only for large, visible decisions and skipping the smaller ones that quietly accumulate into significant unexplained complexity over time. A dependency choice, a data model shape, a decision not to build a feature a stakeholder requested — these are exactly the decisions a future team member will not have the context for, and they rarely feel ADR-worthy in the moment they are made.

A second common failure is writing the ADR after the implementation is already complete, as documentation rather than as a decision record — at which point it reliably omits the alternatives that were genuinely considered and rejected, because by then nobody remembers the version of the proposal that did not happen.

A third is letting ADRs become permanently immutable in a way that discourages revisiting them. An ADR records the best decision available with the information and constraints known at the time; when circumstances change, the correct response is a new ADR that explicitly supersedes the old one, not treating the original decision as unchangeable or, at the other extreme, silently drifting away from it without any record of why.

A fourth, subtler failure is ADRs that record the decision but not the reasoning — "we chose X" with no honest account of why Y was rejected leaves a future reader unable to tell whether the constraint that ruled out Y still applies, which defeats much of the record's purpose.

A recommended approach

Set a genuinely low bar for what warrants an ADR — if two reasonable engineers could plausibly disagree about the choice, or if a future team member might reasonably ask "why did we do it this way," write one. The cost of a short, honest record is measured in minutes; the cost of the context being lost is measured in months of future confusion or a decision being quietly re-litigated from scratch.

Write the ADR at the point of deciding, not after implementation — draft it as part of proposing the decision, so the alternatives considered are the ones genuinely on the table, not a reconstructed, flattering account.

Keep the format short and consistent across the organisation, so ADRs are quick to write and quick to read; a template that takes an hour to fill in correctly will simply not get used under delivery pressure.

Treat supersession as the normal lifecycle event it is — when a decision changes, write the new ADR and explicitly link it back to the one it supersedes, preserving the old record rather than deleting it, so the full decision history remains legible.

Store ADRs alongside the code and architecture they describe, under version control, rather than in a separate document system that drifts out of sync with the thing it is meant to explain.

Actionable takeaways

Lower the bar for what counts as ADR-worthy — the smaller, easily-forgotten decisions benefit from a record at least as much as the large, visible ones. Write the record at decision time, capturing real alternatives, not as retrospective justification. Keep the template short enough that it is actually used consistently. And when a decision is revisited, supersede it explicitly rather than letting practice quietly drift away from an unamended record.

Timcliffe applies ADR practice as part of its Enterprise Architecture and Advisory engagements, and treats decision governance as a core input to Quality Engineering work where technical decisions directly shape what "quality" means for a given system.