Recording architecture decisions for AI agents

Recording architecture decisions for AI agents means writing each settled choice as a short, numbered record that the agent reads before it works on related code, so it stops proposing the option you already rejected. Agents relitigate decisions for a simple reason: they cannot see why the code looks the way it does. Faced with integer cents in a billing module, a fresh session may 'improve' them to floats, because nothing in its view says that was considered and refused. A decision record fixes that cheaply. It states the context, the choice, the alternatives that were ruled out and the consequences, in under a page. It sits at a predictable path, it names the code it governs, and when the decision changes it is superseded rather than quietly edited. This workflow adapts the classic architecture decision record for readers that are models as well as people, and it complements instruction files such as CLAUDE.md rather than replacing them.

Why agents keep reopening settled choices

A human joining a team learns the history in conversations, reviews and hallway explanations. An agent has none of that. It sees the code and whatever text you put in front of it, and it is trained to suggest improvements. Without a reason on record, an unusual choice looks like a mistake to be fixed.

The symptoms are familiar. The agent suggests replacing the hand-written SQL with an ORM you dropped last spring. It adds a dependency to a package that must stay dependency-free. It moves validation into the client when you deliberately kept it on the server. Each proposal is reasonable in isolation, so it costs review time even when you reject it, and occasionally one slips through.

Telling the agent again in chat works for one session. The next session starts without it, and long sessions can lose it to summarization, as described in what gets lost when an agent summarizes a long session. The decision needs to exist outside any conversation, in a form short enough to load every time the related code is touched. When an agent keeps going back anyway, an agent that forgot decisions covers diagnosis.

A format an agent will actually read

Keep each record to one screen. Long essays get skimmed by people and diluted in a model's window. A workable template:

Title and number: 'ADR-0007: Store money as integer cents'.

Status: Proposed, Accepted, or Superseded by ADR-00NN, with a date.

Applies to: the paths or modules it governs, such as src/billing/ and src/export/.

Context: two or three sentences on the problem and constraints.

Decision: the choice, stated as a rule. 'All monetary values are integers in cents. Conversion happens only in money.py.'

Rejected alternatives: each with a one-line reason. 'Floats: rounding errors in totals. Decimal everywhere: too invasive for the export code.'

Consequences: what this makes harder, and what to watch.

Agent rules: plain imperatives. 'Do not introduce float arithmetic for money. If a task seems to require it, stop and ask.'

The rejected alternatives and agent rules carry most of the value for an agent. They turn a vague preference into a check it can apply, and they give it a clear stop condition, which ties into when agents should stop and ask.

Where to keep decision records so they get read

Put the records in the repository, one file each, in a folder such as docs/decisions/, named by number and slug: 0007-money-as-integer-cents.md. Version control gives you history and review for free, and the records travel with the code to every branch.

Then make reading them part of starting work, in three places.

Index: keep a short index file listing each accepted decision in one line with its path. Point to it from your project instruction file with one sentence, rather than pasting every decision into that file.

Task: when you write a task that touches governed code, name the relevant record in the task description. 'Constraints: ADR-0007 applies.' This is the most reliable trigger, because the agent reads the task first.

Code: for decisions that are easy to violate, a one-line comment at the key place helps. '# Money is integer cents, see docs/decisions/0007.'

Avoid loading every record into every session. Twenty decisions in front of a task about the login page are noise. Select the ones linked to the task, which is the idea behind bounded task context.

Superseding a decision without confusing the agent

Decisions change. The mistake is editing the old record in place, because then the history disappears and any task or note that cited it now points at different words.

Instead, write a new record. ADR-0012 says 'Use Decimal for money in the export module', explains what changed, and lists ADR-0007 under 'Supersedes'. Then change ADR-0007's status line to 'Superseded by ADR-0012 on 2026-10-30' and leave its body alone. Update the index so only accepted records appear in the active list.

Tell the agent explicitly. A task description that says 'ADR-0012 replaces ADR-0007 for src/export/' prevents the agent from finding the old record and following it. Search the repository for references to the old number, including code comments and open task records, and update them in the same change.

A partial supersession needs care. If cents still apply to billing but not to export, say so in both records' 'Applies to' lines. Ambiguity here is where agents go wrong, because two accepted rules seem to conflict and the agent picks one.

Finally, when a change silently contradicts a record, treat that as a review failure, not just an agent error.

QUESTIONS

What is an architecture decision record?

A short document that records one significant technical choice: the context, the decision, the alternatives considered and the consequences. Records are numbered, dated and kept with the code. When a decision changes, a new record supersedes the old one instead of overwriting it, so the history stays readable.

Should decisions go in CLAUDE.md or in separate files?

Usually in separate files, with a one-line pointer from the instruction file. Instruction files work best for short, always-true rules. Decision records carry context and rejected options, grow over time and only matter for certain code, so they are better loaded when a task touches that code.

How do I stop an agent following a decision that has changed?

Write a new record that supersedes the old one, mark the old record's status as superseded, update the index and search for references to the old number in tasks and comments. Then name the new record in the next task description so the agent sees the change first.

RELATED GUIDES

• How to read BRAIN FLUID reports and provenance
• How to create a project card in BRAIN FLUID Desk

RELATED HARNESS PAGES

• CLAUDE.md alternatives CLAUDE.md alternatives compared: what a project instruction file does well, where it stops, and what a project harness like BRAIN FLUID adds.
• Why did my AI agent forget what we decided yesterday? Agent sessions don't carry memory, and decisions left in chat vanish. Find where the decision lives, write a record, and read it at session start.
• When an autonomous agent run should stop and ask When an autonomous agent run should stop and ask: failed checks, missing approval, open blockers, impact obligations, out-of-scope writes or uncertain state.
• Bounded task context Bounded task context: give an agent the slice of a project one task needs, chosen by relationship, capped in size, with omissions stated.