Architecture Decision Records: right idea, wrong reader

Earlier this week, someone on a team I work with took an e-commerce merchant live before inventory sync was ready.

It wasn't recklessness. It was a judgment call, the kind engineers make ten times a day. The launch date was fixed, the sync wasn't finished, and the merchant's catalog was mostly in stock anyway. Going live without it looked like a reasonable trade. So they decided, they shipped, and they told no one.

For a few days, nothing happened. Most products were in stock, so most orders were fine. Then the edges showed up. Customers started ordering products that had already sold out. The merchant spotted it before we did, and merchants do not enjoy discovering things before their vendors do. They shut the rollout down and made one thing clear: nothing else moves until inventory is handled.

Now the part that actually stings. The fix, a simple out-of-stock guard, took half a day to build. Half a day, weighed against a killed experiment and a merchant who now double-checks everything we ship. The distance between those two costs is the price of a single unrecorded decision.

Because that is what failed here. Not the code. The code passed review and did exactly what it was built to do. What failed was invisible: a decision existed in exactly one person's head, and the people who could have acted on it had no idea it existed. No one knew, so no one acted.

Run the counterfactual. If "we're going live without inventory sync" had been written down anywhere the rest of the team would actually see it, someone says "that catalog has out-of-stock SKUs, add a guard first," the guard ships before launch, and this story doesn't exist. The whole incident lives in the gap between a decision being made and a decision being known.

The software industry has a name for writing decisions down like this. The practice is fifteen years old, has templates and command-line tooling, and shows up in the official engineering guidance of Microsoft, AWS, and Google. It's called an Architecture Decision Record. I think ADRs got the diagnosis exactly right. I also think they quietly fail at the step that matters most, and that AI coding agents are about to turn that quiet failure into a loud one.

What is an Architecture Decision Record?

An Architecture Decision Record, ADR for short, is a short document that captures one significant decision about how a system is built: what was decided, why, what else was considered, and what follows as a consequence. Not the code. The decision behind the code.

A good ADR fits on a page. The classic shape has a handful of parts: a title ("Use JWTs for session auth"), a status, the context that forced a choice, the decision itself, the alternatives that were considered with their trade-offs, and the consequences you accept by choosing this path. The standard advice is to write it like a news story. Most important thing first, details later.

Then there are the rules, and the rules are where it gets interesting. Each record gets a number in a monotonic sequence: 0001, 0002, 0003. Each record has a status that moves through a small set of states: proposed while under discussion, accepted once it's active, superseded when a newer decision replaces it. And the golden rule: once accepted, an ADR is never edited. If the decision changes, you write a new record that supersedes the old one, and you keep both, so the log shows not just what the rule is but how long each rule governed the work. The files live in the repository next to the code they govern, usually in a folder called doc/adr, in plain markdown, diffable like everything else.

Read those rules again slowly, because they are doing something the authors never quite said out loud. Never edit, only supersede: that's an append-only log. Monotonic numbering: a sequence. Proposed, accepted, superseded: a state machine. Stored with the code, in plain text. Software architects designed a database. They just implemented it in markdown and ran it on human etiquette.

Hold that thought.

Fifteen years of writing decisions down

Michael Nygard coined the term in 2011, in a blog post that was itself formatted as an ADR. The underlying idea was older; Philippe Kruchten had been arguing for decision logs in software architecture for years before that. What Nygard added was restraint. "Agile methods are not opposed to documentation," he wrote, "only to valueless documentation." Not a decision management process, not a governance framework. One page, one decision, stored with the code, written in minutes.

It spread the way good engineering practices spread: sideways, through imitation. Microsoft's engineering playbook tells teams to keep decision logs. AWS publishes prescriptive guidance on running an ADR process. Google Cloud's architecture center recommends them to its customers. There are open-source templates like MADR and command-line tools like adr-tools, whose own repository is documented, naturally, in ADRs. When a practice has templates, tooling, and the blessing of all three major cloud vendors, it has stopped being a tip and become infrastructure.

Spotify wrote one of the more honest accounts of what ADRs actually buy a team. Their Creator team recorded decisions like the 2019 call to adopt React Hooks, made in a bi-weekly engineering meeting after a small experiment, with the consequence stated plainly: no new class components. Then they listed the payoffs. Onboarding: new engineers read the history and understand not just what the system is but why it is that way. Ownership handover: when a system moves between teams, and at a growing company it always eventually does, the reasoning moves with it instead of walking out the door. Alignment: engineers in Stockholm read, referenced, and adopted the Hooks decision that web engineers in New York had written. Their answer to "when should I write an ADR?" was: almost always.

