The failure mode of AI-written code is not usually AI-written code.
It is a feature that works exactly the way the spec described, where the spec described the wrong thing. The code compiles, the tests pass, the thing even runs in production for a day, and then someone opens it and the whole premise collapses because an assumption nobody wrote down was wrong.
That is not a code quality problem. That is a specification quality problem. And since the agent writes code faster than any human can read it, the only way to catch spec problems in time is to make the agent catch them for you, before any code gets written.
So that is what I do now.
Before Claude writes a line, another Claude tears the spec apart.
— A rule I set after watching the agent faithfully build the wrong thing
The two-step loop
The loop is boring on purpose.
The whole thing lives in ~/Documents/Brett Omarchy/Projects/ as plain markdown. One file per feature. Specs are cheap. Specs are also the only artifact worth being careful with, because they are the thing the agent will faithfully execute.
The audit step is the one that changed everything. I used to go from “I know what I want” to “write it” in one leap, because the agent is so fast that drafting a long spec feels like a tax. The tax was never the spec. The tax was reverting the thing the agent built from the first draft of my spec.
The five questions
The audit agent gets a short, mean prompt. Here it is:
That is the whole audit protocol. No framework, no checklist file with forty rows, nothing to install. The constraint “do not propose solutions” matters more than it looks — a solving agent will rewrite the spec, which is not what I want. I want a reviewer, not a replacement.
The categories map pretty cleanly onto the four ways a spec gets you in trouble: things you didn’t say, things you said that fight the codebase, things you didn’t think to handle, and things that could be read two ways. The fifth is scope drift, which is me-shaped: I love tacking “and while we’re at it” onto a spec, and it is almost always how a two-day feature becomes a week.
What the audit catches
A real audit on a recent spec of mine, lightly anonymized, came back with:
- One unstated assumption that a certain field would always be non-null, when nothing in the schema enforces it.
- Two contradictions with how an existing module in the repo already does the same thing one layer down — meaning I was about to write a parallel path instead of extending the one that exists.
- Four edge cases, two of which I had actively, consciously decided to not worry about, and two of which I just hadn’t thought of.
- One ambiguity in a sentence about retry behavior — did I mean retry the whole operation, or retry just the failing step?
- Two scope drift items that I pretended were part of the feature and were, honestly, a different feature.
The entire audit took the agent about ninety seconds and cost less than a nickel. The feature it saved me from building and then reverting would have cost half a day plus the trust-tax of landing a half-right thing on main. The math is not close.
Why a second agent, not the same agent
The thing that makes this work is that the auditor cannot be the same session that will build the thing.
A session that is about to write code is a session with momentum toward writing code. Even if you tell it “pause and audit first,” the undertone of the context is “we are going to build this.” You get a review that finds nothing because the context has already decided the spec is good.
A fresh session, with no history and a prompt that says “find holes,” has nothing invested in the spec being right. It will cheerfully tell you the spec is wrong, because to that session, finding a problem is the win condition. That is the behavior you want.
The uncomfortable part
The uncomfortable part is that most of what the auditor finds is my fault, not the model’s.
I’m an experienced builder. I’ve been shipping software for years. And the audits consistently find holes in my specs — not weird exotic holes, obvious ones. Unstated assumptions I would have caught if I had slowed down. Edge cases I would have hit on my second pass if I had done a second pass. The audit is not telling me the model is dumb. It is telling me I was writing a spec with the belief that the model would fill in the gaps, and the model’s gaps are not the same shape as mine.
The spec is the thing I control. The code is the thing I used to try to control. The whole move of agentic development, done well, is to accept that the control surface is upstream of the code. Which means the care has to be upstream too.
The one-line version
Write the spec. Have a different agent try to kill it. Fix what it finds. Then let the first agent build.
The code was never the problem. The code did exactly what you said.