Same model, a different starting point
Vibe coding and spec-driven development run on the same tools. Cursor, Claude Code, Copilot, the model underneath is identical. The difference sits in what you hand it before it writes anything.
With vibe coding you start with a prompt and keep going until the thing on screen looks right. With spec-driven development you start by writing down what the software has to do, and the AI generates code from that document. The spec is the thing you maintain. The code follows it.
That sounds like process overhead. In practice it changes the one thing that decides whether AI-generated code is worth anything: whether you have a yardstick to hold it against. We wrote about the attitude behind this earlier in vibe coding vs AI-assisted coding. This article is about the method.
The difference at a glance
| Vibe coding | Spec-driven development | |
|---|---|---|
| Where you start | A prompt, then another prompt. | A written spec: what it does, for whom, under which rules. |
| What you maintain | The chat history, until you lose it. | The spec. Code gets regenerated from it. |
| How you judge the result | It runs and it looks right. | It matches the spec, and the gaps are visible. |
| What happens on a change | Ask again and hope the rest survives. | Change the spec, regenerate, review the diff. |
| Where it fits | Prototypes, one-off scripts, anything disposable. | Software with users, data and a second year. |
What a spec actually contains
A spec in this sense is a working document. Nobody is asking for a fifty-page requirements binder from 2008. Most teams that do this well keep three layers, and the AI reads all of them.
What it has to do
The behaviour in plain language. Who uses this, what they can do, what happens at the edges. Written so someone outside the team can tell whether the built thing matches.
The rules it has to obey
Your stack, your conventions, the security boundaries, the things that are off limits. This is the layer that stops the model from inventing its own architecture every session.
The plan to get there
The work cut into steps small enough that each one is reviewable on its own. A step that touches thirty files is a step nobody reviews.
Tooling has grown around this. GitHub’s Spec Kit and Amazon’s Kiro both push you through spec, plan and tasks before generating anything, and the same discipline works with a plain markdown file in the repo that your AI editor reads every session.
Why the spec is really a review tool
Here is the part that matters for anything headed to production. Reviewing AI-generated code without a spec means reconstructing the intent from the code itself. You read a function, you decide it looks reasonable, and you have no way to tell whether it does the thing that was asked or a neighbouring thing the model found easier.
Without a spec you are not reviewing the code. You are guessing what it was supposed to do, from the only evidence available, which is the code you are trying to check.
With a spec, review becomes a comparison. Does this match what we wrote down, yes or no. That question can be answered by a second person, by a test, and increasingly by a second model. The vague version of the question cannot.
This is why we build our own process around a written brief and a human who sees every line before it ships. The model does the typing. The judgement about whether the result is correct stays with a person, and that person needs something to judge against.
Vibe coding still has its place
Spec-driven development is not free. Writing the spec takes real time, and on a throwaway project that time buys you nothing.
You are exploring, not building
When you do not yet know what the thing should be, a spec is a guess written down. Vibe your way to an answer first, then write the spec for the version that survives.
The blast radius is tiny
A script that runs once on your own machine has no users and no second year. Ugly code that works is the correct outcome.
You are three prompts from done
Some tasks are genuinely small. Writing a spec for a fifteen-minute change is ceremony, and everyone can feel it.
The failure mode is starting in exploration mode and never leaving it. The prototype gets a user, then a paying user, then a database with real names in it, and the spec that would have made it reviewable was never written. That is the same trap we described in the last 20% of a vibe-coded project, arriving from a different direction.
Vibe engineering is the same idea under a different name
You will also see this called vibe engineering, a term Simon Willison put forward for the disciplined end of AI-assisted work: you still lean hard on models, and you bring the whole engineering apparatus with you. Specs, tests, review, version control, CI, the ability to say what the software is supposed to do.
Treat vibe engineering and spec-driven development as the same instinct with different emphasis. Spec-driven development names the artifact you start from. Vibe engineering names the practice around it. Both exist because pure vibe coding runs out of road the moment something has to be maintained.
Prompt engineering is a different thing entirely
Prompt engineering gets pulled into this comparison a lot, and it sits on another axis. Prompt engineering is about phrasing a single instruction well: give the model context, format, examples, constraints. It makes any one exchange better.
Spec-driven development is about what persists between exchanges. Your spec survives the session, the context window, the tool you switched to last month and the colleague who picks it up next quarter. A well-phrased prompt gets you a good answer today. A spec gets you a codebase you can still reason about in a year.
Three signals you have outgrown vibing
You cannot say what it should do
Someone asks whether a behaviour is a bug or intended, and the honest answer is that nobody wrote it down. That is the moment a spec pays for itself.
Changes break things elsewhere
Every fix knocks something else over, because the model has no picture of the whole and neither do you. A spec plus small steps is how you get that picture back.
Real data has arrived
Actual users, actual records, actual money. From here on, code that nobody can review against anything is a liability rather than a shortcut.
Conclusion: the spec is what makes AI code reviewable
Vibe coding and spec-driven development sit at two ends of one question: how much of your intent exists outside your own head. Vibing keeps it in the chat and in your memory. A spec puts it in the repo, where a colleague, a test and a model can all read it.
Vibe coding = fast answers
Perfect for finding out whether an idea is worth anything. What you end up with is a prototype, and that is exactly what it is good for.
Spec-driven development = something to maintain
Slower on day one and much cheaper in month six, because everything the AI produced can be checked against something you wrote on purpose.
Most teams need both. The skill is knowing which one you are doing right now, and being honest about when the project moved from one to the other.
What is spec-driven development?
What is the difference between vibe coding and spec-driven development?
Is spec-driven development better than vibe coding?
Is vibe engineering the same as spec-driven development?
How is spec-driven development different from prompt engineering?
When should I switch from vibe coding to a spec?
Built it on vibes and now it needs to hold up?
We read what is actually there, write down what it should do, and tell you what it takes to get from prototype to production.
