Good Spec, Good Robot

When founders ask me how I build with AI, they start with the orchestration layer. How many agents, which framework, queues or loops, subagents or one big context. That’s the decoration.

The thing that actually decides whether AI ships something or just generates something is the oldest, most boring discipline in engineering. A precise spec, real acceptance criteria, a clear definition of done.

Spec-driven development is exactly what it sounds like. You write down what done looks like before anything gets built, in enough detail that something other than you can execute against it and you can tell whether it worked. That used to be paperwork. Now that’s the most important part of the job.

Vibe coding has no fitness function

The reason vibe coding stops working past a demo isn’t code quality. Models write fine code. It’s that there’s nothing for the output to be measured against except your eyes.

You are the fitness function. You look at what came back, you squint, you decide it seems right, you move on. That works at one feature and falls apart at ten, because you can’t hold ten features’ worth of “seems right” in your head at once, and a generator with no target will hand you infinite plausible-wrong code forever and never get tired.

Spec-driven is the opposite move. You encode the fitness function once, up front, so the AI can loop against it and you can trust what comes out without personally inspecting every line.

That’s the difference between generating and shipping.

I’ve argued before that coding was never the job, that the actual work was always the 80% around the code. This is where most of that 80% now lives. Deciding what to build, describing it precisely, and defining how you’ll know it worked.

Specs flipped from brake to steering wheel

This is the same inversion I wrote about with scoring your backlog, and it keeps showing up everywhere.

Specs used to be overhead. They existed because building was expensive and slow, so you wrote things down to stop expensive humans from building the wrong thing for three months. The doc was a brake. I resented writing them, and I think that was fair, because a spec cost me a week and the thing it protected was mostly my own ability to change my mind later.

Then building got cheap. The brake stopped being necessary, and I assumed the spec went with it.

It went the other way. When generation is cheap and fast, the only scarce thing left is knowing what you actually want, precisely enough to recognize it when it shows up. The spec stopped being the brake and became the steering wheel. It’s the one thing that makes cheap generation trustworthy instead of just fast.

Nobody wrote fewer specs because of AI. The people getting real output write tighter ones.

This is not waterfall

I have to be clear about this or half of you are hearing “go back to 2005.”

Spec-driven does not mean a forty-page requirements document signed by three stakeholders. The specs I write are short and self-contained, usually a page or two. Scope, the steps, acceptance criteria, how it gets tested, what’s explicitly out of bounds.

The spec doesn’t need to be big. It needs to be precise about done. Those are completely different properties, and waterfall spent about twenty years confusing them.

The other difference is speed. A waterfall spec got written once, months ahead of the build, and then defended. Mine gets written twenty minutes before the build and thrown away after, because writing it is cheap now too.

What it looks like when it’s running

My whole build flow is one command. Brief, research, then a PRD I have to green light, then the build, then a verify gate, then it lands on a branch.

Two of those steps matter and the rest is plumbing. The PRD gate, where I read the plan and either approve it or send it back, and the verify gate, where the work gets adversarially reviewed before I ever see it.

The verify gate is where the value shows up, and it shows up constantly. On a client feature last month it caught a change that would have silently done nothing in production while still returning a success response, which is the exact category of bug that survives review because every line of it reads correctly. Another one caught a brand new public page throwing a server error on a malformed URL parameter, on a surface that had been live for about four minutes.

Neither of those was found by me reading code. They were found because “done” had been written down well enough that something could check the work against it.

That’s the receipt. Not that AI writes good code, but that a spec plus a gate turns confident output into verified output.

The part that actually changed

AI didn’t retire engineering rigor. It removed every excuse for not having it.

The old tradeoff was real. Rigor cost time, time cost money, so you rationed it and shipped some things loose. That tradeoff is gone. Writing down what done looks like takes fifteen minutes, and it’s now the highest-leverage fifteen minutes in the whole process, because everything downstream of it is close to free.

If your AI output feels like a slot machine, the problem probably isn’t your model or your framework. You just never told it what winning looks like.

Good spec, good robot. It really isn’t more complicated than that. It’s just less fun than arguing about which agent framework to use.