Here is a scenario every team shipping with AI will eventually live through.

Your codebase has a queue between two services. It looks like overkill. Synchronous calls would be simpler, faster to trace, fewer moving parts. There’s a reason the queue exists - a partner API that goes down for hours at a time, discovered painfully in production two years ago - but that reason lives in a Slack thread and one senior engineer’s head.

Now you ask an agent to “clean up the integration layer.”

It sees the queue. It sees no reason for the queue. It does exactly what you’d want a smart engineer to do with unjustified complexity: it removes it. The diff is clean. The tests pass. The PR description says “simplified.”

Three weeks later the partner API goes down, and you get to rediscover the original incident from scratch.

The agent wasn’t wrong. It was uninformed. And unlike a human junior, it will never absorb the context by osmosis - no standups, no war stories over coffee, no “oh, don’t touch that, ask Marko why.” Every session starts at zero.

Chesterton’s Fence, Industrialized

There’s an old principle: don’t remove a fence until you know why it was put up. Human engineers violate it occasionally. Agents violate it by default, because their entire training pushes toward the most plausible-looking code - and deliberate weirdness never looks plausible.

Your architecture is full of deliberate weirdness. The timeout that’s suspiciously long because a legacy client needs it. The two messaging systems that look like inconsistency but exist because one path needs ordering guarantees and the other needs fan-out. The denormalized table someone will “fix” back into a join that takes down the dashboard.

To an agent, every one of these is a bug-shaped invitation.

This isn’t an argument against AI-assisted development. It’s an argument that the cost of unwritten rationale just exploded. A human might trip over an undocumented decision once a year. An agent tripping over it is a coin-flip every session.

ADRs Found Their Real Audience

I’ve written before about Architecture Decision Records: short markdown files, versioned next to the code, each one capturing a decision, its context, and its consequences. The pitch was always about future maintainers - the engineer who joins in three years and asks “why is it like this?”

That pitch just changed shape.

The future maintainer is now an agent. It arrives not in three years but in the next prompt. It reads faster than any human, forgets more completely than any human, and acts with more confidence than any human. ADRs written for a hypothetical someday-reader are now load-bearing infrastructure, read constantly, by something that will act on what it reads - or on the absence of it.

And here’s the compounding effect: agents are also the reason ADRs actually get written now. The classic failure mode of ADRs was discipline - nobody wants to write documentation after the decision is made. But an agent can draft the ADR as part of the change, in seconds, for a human to correct and approve. The excuse is gone.

In the workflow post I gave one rule: every time the LLM proposes a major decision, either point it to an existing ADR, or make it draft a new one first. This post is the why behind that rule. The ADR log becomes the one memory that persists across sessions, across models, across tools - the thing that makes agent number forty-seven behave like it was there for the incident that agent number three caused.

Write Them for a Reader That Doesn’t Ask

One adjustment matters when your audience is a machine that never asks follow-up questions.

Classic ADRs explain. Agent-era ADRs must also constrain. “We chose SQS between orders and fulfillment” explains. “Do not replace this queue with synchronous calls; the partner API has multi-hour outages (see incident 2024-03)” constrains. A human infers the second sentence from the first. An agent needs it spelled out, because the moment of temptation - this queue looks unnecessary - is exactly when it needs the prohibition, verbatim, in context.

The same goes for placement. An ADR the agent can’t see doesn’t exist. Keep them in the repo, reference them from the rules file your tooling loads, and mention them near the code they protect. The model obeys what it can see.

None of this is heavy process. It’s ten minutes per significant decision - most of it drafted by the agent itself.

The teams that skip it will keep having the same experience: five clean-looking edits, then the system quietly loses a property nobody remembered it had. The teams that do it get something genuinely new - an institutional memory that doesn’t retire, doesn’t forget, and gets read before every change.

Your architecture is full of fences. Put signs on them.