Six months after a design is signed off, nobody remembers why a key choice was made. Architecture decision records (ADRs) solve that — a lightweight way to capture the reasoning behind your decisions.
An architecture decision record is a short document capturing one significant decision: what was decided, what the alternatives were, why this one was chosen, and what it commits you to.
The format matters less than the discipline. One decision per record, written at the time, kept immutable afterwards. A record that gets edited as circumstances change becomes a description of the present rather than a record of the reasoning, which is precisely what nobody has when they need it.
Six months after sign-off, three things reliably happen. Someone questions a decision and nobody can reconstruct the reasoning. A new architect joins and inherits constraints with no explanation. And a decision made for a reason that has since expired continues to be honoured because nobody knows it was conditional.
ADRs address all three at a cost of about twenty minutes per decision. That ratio is why they have spread from software teams into enterprise architecture practice.
There is a second, less obvious benefit: writing the alternatives down forces you to have considered some. A decision that cannot articulate what was rejected and why usually has not been made — it has been assumed.
Half a page to two pages. If it runs longer, it is probably several decisions and should be split.
Not every choice. Record decisions that are expensive to reverse, that constrain future options, that will be questioned later, or where the reasoning is not obvious from the outcome.
Technology selections, integration patterns, data ownership boundaries, build-versus-buy calls, and any deliberate deviation from a standard all qualify. Routine choices that conform to existing standards do not — that is what the standards are for.
A practical filter: if you would be annoyed to discover this decision had been made with no explanation, write the record.
ADR practices fail by becoming heavy. Three habits keep them alive.
Write them at the moment of decision. Reconstructing reasoning a fortnight later produces a rationalisation, not a record — and it takes three times as long.
Store them with the thing they describe. In the repository for a system, in the architecture space for a domain. A central ADR library detached from the work gets abandoned; records that live where people already look get read.
Never edit an accepted record. When a decision changes, write a new ADR that supersedes the old one and link them. The chain of superseded decisions is genuinely valuable — it shows how thinking evolved and stops the same rejected option being proposed every two years.
ADRs and governance reinforce each other. A design authority decision should produce an ADR as its output, which turns a meeting minute into a durable artefact. A solution review can reasonably require ADRs for the major choices as part of the submission — it is the fastest way to see whether alternatives were genuinely considered.
Where a decision deviates from a standard, the ADR and the exception record should reference each other. One captures the reasoning, the other the time-boxed permission.
The Architecture Review Kit includes an architecture decision log (ADRs) alongside the checklist, scorecard, risk register and report — a complete review system.
