Specs as source of truth, or slow ceremony?
Spec-Driven Development entered 2026 as the serious developer’s answer to vibe coding drift.
The 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.
In practice, Hacker News called it “Waterfall Strikes Back.”
Both sides have a point.
The Case for SDD in a Vibe-Coding World #
Vibe coding – the practice of writing a loose prompt and iterating on whatever the AI agent produces – works remarkably well for small, exploratory, and throwaway work. For the first six months of 2025, it was the dominant AI coding pattern. Developers shipped scripts, prototypes, and simple tools faster than ever.
Then 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.
Spec-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.
AI coding tools – GitHub Spec Kit, Kiro, BMAD, and a growing set of Claude Code custom workflows – are all implementations of this idea. The tooling is real. The interest is real. The backlash is also real.
What Vibe Coding Is Good At #
Before dismissing vibe coding, it is worth being precise about what it does well.
Exploratory prototypes. When you are not sure what you want to build, the fastest path is to build something rough and react to it. SDD requires knowing what to specify. If you do not know yet, specs are premature.
UI experiments. Visual layout and interaction feel are hard to specify in advance. Vibe coding lets you see options quickly, discard most of them, and converge on something that actually feels right. A requirements doc does not help you here.
Throwaway automation. One-off scripts, data extraction jobs, migration helpers – these rarely need a design document. The cost of getting it slightly wrong is low. The cost of a slow, ceremonial process is real.
Fast feedback. When you need to learn something quickly – does this API work the way I think it does? – vibe coding cuts the learning loop to minutes. SDD would slow that down
for no benefit. The 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.
Where Vibe Coding Breaks Down #
Vibe coding degrades predictably as scope and stakes increase.
Multi-file changes. Once a feature touches five or more files, the agent’s context window starts losing track of invariants. Without a design document, each prompt has to re-establish context that was established and forgotten in a prior session.
Architectural drift. Without explicit non-goals, agents implement things. The agent adds a caching layer because it seems reasonable. Three sessions later, the caching assumption is baked into the data model and removing it is expensive.
Forgotten constraints. “Only authenticated users can trigger this” is a sentence in a requirements doc. In a vibe coding session, it is something you mentioned once in session one and the agent does not remember in session four when it writes the new endpoint.
Hidden security assumptions. Authorization rules, input validation boundaries, secrets handling – these are exactly the kind of implicit requirements that get missed when the agent is optimizing for plausible working code rather than correct, constrained code.
Team handoff. If you built it through iterative prompting, the artifact that records what was decided and why is… the git log. Good luck with that.
What Spec-Driven Development Changes #
SDD does not claim to eliminate iteration. The good versions of SDD are explicitly iterative. What they change is where iteration happens. For the full definition – including how SDD differs from TDD, BDD, and formal methods – see
What Is Spec-Driven Development? Instead of iterating on code and inferring intent from diffs, you iterate on the spec and then implement. The spec becomes the artifact that records what was decided, why, and what is out of scope – serving a similar function to Architecture Decision Records but oriented around feature intent rather than system-level choices. The code implements that intent.
A typical SDD workflow runs through five phases:
Specify. Problem statement, users, goals, non-goals, acceptance criteria, open questions.
Plan. Architecture decisions, affected modules, data model, API contracts, security concerns, test strategy.
Task breakdown. Small implementation slices with explicit validation criteria and human review checkpoints.
Implement. One task at a time, with context reset between tasks, applying constraints
from the spec, and updating the plan when reality differs from the design. Validate. Tests, lint, type checks, acceptance criteria, spec-to-code diff.
The 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.
Why Developers Call It Waterfall #
The waterfall critique is not wrong. It is just aimed at bad SDD, not SDD itself.
The 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.
When 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.
One 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.
The useful critique is not “specs are bad.” It is “long upfront planning before feedback is bad.” Those are different claims.
The Useful Middle Ground #
Good SDD avoids the waterfall trap by keeping the spec small and starting implementation early.
Small specs. A requirements document for a single feature should fit on one screen. If the spec is ten pages, it is either a platform design or it needs to be broken into smaller features. Specs that are too large take too long to review and become stale quickly.
Short task slices. Each task should be implementable in a single agent session, reviewable as a small diff, and testable in isolation. If tasks are too large, the implementation loop stretches and the spec-to-code mapping becomes hard to verify.
Early implementation. Spec the first task, implement it, validate it, then move to the next task. Do not spec everything before implementing anything. The first implementation will reveal things your spec got wrong. Update the spec before continuing.
Living spec. When reality differs from the design – and it will – update the spec, not just the code. The spec is only useful if it reflects what was actually built.
Tests as executable feedback. Every acceptance criterion should map to at least one test. The test suite is the machine-readable version of the spec. If the spec says “only authenticated users can trigger this,” there should be a test that verifies unauthenticated requests are rejected.
This 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.
When SDD Beats Vibe Coding #
Use SDD – even lightweight SDD – when the cost of getting it wrong is real. Risky business logic. Billing, permissions, data migrations, idempotency – any logic where incorrect behavior is expensive or hard to reverse. Vibe coding leaves these kinds of requirements implicit. SDD makes them explicit and reviewable before implementation.
Production API changes. Any change to a public or internal API contract should have a design document. The design document is what you review before the agent writes code that breaks callers.
Multi-agent workflows. When multiple agents are implementing different parts of a feature, the spec is the shared source of truth. Without it, each agent optimizes locally and the pieces may not fit.
Team handoff. If another developer or another agent will continue this work, the spec is the handoff artifact. A git log and a README are not enough.
Significant refactors. Refactors that touch core abstractions need an explicit statement of what must stay the same (behavior) and what is allowed to change (structure). Without that, the agent may break contracts that you thought were preserved.
When Vibe Coding Is Still Better #
SDD is overhead. Sometimes overhead is not worth it.
Quick scripts. A 50-line script to rename files or transform JSON does not need a requirements doc. Write the prompt, check the output, ship it.
Experiments. If you are learning whether an approach is feasible – exploring an API, testing a library, validating a hypothesis – you need speed, not structure. Experiment first, specify if the experiment succeeds.
UI sketches. Interaction design benefits from seeing rather than specifying. Build several rough variations quickly, react to what you see, and only spec what you are actually going to ship.
Disposable automation. One-time scripts, data imports, migration helpers – the cost of a slightly wrong result is usually low, and the artifact is going to be deleted after
use anyway. Solo prototypes. If you are the only person who will ever see this code and the goal is learning rather than production, vibe coding is faster and the downsides are contained.
A Simple Decision Framework #
The practical question is not “SDD or vibe coding?” It is “how much spec do I need for this specific task?”
Use vibe coding when:
- The task takes less than a day
- You are exploring or learning
- The artifact is throwaway or low-stakes
- You are the only person who will touch this
- Feedback speed matters more than correctness
Use lightweight SDD when:
- The task takes two or more days
- Multiple files are affected
- There are explicit security or correctness requirements
- Another person or agent will continue the work
- You need to write tests that map to requirements
Use full SDD when:
- The feature touches a public interface or data contract
- Multiple agents or team members are involved
- The organization requires a design review before implementation
- Compliance or audit trails are required
The 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.
Bad 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.
Useful Links #
GitHub Spec Kit documentation– the portable SDD toolkitMartin Fowler on SDD tools– cautious and useful analysis of Kiro, Spec Kit, and TesslHN: Waterfall Strikes Back– the original waterfall critique threadHN: GitHub Spec Kit launch thread– community reactionWhat Is Spec-Driven Development? The Spec as Source of Truth– the canonical SDD definition: core artifacts, differences from TDD and BDD, costs and benefitsAI Coding Assistants Comparison– tools that support SDD workflows: Cursor, Copilot, Claude Code, KiroWhat is Vibe Coding – Meaning, Tools, Benefits, and Risks in 2026– the full vibe coding cluster pillarAI Developer Tools: The Complete Guide to AI-Powered Development– the ai-devtools cluster homeDecision Records for AI-Driven Software Development– how to keep architectural intent durable alongside your specsClaude Skills for Developers: SKILL.md for VS Code, JetBrains, Cursor– reusable SDD-style workflows in Claude CodePython Design Patterns for Clean Architecture– architecture practices that SDD helps preserve across agent sessionsUnit Testing in Python: Complete Guide with Examples– turning SDD acceptance criteria into executable tests