No. Spec-driven development only becomes waterfall when you freeze the spec on day one. Waterfall was risky because Winston W. Royce's 1970 model pushed real testing to the end, while modern AI-assisted spec loops aim to shrink what used to take months into minutes, often fitting a full spec-build-evaluate-revise cycle into an afternoon.
That's why the “waterfall with markdown” line is catchy but sloppy. It describes a real failure mode. Bloated docs, frozen requirements, spec drift, token-burning ceremony. All real. But that's bad practice, not the core idea. Good SDD treats the spec like code: versioned, revised, argued over, tightened, and tested against acceptance criteria.
You're not trying to recreate a requirements department in a .md file. You're trying to give yourself and your coding agent a moving target that gets sharper fast.
| Approach | Spec behavior | Feedback timing | What usually happens |
|---|---|---|---|
| Classic waterfall | Upfront and fixed | Late | Rework shows up when it's expensive |
| Bad SDD | Markdown doc frozen too early | Still late | You get ceremony plus drift |
| Real SDD | Living, versioned artifact | Early and continuous | You correct direction before code sprawls |
Table of Contents
- The Short Answer Is No If You Do It Right
- The 'Waterfall with Markdown' Failure Mode
- How Real SDD Is Different Living Specs and Fast Loops
- A Practical SDD Workflow for Solo Builders
The Short Answer Is No If You Do It Right
The backlash is reacting to something real. A lot of people are writing giant specs, handing them to Cursor or Claude Code, then acting surprised when they get slow cycles and stale docs. That is waterfall with markdown.
But real SDD isn't a one-time handoff document. It's a living, versioned artifact that stays upstream of implementation and changes as you learn. That distinction matters. It's the whole game. Gigi Labs' analysis of the debate makes that point directly in its breakdown of what spec-driven development actually is, and Marc Brooker's 2026 post argues the same thing: the loop is still iterative, just much faster because AI shortens the distance between spec and code in his comparison of waterfall vs spec-driven development.
Practical rule: If the spec can't change after first contact with reality, you're not doing SDD. You're doing paperwork.
There's also a category mistake hiding in the critique. Ordering is not the same as process. Yes, you think before you code. That alone doesn't make something waterfall.
The 'Waterfall with Markdown' Failure Mode
The failure mode is easy to spot. You write a big markdown doc. You over-spec edge cases. You feed it to an agent. The code drifts anyway. Now you have two things to maintain: the app and the fiction that the spec still matches it.
That's why some developers are annoyed. In a discussion about software development process models, this pattern lands exactly where you'd expect: too much ceremony, not enough learning. The same complaint shows up in live community threads. The r/agile thread on what spec-driven development gets wrong pushes hard on the idea that SDD can become a productivity trap when docs turn into gates instead of tools. A thread in r/brdev about standardizing AI use on dev teams surfaces the same pain in a different way: frozen specs make teams slower, not clearer.
What goes wrong
- The spec gets treated as a contract. Then nobody wants to edit it.
- The agent writes code against stale intent. Then drift starts.
- Review happens too late. Then the “clarity” was fake.
The critique is right about the anti-pattern. It's wrong when it treats the anti-pattern as the method itself.
This is also why “spec-first” gets unfairly lumped together with “spec-as-source.” Those aren't the same thing. A lightweight planning pass is one thing. A rigid pseudo-BRD that nobody revises is another.
How Real SDD Is Different Living Specs and Fast Loops
The core distinction is feedback speed. Waterfall broke because validation happened at the end. Royce said that plainly in 1970. His warning was that the testing phase at the end of the cycle was the first time critical behavior got systematically exercised. That late validation is what made waterfall dangerous. François Zaninotto's 2025 critique is useful here because even while criticizing SDD, it highlights the core historical issue and notes that modern proponents claim AI can compress a full loop that once took months into minutes, often into an afternoon, in his essay on whether waterfall is coming back through specs.
What living specs actually look like
GitHub-style workflows treat the spec as the source of truth, not as a dead attachment. Roger Wong's 2026 analysis describes specs written in Markdown with sections, examples, payloads, and acceptance criteria, then generated, tested, and revised in a repo-native loop in his writeup on spec-driven development patterns. He also points to three distinct patterns: spec-first, spec-anchored, and spec-as-source.
That taxonomy matters because people keep arguing past each other. They say “SDD” when they really mean one narrow, clumsy implementation.
The standard that matters
Simon Willison's test is better than most process debates: if an LLM wrote every line of your code but you've reviewed, tested, and understood it all, that's not vibe coding. That standard applies to specs too. If you haven't reviewed, tested, and understood the spec, it's just generated prose.
A useful mental model comes from content systems. Good specs need the same discipline as managing content from creation to retirement. You create them, update them, prune them, and retire what no longer matches reality.
A living spec isn't longer. It's fresher.
A Practical SDD Workflow for Solo Builders
For a solo builder, keep it lean. You don't need a ceremony stack. You need a tight loop, clear acceptance criteria, and a habit of rewriting the spec when reality changes.
Use this workflow
- Start with the problem, not the feature list. Write the user pain, constraints, and what “done” means.
- Draft a small structured spec. Keep scope boundaries, assumptions, and acceptance criteria visible. If you need a starting point, use a product requirements document template.
- Hand the spec to your coding agent manually. Cursor, Claude Code, Codex, Gemini. Your choice. You are still the one driving.
- Review the output immediately. Check whether the code and the spec still agree.
- Revise the spec after each meaningful discovery. Not weekly. Not “later.” Right then.
The common mistake is pretending the first draft deserves obedience. It doesn't. It deserves pressure.
Here's a walkthrough if you want to see this style of process in action:
What to avoid
- Huge upfront specs
- Acceptance criteria that nobody checks
- Specs that live outside version control
- Agent output you haven't read carefully
If your spec survives unchanged for long, either the task was trivial or you stopped learning.
That's the answer to “Is spec-driven development just waterfall with markdown?” Sometimes, yes, when people use it badly. But practiced well, it's the opposite. It pulls feedback forward, keeps intent visible, and gives solo builders a way to think clearly before burning time in code.
Connect your GitHub repo. Describe the problem. Get a structured spec. Ship with Tekk.coach.
Part of the Spec-Driven Development pillar — a 52-page honest playbook on shipping with AI coding agents.