ADRs (Architecture Decision Records) for coding agents

Software just lost its memory.

Coding agents don't remember why decisions were made. Every session starts from zero.

At prelint, we see this every day in code reviews. The system works. The reasoning drifts. ADRs are how you restore continuity.

Stateless software

At prelint, we call this shift Stateless Software.

Coding agents are stateless systems. They don't carry reasoning across sessions. They don't remember tradeoffs. They don't know why something exists unless it is explicitly written down somewhere they can reach.

This is not a flaw. It's how agents work. Sessions are isolated. Context is local. When the session ends, the working memory is gone.

The code itself remains, but code is an artifact, not an explanation. Code tells you what the system does. It does not tell you why it does it that way instead of another way.

The gap between “what” and “why” used to be bridged by human memory. Now nothing bridges it unless you build the bridge explicitly.

The old world had imperfect memory. The new world has none.

Code used to be written by systems with memory. Now it's written by systems that forget everything between sessions.

The Agent Memory Gap

When a coding agent implements a feature, it operates with rich context. It knows why it chose a specific database schema. It evaluated three libraries and picked one for concrete reasons. It weighed tradeoffs and made judgment calls.

Then the session ends. All of it evaporates. Some reasoning gets compressed into a code comment. Some ends up as a one liner in a commit message. Most of it vanishes.

The next agent sees the code but not the thinking behind it. The effects of past decisions are visible. The rationale is not.

We call this the Agent Memory Gap. Each coding agent session starts with full capability but zero architectural context. The agent reads your code and infers what it can, but inference is a poor substitute for explicit reasoning.

Every agent session is a new engineer with no memory of the company.

And when agents can't find the reasoning behind a decision, they fill the gap with their own. Confidently. Incorrectly.

What the Agent Memory Gap looks like in practice

A team builds a payment system. Agent A implements the checkout flow and makes a deliberate architectural choice. All payment operations use idempotency keys. This prevents duplicate charges when network timeouts trigger retries. The team had a double charging incident three months earlier. Idempotency keys are the fix. Agent A implements the pattern cleanly.

Three weeks later, Agent B builds subscription renewal. It sees the existing payment code but has no context about why idempotency keys are threaded through every transaction. Agent B's renewal logic is clean, well tested, and skips idempotency entirely. Nothing about the code is technically wrong.

Two weeks after that, Agent C builds retry logic for failed payments. It looks at Agent B's subscription code as a reference. Agent B's code doesn't use idempotency keys, so Agent C doesn't either. The pattern drifts further from the original architecture.

A month later, a network timeout during a subscription renewal triggers a retry. Both the original request and the retry succeed. The customer is charged twice. The exact scenario idempotency keys were designed to prevent.

No agent made a mistake. Each one wrote correct, well structured code. But the reasoning behind the original architecture was never recorded. It lived in Agent A's session context, which evaporated the moment that session ended. Three agents later, the codebase had silently abandoned its own safety mechanism.

One ADR would have prevented this.

# Use idempotency keys for all payment operations

## Context

A network timeout during checkout caused a duplicate charge
in January 2026. When retries fire after a timeout, both the
original and retried request can succeed, resulting in double
billing.

## Decision

All payment operations (charges, refunds, subscription
renewals) must include an idempotency key. This ensures that
retried requests produce the same result as the original.

## Consequences

Every payment endpoint requires an idempotency key parameter.
Clients must generate and store keys before initiating
transactions. This adds slight complexity to the payment flow
but eliminates the entire class of duplicate charge bugs.

With this ADR in the repository, Agent B reads it before building subscription renewal. Agent C reads it before building retry logic. The architecture holds.

The Decision Trail

The fix for stateless software is explicit memory. At prelint, we call this building a Decision Trail.

Architecture decision records are short documents that capture individual architectural decisions along with their context and consequences. Michael Nygard introduced the format in 2011. For over a decade, ADRs were a governance tool used mostly by enterprise architecture teams. Most engineering organizations ignored them. Too much process. Too little payoff for the overhead.

That changed when software became stateless.

ADRs capture exactly the reasoning that coding agents lose between sessions. What was decided, why, what alternatives were considered, what constraints existed. They are, accidentally, the perfect memory format for stateless software.

