ADRs for AI Coding Agents. Preserving the Reasons Behind Architecture Decisions

An online store has a regular shopping cart and a separate module for reserving limited-edition products. Both deal with products and orders, so some of their logic is duplicated.

A developer asks an AI coding agent to update the reservation module. The agent inspects the repository, finds two similar implementations, and suggests merging them. Less duplication, shared error handling, and easier maintenance.

Except the team considered that exact approach several months earlier and rejected it.

The regular cart holds selected products but does not reserve inventory. For a limited-edition product, the server holds the item for a buyer for a few minutes. If checkout is not completed in time, the reservation expires.

The team isolated this behavior in its own module to avoid complicating the regular cart and disrupting the existing purchase flow.

The agent knows none of this. It sees duplication and proposes a refactor without knowing why the modules were separated.

Someone could dig through Git history, find the old ticket, or read pull request comments. The explanation might be there. Or perhaps the decision was made in a meeting and never written down.

What an ADR is for

An Architecture Decision Record (ADR) is a short record of an architectural choice. Michael Nygard described the approach back in 2011 in Documenting Architecture Decisions.

An ADR captures the reasoning, alternatives considered, and consequences. For our example, it could be this short.

# ADR-014: Separate Reservation Module

Task: SHOP-284
Status: Accepted
Module: DropReservation

## Context
The regular cart does not reserve stock.
Limited-edition products require a
server-side reservation with an expiry.

## Decision
Keep reservation logic separate from Cart.

## Alternatives
Extend the existing cart.
Rejected because it would affect regular
purchases and complicate reservation handling.

## Consequences
Some logic will be duplicated.
The modules can evolve independently.

## Revisit
Reconsider if a shared reservation
mechanism becomes available.

An ADR should not describe implementation details. There is no need to list classes, methods, and protocols. That information is already in the code and may change in the next refactor. Record the decision and why it was made. Otherwise the document grows and becomes stale.

Retelling the task is not needed either. An ADR should hold what the code cannot say clearly, namely why this particular decision was made and why the alternatives were rejected. That “why” is exactly what usually gets lost later.

With this ADR, a developer or an AI agent can see why two similar modules remain separate. They can still revisit the choice, but with the original constraints in mind.

Matt Pocock’s approach

Matt Pocock’s skills repository includes a domain-modeling skill that covers ADRs.

The skill suggests offering an ADR only when all three conditions hold.

1. Reversing it would be expensive or difficult.
2. A future reader would wonder why it was done this way without context.
3. There were genuine alternatives to choose between.

I like that Pocock does not suggest documenting everything. Its ADR-FORMAT.md even allows a one-paragraph ADR. If a few sentences explain the decision, there is no reason to expand them just to fill a template.

I would adjust the workflow slightly. Every completed task should be checked for decisions worth preserving, even if no architectural work was expected at the start.

A small change can lead to a choice whose consequences only become clear later. For example, fixing a bug might reveal a module constraint that forces the team to avoid the shared error-handling mechanism. The reason seems obvious today. Six months later, the difference could look like a mistake.

That does not mean every bug fix needs an ADR. If there was no meaningful technical decision, another document only adds noise.

When an ADR is final

An ADR can be written before implementation. It gives the team a way to discuss the architecture and record the initial choice. But development can reveal constraints that require a change of plan.

I would keep a draft and update it during the task. It should retain the reasons for the choice, important alternatives, and any significant changes to the initial plan.

For me, the ADR becomes the final task artifact when the task is complete, usually after the code has been merged.

By then, the code has been reviewed and we can check which decisions actually made it into the implementation. The agent prepares the final record using the draft and work history. The developer checks its contents.

Generating an ADR from the finished code alone is worse. An AI agent may invent a plausible explanation for an architecture that was chosen for entirely different reasons.

That is why you should review an ADR yourself, even when the agent wrote it from the draft. It may retell the task instead of giving reasons, or confidently describe a reason that never existed. A wrong explanation misleads more than a missing one.

I would keep the final record with the task, at least as a separate comment in Jira, Linear, or another issue tracker.

If the agent cannot access the tracker, the ADR should also live in the repository or be available through an integration. Otherwise the next agent will not find it.

Existing tools

There are already tools for generating ADRs, beyond Pocock’s skill.

auto-adr works with Claude Code. The /adr command creates a record from the current session history. This can preserve decisions discussed during development rather than reconstructing them solely from code.

docflow takes a more structured approach. It includes skills for creating ADRs, managing tasks, and checking documents when work is completed.

Andrew Connell describes another example in Architecture Decision Records as Long-Term Memory for an AI Coding Agent.

Over several months of working with Claude Code, his project accumulated 141 ADRs. He added a rule that prompts the agent to propose recording important decisions after completing a plan, with the author approving those records.

Connell keeps project rules, specifications, and ADRs separate. The rules tell the agent how to work, specifications describe requirements, and ADRs preserve the reasons behind architectural choices.

When changing old code, the agent can consult those records rather than suggesting options the team has already rejected.

The format and workflow should still fit the particular team. A universal skill is unlikely to reflect how every project makes decisions.

How to set it up

You don’t need a dedicated tool to start. A short rule in AGENTS.md or CLAUDE.md, which the agent reads every session, is enough. I covered how such instructions work in the post on AGENTS.md for Codex and Claude Code.

## ADR

During a task, keep a draft of decisions
in docs/adr/drafts/<task-id>.md.
Record the chosen option,
rejected alternatives and the reason.

Before finishing the task, check three conditions.
1. The decision is expensive or hard to change.
2. Without context, it would be unclear why it was done this way.
3. There were real alternatives.

If all three hold, prepare a final ADR
from the draft and the task history.
Do not retell the task, explain the reasons for the decision.
Do not invent reasons that never came up.
Do not save the ADR without my confirmation.
If the conditions do not hold, delete the draft.

Where the final record lives depends on what the agent can access. If it works with Jira or Linear through an integration, the ADR can go into a task comment. If not, a docs/adr/ folder in the repository works better, with a number and a short name in each file name, such as 0014-drop-reservation.md. The agent can then find records with a regular code search, and the task keeps a link to the file.

Keep the rule itself short. The ADR template can live in a separate file or skill and load only when a record is actually needed. Otherwise the agent’s instructions grow faster than the decisions do.

The point

Before a task, we carefully assemble context for an AI coding agent, including requirements, specifications, documentation, and relevant code. After the work is done, much of the reasoning survives only in the session history.

An ADR keeps that reasoning in a short record. The draft evolves during development, the final version is checked after merge, and it stays attached to the task.

Most of these records may never be needed. But when someone asks a year later why two similar modules were not merged, reading an ADR beats reconstructing an old discussion.