Agent-Optimized ADRs: Architectural Context for Coding Agents

A coding agent is only as good as the context you give it. The decisions that actually shape a codebase, which library to reach for, which pattern to follow, which thing never to do, usually live in someone's head, a stale wiki page, or a CLAUDE.md that went out of date two sprints ago. The agent cannot read your mind, and it will not reliably infer your architecture from the surrounding code.

Architectural Decision Records are the oldest, most battle-tested way to write those decisions down. They turn out to be the right substrate for agents too, but only if you optimize them for an agent reader instead of a human one. That is what an agent-optimized ADR is: the same decision, restructured so a machine can find it, scope it, follow it, and check it.

What an ADR is, in 60 seconds

• Coined by Michael Nygard in 2011, in Documenting Architecture Decisions. One small file per decision, five sections: Title, Status, Context, Decision, Consequences.
• Stored in the repo, versioned next to the code. ThoughtWorks put lightweight ADRs in the "Adopt" ring of its Technology Radar precisely because keeping records in source control keeps them "in sync with the code itself."
• Immutable. You do not edit an accepted decision, you supersede it with a new one. The log is append-only.
• A small ecosystem grew up around the idea: MADR (Markdown Architectural Decision Records), Y-statements, Joel Parker Henderson's template collection, and tooling like Nat Pryce's adr-tools.

Plenty of serious teams already do this

• AWS publishes an ADR process in its Prescriptive Guidance, and tells teams to "use the ADRs as a reference during code and architectural reviews."
• Microsoft calls the ADR "one of the most important deliverables of a solution architect" in the Azure Well-Architected Framework, and treats it as an append-only log you supersede rather than edit.
• Spotify documents decisions as ADRs and reuses them across offices: a decision written by engineers in New York getting picked up by a team in Stockholm.
• Red Hat recommends them, and in November 2025 the UK Government published a whole-of-government ADR framework to ensure "visibility, traceability, and strategic alignment" across departments.
• One distinction worth drawing: Google's well-known design docs solve a related but different problem. A design doc is a forward-looking proposal for one project; an ADR is a durable, granular record of a single decision. They complement each other.

What "agent-optimized" actually changes

The classic ADR was written for a person who reads a few of them, occasionally, and fills the gaps with judgment. An agent reads all of them, every session, under a token budget, and acts on them literally. Same decisions, very different reader. That changes the format.

• Scoped to file globs, not just filed by number. An agent editing a stylesheet has no use for the ADR that governs your database schema, so loading it only burns context. Attach an applies_to glob and each ADR activates for the files it governs and nothing else. This very site does it: its .claude/rules/*.md files each declare what they apply to.
• Imperative, not prose. "MUST use the framework's image component. MUST NOT use a raw img tag." Normative keywords an agent can follow beat a paragraph it has to summarize first.
• Verifiable. Each decision ships with a check, a grep, a lint rule, a command, so the agent or CI can confirm compliance instead of just intending it.
• Token-aware. Anthropic's own guidance is to keep each context file under about 200 lines, because "longer files consume more context and reduce adherence." Agent-optimized ADRs compress down to the decision and the rule, and link out for the narrative.
• Non-conflicting. Anthropic warns that "if two rules contradict each other," the model "may pick one arbitrarily." A human reconciles contradictions on the fly. An agent needs them reconciled in advance.
• Addressable. Stable IDs like R-IMG-001, so a review comment, a commit message, or the agent itself can cite the exact decision.

ADRs are how you do context engineering

The discipline has a name now. Context engineering, as Anthropic frames it, is "the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference." Simon Willison traces the term through Andrej Karpathy and Shopify's Tobi Lütke: the craft of putting the right information in the window, not writing one clever prompt.

• ADRs are the durable, reviewed half of that context. They hold the deliberate, stable decisions, as opposed to the throwaway instructions you type into a single session.
• Keep the records as the system of record, and treat the agent context files as a delivery format. CLAUDE.md is read at the start of every Claude session; AGENTS.md, "a README for agents," is now used in more than 60,000 projects; Cursor has its own rules files.
• Stay agent-agnostic: write the decision once, compile it into whatever each tool reads. Claude, Copilot, and Cursor then build from the same architecture, and changing a decision in one place updates every agent's context with it.

You can roll your own, and you should start today

• Pick a format (Nygard or MADR), store the records in the repo (doc/adr or .claude/rules), scope each one with a glob, and write the rule as MUST/SHOULD with a verify command.
• Wrap the workflow in skills: a "new ADR" skill that scaffolds the file, a "check my diff against the ADRs" skill the agent runs before it opens a PR. People are already publishing ADR skills for exactly this.
• This is the bare minimum, and it has a high likelihood of paying off: even a handful of well-scoped ADRs gives your agents architecture they would otherwise guess at. The harder part is keeping the records true as the codebase changes underneath them.

The hard part: drift, duplication, and conflict

• Context files rot. The same decision gets restated in CLAUDE.md, AGENTS.md, a README, and a wiki page, and the four copies disagree within a few months. Anthropic flatly tells you to "review your CLAUDE.md files" periodically "to remove outdated or conflicting instructions." Almost nobody does.
• That is the chore we built an agent to handle, as a pipeline:
  • Static analysis. Read the actual codebase and infer the decisions already in force, the patterns your code follows whether or not anyone wrote them down.
  • Generate. Have a model draft a candidate ADR for every high-confidence decision it found, turning the implicit patterns into explicit records.
  • De-duplicate. Collapse the same decision, restated across five files, into one record.
  • De-conflict. Find the records that contradict each other and resolve them before an agent has to guess.
  • Agent-optimize. Rewrite each record into the scoped, imperative, verifiable, token-tight form above.

Then keep them true, automatically

• In the codebase. The agent keeps your ADRs and context files current as the code changes, so your ADRs describe the system you have, not the one you had last release.
• Human decisions, integrated. When someone makes an architectural call by hand, the agent works out how it fits the existing set, folds it in, and alerts the team to anything it contradicts instead of letting two decisions quietly disagree.
• Big changes, made tractable. Migrations, modernizations, and refactors usually mean changing whole sets of dependent ADRs at once. The agent gives you a way to do that en masse, with visualizations of what depends on what and suggested edits across the set.
• As a skill or MCP. Call the Architecture Advisor from your own agent or IDE to ask "what is the decision here?" before you write the code, so the relevant records get pulled into context instead of pasted by hand.
• In review, connected to GitHub. It reviews pull requests for architectural compliance, the gate AWS names by name, and proposes a new ADR when it spots a decision being made in code that nobody has recorded.

The takeaway

ADRs were always a good idea that asked for a discipline humans rarely sustained. Coding agents change the math. The record is no longer a courtesy to the next engineer, it is load-bearing context the agent reads on every run. So write the decisions down, write them for the reader that never skims, and keep them honest. That last part is the real work, and it is the part worth automating.

---

Actual AI builds an architecture agent that turns the decisions already living in your codebase into agent-optimized ADRs, keeps them deduplicated and conflict-free as the code changes, and enforces them in review. Your coding agents inherit your architecture instead of guessing at it.