A developer on my team asked our AI coding agent to “switch the API to use controllers instead of Minimal API.” The agent did it — efficiently, thoroughly, touching every endpoint. It also removed the response caching middleware, eliminated the typed HttpClient registrations, and restructured the exception handling in ways that introduced three latency regressions.

Why? Because the agent had no idea why we chose Minimal API in the first place. It didn’t know about the performance requirements that drove that decision. It didn’t know that the “unusual” caching configuration was compensating for a vendor API’s aggressive rate limiting. Without the why, it optimized for the what it could see — and broke things it couldn’t.

This is the ADR problem in the AI era. And it has a solution.

What Changed: ADRs as Agent Memory

Architecture Decision Records have been good practice for a decade. Michael Nygard wrote the canonical format in 2011. The case for them has always been: new team members need to understand why decisions were made, not just what was decided. Without that context, they reverse decisions for reasonable-seeming local reasons that ignore global constraints.

In 2026, that new team member is often an AI agent.

The difference is speed and scale. A human engineer reads your ADR once and carries the knowledge forward. An AI agent reads your codebase fresh on every significant task — or forgets the earlier conversation when the context window resets. Without persistent, machine-readable documentation of your architectural reasoning, every agent task starts with a blank slate.

ADRs are now the mechanism by which your architectural decisions persist across agent interactions. If the reasoning isn’t written down in a format the agent can find and parse, the agent will infer it from the code — and inference from code tells the agent what, never why.

What Agents Struggle With (and ADRs Fix)

There are three categories of architectural knowledge that agents consistently get wrong when they lack explicit documentation:

Constraint-driven decisions: “We use X because Y vendor only supports X” or “We avoided Z because of a compliance requirement.” The code shows X is used; it doesn’t show that Z was consciously rejected.

Trade-off decisions: “We chose the simpler approach knowing it has a 15% performance cost because maintainability was higher priority.” The agent sees the simpler approach and optimizes it away, unaware of the deliberate trade.

Temporal decisions: “We’ll migrate this to the new pattern after Q3 when the vendor migration completes.” The agent sees legacy code and modernizes it at the wrong time, in the wrong order.

Good ADRs make all three visible.

Writing Agent-Readable ADRs

The standard ADR format (Title, Status, Context, Decision, Consequences) is a good start. Agent-readable ADRs add two things: explicit constraints and a “what would confuse an AI?” section.

Standard ADR (minimal, human-optimized):

# Use Minimal API over Controllers

## Status
Accepted

## Context
We needed to build a high-throughput internal API.

## Decision
We chose ASP.NET Core Minimal API.

## Consequences
- Faster startup
- Less boilerplate
- Some features require more manual configuration

Agent-readable ADR (explicit, constraint-aware):

# ADR-007: Use Minimal API over Controllers for OrderProcessing Service

## Status
Accepted (2025-11-14) — Do not reverse without reviewing ADR-012

## Context
OrderProcessing service handles 2,000-4,000 requests/minute with a
P99 latency SLA of 50ms. Controllers were evaluated and rejected because:
- Startup time with full MVC pipeline added ~180ms (unacceptable for
  our Lambda cold-start budget)
- Filter pipeline overhead was measurable at this request volume
- Team evaluated this over 2 sprints; see benchmarks in /docs/benchmarks/

## Decision
ASP.NET Core Minimal API for all OrderProcessing endpoints.

## Explicit Constraints (DO NOT change without updating this ADR)
- The ResponseCaching middleware in Program.cs is NOT redundant —
  it compensates for VendorX's 100 req/min rate limit on product lookup.
  Removing it will cause 429 errors under normal load.
- TypedHttpClients registration order matters — see comment in
  ServiceExtensions.cs explaining the dependency chain.
- We deliberately do NOT use output caching on the POST /orders endpoint
  because order submission must be idempotent, not cached.

## What Would Confuse an AI Agent
- The `LegacyAdapter` class is not legacy code to be removed — it bridges
  the old vendor SDK that we cannot upgrade until Q1 2026.
- The inconsistent error handling in the `/webhook` endpoints is intentional —
  we return 200 on all webhook calls per PCI-DSS requirement 6.4.2.
- The commented-out code in OrderValidator.cs is a future feature gate,
  not dead code. See ADR-015.

## Consequences
- Positive: P99 latency consistently 28-35ms in load tests
- Positive: Cold-start under 800ms on Lambda
- Negative: Some authentication middleware requires manual registration
- Negative: Swagger configuration is more verbose
- Trade-off: Accepted lower code readability for performance requirement

## Related Decisions
- ADR-012: API versioning strategy (read before changing endpoint routes)
- ADR-015: Feature flag implementation (explains commented-out validators)

The difference is significant. The second ADR tells an agent: here are the things you might reasonably change, and here’s exactly why you shouldn’t. The “Explicit Constraints” and “What Would Confuse an AI Agent” sections are the new additions that matter most.

Implementation: Where and How

File structure:

docs/
└── decisions/
    ├── README.md          (index of all ADRs)
    ├── ADR-001-database-choice.md
    ├── ADR-007-minimal-api.md
    └── ADR-012-versioning.md

Naming convention: ADR-NNN-short-description.md. Numeric prefix enables easy referencing and sorting. Short description enables grep and semantic search.

The README index matters: agents often start with a directory listing before diving into files. A clear index helps the agent navigate to relevant ADRs before editing the code it governs.

# Architecture Decision Records

## Quick Reference
| ADR | Title | Status | Covers |
|-----|-------|--------|--------|
| 007 | Minimal API over Controllers | Active | src/OrderProcessing/ |
| 012 | API Versioning Strategy | Active | All public endpoints |
| 015 | Feature Flag Implementation | Active | All feature gates |

Linking ADRs to code: add a brief comment in the relevant file pointing to the ADR. This is the most reliable way to ensure the agent encounters the relevant ADR when it’s looking at the code in question:

// Architecture: Minimal API by design. See docs/decisions/ADR-007-minimal-api.md
// before modifying this registration pattern.
var builder = WebApplication.CreateBuilder(args);

Tools

adr-tools is the reference CLI for ADR management:

npm install -g adr-tools
adr init docs/decisions
adr new "Use Minimal API over Controllers"

It creates the file with the right naming pattern and updates a README.md index automatically.

GitHub ADR template: add a .github/DECISION_TEMPLATE.md with your org’s extended sections (including “Explicit Constraints” and “What Would Confuse an AI Agent”) so new ADRs get the right structure automatically.

Integrating ADRs with agent context: in your agent setup (Claude Code CLAUDE.md or similar), add:

## Architecture Decisions
Before modifying any service, check docs/decisions/ for relevant ADRs.
ADRs with "Explicit Constraints" sections document things you MUST NOT
change without explicit instruction.

This instructs the agent to consult the ADR directory as part of its standard workflow, not just when it happens to encounter a comment.

The Return on Investment

Writing good ADRs takes thirty minutes per decision. Fixing a production incident caused by an agent that didn’t know why something was the way it was takes… considerably longer.

The calculus changes in the AI era because the frequency of “new participant encounters existing decision” events increases dramatically. A human team of eight has eight people who might encounter an old decision. An AI agent on that team might encounter it fifty times a day across different tasks. Each encounter without context is a risk.

ADRs written for AI agents aren’t different in kind from ADRs written for humans. They’re just more explicit about constraints, more specific about what not to change, and more honest about what might look wrong but isn’t. Humans often infer those things from surrounding context. Agents often don’t.

Your ADRs are your agent’s institutional memory. Write them accordingly.

---

Tools referenced: adr-tools, MADR format, Claude Code context engineering.