When you leave ADRs throughout your project, you create a Decision Trail. Each record is a marker explaining not just what was decided but the landscape that led to that choice. Future agents follow the trail. They arrive at decisions already armed with context instead of reconstructing it from code alone.

The framework

Stateless Software describes the world. Coding agents don't retain reasoning. Code alone doesn't carry intent. Software development no longer has built in memory.

The Agent Memory Gap describes the problem. Each session resets context. Reasoning evaporates. Agents fill the void with confident fabrication.

The Decision Trail describes the solution. ADRs stored as text files in your repository restore continuity between sessions. Every agent inherits the accumulated reasoning of every session before it.

This is a model of the world, not a productivity tip. If you accept that software is now stateless, everything else follows.

Agents don't understand your system. They search it.

This determines where your ADRs live and how they should be structured.

Coding agents don't browse your codebase. They grep. They scan file paths. They run file searches and read results.

Even with embeddings, agents default to search. Text search and path traversal is how they find what matters.

If something cannot be found through grep or file traversal, for a coding agent, it functionally does not exist.

A design decision documented in Confluence doesn't exist. A rationale explained in a Slack thread doesn't exist. A tradeoff discussed in a Google Doc doesn't exist. These are all invisible to the systems now writing your code.

A markdown file at /adr/003-idempotency-keys-for-payments.md exists. The file path alone tells the agent what the decision concerns before it reads a single line. The content is instantly searchable. No authentication, no API, no special tooling. Text in a file.

This is why ADRs stored as plain text in your repository are the highest leverage format for agent context. Not because markdown is elegant. Because grep works on it.

Immutable ADRs are a mistake in agentic systems

Traditional ADR practice says records should be immutable. When a decision changes, you mark the old record as “Superseded” and create a new one. Humans can follow these chains. Agents can't.

An agent searching for your database decision finds four records. ADR 003 (Superseded), ADR 009 (Superseded), ADR 014 (Superseded), ADR 017 (Accepted). It parses all four, reconstructs the timeline, determines which is current. This costs tokens, time, and accuracy.

Immutable ADR chains are a mistake in agentic systems. Agents don't need history. They need truth.

Immutability was designed for a world where humans maintained institutional memory and documents served as audit trails. The paradigm changed. Documents are now the primary memory for stateless systems. Immutability is overhead that works against the systems consuming the records.

Update your ADRs to reflect current state. Delete the ones that no longer apply. Git already tracks every change with timestamps, authors, and diffs. You don't need a second versioning system on top.

That discomfort you feel about editing an existing ADR is a signal. You're adapting the practice to the actual problem instead of performing a process.

What to put in your ADRs

Start with architectural decisions. Why you chose a specific database, framework, or vendor. Why you structured a module a particular way. Why you picked one design pattern over another.

But the most valuable ADRs capture the terrain around the decision, not just the decision itself.

Explored alternatives

Document what you considered and why you rejected it. A future agent facing a similar problem in a different module can apply the same reasoning without re evaluating from scratch.

Constraints that might change

This is the most underrated thing you can put in an ADR. Sometimes you make a suboptimal choice because the better option doesn't fit your current stack, timeline, or budget. Record that explicitly.

Consider this example.

We chose SendGrid for transactional email because Resend did not support our required DKIM configuration in March 2026. Resend has since announced this feature on their roadmap. Revisit this decision when Resend ships DKIM support.

That paragraph prevents artificial permanence. Decisions stay flexible when the reasoning is explicit. They calcify when it's missing.

Rationale that agents can relay

When an engineer asks “why did we pick vendor A over vendor B for email,” an agent with access to the relevant ADR gives a real answer grounded in actual reasoning. Without the ADR, the agent constructs a plausible but fictional explanation. A confident wrong answer is worse than no answer at all.

How to start

You don't need a tool. You don't need a process. You need a folder and a first file.

Create an ADR directory

Add an adr/ folder in your repository root. Some teams use decisions/ or docs/adr/. The location matters more than the name.

Write your first record

Pick a decision you've already made where you still remember the reasoning. Don't worry about format. A few sentences explaining what you decided and why is enough.

# Use PostgreSQL for primary data store

## Context

We needed a primary database. The team evaluated PostgreSQL,
DynamoDB, and MongoDB.

## Decision

PostgreSQL. The team has deep experience with relational
databases, and the data model requires complex joins across
multiple entities.

## Consequences

