Somebody on your team probably wrote an ADR last month titled something like “Adopt Prettier for the billing service,” or “Standardize on camelCase for internal package names.” Go read it back in six months and ask what it’s actually protecting. Nothing. It’s not wrong, exactly, it’s just not architecture, and it’s sitting in the same collection as the decision about who owns the customer identity record, as if the two carry the same weight.
That’s how ADR programs actually fail, and it took me a while to see it clearly. Not from neglect, from scope. Somebody writes five of them in the first month, three about which linter to use and two about a naming convention, and by month three nobody can tell which records in the pile actually matter. Meanwhile the load-bearing decisions, the ones that would actually constrain a future architect if they knew about them, never get written down at all. Nobody decided that on purpose. It just happens.
The theater everyone half-recognizes
There’s a name for this now, and I wish I’d had it years ago. A recent writeup on ADR operating patterns calls it “Decision Documentation Theater,” and the diagnosis matches what I’ve watched happen across every org I’ve been part of: teams pick a template without ever defining the operating model around it, and the collection fills with either trivial choices or vague, unfalsifiable ones (“be cloud-native”) while the decisions that actually mattered, the ones with real trade-offs attached, get skipped entirely. The same piece makes a point worth sitting with, and I think it’s the whole ballgame: the format debate is a distraction. Nygard’s original four sections, context, decision, status, consequences, are still the right default for most teams. MADR’s extra rigor around considered options is worth the overhead only once a team has the discipline to keep it current, and be honest with yourself about whether yours does. Scope is the problem people keep mistaking for a template problem.
Score it, don’t feel it
“Architecturally significant” is not a feeling, and I used to talk about it like it was one, which is exactly how you end up with two senior architects disagreeing about whether the same decision needed a record. If you can’t turn it into a yes/no test that two different architects apply the same way, you don’t have a scope rule, you have a personality trait. The test I use has three parts, and a decision needs to clear at least two of them before it earns an ADR:
- Reversibility. Is this a one-way door or a two-way door? Swapping a logging library is a two-way door, undo it in an afternoon and nobody remembers. Picking the system of record for customer identity is a one-way door, undoing it touches every downstream consumer you have.
- Blast radius. Does this decision constrain more than one team or one service? A formatting rule scoped to a single repo doesn’t. A choice about how services authenticate to each other does, because every future service inherits that constraint whether its owners were in the room or not, or even knew the room existed.
- Cost to be wrong. If this turns out to be a bad call in eighteen months, what does it cost to unwind, in dollars, in migration effort, in security exposure? If the answer is “we change a config value,” it’s not an ADR. If the answer is “we replatform,” it is, full stop.
The community site for the ADR format phrases the same idea more simply: per the ADR GitHub project’s guidance, if it’s something the team will argue about again in six to twelve months, it probably deserved a record the first time. That’s a decent gut check, and I don’t dismiss it, but I’d rather architects run the three-part test than lean on a feeling about future arguments, because that feeling is exactly what produces both the under-documentation and the noise problem at the same time. You can’t fix a scope problem with more intuition. That’s how you got the scope problem.
The noise that trains people to stop reading
Say the quiet part: most of what teams write ADRs for is implementation detail, not architecture. Formatter and linter choice. Internal package naming. Which testing library a single service uses. Local caching strategy inside one component’s boundary. None of that constrains anyone outside the team that made the call, none of it is expensive to reverse, and writing it up as an ADR doesn’t add rigor, it adds noise, and noise is what trains people to stop reading the collection at all. Once that happens the one record that actually mattered is sitting unread right next to forty that didn’t. If it lives entirely inside one service’s blast radius and a junior engineer could reverse it in a sprint, it’s a design note or a PR description. It is not a governance record, and pretending otherwise doesn’t make anyone safer.
The decisions that actually need one
Data ownership and system-of-record decisions. Identity and access boundaries between services. Integration patterns that other teams will build against. Any security control trade-off where you’re accepting risk in exchange for velocity or cost, and you are always accepting one or the other, whether you write it down or not. Vendor and platform commitments that are expensive to unwind, the kind of call I’ve written about before when the pitch is “best of breed.” Anything that, if silently reversed by someone who didn’t know the original reasoning, could reintroduce a risk the org already decided to accept or reject. That last category is exactly where I want the ADR discipline tightest, because it’s the one an ADR functions as a governance control for, not a documentation habit. Those two things get treated as the same thing constantly, and they aren’t.
Borrow your ARB’s trigger
You don’t need a separate committee to decide what’s ADR-worthy, and honestly, standing one up just for this would be its own kind of overhead problem. If your Architecture Review Board is already scoped correctly, it’s applying the same blast-radius logic to decide what needs a hearing, and I’ve argued that a board that tries to gate everything instead of the narrow set of decisions with real blast radius collapses under its own docket. Use the same trigger for both: if it’s big enough to need ARB eyes, it’s big enough to need a record. If it isn’t, it’s a design note that lives with the code, not a permanent entry in your architecture repository.
Make it findable, not just written
Write the ADR as a stub if you have to, title, status, one paragraph of context, the decision, the consequence you’re accepting. Two pages is a ceiling, not a target, and if you’re past two pages you’re probably documenting your reasoning process instead of the decision. And it goes in the EAM system tied to the component or capability it constrains, not a wiki page that drifts out of sync with the thing it describes within a quarter. A record nobody can find when they’re about to make the same call again isn’t a control, it’s an artifact, and there’s a real difference between the two even though they look identical sitting on a shelf.
Next time you sit down to write one, ask yourself the only question that matters: if someone reversed this decision next year without reading it, would it actually hurt?