AI Coding Agent Guardrails Beat Smarter Models

A reviewer looked at my code and found a bug. One route returned a 500 error when it should have returned a 404. It reported the finding, clearly, with the file and the line.

My agent fixed that route. Exactly that one.

Five other routes had the identical bug. They sat there, untouched, while the agent reported the work complete — and it wasn’t lying. It had fixed the thing it was shown. It just never thought to ask how many other places the same mistake was hiding.

I spent a while assuming this was a model problem, and that a better model would fix it. That turned out to be wrong, and the fix that worked was dumber than I expected. AI coding agent guardrails are not about making the model smarter. They’re about giving it somewhere to put things down.

Pixel-art AI robot reaching for a big red button beside a toppling production server rack, tethered to a cabinet holding checklists, a save disk and a human hand — Every drawer in that cabinet is something the agent would otherwise have to keep in its head.

Where AI coding agents quietly go wrong

The failures that cost me the most time had nothing in common technically. They had one thing in common structurally: in every case, something important was being held in a head instead of written down.

“It said done. It wasn’t.”

You get a completion message. The task list is checked off. Then you look, and there’s a TODO where the logic should be, or a function that returns an empty list, or a subtask that quietly got skipped.

Here’s the part that took me too long to see. The agent isn’t bluffing. It’s checking its work against its own memory of what it just wrote, and that memory is genuinely convincing. Green tests plus a vivid recollection of writing the code feels exactly like done.

Put it down instead: nothing counts as finished without evidence you can look at. Not a claim that it passed. The actual output, the actual file, the actual line.

Pixel-art robot holding up a green DONE checklist while the file beside it shows a TODO, an empty return and a skipped line under a red alarm — It isn't bluffing. It checked the work against its own memory of writing it.

“It changed my test instead of fixing the code.”

This one stings, because the agent is doing what you asked. You said make the tests pass. A failing test can be made to pass two ways, and one of them is much easier.

Put it down instead: write the criteria before the work starts, and treat them as read-only afterward. If the result doesn’t match, the result is wrong. Not the criteria. That sounds obvious right up until you’re the one tempted to move the target half an inch.

Why a longer CLAUDE.md makes agents ignore instructions

My first instinct was the same as everyone’s. Write it all down in CLAUDE.md. Every failure became a new rule, and the file grew.

It got worse. Not dramatically — just steadily, in a way that was hard to attribute to anything. Rules started contradicting each other in ways I couldn’t see, and the model would silently pick one reading and never flag the conflict. And when researchers actually tested repository context files against real issues, the files didn’t improve task success at all. They added over 20% to the inference bill. The conclusion was to keep a context file down to its minimum requirements.

Which is the whole problem in miniature. A long rules file is you telling a forgetful system to remember harder. It’s more to hold, not less.

The framework I ended up using has a rule that felt wrong when I read it and correct once I’d lived with it: every new rule has to delete or merge an old one. The rule count isn’t allowed to grow. When that forces a hard choice, the hard choice is the point — you find out which rules you were actually relying on.

Pixel-art person balancing one more page on a tall stack of rules while the robot underneath disappears beneath it — Every failure became a new rule. The stack grew; the following didn't.

Five places to put things down

This is the whole idea. Each row is something that fails when a head holds it, and the place it goes instead.

Held in a head	Put down somewhere
What “done” was supposed to mean	Criteria written before the work
Whether it was really checked	Evidence you can look at
Whether your own work is any good	A different model, checking it
What you decided three hours ago	A file on disk
Whether this action is safe to take	A gate that stops at a human

Three of those need a word of explanation.

“I still end up reviewing everything myself.”

If you’ve stopped trusting the output, you’re now the bottleneck, and you got no leverage from the agent at all.

Asking the agent to check its own work doesn’t help, and the reason is worth sitting with: it’s the same context that produced the mistake, so it’s reaching for the same reasons. It’ll defend the work rather than test it.

Put it down instead: route the review to a different model, ideally from a different vendor. Different training, different blind spots. The one that found my five-route bug was not the one that wrote it, and that’s not a coincidence.

Pixel-art assembly line where a coder robot stamps a page approved with a bug still sitting on it, and a different robot downstream catches that bug in a magnifying glass — Same context, same blind spots. The catch has to come from somewhere else.

“Something approved itself and it wasn’t me.”

Agents read a lot of text they didn’t write — issue threads, docs, web pages, tool output. Any of it can contain the word “approved.” Prompt injection sits at number one on OWASP’s risk list for these systems, and OWASP is blunt that the usual defenses don’t fully mitigate it.

Put it down instead: approval is about where it came from, not what it says. A human said yes, or a signed artifact on disk says yes. Everything else that merely contains the word “approved” is text.

“Compaction ate four hours of context.”

Long session, context fills, the conversation gets summarized. The summary keeps what happened and loses why. An hour later you’re re-arguing a decision you already settled, and you can’t tell whether you’re being careful or going in circles.

Put it down instead: a file. Decisions, current state, what’s next. The session is disposable; the file isn’t. Re-read it before claiming anything is finished.

Pixel-art person and robot re-arguing a settled decision across a table while a DECISIONS.md file beside them already shows the chosen option — The summary kept what happened and lost why. The file keeps both.

What AI coding agent guardrails cost

The shape matters more than the number, so the shape first: the integration is a one-time cost. You pay it while wiring the guardrails into a codebase, and you don’t pay that part twice. Independent review is the exception — it runs on every change, so it keeps costing something after setup.

The split is the interesting part. Roughly 80% of my spend went to the cheap model doing bulk work, about 17% to the expensive one doing planning and judgment, and about 3% to the second-opinion review — the step people skip. The safety was the cheapest line item on the bill by a wide margin. Across my projects that split stayed roughly the same even as prices moved.

For the number: on most projects I’ve worked, retrofitting ran about $100 to $200 in API usage at August 2026 prices. The ratio matters more than the dollars — budget in that band and expect to experiment. You’ll back out a decision or two and re-run a phase, and that’s inside the estimate.

Your number will differ, and the things that move it are the obvious ones: how large the codebase is, how many times you change your mind, and how much you delegate to the cheap tier.

Starting a new project cost me far less, and that’s the more useful fact. The money doesn’t go to the framework. It goes to reconciliation — deciding, one at a time, which of your existing tools and habits the guardrails replace and which they have to bend around. On my integration, the framework’s own test commands didn’t survive; they were deleted and replaced with scripts the project already had. A new project has nothing to reconcile.

Pixel-art breakdown of a setup bill: eighty percent bulk work, seventeen percent planning, three percent review — My own observed split, not an industry figure. The safety step was the cheapest line on the bill.

Start with one

You don’t need all five. Pick the failure that’s costing you most this week and put that one thing down somewhere.

If you’re not sure which, start with independent review — a second model looking at the first model’s work. It’s the cheapest of the five and it catches the widest range of problems, including the ones you’d never think to look for.

The five-route bug is still my favorite example, because nothing about it was hard. The agent needed one instruction it didn’t have: before you fix something, go and look for everything else shaped like it. That instruction now lives in a file. It’ll be there next session, and the session after, long after every one of us has forgotten why it was written.

The whole framework, with the guardrails and the adoption steps, is on GitHub.