The ADR Your Agent Never Read

Your team rejected the microservices split in 2024. There was a two-hour meeting, a heated Slack thread, and a spreadsheet comparing operational costs. The conclusion was firm: the monolith stays until the platform team ships multi-region deploys. Everyone who was in the room still remembers.

Your coding agent was not in the room. Last Tuesday it proposed the split again — confidently, with a clean migration plan and a well-argued design doc. The Tuesday before that, a different agent session proposed extracting the billing service. Next week, a third one will suggest replacing your bespoke job queue with the message broker you evaluated and rejected twice. None of them are wrong on the merits as they can see them. They just can't see the merits, because the reasoning that settled these questions lives in a Slack thread that expired, a meeting that wasn't recorded, and the heads of two engineers, one of whom left.

This is the quiet failure mode of agent-assisted engineering: settled questions get re-litigated at machine speed. And the fix is a practice most teams filed under bureaucratic nice-to-haves a decade ago — the architecture decision record.

Undocumented Decisions Get Re-Argued at Machine Speed

Human teams have always leaked decision context. People forget, leave, or were never told. But human re-litigation had natural rate limiting: a new engineer proposes the rejected thing maybe once, gets told "we tried that in 2024, here's why it didn't work," absorbs the lore, and becomes a carrier of it. The tribal-knowledge system was lossy but self-healing, because the humans who bumped into the wall stayed around and remembered where the wall was.

Agents break both properties. They don't stay around — every session starts from zero, with no memory of being told "we tried that." And they don't propose the rejected thing once; they propose it every time the local evidence suggests it, which is every time they read the code. A codebase with a deliberately chosen "wrong" pattern — the denormalized table you kept for read performance, the synchronous call you left in place because the downstream team can't handle retries, the old framework version pinned for a compliance reason — looks to a fresh agent like a codebase full of improvement opportunities.

Worse, agents act on it. A human junior engineer proposes the migration in a design review, where someone can catch it. An agent doing autonomous refactoring, dependency upgrades, or "cleanup" sweeps may simply start doing the thing you decided against, and now the rejection has to be re-derived, re-argued, and re-enforced — in code review, at whatever volume your fleet generates diffs. Teams running multiple concurrent agent sessions report the same proposal surfacing independently in three different PRs in the same week. Each one costs reviewer attention. The aggregate cost is a tax on every undocumented decision you've ever made.

The uncomfortable insight: the decision was never actually settled. It was settled for the people who were there. An organization's decisions are only as durable as their most durable representation, and for most teams that representation was collective memory. Agents just exposed how little was actually written down.

Why ADRs Suddenly Matter More Than They Did

Architecture decision records have been around since Michael Nygard's 2011 formulation: a short document per significant decision, capturing the context, the decision itself, and its consequences. Numbered, immutable, stored in the repo next to the code. The format never failed on its merits — it failed on its economics. Writing the record cost a motivated engineer thirty minutes; the payoff was diffuse, deferred, and mostly accrued to future strangers. In DORA terms, ADRs stayed an elite-team practice because only elite teams could sustain paying present costs for future benefits.

Agents flip the economics on both sides.

The payoff is no longer diffuse or deferred. An ADR in the repo is context an agent can load today, on the next task it runs. ADRs turn out to be an almost accidentally perfect fit for LLM consumption: they're natural language, so no retrieval pipeline or schema is needed; they're short and self-contained, so they fit in a context window without crowding out the task; they're colocated with the code, so agents that explore the filesystem find them the same way they find your README. A structured knowledge base or ontology can outperform loose documents for machine reasoning — but ADRs capture most of that value at a fraction of the ceremony, because the unit of an ADR is the reasoning chain: here was the situation, here were the options, here's why we picked this one.

Meanwhile the cost of writing them has collapsed. The moment a decision gets made — in a design discussion, in a PR debate, in the middle of an agent session — you can have the agent draft the ADR while the context is still in the window. The human's job shrinks to verifying that the recorded reasoning is the actual reasoning, not a plausible reconstruction. Thirty minutes of motivated-engineer time becomes three minutes of review.

When a practice's costs drop tenfold and its benefits move from next-year to next-session, it stops being a maturity signal and becomes infrastructure. That's the shift: ADRs are no longer how disciplined teams communicate with future teammates. They're how any team communicates with the part of its workforce that has no long-term memory.

Wiring "We Tried That" Into the Loop

Having ADRs and having agents read them are different problems. A docs/adr/ folder the agent never looks at is exactly as useful as the expired Slack thread. The wiring matters, and there are three levels of it.