We accept the operational overhead of managing a relational
database. We gain query flexibility and strong consistency
guarantees.

That took thirty seconds to write. It will save hours of confused agent sessions.

Tell your agent about the directory

Add one line to your CLAUDE.md, .cursorrules, or equivalent configuration.

Architectural decisions are documented in /adr.
Read relevant ADRs before making architectural changes.
Write a new ADR when making significant decisions.

That's all the instruction you need. Claude and other major coding agents already understand ADR structure. They know what a good ADR looks like. You don't need to specify a template or enforce a format.

Let the agent work

After a few sessions, check what the agent produced. You'll find it writes clear, useful records without additional guidance. Adjust scope and detail level based on what's actually helping.

Build the habit

Ask your agent to write an ADR at the end of any session where it made a significant architectural choice. The reasoning is freshest in the same session where the decision happened. Waiting means forgetting.

ADRs are not documentation

This distinction matters and most teams get it wrong.

Specifications are snapshots. They describe a feature at a point in time with maximum detail. Database schemas, API contracts, wireframes, copywriting details. Everything. Specifications are the most complete format. You interact with them when building the feature. After that, they age.

Documentation is explanatory. Written for a specific audience at an appropriate level of abstraction. It describes how things work. But it doesn't capture why individual decisions were made. That's not its purpose.

ADRs are vertical slices. They cut through a single decision and capture the full context around it. They're not exhaustive. They're surgical.

At prelint, we see ADRs not as documentation but as memory infrastructure for agent built systems. They solve a different problem than docs or specs. Treating them as the same thing leads to ADRs that are too long, too formal, and too infrequent.

Mistakes that kill ADR adoption

Making ADRs a compliance exercise. If writing one feels like filing paperwork, you'll stop after the third. Keep them conversational. Three paragraphs is enough. If it takes more than five minutes to write, you're overcomplicating it.

Storing ADRs where agents can't reach them. Notion, Confluence, Google Docs. Fine for humans. Invisible to agents. If agents are a primary consumer of your ADRs, the records must live in the repo.

Versioning instead of updating. Immutable chains create navigation overhead for agents. Update the record. Let git track history.

Obsessing over templates. There's no golden template. Nygard, MADR, free form paragraphs. Whatever feels natural is the right format. Time spent evaluating ADR frameworks is time not spent writing ADRs.

Forgetting to connect agents to the ADR directory. A folder full of perfect ADRs is useless if your agent doesn't know to look there. One line in your agent configuration makes the difference between persistent context and an expensive text file.

ADR checklist for agentic engineering

• ADR directory exists in your repository
• Agent configuration references the ADR directory
• At least one ADR exists for a past architectural decision
• ADRs stored as markdown or plain text files
• Each ADR covers a single decision
• Each ADR includes context, decision, and reasoning
• Rejected alternatives documented where relevant
• Constraints and conditions for revisiting noted
• Records reflect current state, not historical chains
• No special tooling required to read or write them

FAQ

What is an architecture decision record?

A short document that captures a single architectural decision along with its context, alternatives considered, and consequences. It answers why something was decided, not just what.

Do ADRs replace documentation?

No. Documentation explains how the system works. ADRs explain why specific decisions were made. They serve different purposes and complement each other.

How long should an ADR be?

A few paragraphs. Long enough to capture the reasoning and alternatives. Short enough that an agent processes it in seconds. If it takes more than five minutes to write, scope it down.

Do I need a specific ADR template?

No. Coding agents already understand common ADR formats. Use whatever structure feels natural. Title, context, decision, and consequences is a reliable starting point.

Should I write ADRs for every decision?

Only for architecturally significant ones. If you'd explain the reasoning to a new team member joining the project, it's worth an ADR. If the reasoning is obvious from the code, skip it.

Can coding agents write ADRs themselves?

Yes. Ask the agent to document its decision at the end of the session where the choice was made. The reasoning is freshest at that moment.

Where should I store ADRs?

In your repository as markdown files. An /adr directory at the root is the most common pattern. Avoid external systems that agents can't access through standard file operations.

Why not just use code comments?

Comments explain what code does. ADRs capture project level decisions that span multiple files and modules. Different granularity. Use both.

Do ADRs work with all coding agents?

Any agent that reads files in your repository can use ADRs. The format is plain text. There's nothing agent specific about it. That's the point.