Vibe coding vs spec-driven dev: a per-task decision guide
Spec-driven development (SDD) arrived in 2026 as the disciplined counter to vibe coding drift. The idea: write requirements, design, and a task plan first, then implement one slice at a time against that spec. Hacker News called it “Waterfall Strikes Back.” Both sides have a point. The real question is not which approach wins globally. It is how much spec a specific task actually needs.
Where vibe coding genuinely wins
Vibe coding dominated AI-assisted development through 2025 for good reason. For the right tasks, nothing beats it on speed.
- Exploratory prototypes. SDD requires knowing what to specify. When you don’t know what to build yet, a rough prompt and fast iteration beats ceremony.
- UI experiments. Layout and interaction feel resist advance specification. Generate options quickly, discard most, converge on what works.
- Throwaway automation. One-off scripts, extraction jobs, migration helpers. The cost of being slightly wrong is low. The cost of writing a full spec is real.
- Fast API validation. Answering “does this endpoint behave the way I think?” takes minutes with vibe coding. SDD slows that loop for zero benefit.
The problem is exporting these patterns to production features with real users, security requirements, and consequences.
Where vibe coding predictably breaks
- Multi-file changes. Past roughly five files, the context window loses invariants. Without a design doc, every new prompt re-establishes context a prior session already built and forgot.
- Architectural drift. Without explicit non-goals, agents implement things that seem reasonable. A caching layer baked into the data model in session three becomes expensive to remove in session ten.
- Forgotten constraints. “Only authenticated users can trigger this” lives in a requirements doc. In a vibe session it was mentioned once in session one and gone by session four’s new endpoint.
- Hidden security assumptions. Authorization rules, validation boundaries, secrets handling. These are exactly the implicit requirements an agent misses when optimizing for plausible working code.
- Team handoff. When the record of what was decided and why is the git log, handoff is a problem.
What SDD actually changes
Good SDD does not eliminate iteration. It moves iteration earlier. You iterate on the spec first, then implement, rather than iterating on code and inferring intent from diffs. The spec records what was decided, what is out of scope, and why.
The loop runs: specify, plan, tasks, implement, validate, with a human review gate per phase. The agent participates in most phases, but humans review artifacts before implementation starts. That review gate is the central difference from vibe coding.
Why the waterfall critique lands sometimes
The critique targets bad SDD, not SDD itself. Waterfall’s defining failure is a feedback loop stretched to weeks: requirements locked, then design, then build, with wrong assumptions discovered after weeks of work. Generating a 200-line task list and polishing requirements for two days before writing a line of code is waterfall with markdown instead of UML. One Hacker News commenter using Spec Kit on a small CLI tool found it “too slow, too much tweaking before seeing code” and was right to reject it for that task.
The useful critique is not “specs are bad.” It is “long upfront planning before feedback is bad.” Different claims.
The per-task decision
The source article includes a decision table worth saving. The condensed version:
- Vibe coding: under a day, one or two files, low stakes, solo throwaway work, no review gate needed.
- Lightweight SDD: two or more days, multiple files touched, handoff to a person or agent, tests that map to requirements.
- Full SDD: multi-week features, public interfaces or data contracts, compliance requirements, multiple agents or team members, design review before implementation starts.
The two classic errors: applying full SDD to tasks that need lightweight SDD, and using no spec at all on tasks that need at least a lightweight one.
The middle ground that works
Good SDD dodges the waterfall trap with five habits: keep specs short enough to fit on one screen, slice tasks to one agent session and one reviewable diff, implement against the first task before finishing the full spec so errors surface early, update the spec when reality diverges from the design, and map every acceptance criterion to at least one test. That last one matters. A test rejecting unauthenticated requests is the machine-readable version of “only authenticated users can trigger this.”
The tooling making this practical includes Superpowers (enforced SDD skills across harnesses), Spec Kit, and Kiro. Links to comparisons and enforcement details are in the source article.
I’m founder of BizStack at Cagri Sarigoz LLC and a passionate advocate for entrepreneurs.
With over 14 years in tech, marketing, and AI, including my role as Head of SEO at CitizenShipper and co-founder of TaleBot at Intale AI, I’m dedicated to sharing genuine, useful product insights and tips.
At BizStack, I aim to cut through the digital noise to provide clear, actionable advice.
And more than all else, I’m a father to a (always) little girl and a husband.
Contact me at [email protected] for assistance.
