ADRs Are AI Agent Fuel
Your AI assistant keeps suggesting the ORM you already tried and ripped out. It proposes the caching layer you rejected in March. It's not being dumb — it's reading your codebase, and the codebase only shows what you built, never why. The rejected options, the trade-offs, the constraints — none of that lives in the code. Architecture Decision Records put it back.
The missing why
Code is a record of conclusions. When an AI assistant scans your repo, it sees that you use Postgres, that there's no message queue, that auth is handled by a home-grown middleware. What it cannot see is that you evaluated three queues and rejected all of them because your ops team is two people, or that the "obvious" auth library was tried and removed after a licensing problem.
Humans on the team carry this history in their heads. The AI has no heads to ask. So it does the statistically reasonable thing: it re-suggests the popular option — the exact one you already rejected. Every time you correct it in chat, that correction evaporates when the session ends. You need the why written down somewhere the assistant will actually read.
Anatomy of a decision record
An ADR is a short markdown file — one file per decision, numbered, living in docs/decisions/ in the repo itself. The classic format has four parts:
- Context — the situation that forced a decision. Team size, traffic, deadlines, existing constraints.
- Decision — what you chose, stated plainly. "We will use Postgres with logical replication."
- Alternatives rejected — and why — the section that matters most for AI. "MongoDB: rejected, our queries are relational. Kafka: rejected, operational overhead too high for a two-person ops team."
- Consequences — what this decision makes easier, what it makes harder, and what would have to change for you to revisit it.
That's it. No template ceremony, no approval workflow. A decision gets made, a file gets written, both land in the same commit when possible.
What changes for your AI
Once ADRs exist in the repo, they become context like any other file. Point your assistant at docs/decisions/ — via your project instructions file, or just by telling it to read the directory before proposing architecture changes. The behavior shift is immediate and specific: instead of "you should consider MongoDB for this," you get "ADR-0003 rejected document stores because your queries are relational — staying with Postgres, but here's how to handle the new requirement within it."
The assistant stops re-litigating settled questions and starts building on top of them. Rejected alternatives stay rejected. And when a decision genuinely deserves revisiting, the ADR's consequences section tells the assistant — and you — exactly what changed conditions would justify it.
Power tricks
- Write the first ADR today, for the biggest decision currently in play. Don't backfill history — capture the live decision while the alternatives and reasoning are fresh. Backfill old ones only when they come up.
- Keep each ADR to one page. A long ADR won't get read by humans and wastes context window for the AI. If it doesn't fit on a page, you're documenting two decisions.
- Link the ADR directory from your README (and from your AI instructions file). Discoverability is the whole game — an ADR nobody's tooling finds might as well not exist.
Resources
Building an AI feature? Yeda AI designs, audits, and ships production LLM systems.