Level one: make the records discoverable. Keep ADRs in the repository, in a conventional location, in plain markdown. Reference the folder from your agent instructions file — CLAUDE.md, AGENTS.md, whatever your tooling reads — with one line about what lives there and when to consult it: "Before proposing architectural changes, check docs/adr/ for prior decisions." Agents that explore before acting will find them; agents that don't will at least be pointed there. This costs nothing and catches the worst offenses.

Level two: inject the load-bearing ones. Discoverability relies on the agent choosing to look, and for the handful of decisions that get re-litigated most — the ones about your database, your service boundaries, your framework choices — hoping isn't a strategy. Summarize those in the instructions file itself, one line each with a pointer to the full record: "We use a monolith deliberately (ADR-0012); do not propose service extraction." The full ADR carries the reasoning for when the agent needs to explain or extend the decision; the summary carries the constraint for when it just needs to not violate it.

Level three: put decisions where the temptation is. The agent refactoring your payments module doesn't know ADR-0031 exists and doesn't know it's relevant. A one-line comment at the site of the deliberate weirdness — // intentionally synchronous, see ADR-0031 — converts a global document into local context that arrives exactly when the agent is looking at the code it governs. This is the same trick that works on human readers, but agents reward it more consistently: they read every line of the file they're editing, which is more than you can say for most of us.

The pattern across all three levels: reasoning must be retrievable at the point of decision, not merely stored somewhere. Experiments with agent knowledge bases keep finding the same gap — retrieval over loose documents reliably surfaces what was decided and reliably misses why, because the why is scattered across sources that don't co-occur in any single chunk. ADRs solve this structurally by making the why and the what the same document. But only if the document is in the loop.

The New Failure Mode: The ADR That Outlived the Decision

Here's what nobody warns you about, because it barely mattered when only humans read these documents: an authoritative record of a decision you've since un-decided is worse than no record at all.

Human readers treat documentation with ambient skepticism. An engineer who reads a 2023 ADR forbidding Kubernetes, while standing in a codebase visibly full of Helm charts, resolves the contradiction instantly — the doc is stale, the code is truth, moving on. Agents don't reliably do this. An instruction file or decision record carries authority in a way ambient code does not; that's the entire mechanism by which it works. The same authority that makes a current ADR powerful makes a stale one actively toxic: the agent will decline to use the approach you now prefer, "correct" new code back toward the superseded decision, and cite the record as justification — with the confident tone of an agent following instructions, because it is.

For humans, stale docs are friction. For agents that reload the docs on every request, stale docs are poison delivered continuously.

The classical ADR discipline already contains the answer; it just went from good hygiene to load-bearing. Never edit an accepted record — write a new one that supersedes it, and mark the old one superseded in its own header, not just in an index the agent may never read. The status line is doing real work now: an agent that opens ADR-0012 must be able to see, in that file, that ADR-0031 replaced it. Beyond that, two practices earn their keep:

• Treat decision reversals as doc changes. The PR that un-decides something updates the ADR chain and the instructions-file summary in the same diff, the way you'd update a type signature and its call sites together. A reversal that only lives in the merge commit is the 2024 Slack thread all over again.
• Audit the summaries, not just the records. The one-line constraints you injected into CLAUDE.md at level two are the highest-authority, highest-drift-risk surface you have. A quarterly pass asking "do we still believe each of these?" is cheap. An agent can do the first pass itself: cross-reference each stated constraint against the current codebase and flag the ones the code no longer honors.

There's a useful reframe hiding in this: your decision records are now a config file for your workforce. Nobody ships config they never revisit — or rather, teams that do, get exactly the incidents they deserve.

Write Down Why, Because the Reader Has Changed

For fifteen years the case for ADRs was an appeal to empathy: write it down for the future teammate you'll never meet. The case now is an appeal to throughput: write it down or your agents will re-argue it forever, one confident proposal at a time, and you'll pay for every re-litigation in review bandwidth — the one resource agent-assisted engineering doesn't multiply.

Start with the next decision you reverse or reject; that's the highest-value record you can write, because rejection reasoning is precisely what the code can never show. Have the agent draft it while the argument is fresh, spend three minutes making sure the recorded why is the real why, and put a pointer to it wherever the temptation will strike. Then, over time, backfill the greatest hits — every proposal your team has already swatted down twice is telling you which ADR to write next. Your agents are, in their obtuse way, generating a prioritized list of your undocumented decisions.

The teams that get this right will notice something subtle: the discipline was never really about the documents. It was about forcing decisions to have articulable reasons — a forcing function that tribal knowledge let everyone skip. Agents just ended the grace period.