Ask your coding agent why the retry wrapper exists and watch what happens. It reads the code, infers a plausible reason, and states it with total confidence. The plausible reason is wrong — the wrapper exists because a specific provider returns 200 with an error body, which is not visible from the wrapper at all.
The real reason was written down. It is in an architecture decision record, in a folder, that nobody has opened since it was merged. The agent did not read it because nothing told it the record existed or that it was relevant to the file being edited.
That is the failure mode this post is about, and the fix is not "write more ADRs". It is turning the records you already have into something an agent can traverse.
Why prose ADRs do not work for machines
The standard ADR is a markdown file with a context, a decision and consequences. It is a good format for humans and a poor one for programs, for three specific reasons.
No edges. Decision 0084 supersedes 0061 and rests on 0012. In prose that relationship is a sentence — sometimes a link, often just a number in a paragraph, occasionally only implied. There is nothing to traverse, so "what does this decision depend on" is a reading-comprehension task rather than a query.
No stable identity. Records get renamed when the title is improved, renumbered when someone reorders the folder, moved when the directory is reorganised. Every reference to them silently rots. Six months in, half the cross-references point at nothing, and nobody notices because nothing checks.
No validation. A broken link between two documents is invisible. Compare that to code: a reference to a symbol that does not exist fails the build immediately, which is precisely why code stays more internally consistent than documentation does.
Fix those three and the ADR folder stops being a shelf and becomes an index.
Making it a graph
Mint the identifier once, never move it
Give every record an identifier assigned at creation and never changed — not the title, not the folder position, not the sequence number in a list somebody might reorder. Everything else about the record can change freely: the title, the directory, the wording, the status. References point at the identifier, so they survive all of it.
This is the single highest-leverage change, and it is worth doing even if you adopt nothing else here. The cost is one line of frontmatter. The benefit is that a reference written today is still valid after two reorganisations.
One edge kind, not seven
The temptation is a rich vocabulary: supersedes, refines, conflicts with, implements, relates to. Resist it. Rich edge taxonomies get applied inconsistently by the third contributor, and an inconsistently-typed edge is worse than an untyped one because queries now silently miss things.
One edge kind carries almost all the value: rests on. Decision B rests on decision A when A being wrong would put B in question. That single relation gives you dependency traversal, impact analysis, and a topological reading order. Status (accepted, superseded, rejected) lives on the node, not the edge, which keeps supersession from needing its own relation.
A dangling edge fails the build
This is the rule that makes the rest survive contact with a real team. A reference to an identifier that does not exist is not a warning printed into a log nobody reads — it fails validation, and validation runs in CI alongside the tests.
The same check enforces acyclicity. A cycle in "rests on" means the reasoning is circular, and it is far easier to catch at the moment it is introduced than six months later when someone is trying to understand the chain.
Once validation is a gate rather than a report, the graph stays true without anyone maintaining it as a chore. That is the whole trick: the discipline is enforced by a machine, so it does not depend on anyone remembering.
Connect the graph to the code
A validated graph of documents is still a separate world from the source. The bridge is a marker: a short annotated comment at the definition it applies to, naming the decision identifier.
// @decision ADR-0084 — retry wrapper: this provider returns 200 with an error body
export async function callProvider(req: Request): Promise<Result> {
Cheap to write, and it changes what is possible on both sides. From the code, an agent editing this function can ask what was decided here. From the graph, a decision can enumerate the code that implements it. And a marker pointing at a decision that does not exist fails the same validation as a dangling edge, so the bridge cannot silently rot either.
What the agent gets to ask
With the graph in place, three questions become single calls rather than archaeology:
| Question | What it returns |
|---|---|
| Why is this the way it is? | The decisions attached to this file or symbol, plus what they rest on — the reasoning chain, not a search result. |
| What does this change put at risk? | Everything that rests on the decision being touched, transitively. The review checklist, derived rather than remembered. |
| In what order should I read this? | A topological walk from foundations upward, so an agent onboarding to an area reads causes before effects. |
The second one is the one that pays for the whole exercise. "What else does this affect" is the question that regressions are made of, and it is exactly the question that a human answers from memory and an agent cannot answer at all — unless the dependencies are written down as edges.
Provenance: the other half
A decision graph explains why. It does not explain how this symbol came to be the way it is — which is a different question with a different answer.
Derive that from what actually happened rather than storing it by hand. A symbol gets renamed, moved to another module, split into two, and later merged back. Every one of those events is recoverable from history, and chained together they answer "where did this come from" long after the original name is gone.
The important design decision is what to do when the chain breaks — when a rename is ambiguous, or a file was rewritten wholesale. The wrong answer is to guess and present the guess as history. The right one is to report the break: "the chain is continuous to this commit, and before that it cannot be established." An agent can work with a bounded history. It cannot work with a fabricated one.
Is this worth it for a normal team?
Honest answer: the identifier rule and the validation gate are worth it at almost any size, because they cost close to nothing and they prevent the slow rot that makes documentation untrustworthy. I run 191 decision records this way and the maintenance overhead is close to zero, precisely because it is enforced rather than remembered.
The markers and the provenance layer earn their keep when you have agents editing code you did not personally write, or a team large enough that the reasoning has left the room. Below that threshold, the graph without the code bridge is still a large improvement over a folder.
The one thing not worth doing is adopting the ceremony without the enforcement. An ADR folder with a rich edge vocabulary and no validation is more expensive than no folder at all — it looks authoritative and it drifts.
Takeaways
- Prose ADRs fail machines on three counts: no traversable edges, no stable identity, no validation.
- Mint the identifier at creation and never change it. Highest return, lowest cost.
- One edge kind — rests on. Status lives on the node. Rich taxonomies get applied inconsistently.
- A dangling reference fails the build. Enforcement is what keeps the graph true without anyone maintaining it.
- Markers in code connect the graph to the source in both directions, and validate the same way.
- Derive provenance from what happened; when the chain breaks, report the break instead of guessing.
- Adopt the enforcement or do not adopt the ceremony — an unvalidated graph drifts while looking authoritative.
The decision graph answers why; persistent memory answers what we already learned the hard way; and the general rule behind both — that an answer must state its own reliability — is the normative model for agent-facing services. If you want this built into your repository, that is the AI development engagement.