And underneath all of that sits the quietest benefit, the one Martin Fowler keeps pointing at: the act of writing forces clarity. A decision that sounds obvious in a meeting develops visible weak spots the moment someone has to write down the alternatives it beat. Half the value of an ADR is extracted before anyone else reads it.

All of this is true, and nothing in the rest of this post argues otherwise. ADRs are one of the highest-leverage documentation habits a team can adopt.

They just have a reading problem.

Why ADRs quietly fail

Notice what every benefit in the Spotify list has in common. Onboarding, handovers, understanding old choices: they are all retrospective. The reader is looking backward, with time on their hands, deliberately seeking context. For that reader, ADRs work beautifully.

But the inventory incident needed something else. It needed a decision to reach the right people at the moment it was made, before the consequences landed. And for that job, the ADR pipeline breaks in five places.

First, ADRs are pull, not push. A record sits in a folder waiting to be found, and discovery depends on the reader already suspecting there's something to discover. The engineer about to violate ADR-0034 is, almost by definition, the person who doesn't know ADR-0034 exists. If they knew about it, they wouldn't be about to violate it. A decision record that has to be sought out will reliably be missed by exactly the people who need it most.

Second, the significance filter points at the wrong target. Every guide says to write ADRs for significant decisions, and every team calibrates "significant" to mean architectural: frameworks, databases, auth patterns, service boundaries. Now run my inventory story through that filter. "Go live before sync is ready" is not architecture. There's no layer diagram in it, no technology choice. It felt like a Tuesday, not a turning point. Nobody anywhere would have opened the ADR template for it. It sat in a band that every real codebase generates constantly: decisions too small for ceremony and too consequential for silence. That band is where most of the actual damage happens, and the ADR process, by design, doesn't cover it.

Third, ADRs are homework. Writing one is a separate act from doing the work, performed afterward, by the person with the least remaining energy for it, under a deadline that rewards shipping over documenting. Every team that adopts ADRs has a doc/adr folder that is dense for the first three months and sparse after. Nobody decided to stop. The friction just wins.

Fourth, a markdown file doesn't know who it affects. The record that deprecates an endpoint has no idea the mobile app still calls that endpoint. It can't notify the consumer, and the author, having "documented it properly," reasonably assumes the job is done. The information exists and still doesn't move.

Fifth, nothing enforces them. You can merge code that violates an accepted ADR every day of the week and the repository will not object. So the records and the codebase drift apart, and every stale record teaches readers to trust the folder a little less, which means it gets read less, which means it goes stale faster. That's the death spiral of most internal documentation, and ADRs, for all their discipline, are not exempt from it.

None of these failures is loud, and that's the trap. A missing decision record doesn't throw an exception. It surfaces weeks later, as a merchant noticing sold-out products in their order feed, and by then nobody connects the incident back to the sentence that was never written.

The style guide and the squiggle

Here's another way to see the problem, and it doesn't require knowing anything about software.

Every company has a writing style guide. Somewhere on the intranet sits a forty-page document about tone, capitalization, and whether it's "sign in" or "log in." Real effort went into it. Nobody reads it. Ask anyone in the building where it lives and you'll get a guess.

And yet everyone in that same building fixes their typos, every day, without being asked. Because of the red squiggle. The little wavy line that appears under a misspelled word the instant you type it. Nobody reads the dictionary either. The dictionary didn't get better; the delivery did. A style guide is knowledge stored where you'd have to go find it. The squiggle is the same knowledge showing up uninvited, at the exact moment and in the exact place you're about to get it wrong.

Software teams have already run this experiment on their own behavior once. For years, teams wrote code style documents and argued about formatting in review comments. Then they adopted linters: small programs that check code against the team's rules automatically, the way spell-check checks prose, and block the merge if a rule is broken. The formatting debates died almost overnight. Nobody reads the style doc anymore; everybody obeys the squiggle in the editor and the check in the pipeline. The rules didn't change. They moved from a document you had to remember into a system that remembers for you.

An ADR is a style guide. What teams actually need, for decisions, is a squiggle.

For fifteen years there was a respectable excuse for not building one: the reader was human, and humans come with a built-in compensating layer. Someone half-remembers the decision. Someone mentions it at standup. The reviewer who's been on the codebase for six years catches the violation with a one-line comment. The document was static, but the organization around it was alive, and the living organization absorbed most of what the dead document dropped.

Then the reader changed.

Then the reader changed

AI coding agents have no compensating layer. There's no standup between Claude Code and Codex, no hallway conversation, no reviewer with six years of memory. An agent session starts blank. If a decision isn't explicitly in the agent's context window, then as far as that agent is concerned, the decision was never made. A folder of markdown files three directories up might as well be on another machine.

