# How I Taught My AI Coding Agent to Stop Undoing My Design Decisions > Source: > Published: 2026-09-09 14:32:40+00:00 My AI coding agent kept "fixing" things I had broken *on purpose* — reverting deliberate design decisions back to textbook defaults, over and over. The fix wasn't better prompting. It was giving the agent a memory of **why** decisions were made: lightweight Architecture Decision Records (ADRs) wired directly into its context. Six months later, the agent hasn't relitigated a single settled decision. Here's the exact setup, the format that works, and 5 lessons. 🚀 I run a fully autonomous implementation system — an AI agent (built on Claude Code) that picks up tasks, writes code, runs tests, and opens changes for review with minimal supervision. It's been running for months across several projects, and most of the time it's great. But there was one failure mode that drove me up the wall. Every codebase accumulates decisions that look *wrong* unless you know the history: To a fresh pair of eyes, every one of these looks like a bug. And an AI agent is *permanently* a fresh pair of eyes. So my agent would touch a nearby file, notice the "obviously wrong" pattern, and helpfully modernize it. Polling → webhooks. Sync writes → async. Old pin → latest version. Each individual change looked like a competent refactor. Each one reintroduced a bug we'd already paid for once. The worst part: it wasn't random. It was *recurrent*. The agent has no episodic memory across sessions, so it rediscovered the same "improvement" every few weeks, like a groundhog day of well-intentioned regressions. My review load wasn't "check the new feature" — it was "re-argue settled decisions with someone who forgot the argument." I tried the obvious fix first: I stuffed rules into my `CLAUDE.md` (the instruction file Claude Code loads at session start). "Do not change the polling integration. Do not make file writes async. Do not upgrade dependency X." It sort of worked, and completely didn't scale: The insight that unlocked it: the agent didn't need more **rules**. It needed the **history** — the same thing a new human teammate needs. And software engineering already has a boring, 15-year-old tool for exactly this: Architecture Decision Records. An ADR is just a short markdown file recording one decision: context, decision, consequences. Humans have used them forever. It turns out they're an almost perfect memory format for AI agents — *if* you make three adjustments. Here's my full template. Note the `Scope` field — that's the load-bearing addition for agents: ``` # ADR-014: Use polling, not webhooks, for order-sync integration Status: accepted (2026-03) Scope: src/integrations/orders/**, src/jobs/order_poll* ## Decision We poll the vendor API every 30s instead of subscribing to webhooks. ## Context Vendor webhooks silently dropped ~2% of events under load (confirmed with vendor support, ticket from our March incident). Missed events caused unfulfilled orders. Polling is chattier but lossless — the poller reconciles against a cursor, so nothing is missed. ## Consequences - Accept ~30s max latency on order sync. This is fine for our SLA. - Do NOT "upgrade" this to webhooks, even as a fallback layer. A hybrid was tried; it doubled the failure modes. ## Revisit if Vendor ships webhook delivery receipts / retry semantics. ``` The agent-specific adjustments: `Scope` is a glob, not prose.`src/integrations/orders/**` is checkable in one line.`Consequences` states the forbidden action explicitly`Revisit if` keeps the decision honest. Don't paste ADRs into your prompt. The whole point is keeping per-session context small. My `CLAUDE.md` contains only this: ``` ## Design decisions (MANDATORY) Settled decisions live in docs/adr/. INDEX.md maps file globs to ADR numbers. Before modifying any file: 1. Check INDEX.md for globs matching the file. 2. Read the matching ADRs *before* writing code. 3. Never revert or work around an accepted decision. If your task conflicts with one, STOP and flag the conflict in your summary instead of coding around it. 4. If you make a new non-obvious design choice, append a draft ADR (Status: proposed) and add it to INDEX.md. ``` And `docs/adr/INDEX.md` is a ~30-line lookup table: ``` | Globs | ADR | |--------------------------------|-----------------| | src/integrations/orders/** | ADR-014 | | src/storage/writer* | ADR-009 | | package.json (dep: serializer) | ADR-011, ADR-017| ``` The flow, end to end: ``` php flowchart LR A[Task assigned] --> B[Agent checks INDEX.md
for matching globs] B -->|match| C[Reads ADR body] B -->|no match| D[Proceeds normally] C -->|no conflict| D C -->|task conflicts
with ADR| E[STOP: flag conflict
for human review] D --> F[New non-obvious choice?] F -->|yes| G[Drafts proposed ADR] ``` Cost per session: ~40 lines of index in context, plus 1–2 ADR bodies (~300 tokens each) *only when relevant*. Compare that to a rules file where every commandment taxes every session. Rule 4 above is the compounding part. When the agent makes a judgment call — picks a retry strategy, chooses denormalization, adds a cache — it drafts a `Status: proposed` ADR. I review these with the diff (approving or deleting one takes about a minute), and accepted ones become memory that binds *future* sessions. After six months my repos have 20–40 ADRs each. Roughly a third were drafted by the agent. The decision log now grows as a side effect of normal work, which is the only way documentation ever actually stays alive. **Agents don't need more rules; they need the *why*.** A rule without context gets pattern-matched away or "helpfully" worked around. A recorded reason — with the incident that produced it — gets respected. This mirrors human teams exactly, which shouldn't have surprised me, but did. **Relevance beats completeness in context.** Moving from "all rules, always" to "small index + on-demand bodies" improved compliance *and* cut context bloat. The glob-scoped index is the highest-leverage 30 lines in my repo. **Give the agent a legal escape hatch, or it will build an illegal one.** "STOP and flag the conflict" matters as much as "never revert." Absolute prohibitions with no outlet are how you get webhook layers hidden behind polling code. My agent has flagged real conflicts several times — twice it was right and the ADR got amended. **Make the agent pay into the system it benefits from.** Agent-drafted ADRs are what made this sustainable. If writing decision records had stayed a human-only chore, the log would have gone stale in a month, and stale ADRs are worse than none — the agent trusts them. **"Boring" pre-AI practices are quietly becoming AI infrastructure.** ADRs are from 2011. Nothing here is novel — that's the point. Practices designed for onboarding forgetful humans (ADRs, runbooks, conventional commits) turn out to be *exactly* what stateless agents need. Before inventing an agent-memory system, check whether one already exists in a dusty corner of software practice. 💡 Two experiments in flight: I'm also curious whether this scales down: even on tiny solo projects, I've started writing a three-line ADR whenever I do something deliberately weird. Cheap insurance against both future-me and future-agent. If your AI agent keeps relitigating decisions you've already settled: stop adding rules, start recording reasons. A `docs/adr/` folder, a glob-scoped index, and three instructions in your agent config — that's the whole system. If this was useful, **follow me here on Dev.to** — I write regularly about running autonomous coding agents in real projects: what breaks, what works, and what I'd do differently. And if you haven't tried agentic coding yet, [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) is where I'd start. ✅ *Setup referenced in this post: Claude Code (CLI, 2026 builds) with Node.js 22.x — the pattern itself is tool-agnostic and works with any agent that loads instruction files.* **What's the decision in your codebase an AI agent would "fix" first?** Drop it in the comments — I'll bet at least one of you has a webhook/polling story too. 👇