ADRs Are the Guardrails Your AI Coding Agent Is Missing

If you work with AI coding agents every day, you have probably seen this: you ask for a small change, and the agent suggests swapping your authentication library, changing your data access pattern, or "simplifying" something that was built that way for a good reason.

The agent isn't doing this on purpose. It just doesn't know why your decisions were made.

I've been using Architecture Decision Records (ADRs) for years as a team practice. Since AI agents became part of my daily work, they stopped being "nice documentation" and became one of the most effective guardrails I have. This post explains why, shows a real example from one of my projects, and describes how I turn ADRs into guardrails that an agent actually follows.

An agent like Claude Code, Cursor or Copilot knows a lot about software in general and very little about your project in particular. Three things make this worse than it sounds:

That "why" used to live in the heads of the people who had been on the team the longest. A new developer would ask, and someone would explain. An agent doesn't ask. It acts on what it can read. If the reasoning isn't written down, from the agent's point of view it doesn't exist.

An ADR is a short document that records one architectural decision. It is not a design doc and it is not a wiki page that tries to describe the whole system. It captures a single decision at a single point in time.

This is the template I use. It is intentionally small:

# NNNN. Title - **Status:** Proposed | Accepted | Superseded by NNNN - **Date:** YYYY-MM-DD ## Context What forces are at play (product goals, technical constraints, costs)? ## Decision What we decided, stated in full sentences ("We will…"). ## Consequences What becomes easier or harder, the risks we accept, and the follow-ups this creates. Enter fullscreen mode Exit fullscreen mode ADRs live in the repository, usually in docs/adr/, numbered in order, with an index in docs/adr/README.md. Two rules make them work over time:

I'm building a personal running app (React Native with Expo, a Node API, Strava integration). It has 32 ADRs so far. Here is a pair that shows why this matters with agents.

ADR 0004 says: the app does not record GPS. Strava is the single source of recorded activities. The reasoning is in the context section: the watch and Strava already record runs well, background GPS isn't available in Expo Go, and duplicating recordings would only add battery drain and complexity.

Without that ADR, an agent asked to "show the distance of each interval" would very likely add GPS recording. It is the obvious solution, and it would quietly break a decision I made on purpose.

Then a real need appeared. During track workouts with timed reps (for example, 10 × 30 seconds), I don't know how far I ran in each rep, and my coach asks for it. That is a different problem: I don't need a recorded activity, only the distance inside each fast window.

So I didn't "just add GPS". I wrote ADR 0020, which partly supersedes ADR 0004, for timed reps only. It records:

The important part is the last line of that ADR: Strava stays the source of recorded activities (the rest of ADR 0004 holds).

Now, when an agent works on this code, it can read exactly where the line is. GPS is allowed for timed reps, under specific rules. It is still not allowed for recording runs. And if I ever ask for something that crosses that line, the agent has what it needs to stop and tell me: "this conflicts with ADR 0004 and ADR 0020".

That is the shift. The agent stops being something that might break your decisions and becomes something that can defend them.

Writing ADRs is the first step, but an ADR sitting in a folder is only useful if the agent reads it. Over time I ended up with four layers. Each one covers a weakness of the previous one.

The ADRs are the source of truth for decisions and their reasoning. Everything else points to them.

Agents read an instruction file at the start of every session ( CLAUDE.md, AGENTS.md,.cursor/rules, copilot-instructions.md, depending on the tool). This is where ADRs become short, explicit rules, each one citing the ADR that explains it.

Here is part of the CLAUDE.md from the running app:

Read `README.md` and `docs/adr/` before changing architecture. ## Rules 1. Every project decision becomes an ADR in `docs/adr/` (template there; never rewrite an accepted ADR, supersede it). Update the index in `docs/adr/README.md`. 2. `packages/domain` is framework-free: no React, Expo, Node or HTTP imports. 3. Mobile runs in Expo Go. Anything that needs a dev build (Face ID, HealthKit, background GPS) requires an ADR first. 5. Strava is the activity source; never record activities with GPS (ADR 0004). GPS only measures timed reps (ADR 0020). 7. Tokens only in secure storage; never in AsyncStorage/SQLite/logs (ADR 0005). Enter fullscreen mode Exit fullscreen mode A few things make this work:

Agents are good at writing ADRs. They are fast at summarizing context, listing alternatives and spelling out consequences. So I let them draft, and I decide.

This keeps a human in charge of the decisions while the agent does most of the writing. It also means the history is never lost: six months later, both I and the agent can follow the chain from ADR 0004 to ADR 0020 and understand why the code looks the way it does.

Instruction files are strong guidance, not guarantees. Agents follow them most of the time, but not always, especially in long sessions or when the context gets crowded. So for decisions where a violation would be expensive, I don't rely only on the agent reading a rule. I make the build fail.

Some examples of decisions that can be enforced automatically:

None of these layers is enough on its own. Together, they cover each other's gaps. The ADR is what ties them together: every rule, gate and check can point back to a decision with a written reason.

If your project has no ADRs yet, you don't need to document its entire history. Start small:

From then on, every new decision gets an ADR, and you can ask the agent to draft it.

Documenting decisions has always been good practice. The difference now is who reads them. With AI agents on the team, your ADRs are read every day, by a reader that has no memory, never asks "why", and will happily change anything that isn't explained.

Write the "why" down, turn it into rules, and enforce what matters most. That's what makes an agent's work fit your project instead of a generic idea of what a project should look like.

Do you use ADRs in your projects? How do you give that context to your agents? I'd like to hear what has worked for you.