What Happens When Coding Agents Read Your ADRs
Every codebase has rules that aren't written down anywhere an agent will find them: where tests go, which helper to use, how a new feature gets wired through each layer. Architecture Decision Records (ADRs) write those rules down. We wanted to know how much difference they make to a coding agent, so we measured it.
We took 15 real feature requests from 10 open-source projects: Documenso, Drupal, Dify, Pydantic, Puck, Svelte, Zod, Payload, Excalidraw and Next.js. The agent did each task twice, starting from the same code: once on its own, and once with the project's ADRs from Actual AI. You can watch every recording at demos.actual.ai.
The results
With ADRs, the agent:
- Took about 90% fewer wrong turns: 191 across all 15 tasks without ADRs, and 20 with them. A wrong turn is a step that heads away from the goal or breaks the project's conventions, as flagged by an AI judge that reviews every step the agent takes.
- Took no wrong turns at all on nine of the 15 tasks.
- Used 37% fewer tokens across all 15 tasks. Tokens are what you pay for, so this is the cost of the work.
- Finished 22% faster. The 15 tasks took 120 minutes in total without ADRs, and 94 minutes with them.
What the difference looks like
The numbers come from ordinary tasks, the kind a team hands an agent every day.
Locking a field once a record is published, in Payload. The lock has to hold in two places, the editing screen and the data API, and the pattern for wiring that through the framework isn't in any one file. Without ADRs, the agent took 14 wrong turns working it out. With them, it took none and used 58% fewer tokens.
Tracking unsaved changes in the Puck page editor. Nothing in the codebase shows how to do this, so the agent has to decide where to store the state, when work counts as saved, and how to expose it. Without ADRs, it hit 23 dead ends. With them, it hit none and used 69% fewer tokens.
Adding a browser helper to Svelte. Svelte code also runs on the server, where browser-only features crash the page. Without ADRs, the agent copied a similar-looking helper and shipped code that breaks during server rendering. With them, it followed the server-safety rule and got it right the first time.
Agents read the rules, and only the ones they need
Better results only mean something if the agent actually used the ADRs. So we checked which files it opened in each recording.
- Agents read only the rules that apply. The 15 projects have 187 ADRs between them, and most were opened for at most one task. The agent picks out the few that matter for the change in front of it.
- They read the rules before writing code, almost always before the first edit, not halfway through after something has gone wrong.
- Reading the rules is cheap. It accounts for about 5% of the agent's tokens, while the tasks as a whole used 37% fewer tokens.
That's the case for ADRs in a sentence: a little reading up front replaces a lot of rediscovering the project the hard way.
Making the rules better
The same check shows us which rules agents skip. When an ADR covers code the agent changed but the agent never opened it, the rule's title or scope isn't telling the agent it's relevant. We now use that to improve how we write ADRs, so the right rule gets read for the right change. For more on what makes an ADR easy for an agent to use, see ADRs for Coding Agents.
A note on the numbers
Each task was recorded once with ADRs and once without, so any single task is an example rather than proof. The result is the consistency: fewer tokens and fewer wrong turns on all 15 tasks, across 10 different projects.
Watch any of the 15 tasks side by side, with and without ADRs, at demos.actual.ai.