Architecture Decision Record Template for AI-Generated Code

An architecture decision record template is a short, fixed structure for writing down one significant technical decision: the context, the decision, its status and its consequences. The format has been around since 2011. It matters more now because agents write a growing share of production code, and an agent never leaves a gap blank. It fills it with a plausible default, and the default reads exactly as confident as a choice someone thought hard about.

That is the problem this page solves. A reviewer looking at agent-written code cannot tell which choices were deliberate and which were assumed, so both human and AI reviewers either wave through accidental decisions or argue about deliberate ones. The second outcome is a large share of the noise teams blame on AI code review tools. Below: the two standard ADR formats, a lighter intent note for agent-written changes, where agents should read and write these files, and how to route the risky ones to a human.

What goes in a classic architecture decision record?

Michael Nygard’s 2011 post “Documenting Architecture Decisions” defined the format most teams still use. Each record is one or two pages, written in full sentences “as if speaking to a future developer”, stored in the repository and numbered sequentially without reuse.

Section	What it holds
Title	A short noun phrase, numbered: “ADR 9: LDAP for multitenant integration”
Context	The forces at play (technical, political, social, project-local), stated as facts, including the tensions between them
Decision	The response to those forces, in active voice: “We will…”
Status	Proposed, Accepted, and later Deprecated or Superseded (with a link to the replacement)
Consequences	Everything that follows from the decision, positive, negative and neutral

A reversed decision is not deleted. The old record stays, marked superseded, so a reader can see what the team once believed and why it changed.

When should you use MADR instead?

MADR (Markdown Architectural Decision Records) is the more structured alternative. The current release is 4.0.0, from September 2024. Its template adds the parts Nygard leaves implicit:

• Context and Problem Statement
• Decision Drivers (optional)
• Considered Options
• Decision Outcome, with optional Consequences and Confirmation subsections
• Pros and Cons of the Options
• More Information (optional)

MADR’s convention is to store records in docs/decisions/ as NNNN-title-with-dashes.md. Use it when the rejected options matter, which is often the case with agent-written code: an agent that does not know option B was tried and abandoned will happily propose option B again. The Confirmation section is also useful, because it says how compliance is checked, and a check is something a reviewer or CI can run.

Why does AI-generated code need recorded intent?

Three mechanisms make ADRs more valuable when agents write the code.

Agents decide implicitly. Ask an agent to add caching and it will pick an eviction policy, a TTL, a key scheme and an invalidation strategy. Some of those are things the team cares about; most were never discussed. The diff shows all of them with equal authority. A human author would at least remember which ones they agonised over. The agent does not carry that memory into the next session.

Reviewers cannot see intent in a diff. An AI reviewer that flags an unusual retry policy as a bug is doing its job if the policy was an accident, and generating noise if the policy was deliberate. The Tech Manager Weekly #504 community thread (19 October 2026) on AI reviews flagging unlikely edge cases landed on the same fix: record decision intent next to the code, so the reviewer knows what was deliberate, and route high-risk changes to a human.

Agents re-litigate settled decisions. Without a record, every new session starts from zero. An agent asked to “improve performance” may undo a deliberate consistency trade-off made two quarters ago. A short ADR that says “We chose strong consistency over latency for the ledger; do not introduce read replicas for balance reads” stops that in the instruction context, before any code is written.

The maintenance and tech debt page covers the longer-run cost: code nobody can explain becomes code nobody will touch.

A lightweight ADR template for AI-written changes

Full ADRs are for decisions that shape the system. Most agent-written pull requests do not need one, but many contain one or two choices that someone will later ask about. For those, a smaller intent note works better. It can live in the PR description, or as a short file next to the code it explains, and it graduates to a full ADR if it turns out to be architectural.

The key addition is the split between deliberate and assumed. Deliberate choices were specified by a person or an existing ADR. Assumed choices were filled in by the agent. Reviewers spend their attention on the assumed list.

# Intent note: <short title>

- Date: 2026-10-19
- Owner (DRI): <human name, not the agent>
- Change: <PR link>
- Status: Proposed | Accepted | Superseded by <link>
- Risk tier: low | medium | high   (high = routed to a named human reviewer)

## Goal
One or two sentences on what this change is for.

## Deliberate decisions
Choices a person made or that follow from an existing ADR.
- Use idempotency keys on POST /payments (ADR-0012).
- Retry at most 3 times with jitter; the upstream SLA allows it.

## Assumed decisions
Choices the agent filled in. Each one needs a reviewer's yes, no, or "promote to ADR".
- Cache TTL set to 300s. No requirement given.
- Chose an in-process LRU over Redis for simplicity.

## Not in scope
What the change deliberately does not do, so reviewers do not flag its absence.

