Architecture decisions: the first thing an agent cannot guess about your code

In 2011, Michael Nygard wrote that "one of the hardest things to track during the life of a project is the motivation behind certain decisions." Almost fifteen years later, the sentence describes a new problem: the coding agent that enters your repository arrives without that motivation and has nobody to ask.

This piece defends a simple thesis: when an agent enters a repository, the first thing to write is not a better prompt. It is the decisions that cannot be reversed without cost, with their context and the alternatives that were ruled out, in the repository and where the agent will read them.

What the code does not say

Code says what the system does. It does not say why it has that shape: why there is a queue where a direct call would seem enough, why one service is the only one writing to the database, or why the option that looks obvious today was rejected. That why usually lives in the heads of two or three people.

A new developer recovers it by asking. Benjamin Cane, who writes about architecture and coding agents, puts it bluntly in May 2026: unlike human engineers, agents do not get context from hallway conversations, shadowing others or tribal knowledge. They only know what is captured.

Nygard's dilemma, at agent speed

Nygard described what happens to someone who inherits a project without knowing its decisions: they either accept them blindly or reverse them blindly. His conclusion is that it is better to avoid both. An agent is in exactly that position, with one difference: it acts fast. If it accepts blindly, it repeats a pattern whose reason no longer exists. If it reverses blindly, it undoes a decision someone made for a reason.

Microsoft's Azure architecture guidance puts it another way: a decision that is made but never recorded will likely be forgotten, leading to repeated debates or later changes that unknowingly contradict the original intent.

What deserves a record, and what it looks like

Not everything deserves a record. Microsoft recommends including only decisions that affect the structure of the system, its key quality attributes or that are difficult to reverse, with the alternatives that were ruled out. Nygard proposes a short format, one or two pages, numbered sequentially and with five parts:

An illustrative example, invented and unrelated to any client:

• Title: orders are written only from the orders service.
• Status: accepted.
• Context: several services wrote to the same table and the data arrived inconsistent.
• Decision: a single service writes; the rest publish events. A database per service was ruled out because of the cost of running so many.
• Consequences: a change to orders requires coordinating with the orders service. That friction is accepted.

With this in front of it, an agent asked to "write the order from the billing service" should be able to detect that it clashes with the decision and stop to check. Without it, it has no way of knowing.

Another rule from Microsoft's guidance helps the agent: accepted records are not edited. If a decision changes, a new one supersedes it and the two are linked, so the history of why the direction shifted remains.

Where to put them so the agent reads them

Cane recommends keeping them in Git, alongside the code, because that gives versioning, review workflows and automated validation. If the architecture spans several services and repositories, he proposes a central architecture repository added as an extra directory when running the agent. And if they already live in a wiki, an MCP server (Model Context Protocol) can serve them to the agent, at the cost of more infrastructure.

It helps not to confuse what each layer does. Shared instructions guide the agent day to day, as we saw in shared, curated instructions. What must hold is enforced with controls, not a file, as we explained in Claude Code for teams: context is not control. The decision record is the third layer: it orders nothing, it explains why things are the way they are.

How far to take it: rules the machine checks

Some go further. In March 2026, a team of authors published "Architectural Governance at AI Speed" on InfoQ. They propose turning each decision into a brief directive that both person and agent can internalize, and that the agent checks against the code. They describe the decision record as an "atomic unit of intent" and point out that, if every record must be approved before implementation, people end up as the bottleneck.

Where to start if the code is years old

Microsoft advises starting the record on existing projects too and, if the data is available, generating it retroactively from known past decisions. You do not need to document the whole system: start with the part the agent is going to touch, as we explained in specifying legacy code before AI agents.

1. List the decisions in that part of the code that would be costly to reverse.
2. Ask whoever made them, while they are still on the team, for the context and the alternatives that were ruled out.
3. Write each one in one or two pages, with the five parts, and keep it in the repository.
4. Have the agent read them before touching that part of the code, and have a person review any change that contradicts them.
5. When a decision changes, write another that supersedes it and link the two.

This builds on the rest of the method. The threshold for what gets specified and what does not, in Spec-Driven Development (SDD, development guided by specifications), is covered in SDD templates are now free, and the test safety net that catches errors in before the agent, the safety net.

Where onext fits

In AI-Accelerated Development we build, with your team, the context the AI works in and the process you work with. Both stay with you. A person decides where there is risk. The first step is a free diagnostic, and if the diagnostic shows no difference, there is no Quick-start.

Frequently asked questions

What is an architecture decision record (ADR)?

A short document that records an architecture decision: what was decided, in what context and with what consequences. Michael Nygard proposed it in 2011 with five parts: title, status, context, decision and consequences.

Why does an agent need decisions in writing?

Because it has nobody to ask. Benjamin Cane puts it this way: unlike human engineers, agents do not get context from hallway conversations, shadowing others or tribal knowledge. They only know what is captured.

Which decisions deserve a record?

Those that affect the system structure, its key quality attributes or that are hard to reverse. Microsoft advises including only those.

Can an accepted record be edited?

It is better not to. Microsoft's guidance treats it as an append-only log: if a decision changes, a new record supersedes the original and the two are linked, so the history of why the direction shifted is kept.

Where do you keep them so the agent reads them?

Cane recommends keeping them in Git alongside the code, since that gives versioning and review. If the architecture spans several repositories, a central architecture repository; if they live in a wiki, an MCP server (Model Context Protocol), at the cost of more infrastructure.

Can machines enforce decisions without a person?

That is a trend: InfoQ proposes turning each decision into a brief directive the agent checks against the code. New decisions, and exceptions, still need a person to decide.

Sources

• Michael Nygard, "Documenting Architecture Decisions", Cognitect, 15 November 2011.
• Microsoft Learn, "Maintain an architecture decision record (ADR)", Azure Well-Architected Framework, 10 April 2026.
• Benjamin Cane, "Your coding agent is missing one thing: architectural context", 28 May 2026.
• Kyle Howard, Christian Johansen, Dana Katzenelson, Brian Rhoten and Warren Gray, "Architectural Governance at AI Speed", InfoQ, 26 March 2026.
• The example record, the agent column and the reading are onext's own elaboration; the example is illustrative, invented and does not correspond to any client.