Why Vibe-Production Isn’t Waterfall (Even Though It Looks Like It)
When the spec is for the AI, not the team
Spec-driven development resembles waterfall planning but works in a completely different economic context
Solo builders using AI agents treat upfront specs as thinking aids, not handoff documents
The moment you add a second person or maintenance burden, the approach breaks in traditional waterfall ways
Professional software development and vibe-production are different problem classes requiring different methods
I got into a respectful disagreement on LinkedIn recently. A developer had posted a critique of spec-driven development, citing evidence that it takes longer and produces worse results than iterative approaches. I commented that as a non-developer, I use SDD to deliver things alone that I could never deliver in the past. Workflow automations, production tools, time-savers. Yes, I produce a lot of markdown upfront, waterfall-style. But I’m also not “vibing” without the big picture and rebuilding ten times.
The response was polite but firm. What I was describing wasn’t software development. It might work for small, self-contained automations where one person is both requester and user, but that’s not what professionals do. Professional software development involves changing requirements, multiple people, production systems, users whose needs you discover over time. The reason Agile moved away from big upfront specs wasn’t that planning is bad. It was that specs go stale the moment reality shows up.
He was right. And so was I. We were talking about different things entirely.
The waterfall-shaped ghost
Spec-driven development, at least in the way I practise it, looks exactly like waterfall from the outside. I write comprehensive markdown documents before any code gets generated. I specify interfaces, data structures, edge cases, error handling. I think through the whole system upfront. To someone who lived through the CASE tool era and the Big Design Up Front disasters of the 1990s, this looks like all the mistakes we already made.
The Agile Manifesto’s second value, “Working software over comprehensive documentation,” was written in 2001 by seventeen practitioners who had direct experience with heavyweight methodologies. Their collective wisdom was that working software, delivered iteratively, was more valuable than comprehensive upfront specifications. This wasn’t ideology. It was pain, distilled.
So when a professional developer sees me producing thousands of lines of markdown to generate hundreds of lines of code, the pattern-matching is immediate. This is waterfall. Waterfall failed. Therefore this will fail.
The mistake is assuming the same constraints apply.
What the spec actually does
In traditional waterfall, the specification is a handoff document. It’s how the business communicates requirements to developers who will build the thing, hand it to testers who will verify it, and eventually deliver it to users who will live with it. The spec has to be comprehensive because it’s crossing organisational boundaries. Once it’s written, changing it is expensive. Political, even. The cost of being wrong in a waterfall spec is high because course correction requires renegotiation, replanning, and rework across multiple teams.
In vibe-production, the spec is for me and the AI. There’s no handoff. There’s no team. There’s no political cost to being wrong. The spec is external working memory. It’s how I think clearly enough about a problem to delegate it. When the AI generates code that’s almost right, I don’t file a change request. I update three lines of markdown and regenerate. The iteration cost is seconds, not sprints.
The Agile Manifesto assumed two things: that the cost of change was non-trivial, and that communication between humans was the expensive part. Both assumptions are false in vibe-production. Change is cheap. There’s no communication overhead because there’s no second person.
The boundary conditions
Vibe-production works under very specific constraints. Violate any of them and it degrades into waterfall with all the traditional pathologies.
User equals builder. I’m building for myself. I know what I want. When the generated code doesn’t quite work, I know immediately because I’m the one testing it. There’s no requirements gathering phase because there’s no gap between what I need and what I understand.
No handoff. The spec never leaves my head. I’m not writing it so someone else can implement it. I’m writing it so I can think clearly. The moment I need to hand this to another developer, the spec becomes a contract and all the waterfall problems return.
Instant iteration. When something doesn’t work, the fix is a markdown edit and a regenerate. There’s no pull request, no code review, no deployment pipeline. The entire loop from “this is wrong” to “this is fixed” takes minutes.
Personal maintenance burden. I’m the one who’ll maintain this. If I cut corners, I pay the price. If I over-engineer, I pay that price too. The feedback is direct and immediate.
Self-contained scope. I’m building workflow automation, not distributed systems. The problem fits in my head. The spec fits in one document. There are no integration points with other teams’ code, no shared databases, no service boundaries to negotiate.
Remove any one of these constraints and the approach breaks. Add a second developer and you need shared understanding. Add a product owner and you need negotiation. Add a six-month maintenance window and you need the spec to stay current. Add changing requirements from external stakeholders and you need the ability to pivot without rewriting the entire foundation.
Those are the conditions where Agile works and waterfall fails. Vibe-production doesn’t operate in those conditions.
Why producers are positioned for this
Game producers spend our careers spec’ing work for others. We know what a good specification looks like. We understand scope. We know what “done” means. We’ve written enough design documents and acceptance criteria to recognise when a requirement is testable and when it’s wishful thinking.
This makes us unusually well-suited to vibe-production. We already think in the structured way that AI agents need. We already know how to externalise complexity into documents. We already have the discipline to think through a problem before asking someone else to solve it.
But this only works for a specific class of problem. I can use vibe-production to automate my weekly stakeholder reports, generate my milestone dependency matrices, or build tools that parse Jira exports into useful formats. These are tasks that were never going to justify professional development resources. They’re too small, too specific, too personal.
The moment I need to build something for my team, the rules change. Now I need working software that someone else can modify. I need tests that someone else can run. I need architecture that someone else can extend. I need all the things Agile optimises for: communication, adaptation, shared understanding.
Vibe-production doesn’t replace professional development. It expands the category of problems I can solve alone.
Different problem classes
The question that came up in that LinkedIn thread was “Why should software be built by the masses?” The framing assumes the masses are trying to do what professionals do, just worse.
That’s not what’s happening.
There’s a vast category of automation that was always too expensive to professionalise. Workflow tools that save you two hours a week. Scripts that reformat data from one system to another. Dashboards that pull together metrics you check every morning. None of these justify a sprint. None of these deserve a ticket in the backlog. But they add up.
Before AI agents, these problems had two solutions: live with the friction, or learn to code well enough to solve them yourself. Most people chose the first option. Now there’s a third option: write a clear specification and let the AI generate the implementation.
This isn’t amateurs trying to build production systems. It’s individuals solving problems that were never going to be production systems in the first place.
The professional developer who sees this and thinks “waterfall” isn’t wrong about the shape. They’re wrong about the context. The upfront spec looks like Big Design Up Front because both involve writing comprehensive documentation before code. But BDUF failed because the documentation was a contract between humans with misaligned incentives and imperfect communication. Vibe-production uses documentation as a thinking tool for one person working with a deterministic agent.
Same shape. Different function. Different constraints. Different failure modes.
What matters is the boundary
The hard part is knowing where the boundary is. At what point does adding a second person, or a longer maintenance window, or a changing requirement from someone else tip you over from vibe-production into bad waterfall?
I don’t have a formula. But I know the smell. If I’m writing the spec and thinking “this needs to be clear for the developer who picks this up in six months,” I’ve crossed the line. If I’m negotiating requirements with a stakeholder, I’ve crossed the line. If I’m building something that will integrate with someone else’s system, I’ve crossed the line.
Inside that boundary, vibe-production works. The waterfall-style spec is a thinking aid, the AI is a force multiplier, and the iteration speed is high enough that being wrong is cheap.
Outside that boundary, you’re doing software development. Use the practices that work for software development. Don’t pretend the upfront spec will save you. It won’t.
The developer who challenged me wasn’t wrong about spec-driven development in professional contexts. He was defending hard-won lessons about what fails at scale, under change, with teams. Those lessons are still true.
But they don’t apply to me, alone, building a tool that saves me an hour a week, that I’ll maintain myself, that no one else will ever touch.
Different problem. Different method. Both valid.
Proper usage of AI is AGILE as hell. Because you either check the result incrementally and often, or you wake up with both of your hands in the potty.
Love that you mention AGILE's "Working software over comprehensive documentation".
AI for proper working needs even more documentation. But not that shit devs used to write ;-)