Specs Aren't Waterfall When the Rebuild Takes 15 Minutes
The HN Crowd Has a Point
The Hacker News post titled "Spec-Driven Development: The Waterfall Strikes Back" hit roughly 332 points and dragged the same debate onto the front page three separate times in a month. The receipts piled up fast. François Zaninotto argued specs eat more than half of project time. A widely-shared Medium piece coined "Waterfall in Markdown." Someone posted screenshots of an agent generating 1,300 lines of markdown to render a date.
If you have watched a founder try to ship through a planning-heavy AI workflow, none of this is shocking. You write a spec. The agent half-reads it. You discover the constraint that actually matters two weeks in. You rewrite the spec. The agent forgets. The "spec-driven" part of the workflow starts to feel like every shoulder-tap meeting you have ever sat through, only now the meeting writes itself.
The critics are not wrong about what they are seeing. They are wrong about what is actually broken.
Waterfall Wasn't Killed by Documents
Go back to why waterfall failed in the first place. The original sin was not that someone wrote requirements down — most successful engineering teams write requirements down. The sin was that the cost of discovering a wrong requirement was a six-month rebuild. You wrote the spec, handed it over, came back two quarters later, and learned in production that the assumption underneath section 4.2 did not survive contact with a real user.
Waterfall is a loop-length problem disguised as a document problem.
A 1,300-line markdown file is not waterfall on its own. It becomes waterfall the moment changing a single assumption requires a multi-week rewrite of the artifact and another long cycle of "let the agent run." The HN complaint is not really about specs. It is about tools that turn a spec into a contract — frozen, expensive to revise, and only loosely connected to the thing that eventually gets built.
The "agents ignore the specs" complaint follows the same shape. If your tooling cannot keep the spec and the output in sync, of course the spec drifts into decoration. That is not a verdict on spec-driven work. It is a verdict on tools that pretend to be spec-driven and aren't.
Marc Brooker made roughly this point in his April 9, 2026 pushback piece. The backlash is not an argument against thinking before building. It is an argument against a particular generation of tools that made thinking expensive again.
The Spec Is the Feedback Loop — When the Loop Is Fifteen Minutes
Here is the version of spec-driven work the critics are not describing.
You write a short spec — not a 50-page PRD, more like a few paragraphs and a list of decisions. The system generates a working build in minutes. You poke at it, find the thing that does not match your intent, change a line in the spec, regenerate. The build comes back different. You argue with it again.
In that loop, the spec is not a contract handed to a downstream team. It is a live surface — closer to a Figma file or a Jupyter notebook than to a Word doc your CTO signs. The cost of being wrong is the next fifteen minutes, not the next quarter.
That changes what a spec is actually for:
-
Capture the decisions that change the shape of the product — who it serves, what action they take, what they walk away with — so you can change those decisions deliberately instead of by accident.
-
Make disagreement cheap. When you can regenerate from a different assumption in minutes, you actually try the other assumption.
-
Hand the same artifact to the system, your co-founder, and your first hire so everyone argues about the same thing instead of three different mental models.
-
Keep the build downstream of the thinking so what ships matches what you decided, not what the model improvised at 2 a.m.
Vibe coding will get you a prototype that looks like the product. Spec-driven work — the kind where the loop is short enough to argue with — gets you a product. That is the wedge, and the backlash does not break it. It mostly proves that the wrong tools make it look broken.
What Spec-as-Conversation Looks Like Monday Morning
If you are a non-technical founder watching this debate and wondering whether to write anything down at all, here is the version that actually works.
Do not start with a PRD. Start with three answers. Who is this for, specifically? What single action are they trying to complete? What do they walk away with that they did not have before? Those three answers will change the shape of everything downstream. Write them down. Show them to one real prospective user before you let any system generate anything.
Then hand those three answers to a tool that can build from them in minutes. Read what you get back. The first build will be wrong in instructive ways — a flow you assumed was obvious will turn out to need a step you did not name; a decision you thought was a detail will turn out to be the whole product. Edit those three answers. Regenerate. Repeat until the build stops surprising you.
That is the loop. It looks like writing, but the writing is doing the same job a sketch does for a designer — letting you see the consequence of a decision cheaply enough that you make better decisions.
Try the Loop Before You Commit to the Build
Codalio is built around exactly this loop: turn the few decisions that matter into a working build in minutes, then change them and watch the build change with you — so the spec stays a conversation instead of hardening into a contract you regret a quarter from now.
If you are about to spend a quarter and a budget on a build, try Codalio before you start building at codalio.com. You will see in one session what your product actually wants to be — and where your current spec is quietly lying to you.
If you want a starting structure for those first three answers, the Startup Software Requirements worksheet on the site is the shortest version we ship.
References
-
Hacker News thread: "Spec-Driven Development: The Waterfall Strikes Back" (item 45935763, ~332 points)
-
Marc Brooker, "Spec Driven Development isn't Waterfall" (April 9, 2026)
-
"Your Spec Driven Workflow Is Just Waterfall With Extra Steps" — Augment Engineer
-
"Spec-Driven Development Is Waterfall in Markdown" — Medium