Agents · Context

An agent will delete
a reason it cannot see.

Architecture decision records sat dormant for a decade because keeping them was work. They came back in 2026 for a reason nobody predicted: coding agents now write a large share of the code, and a constraint whose justification is invisible looks exactly like a mistake worth cleaning up.

Write one free — no signup See the product ⟶

The failure

It is not a hallucination. It is a clean, confident diff.

This is what makes it hard to catch in review — the change is locally correct and the reasoning it destroys was never written down.

The retry that looks wrong

Exponential backoff with jitter next to three services using a flat delay reads as inconsistency. The agent tidies it. Nobody remembers that the flat delay is what emptied the connection pool in February.

The check that looks dead

A null guard for a case that cannot happen — except through one upstream client that still sends the old payload shape. Unreachable by inspection, load-bearing in production.

The index that looks redundant

Duplicated by a broader composite index, so dropping it is obviously safe. It is the one the nightly reconciliation query actually plans against, and that job runs when nobody is watching.

In all three the agent behaved reasonably given what it could see. The defect is not in the model. It is that the reason existed only in a review thread, an incident channel and somebody’s memory.

The distinction

AGENTS.md carries the rule. A record carries the reason.

Both belong in a repository, and they are not substitutes. Teams already keeping an AGENTS.md have done the harder half of the work.

An instruction

“Always use exponential backoff with jitter.” Followed until it conflicts with something else, at which point it is weighed against a rule with a visible justification and loses. An instruction with no reason attached is the weakest thing in the context window.

A record

“A fixed five-second retry took production down on the 9th — every client woke at once and hit an empty pool. Fixed delay was rejected in PR #418.” That is something an agent, or a person, can actually reason with rather than merely obey.

What to do

Three things, in order of return

Step

Put the reasons in the repo

A docs/decisions/ directory of plain markdown. An agent reads what it can reach — a decision behind a wiki login is invisible at the moment it matters, which is while the file is being edited.

Step

Record what you rejected

The rejected option is the part that prevents the refactor. An agent proposing the flat delay has, in effect, proposed something your team already tried; the record is what lets it find that out.

Step

Stop writing them by hand

The practice died the first time because the writing was a separate act of will. The work already happened in the commits and the review — an agent that reads those can write the record without anyone remembering.

The symmetry

The same records serve the new hire and the agent

Which is what makes this worth doing even if you are sceptical about how much code agents should be writing.

An engineer joining in March and an agent editing a file at two in the afternoon are asking the same question in the same words: why is this like this? Both are blocked by the same missing sentence, and both are unblocked by the same file. There is no separate artefact to maintain for the machine — a decision record written so a person can follow it is already in the format an agent reads best, because plain markdown in a predictable directory is the lowest common denominator of both.

That is the argument for putting the effort here rather than into another wiki space. One archive, two readers, and the only one of your documentation surfaces that gets more valuable as the codebase moves faster.

Questions

What people ask about this

01Why would a coding agent undo a deliberate decision?+

Because from inside the diff it looks like an inconsistency. A hand-tuned retry with jitter reads as needless complexity next to a clean fixed delay; a defensive null check reads as dead code; an odd-looking index reads as a mistake. The agent is not wrong about the code — it simply cannot see the incident that produced it.

02Is not this what AGENTS.md or CLAUDE.md is for?+

Those carry standing instructions, and they are worth having. A decision record carries the reasoning underneath them. "Always use exponential backoff" is an instruction an agent will follow until it conflicts with something else; "a fixed delay took production down on the 9th because every client woke at once" is a reason it can weigh. Instructions without reasons lose arguments.

03Should decision records live in the repo for this to work?+

Yes, for a practical reason: an agent reads what it can reach. A decision in a wiki behind a login is invisible at the moment the agent is editing the file it concerns. Markdown in the repository is readable by every agent, every editor and every new hire without configuration.

04Do agents actually read documentation directories?+

They read what is in the working tree and what you point them at. A docs/decisions/ directory sits in the repo alongside the code, so it is available to grep and to read like any other file — which is why the format that survives is plain markdown in a predictable place, not a database.

05Can the agent write the records as well as read them?+

That is the whole idea. The work that produced the decision is already in the commits, the review thread and the incident. An agent that reads those can write the record without anyone remembering to, which removes the discipline requirement that killed the practice the first time round.

06What if the record is wrong?+

Every claim should cite the commit, pull request or message it came from, so a wrong record is checkable rather than merely believable. Anything that cannot be traced to something a person actually wrote should be left blank and flagged, not filled in plausibly — a confident invention is worse than a gap.

Keep going

Free ADR generator

Turn a merged pull request into a decision record your agent can read. No account.

Documentation that keeps the why

The agent that writes these from your commits, pull requests and incidents.

ADR vs wiki

Why a living page cannot answer what the team believed in March.

Write the reason down before something removes it

Start with one decision your team argued about this quarter. If a record of it would have changed a review, that is the whole case.

Try it free — no signup See how it works