## Constraints the reviewer should enforce
- No new network calls in the request path.
- Must not change the public API.

Two rules keep it honest. The owner is always a person, because an agent cannot be accountable (the AI code ownership policy page explains why). And the assumed list is written by the agent itself: ask it, at the end of a task, to list every choice it made that was not in its instructions. Agents are good at this when asked directly, and the list is the most useful review artefact a change can carry.

Where should agents read and write ADRs?

ADRs only constrain agents if agents load them. Every major coding agent reads a project instruction file, so point that file at your decisions.

File	Read by	What to put in it
AGENTS.md	A shared format stewarded by the Agentic AI Foundation under the Linux Foundation; supported by Codex, Cursor, GitHub Copilot coding agent, Gemini CLI, Jules, Windsurf and others	”Before changing architecture, read docs/decisions/. Do not contradict an Accepted ADR. Propose new ADRs with status Proposed.”
CLAUDE.md	Claude Code, including its Code Review service	The same rules; Claude Code Review flags changes that violate CLAUDE.md rules as findings
.github/copilot-instructions.md	GitHub Copilot, including Copilot code review	The same rules, or a pointer to AGENTS.md, which Copilot also reads
REVIEW.md	Claude Code Review only	”Treat a change that contradicts an Accepted ADR as Important.”
.cursor/BUGBOT.md	Cursor Bugbot	The same review rule

The AGENTS.md convention also supports nested files in subprojects, with the nearest file taking precedence. That lets a payments service carry its own decision pointers without bloating the root file.

Write rules for agents in plain imperatives:

1. Read docs/decisions/ before any change that touches data models, public APIs, dependencies, or cross-service calls.
2. Never edit an ADR with status Accepted. To change direction, create a new ADR that supersedes it.
3. When you make a choice not covered by the instructions or an ADR, list it under “Assumed decisions” in the PR description.
4. If an assumed decision is architectural, draft a new ADR with status Proposed in the same PR.

How should ADRs route review?

Recording intent pays off when it changes who reviews what. Three mechanisms do the routing.

Code owners on the decisions folder. On GitHub, a CODEOWNERS entry such as docs/decisions/ @org/architecture means any PR that adds or changes an ADR requires review from that group. An agent can propose; only the named owners can accept.

Risk tiers on the intent note. A change marked high risk (auth, payments, data deletion, migrations, anything touching personal data) goes to a named human reviewer regardless of what the AI reviewer said. The tier should be set by path rules where possible, not by the agent’s own judgement of its work.

AI reviewer rules that cite ADRs. Put “flag contradictions with Accepted ADRs” in the AI reviewer’s rule file. This turns the reviewer from a generic bug-hunter into a consistency checker for your own decisions, which is the kind of finding engineers act on. It also cuts noise: a reviewer that knows a choice was deliberate stops flagging it.

What should not get an ADR?

Over-recording kills ADR practices faster than under-recording. Skip ADRs for choices that are cheap to reverse, local to one file, or enforced by a linter. A useful test: if someone reverses this in six months without knowing why it was made, does anything break or cost real money? If not, a line in the PR description is enough. If so, write the record.

The same test works for agents. The goal is a short, accurate decisions folder that every agent session loads, not a long archive nobody reads.

Getting started in one sprint

1. Create docs/decisions/ and copy the MADR template (or Nygard’s, if your team prefers brevity).
2. Write ADR-0001: “We record architecture decisions.” Then backfill the five decisions people most often get wrong, as Accepted ADRs.
3. Add the four agent rules above to AGENTS.md and to your tool-specific instruction file.
4. Add a CODEOWNERS entry for the decisions folder.
5. Add the intent-note template to your PR template, with the deliberate/assumed split.
6. Add one line to your AI reviewer’s rule file about contradicting Accepted ADRs.

Verdict: the ADR format itself has not changed since 2011. What changed is the author. When agents write the code, the record of what was deliberate is the only reliable way to tell a reviewer, human or AI, where to look.

---

Sources & methodology

• Michael Nygard, “Documenting Architecture Decisions” (Cognitect, 15 November 2011)
• MADR: Markdown Architectural Decision Records, version 4.0.0 (17 September 2024)
• AGENTS.md, format description and supporting tools
• Anthropic: Customize Code Review with REVIEW.md and CLAUDE.md
• GitHub Docs: Copilot code review custom instructions
• Cursor Bugbot documentation
• GitHub Docs: About code owners
• Tech Manager Weekly #504 (19 October 2026), community thread on AI code reviews and recorded intent
• Methodology: format details are taken from the primary sources above. The intent-note template is an original synthesis for this page and is free to copy and adapt.