The spec is the floor, not the senior engineer

Spec-driven development is having its year. Every major AI coding tool shipped a spec-first mode, GitHub’s Spec Kit, AWS’s Kiro, a flavour of it in Claude Code and Cursor. And it earns the attention. Hand an agent a real spec instead of a one-line prompt and the first draft comes back closer to right, with far less of the throw-it-out-and-regenerate churn. GitHub reports teams using Spec Kit clear more work on the first pass and start over far less often. Write the spec. I am not arguing with that.

The part I would argue with is the claim riding alongside it: that a detailed enough spec makes an agent ship like a senior engineer. The usual objection is “you still have to review the output,” which is true and not very interesting. Everyone agrees with it and then doesn’t do it. The real problem sits one level down. A good spec doesn’t just leave the reviewing undone. It makes the reviewing harder.

A good spec lowers your guard

Spec-shaped code arrives looking like exactly what you asked for. It uses your names, follows your structure, satisfies the acceptance criteria you wrote down. It looks authorised, and output that looks authorised gets waved through, because a rigorous-looking front end quietly vouches for the back end.

Take a shape this actually takes. Your spec says validate the request before processing it. The agent adds the validation, right there in the diff, and writes a test that confirms validation runs. The test passes. What neither the spec nor the test says is that the check has to reject a quantity of minus one, so it doesn’t, and the refund goes through. Every line of the spec is satisfied. The pull request looks thorough. The bug ships anyway.

Vibe-coded slop has one accidental virtue. It looks like slop, so you read it properly. A clean, spec-shaped pull request disarms the exact scrutiny it still needs. That is how a careful team ships a confident wrong answer faster than a sloppy one does, and the defect rate underneath has not moved much. Studies keep finding that a large share of AI-generated code, by some counts close to half, carries a security flaw the spec did nothing to prevent.

You can write a spec. You can’t write the catch.

Here is why “ships like a senior engineer” is wrong at the root. A spec is judgment you can write down in advance: intent, constraints, the edge cases you already know about. The senior engineer’s value was never that document. It was the live catch, the thing nobody specified because nobody saw it coming. The minus-one quantity. The function that satisfies every line and still does the wrong thing.

That judgment is a reaction to what the agent actually did, so you can’t pre-bake it. It only exists once there is an output to react to. The pull request I have learned to slow down on is the one that matches the spec perfectly, because that is the one my guard is lowest on.

What actually closes the gap

None of this is an argument for writing worse specs, or for reading every line by hand, which stops scaling the moment an agent is producing most of the code. It is an argument for putting the catch somewhere other than your own attention at six in the evening. On my own work that means a second model that has to disagree before anything lands, and a gate that runs before push. The spec is one input to that system. It is not the whole of it, and it is not a stand-in for it.

So write the spec. It earns its place. Just don’t read it as a finished job. A spec is the half of the work you can see, the half where you say what you want. The other half is the catch on what the agent actually did, and that half was always the senior engineer, not the document. It is still there, only harder to see now that the output arrives looking authorised. Miss it and you don’t find out at review, where it is cheap. You find out in production, where the minus one already went through.