Open most architecture repositories and you will find a confident account of what exists. There is a diagram of the services, a list of the queues, a note on which database backs which bounded context. What you will rarely find is the only thing that matters six months later: why. Why this database and not the other. Why the team accepted eventual consistency here. Which three options were weighed, and what was given up to choose this one. The build is documented. The decision is gone.
This is the quiet failure mode of most engineering organisations. Teams document what they built, not why they built it — and the why is the actual deliverable. An architecture is not its diagram; it is the accumulated set of decisions that let an organisation change safely and deliver consistently. When the reasoning behind those decisions evaporates, what remains is a snapshot that cannot defend itself the moment a later choice quietly defeats an earlier one.
The record was always about the reasoning
Michael Nygard named the problem precisely in his November 2011 essay 'Documenting Architecture Decisions', where he coined the term Architecture Decision Record. His argument was almost mundane in its honesty: nobody reads the large documents, but losing the rationale behind a decision is disastrous, because future teams inherit consequences without context and start undoing choices they never understood (Nygard, via Fowler). To be fair to the lineage, Nygard did not invent the decision log — he drew on Philippe Kruchten's decision registers — and that attribution matters; the ADR as a named, lightweight practice is his, not ours.
The template that followed is deliberately small and has stayed stable for over a decade: Title, Status, Context, Decision, Consequences. Thoughtworks moved lightweight ADRs to 'Adopt' and makes one structural insistence we think is load-bearing — store the records in source control, in the same repository as the code, so the record stays in sync with what it describes (Thoughtworks Radar, vendor framing). An ADR that drifts from the system is worse than none, because it lies with authority.
Knowledge does not fade; it vaporises
The academic framing is sharper than 'good documentation hygiene'. Researchers describe architectural knowledge vaporisation: when documentation is skipped, the context, assumptions, drivers, considered alternatives and trade-offs do not degrade gently — they disappear, raising maintenance cost and accelerating architectural drift and erosion (RUG/Springer). The decision that felt obvious in the room becomes an unexplained constraint that the next team routes around, then around the route, until the architecture no longer reflects any coherent intent.
That this practice works is not merely asserted. A 2024 action-research study introduced markdown ADRs at a microservices company over three months and found measurable improvement in documentation culture, knowledge transfer and information prioritisation, and notably better cooperation between teams (Ahmeti, Linder, Groner, Wohlrab; ECSA 2024). The same study delivers the contrarian lesson that should reorganise how teams adopt ADRs: the limiting factor is not the notation. The decision on where records are stored 'has a massive influence' on perceived usefulness, and the hard parts are organisational — documentation culture and deciding what is worth recording — not the choice of template. The template is the easy 10 per cent.
Governance bodies now agree it is standard practice rather than craft preference. The UK Government Digital Service launched an ADR Framework in December 2025, mandating ADRs for decisions brought to its Technical Design Council specifically to reduce lost context and duplicated effort. When a public-sector governance body codifies the practice, the argument has moved from 'should we' to 'how well'.
An ADR without the rejected options is just a changelog
The value of an architecture decision lives in the alternatives you discarded and the trade-off you accepted. Record only the choice, and you have written a changelog. Record the why, and you have written architecture.
This is where our Delivery Architecture view diverges from the standard treatment. Most coverage frames ADRs as records of the past — instruments of knowledge retention. We treat them as decision-quality instruments that connect the full delivery chain: business strategy to product to architecture to engineering to operations to outcomes. A decision is only legible downstream if the rationale travels with it. That is why the rejected alternatives, the drivers and the trade-off are not supporting detail; they are the content. Everything else is metadata. This is the same thesis we set out in Architecture Is Not About Technology — It Is About Decision-Making — architecture is decision quality, not diagrams — and it is the practical mechanism behind the The Missing Architecture Layer Between Strategy and Delivery: ADRs are the translation layer that lets a strategic intent survive contact with an engineering team it never met.
There is also a reversibility dimension the canonical template omits. Borrowing Jeff Bezos's one-way versus two-way doors, a decision that is cheap to reverse deserves a different weight of deliberation than one that is not. Tagging each record with a reversibility class turns the log from a flat archive into a triage instrument: it tells a future team which decisions they may revisit lightly and which they must treat as load-bearing.
The AI inversion most people are missing
The obvious AI story is that large language models can draft ADRs and analyse trade-offs faster. The 2025-2026 research broadly supports this, with two caveats worth holding onto: context strategy matters more than model size, and human expertise remains essential for validating any drafted decision against real constraints (arXiv 2025-2026). Vendor framing that promises to 'generate your ADRs with our agent' inverts the value: it automates the cheap part and risks hollowing out the expensive part.
The sharper field note runs the other way. ADRs are becoming the context layer that lets AI agents make and respect decisions. The trade-off log — drivers, rejected options, accepted consequences — is exactly the Context Engineering: Context Is the New Architecture artefact that agents otherwise lack. An agent given the code can reproduce patterns; an agent given the decisions can avoid defeating them. This is the bridge to The Acceptance Gap: humans accept AI output only when the reasoning is legible, and a well-kept ADR makes both the human's and the machine's reasoning inspectable in the same place. For teams building toward The Agentic SDLC Is an Acceptance-Gate Problem and What Is Agentic Engineering?, the decision record stops being archaeology and becomes operational input.
The practice: a decision flow, not a markdown file
Because the 2024 evidence shows the constraint is process and storage rather than format, the downloadable we recommend is not another template. It is a one-page Delivery Architecture decision practice that forces the parts teams skip. It captures context and drivers; the options actually considered; the trade-off accepted in plain language; the reversibility class (one-way or two-way door); and an explicit AI-context block stating what an agent must respect. Crucially, it wraps these in a decision flow drawn from the architecture advice process — the Harmel-Law and Fowler lineage that Thoughtworks placed in Trial in April 2025 — in which anyone may make a decision provided they seek advice from those affected and those with relevant expertise, with the ADR keeping that distributed decision informed. Thoughtworks cites DORA's finding that traditional architecture review boards are counterproductive; the advice process is how you decentralise decisions without losing the thread.
Keep the human decision and the trade-off as the load-bearing content and the practice scales from a single team to a programme without becoming bureaucracy. That balance — distributed authority with retained rationale — is the subject we develop in Architecture Governance Without Bureaucracy, where ADRs become the lightest possible governance surface that still produces consistent delivery. Document the why, store it next to the code, and the architecture stops being a diagram someone has to defend from memory. It becomes a chain of decisions an organisation — and increasingly its agents — can follow on purpose.