{"slug": "spec-driven-development-vs-vibe-coding-waterfall", "title": "Spec-Driven Development vs Vibe Coding: Waterfall?", "summary": "Spec-Driven Development (SDD) has emerged as a disciplined alternative to vibe coding for AI-assisted software development, with tools like GitHub Spec Kit and Kiro implementing the approach. Proponents argue that AI agents produce more consistent output when working from reviewed specifications, while critics on Hacker News have labeled it 'Waterfall Strikes Back.' The debate highlights that vibe coding excels for exploratory prototypes and throwaway automation but degrades with multi-file features, architectural drift, and forgotten constraints.", "body_md": "# Spec-Driven Development vs Vibe Coding: Waterfall?\n\nSpecs as source of truth, or slow ceremony?\n\nSpec-Driven Development entered 2026 as the serious developer’s answer to vibe coding drift.\n\nThe argument is simple: AI agents produce better, more consistent output when they implement against a reviewed specification rather than an ad-hoc prompt. Hard to argue with in theory.\n\nIn practice, Hacker News called it “Waterfall Strikes Back.”\n\nBoth sides have a point.\n\n## The Case for SDD in a Vibe-Coding World\n\n[Vibe coding](https://www.glukhov.org/ai-devtools/vibe-coding/) – the practice of writing a loose prompt and iterating on whatever the AI agent\nproduces – works remarkably well for small, exploratory, and throwaway work. For the first\nsix months of 2025, it was the dominant AI coding pattern. Developers shipped scripts,\nprototypes, and simple tools faster than ever.\n\nThen the projects grew. Multi-file features started drifting. Constraints established in session one were forgotten by session three. Security assumptions got dropped. Architectural decisions shifted mid-feature because the agent had no durable memory of intent.\n\nSpec-Driven Development (SDD) appeared as the disciplined response. The core claim: make the specification the central artifact, not the prompt. Write requirements, a design, and a task plan first. Let the agent implement against those artifacts one slice at a time. Keep the spec versioned and updated.\n\n[AI coding tools](https://www.glukhov.org/ai-devtools/ai-coding-assistants/) – GitHub Spec Kit, Kiro, BMAD, and a growing set of Claude Code custom workflows – are all\nimplementations of this idea. The tooling is real. The interest is real. The backlash is\nalso real.\n\n## What Vibe Coding Is Good At\n\nBefore dismissing vibe coding, it is worth being precise about what it does well.\n\n**Exploratory prototypes.** When you are not sure what you want to build, the fastest path\nis to build something rough and react to it. SDD requires knowing what to specify. If you\ndo not know yet, specs are premature.\n\n**UI experiments.** Visual layout and interaction feel are hard to specify in advance. Vibe\ncoding lets you see options quickly, discard most of them, and converge on something that\nactually feels right. A requirements doc does not help you here.\n\n**Throwaway automation.** One-off scripts, data extraction jobs, migration helpers – these\nrarely need a design document. The cost of getting it slightly wrong is low. The cost of\na slow, ceremonial process is real.\n\n**Fast feedback.** When you need to learn something quickly – does this API work the way\nI think it does? – vibe coding cuts the learning loop to minutes. SDD would slow that down\nfor no benefit.\n\nThe mistake is to take the success patterns from these contexts and apply them to production features with real constraints, real users, and real consequences for getting it wrong.\n\n## Where Vibe Coding Breaks Down\n\nVibe coding degrades predictably as scope and stakes increase.\n\n**Multi-file changes.** Once a feature touches five or more files, the agent’s context window\nstarts losing track of invariants. Without a design document, each prompt has to re-establish\ncontext that was established and forgotten in a prior session.\n\n**Architectural drift.** Without explicit non-goals, agents implement things. The agent\nadds a caching layer because it seems reasonable. Three sessions later, the caching\nassumption is baked into the data model and removing it is expensive.\n\n**Forgotten constraints.** “Only authenticated users can trigger this” is a sentence in a\nrequirements doc. In a vibe coding session, it is something you mentioned once in session one\nand the agent does not remember in session four when it writes the new endpoint.\n\n**Hidden security assumptions.** Authorization rules, input validation boundaries, secrets\nhandling – these are exactly the kind of implicit requirements that get missed when the\nagent is optimizing for plausible working code rather than correct, constrained code.\n\n**Team handoff.** If you built it through iterative prompting, the artifact that records\nwhat was decided and why is… the git log. Good luck with that.\n\n## What Spec-Driven Development Changes\n\nSDD does not claim to eliminate iteration. The good versions of SDD are explicitly\niterative. What they change is where iteration happens. For the full definition –\nincluding how SDD differs from TDD, BDD, and formal methods – see\n[What Is Spec-Driven Development?](https://www.glukhov.org/app-architecture/documentation/what-is-spec-driven-development/)\n\nInstead of iterating on code and inferring intent from diffs, you iterate on the spec and\nthen implement. The spec becomes the artifact that records what was decided, why, and what\nis out of scope – serving a similar function to\n[Architecture Decision Records](https://www.glukhov.org/app-architecture/documentation/decision-records-ai-driven-development/)\nbut oriented around feature intent rather than system-level choices. The code implements that intent.\n\nA typical SDD workflow runs through five phases:\n\n**Specify.** Problem statement, users, goals, non-goals, acceptance criteria, open questions.\n\n**Plan.** Architecture decisions, affected modules, data model, API contracts, security\nconcerns, test strategy.\n\n**Task breakdown.** Small implementation slices with explicit validation criteria and human\nreview checkpoints.\n\n**Implement.** One task at a time, with context reset between tasks, applying constraints\nfrom the spec, and updating the plan when reality differs from the design.\n\n**Validate.** Tests, lint, type checks, acceptance criteria, spec-to-code diff.\n\nThe agent participates in most phases – drafting the spec, generating the design, proposing tasks – but humans review the artifacts before implementation starts. That review step is the central difference between SDD and vibe coding.\n\n## Why Developers Call It Waterfall\n\nThe waterfall critique is not wrong. It is just aimed at bad SDD, not SDD itself.\n\nThe specific failure mode is long upfront planning. Waterfall’s defining characteristic is a feedback loop that stretches to weeks or months: requirements phase, design phase, build phase, test phase, ship. Feedback arrives late. By the time you discover that the design assumption was wrong, you have built on top of it for weeks.\n\nWhen a developer uses Spec Kit and generates a 200-line task list before writing a single line of code, and then spends two days polishing the requirements document before the agent touches anything, that is waterfall. It is waterfall with markdown instead of UML, but the failure mode is identical.\n\nOne HN commenter described using Spec Kit for a small CLI tool and finding it “too slow, too much tweaking before seeing code.” That is the bad version. That user was right to reject it for that task.\n\nThe useful critique is not “specs are bad.” It is “long upfront planning before feedback is bad.” Those are different claims.\n\n## The Useful Middle Ground\n\nGood SDD avoids the waterfall trap by keeping the spec small and starting implementation early.\n\n**Small specs.** A requirements document for a single feature should fit on one screen.\nIf the spec is ten pages, it is either a platform design or it needs to be broken into\nsmaller features. Specs that are too large take too long to review and become stale quickly.\n\n**Short task slices.** Each task should be implementable in a single agent session,\nreviewable as a small diff, and testable in isolation. If tasks are too large, the\nimplementation loop stretches and the spec-to-code mapping becomes hard to verify.\n\n**Early implementation.** Spec the first task, implement it, validate it, then move to the\nnext task. Do not spec everything before implementing anything. The first implementation\nwill reveal things your spec got wrong. Update the spec before continuing.\n\n**Living spec.** When reality differs from the design – and it will – update the spec,\nnot just the code. The spec is only useful if it reflects what was actually built.\n\n**Tests as executable feedback.** Every acceptance criterion should map to at least one\ntest. The test suite is the machine-readable version of the spec. If the spec says “only\nauthenticated users can trigger this,” there should be a test that verifies unauthenticated\nrequests are rejected.\n\nThis hybrid – small specs, short tasks, early implementation, living documents – is what actually works. It is not vibe coding and it is not waterfall. It is controlled iteration with durable artifacts.\n\n## When SDD Beats Vibe Coding\n\nUse SDD – even lightweight SDD – when the cost of getting it wrong is real.\n\n**Risky business logic.** Billing, permissions, data migrations, idempotency – any logic\nwhere incorrect behavior is expensive or hard to reverse. Vibe coding leaves these kinds\nof requirements implicit. SDD makes them explicit and reviewable before implementation.\n\n**Production API changes.** Any change to a public or internal API contract should have a\ndesign document. The design document is what you review before the agent writes code that\nbreaks callers.\n\n**Multi-agent workflows.** When multiple agents are implementing different parts of a\nfeature, the spec is the shared source of truth. Without it, each agent optimizes locally\nand the pieces may not fit.\n\n**Team handoff.** If another developer or another agent will continue this work, the spec\nis the handoff artifact. A git log and a README are not enough.\n\n**Significant refactors.** Refactors that touch core abstractions need an explicit statement\nof what must stay the same (behavior) and what is allowed to change (structure). Without\nthat, the agent may break contracts that you thought were preserved.\n\n## When Vibe Coding Is Still Better\n\nSDD is overhead. Sometimes overhead is not worth it.\n\n**Quick scripts.** A 50-line script to rename files or transform JSON does not need a\nrequirements doc. Write the prompt, check the output, ship it.\n\n**Experiments.** If you are learning whether an approach is feasible – exploring an API,\ntesting a library, validating a hypothesis – you need speed, not structure. Experiment\nfirst, specify if the experiment succeeds.\n\n**UI sketches.** Interaction design benefits from seeing rather than specifying. Build\nseveral rough variations quickly, react to what you see, and only spec what you are\nactually going to ship.\n\n**Disposable automation.** One-time scripts, data imports, migration helpers – the cost\nof a slightly wrong result is usually low, and the artifact is going to be deleted after\nuse anyway.\n\n**Solo prototypes.** If you are the only person who will ever see this code and the goal\nis learning rather than production, vibe coding is faster and the downsides are contained.\n\n## A Simple Decision Framework\n\nThe practical question is not “SDD or vibe coding?” It is “how much spec do I need for this specific task?”\n\n**Use vibe coding when:**\n\n- The task takes less than a day\n- You are exploring or learning\n- The artifact is throwaway or low-stakes\n- You are the only person who will touch this\n- Feedback speed matters more than correctness\n\n**Use lightweight SDD when:**\n\n- The task takes two or more days\n- Multiple files are affected\n- There are explicit security or correctness requirements\n- Another person or agent will continue the work\n- You need to write tests that map to requirements\n\n**Use full SDD when:**\n\n- The feature touches a public interface or data contract\n- Multiple agents or team members are involved\n- The organization requires a design review before implementation\n- Compliance or audit trails are required\n\nThe most common mistake is applying full SDD to tasks that only need lightweight SDD, and applying no spec at all to tasks that need at least a lightweight one.\n\nBad SDD is waterfall with markdown. Good SDD is controlled iteration with durable artifacts. Vibe coding is the right tool for the right tasks – and the wrong tool for the wrong ones. Knowing the difference is the skill.\n\n## Useful Links\n\n[GitHub Spec Kit documentation](https://github.github.io/spec-kit/)– the portable SDD toolkit[Martin Fowler on SDD tools](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)– cautious and useful analysis of Kiro, Spec Kit, and Tessl[HN: Waterfall Strikes Back](https://news.ycombinator.com/item?id=45935763)– the original waterfall critique thread[HN: GitHub Spec Kit launch thread](https://news.ycombinator.com/item?id=45154355)– community reaction[What Is Spec-Driven Development? The Spec as Source of Truth](https://www.glukhov.org/app-architecture/documentation/what-is-spec-driven-development/)– the canonical SDD definition: core artifacts, differences from TDD and BDD, costs and benefits[AI Coding Assistants Comparison](https://www.glukhov.org/ai-devtools/ai-coding-assistants/)– tools that support SDD workflows: Cursor, Copilot, Claude Code, Kiro[What is Vibe Coding – Meaning, Tools, Benefits, and Risks in 2026](https://www.glukhov.org/ai-devtools/vibe-coding/)– the full vibe coding cluster pillar[AI Developer Tools: The Complete Guide to AI-Powered Development](https://www.glukhov.org/ai-devtools/)– the ai-devtools cluster home[Decision Records for AI-Driven Software Development](https://www.glukhov.org/app-architecture/documentation/decision-records-ai-driven-development/)– how to keep architectural intent durable alongside your specs[Claude Skills for Developers: SKILL.md for VS Code, JetBrains, Cursor](https://www.glukhov.org/ai-devtools/claude-code/claude-skills-for-developers/)– reusable SDD-style workflows in Claude Code[Python Design Patterns for Clean Architecture](https://www.glukhov.org/app-architecture/code-architecture/python-design-patterns-for-clean-architecture/)– architecture practices that SDD helps preserve across agent sessions[Unit Testing in Python: Complete Guide with Examples](https://www.glukhov.org/app-architecture/testing-architecture/unit-testing-in-python/)– turning SDD acceptance criteria into executable tests", "url": "https://wpnews.pro/news/spec-driven-development-vs-vibe-coding-waterfall", "canonical_source": "https://www.glukhov.org/ai-devtools/vibe-coding/spec-driven-development-vs-vibe-coding/", "published_at": "2026-06-29 07:01:23+00:00", "updated_at": "2026-06-29 10:32:49.450260+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "developer-tools", "generative-ai", "large-language-models"], "entities": ["GitHub Spec Kit", "Kiro", "BMAD", "Claude Code", "Hacker News"], "alternates": {"html": "https://wpnews.pro/news/spec-driven-development-vs-vibe-coding-waterfall", "markdown": "https://wpnews.pro/news/spec-driven-development-vs-vibe-coding-waterfall.md", "text": "https://wpnews.pro/news/spec-driven-development-vs-vibe-coding-waterfall.txt", "jsonld": "https://wpnews.pro/news/spec-driven-development-vs-vibe-coding-waterfall.jsonld"}}