At the same time, agents multiply exactly the thing ADRs were meant to manage. A developer with an agent ships in a day what used to take a week, which means the number of decisions made per day goes up by roughly the same multiple. And the decisions collide faster. Agent A renames an endpoint at 2pm. Agent B, in a parallel session with no idea, spends the afternoon building against the old name. With human teams, contradictions like this surfaced over days, slowly enough for the compensating layer to catch some of them. With agents, both sides of the contradiction are fully built by evening.

The standard answer right now is the rules file: AGENTS.md, CLAUDE.md, a pinned context document. Rules files are genuinely useful, for constants. "We use JWTs." "Payments is gRPC." But a rules file is just a style guide that happens to live in the context window. It's written once and read at session start. It says nothing about what changed this morning. It goes stale by Thursday, there's one per repo per tool, and it has no way to carry a fresh decision from my agent to yours before yours acts on the old reality.

There's also a more ironic answer: AI has made ADRs easier to write than ever. There are agent skills now that will interview you and draft a well-structured ADR from a conversation. I like them. But notice which half of the problem they solve. Writing was never the real bottleneck; a page took twenty minutes even by hand. The failure was always on the read side, the right record reaching the right reader at the right moment. Making the write side free while the read side stays broken just produces a bigger folder that nobody reads at the moment it matters.

So here's the situation. The decisions-per-day count is exploding. The one reader that compensated for stale, unfound documents is being replaced by a reader with no memory at all. The write side is automated and the read side is still 2011.

A decision record designed for a reader that acts

Suppose you kept Nygard's core insight, that decisions deserve to be first-class records with statuses and history, and redesigned everything else around today's reader: software, fast, forgetful, and everywhere at once. Five things change.

Recording happens in the flow of work. The agent making a change proposes the decision record as part of making it. One tool call, a few seconds. When recording costs nothing, the significance filter stops mattering. "Going live without inventory sync" gets recorded not because someone judged it architecturally significant, but because recording it was cheaper than not recording it.

Records push instead of waiting to be pulled. The system holds a dependency graph: who consumes which endpoint, which schema, which contract. When a decision touches a shared surface, every consumer of that surface hears about it at decision time. The mobile team learns about the deprecated endpoint from the record itself, not from the 404.

Every session starts with a briefing. When an agent wakes up, the first thing it receives is what it missed: new binding decisions, changed contracts, open questions, ordered by blast radius so the change that breaks three services outranks the cosmetic rename. The blank-slate problem inverts. Instead of hoping the agent finds the folder, the folder's contents arrive as the agent's starting state.

The record has teeth. Real-time coordination will always be best-effort, so at merge time a gate checks every changed shared surface against the ledger. A shared contract changed with no binding decision behind it doesn't merge. This is the linter for decisions. The squiggle, made real, at the last moment it can still act.

And underneath, it's still an ADR. Append-only. A decision is proposed, acknowledged by the people it affects, becomes binding, and is eventually superseded. Never edited, only superseded, exactly the discipline the ADR literature has taught for fifteen years, except enforced by software instead of etiquette. Anyone who has maintained a doc/adr folder will recognize the shape immediately, because it's the same shape. The markdown database that architects designed in 2011, finally given a runtime.

Where Lockstep fits

This is what I'm building. Lockstep is a shared decision ledger for AI coding agents: the proposal, notification, briefing, and merge-gate mechanics above, exposed through MCP so it works the same whether the agent doing the typing is Claude Code, Codex, or Gemini CLI. A coordination layer has no business caring about the vendor. And only decisions and metadata flow through it. Source code, diffs, file contents: none of it leaves the developer's machine, because a system of record for decisions doesn't need to read your code, only your choices.

It also treats fifteen years of ADR practice as an inheritance, not a rival. An existing doc/adr folder can be ingested as the ledger's opening state, and any decision in the ledger can be exported back out as a plain markdown ADR for the humans and auditors who want one. The archive keeps its history and gains a reader that acts on it.

The merchant story, meanwhile, ended the way these stories end. The guard shipped in half a day. The experiment is being rebuilt. The trust is coming back more slowly than either. And the decision at the center of it was never wrong, exactly. It was made by a competent person for defensible reasons. It just had no way to travel from the head it lived in to the people it affected, and every tool we had, the repo, the tracker, the chat, was built to carry code and conversation, not decisions.

Nygard had the right instinct in 2011: the decisions are the real asset, so record them like one. What he couldn't have designed for was a reader that never sleeps, never skips the folder, and can intervene at the exact moment a rule is about to be broken. For fifteen years, ADRs were documents waiting for that reader.

The reader exists now. It just isn't human.

ADRs aren't going anywhere. They're becoming an input.