The Vibe Father
Method
Most AI coding today is conversational: you prompt, the agent produces something, you notice it's not quite right, you prompt again, and you converge — eventually — through a drift of corrections. Spec-driven development inverts that. You write the specification first, get it right on paper where changes are cheap, and only then let the agent build to it. Kiro is one visible example of this approach, but the interesting thing isn't the product — it's the discipline, and you can practice it in any tool you already use. Here's what spec-driven AI coding is, why it cuts rework, and how to actually do it.
The problem it solves
Prompt-and-correct works fine for small tasks. It falls apart as the task grows, and it fails for a predictable reason: the agent has to infer your intent from an underspecified prompt, guesses at everything you didn't say, and produces code shaped by those guesses. When the guesses are wrong, you don't find out until you're reading the output — by which point the wrong assumption is baked into structure, naming, and control flow. Fixing it means unwinding decisions, not tweaking lines. Do this across a multi-file feature and you spend more time steering the agent off the wrong path than you'd have spent building it yourself.
The root cause is that the specification exists only in your head, and the agent is reverse-engineering it one correction at a time. Every round of "no, I meant…" is you transmitting one more piece of a spec you never wrote down. Spec-driven development says: write the spec down first, in full, and hand the agent a target instead of a hint.
What a spec actually contains
A useful spec isn't a novel. It's the set of decisions that, left unstated, force the agent to guess. In practice that's a handful of sections:
- The goal, in one paragraph. What this change accomplishes and why — the context that lets the agent make judgment calls in your direction rather than a random one.
- Behavior, concretely. Inputs, outputs, and what happens at the edges. The edge cases are the whole game: "what happens when the list is empty," "what happens when the token is expired," "which of these two plausible behaviors is correct." Every edge case you specify is a guess the agent doesn't get to make wrong.
- Constraints. The existing patterns to follow, the libraries to use or avoid, the interfaces that can't change, the performance or security boundaries. This is how you keep the agent inside your architecture instead of inventing its own.
- Definition of done. How the change will be verified — the tests it must pass, the behavior you'll check. This doubles as the agent's target and your acceptance criteria.
Notice what writing this does even before any agent touches it: it forces you to resolve the ambiguities. Half the value of a spec is that you discover the questions you hadn't answered — the edge case you'd have hand-waved, the interface decision you'd have deferred — while it's still just words. That thinking was going to happen either way. Doing it up front is cheaper than doing it in a review of generated code.
Why it reduces rework
Rework comes from wrong assumptions discovered late. A spec front-loads the assumptions and makes them explicit, so the expensive discoveries happen in text rather than in code. When the agent builds from a real spec, three things change: it has fewer things to guess, so it guesses wrong less often; when it does go wrong, you can point at the spec — "this doesn't match section 2" — instead of re-explaining from scratch; and the definition of done gives you an objective acceptance test instead of a vibe check. The net is fewer correction rounds, and the corrections you do make are precise.
How to do it in any tool
You don't need a dedicated product. The workflow is portable:
1. Draft the spec, then have the agent stress-test it. Write your spec, then ask the agent to read it and list every ambiguity, missing edge case, and unstated assumption it can find before writing any code. This is one of the highest-leverage uses of an agent that exists — it's very good at spotting the holes in a spec, and every hole it surfaces now is a rework round you skip later.
2. Freeze the spec, then build to it. Once the spec is solid, have the agent implement against it. Keep the spec in the context so the agent can check its work against the target rather than against your last prompt.
3. Verify against the definition of done, not the agent's confidence. The spec's acceptance criteria are your checklist. Run the tests it named, check the behavior it described. A model's "I'm done" is not evidence; the spec's definition of done is.
4. Update the spec, not just the code. When requirements change, change the spec and rebuild the affected part. The spec becomes a living artifact — documentation that's actually true because it's the thing the code was built from.
Where Kiro and the approach fit
Kiro is one example of a tool built around this idea — putting the spec at the center of the workflow rather than treating it as optional prose you might write afterward. We're careful not to invent product specifics we can't verify; the durable point is the method, and the method works whether you adopt a spec-first tool or just start writing specs in a markdown file before you prompt. The tool can make the discipline more ergonomic; it can't make the discipline optional. A spec-first workflow in a general-purpose agent beats a spec-optional workflow in a spec-branded one.
When to skip it
Honesty demands the caveat: spec-driven development is overhead, and overhead is only worth it when the task is big enough to earn it. For a one-line fix or a mechanical change with an obvious shape, writing a formal spec is ceremony — just prompt and go. The break-even is roughly where you'd otherwise expect multiple correction rounds: multi-file features, anything with real edge cases, anything where a wrong architectural guess would be expensive to unwind. On those, the spec pays for itself the first time it prevents a rebuild. On trivia, it's friction. Know which one you're doing.
The broader family this belongs to — writing to the agent's strengths, verifying externally, keeping intent explicit — runs through most of what we cover in prompt engineering for coding agents and context engineering. Spec-first is the version of those ideas aimed at rework, and on large tasks it's one of the highest-return habits you can build.
