I promised this one. Back in one-way and two-way doors I said that for the decisions you can’t easily walk back, the bit people skip is to write down why — and that it deserved a post of its own. Here it is.
It’s also the idea this whole blog started from: somewhere to capture the reasoning behind a decision, not just the decision itself. An architecture decision record is that same instinct, made into a team habit.
The thing that actually evaporates
Six months after a decision, the decision itself is usually still legible. The code is there. The diagram, if you have one, shows the boxes and arrows. What’s gone is everything that led to it: the three options you weighed, the constraint that ruled out the obvious one, the trade-off you accepted with your eyes open. So the next person — often you — finds a choice that looks arbitrary, assumes it was, and either cargo-cults it or rips it out and rediscovers the constraint the hard way.
A diagram tells you what you built. It almost never tells you why, or what you didn’t build and why not. That “why not” is the most expensive knowledge in the system and the first to disappear.
What an ADR is
An architecture decision record is a short, dated note — a page, rarely more — capturing one decision at the moment it’s made. The format (Michael Nygard’s, the one most people use) is deliberately thin:
- Context — the forces at play. What’s true, what’s constraining, what we’re optimising for.
- Decision — what we’re going to do, stated plainly.
- Alternatives — what else we seriously considered, and why we didn’t pick them.
- Consequences — what this makes easier, what it makes harder, the trade-off we’re accepting.
- Status — proposed, accepted, superseded, deprecated.
It lives in the repo, next to the code, in version control — not in a wiki that rots in a different building. And crucially, you don’t edit an old one when you change your mind. You write a new one that supersedes it. The record is a history of how the thinking moved, not a snapshot pretending the present was always obvious. (That’s the same expand-don’t-mutate discipline from the doors post, applied to knowledge instead of schemas.)
Why the document isn’t really the point
Here’s where it gets more interesting than “write good docs.” Svyatoslav Kotusev, who has spent a lot of research effort on what architecture artifacts actually do in organisations, draws a useful line between two kinds. Facts artifacts document objective reality — what exists, the current state. Decisions artifacts capture an agreement about a desirable future course. They’re fundamentally different things, and they succeed or fail for different reasons.
An ADR is squarely a decisions artifact, and that reframes its value in two ways.
First, Kotusev’s finding is that the critical success factor for a decisions artifact is the timely involvement of the relevant stakeholders in producing it. In other words, the value isn’t really created when the document is finished — it’s created in the conversation the document forces. Writing “alternatives considered, and why rejected” is what makes you actually consider the alternatives and get the right people to agree. Half the benefit of an ADR is paid out before anyone ever reads it back, in the rigour the act of writing imposes.
Second — and this is the warning — decisions artifacts are exactly the ones that rot into shelfware. Kotusev’s blunt observation is that even comprehensive architecture documentation routinely ends up on a shelf, consulted by no one, improving nothing. A folder of two hundred ADRs that nobody opens isn’t a knowledge base; it’s a graveyard with good intentions. The artifact only pays off if it’s genuinely used — read when someone’s about to change the decision, and honestly superseded when it does change.
So: write fewer, mean them
The way I keep ADRs from becoming shelfware is to be ruthless about which decisions earn one. Most decisions are two-way doors — reversible, low consequence, not worth the ceremony. You don’t ADR your folder structure. You ADR the choices that are expensive to reverse and whose reasoning a newcomer couldn’t reconstruct from the code:
- The ones where you picked the non-obvious option and the obvious one will look tempting again later.
- The ones that encode a constraint that isn’t visible in the system — a regulatory line, a contractual one, a “we tried it the other way in 2022 and it burned us.”
- The ones a future team will be tempted to undo without knowing what they’d be reopening.
If a decision is genuinely reversible and self-explanatory, skip it. The discipline isn’t recording everything; it’s recording the things whose why is load-bearing and perishable.
The honest caveat
ADRs aren’t free, and they’re not a substitute for the conversation — they’re the residue of it. Done badly they become a box-ticking ritual, a PR gate that produces beautifully-formatted records nobody consults, which is the shelfware failure wearing a process badge. Done well they’re almost the cheapest insurance in software: a few minutes, at the one moment the context is still fresh in everyone’s head, spent so the next person inherits the reasoning and not just the result.
The one-line version
The decision is the cheap part — it’s there in the code. An architecture decision record captures the part that vanishes: the forces, the roads not taken, and the trade-off you chose on purpose. Write them for the decisions whose “why” is worth more than the “what” — and then, unlike most teams, actually go back and read them.