Spec-Driven Development: Is It Actually Different From Vibe Coding?
Every dev newsletter I read this month has a piece on “spec-driven development” — the idea that instead of prompting an agent conversationally and iterating on whatever it spits out, you write a formal spec first (requirements, a plan, sometimes explicit acceptance criteria), hand that to the agent, and only then let it generate code. It’s being pitched as the mature, grown-up answer to vibe coding — the thing that turns “AI wrote my app and I have no idea how it works” into an actual engineering discipline. I was curious enough, and skeptical enough, that I tried it properly on a real client project instead of just reading takes about it. My conclusion is messier than either the hype pieces or the dismissals: it’s a real improvement for a specific kind of work, and a rebrand for the rest.
Where it genuinely helped: anything with more than one plausible interpretation
I was adding a multi-tenant permissions system to an internal tool — the kind of feature where “what happens when a user belongs to two teams with conflicting role settings” has no obviously correct answer, it’s a business decision. In the past I’d have just started prompting an agent and corrected its assumptions as they came up, which meant re-litigating the same ambiguity three or four times across a session. This time I wrote the spec first: explicit rules for role precedence, what happens on team removal, what the audit log needs to capture. Writing that out surfaced two edge cases I hadn’t actually thought through myself, before any code existed. That’s the real value — not that the agent produces better code from a spec, but that writing the spec forces me to make decisions I’d otherwise have made implicitly and inconsistently, mid-generation, without noticing.
Where it was just vibe coding with extra paperwork: anything I already knew how to do
I tried the same process on a straightforward CRUD endpoint with standard REST conventions, and writing a formal spec for it felt like theater. There was no ambiguity to resolve — I know what a paginated list endpoint with filtering looks like, I’ve built dozens of them, and turning that into a spec document before generating code just added a step that didn’t change the outcome. The people most excited about spec-driven development online tend to talk about it as a universal practice, “always write the spec first,” and that’s the part I don’t buy. A spec is worth writing when the ambiguity is real. When it’s not, you’re just typing the same information twice — once as a spec, once as it inevitably shows up in the code anyway.
The framing doing a lot of the marketing work is “this prevents vibe-coding debt.” I’ve written before about why I think that debt panic is overblown as a new phenomenon — it’s mostly old undisciplined-team problems running faster. Spec-driven development doesn’t fix that on its own. I can write a spec, hand it to an agent, get code back that technically matches the spec, and still end up with the same kind of mess I’d get from vibe coding: inconsistent error handling, duplicated logic across files, comments that don’t match what the code does. A spec constrains the what, not the how, and most of the debt I actually clean up in client codebases lives in the “how” — the small implementation choices nobody wrote down because nobody thought they needed to. If you skip code review because you trust the spec, you’ve just moved the same discipline problem one layer up.
What actually made the difference: the review checkpoint, not the document
Before generating anything, I now have a written artifact I can put in front of a client or a teammate and ask “is this what you meant?” before an hour of agent output exists to sunk-cost me into accepting it. That’s a genuinely useful gate. But I could get most of that same value from a two-paragraph email describing my plan before I start coding — which, honestly, is a thing disciplined engineers have done forever, long before “spec-driven development” was a phrase with its own conference talks. Calling it a new methodology feels a bit like calling “writing down what you’re about to build before you build it” a breakthrough. It’s good practice. It’s just not new practice.
The tooling side is where I’m more genuinely impressed. A few of the newer agent frameworks now treat the spec as a living document the agent references throughout a session rather than a one-time prompt, and re-check its own output against it before finishing — that part is a real mechanical improvement over pasting a spec into a chat window and hoping the model stays anchored to it forty messages later. I’ve started keeping a lightweight SPEC.md per feature branch for exactly this reason, not because the ceremony demands it, but because it’s a genuinely useful anchor for a long agent session that would otherwise drift. That’s the part of this trend I’ll keep. The part where every team is told they need a formal spec-writing phase for every single change, including the boring CRUD endpoint, is the part I think will quietly fade once the current wave of “here’s my methodology” blog posts moves on to the next thing.
Where I’ve landed, practically
I write a real spec when the feature has a decision buried in it that more than one reasonable person could get wrong — permissions, billing logic, anything touching money or access control, anything where “what should happen” is itself the hard part. I skip the ceremony for the fifty CRUD endpoints and standard integrations that make up most of a typical week, because forcing a spec onto unambiguous work doesn’t add rigor, it adds friction that eventually gets skipped anyway under deadline pressure — which is exactly the failure mode this whole movement claims to be solving.
I don’t think spec-driven development is a scam, and I don’t think it’s the discipline that finally tames agentic coding either. It’s a genuinely useful practice for the subset of work where ambiguity is the actual risk, wrapped in enough conference-talk framing to make it sound universal. Use it where the ambiguity is real. Don’t let anyone tell you a spec document by itself is what separates careful engineering from vibe coding — the review discipline was always the thing doing that work, spec or no spec.