this is like a waterfall approach on steroids.
Verified Spec-Driven Development (VSDD) Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl Spec-Driven Development: The Waterfall Strikes Back Spec-driven development doesn’t work if you’re too confused to write the spec
Spec-driven development means writing a “spec” before writing code with AI (“documentation first”). The spec becomes the source of truth for the human and the AI.
We’ve gone from AI auto-complete to agentic coding to spec driven development and a new argument has popped up about the future of programming. It goes something like: source code is the new assembly language. Engineers will stop caring about it, move up a level of abstraction, and be judged on outcomes rather than code quality.
So, ok. We can just write the spec for business-rules and have it turn it into code right?
Well no. Usually we are actually confused about the business-rules. Usually, we don’t actually understand it until we work through. You go to formalize the relationships and invariants, and the act of making them precise and consistent teaches you things about the domain that you didn’t understand when you started.
The machine pushes back on you: this rule contradicts that one, this entity doesn’t fit cleanly into the structure you assumed, this edge case reveals that your model was wrong. The difficulty at this level isn’t that there are a lot of letters to type. It’s that you have to refine your thinking as you write it down. A high-level fuzzy idea becomes a specific set of relationships, semantics, and rules, and they all have to cohere.
Spec-driven development doesn’t save us here, it’s just an opening of a conversation. Any spec unambiguous enough to work is already close enough to code that we could just express it as code. Writing that spec is a discovery process. You learn what you’re building by trying to make a computer understand it.
***Really, my guess is we’ll get better at writing unambiguous specs.
Spec-driven development doesn’t work if you’re too confused to write the spec
Agile methodologies killed the specification document long ago. Do we really need to bring it back from the dead?
SDD reminds me of the Waterfall model, which required massive documentation before coding so that developers could simply translate specifications into code.Software development is fundamentally a non-deterministic process, so planning doesn’t eliminate uncertainty (see the classic No Silver Bullet paper). Also, who is SDD really for? You must be a business analyst to catch errors during the requirements phase, and a developer to catch errors during design. As such, it doesn’t solve the problem it claims to address (removing developers), and it can only be used by the rare individuals who master both trades. SDD repeats the same mistake as No Code tools, which promise a “no developer” experience but actually require developers to use them.
Agile methodologies solved the problem of non-deterministic development by trading predictability for adaptability. I believe they show us a path where coding agents can help us build reliable software, without drowning in Markdown.
Give a coding agent a simple enough problem, and it won’t go off the rails. Instead of translating complex requirements into complex design documents, we should split complex requirements into multiple simple ones.
When implementing simple ideas is cheap, building in small increments is the fastest way to converge toward a good product.
Agile methodologies freed us from the bureaucracy of waterfall. They showed that close collaboration between product managers and developers eliminates the need for design documents. Coding agents supercharge Agile, because we can literally write the product backlog and see it being built in real time—no mockups needed!
Spec-Driven Development: The Waterfall Strikes Back
The “airtight spec before building” assumption is the same original sin that killed traditional waterfall development, and VSDD repeats it while dressing it up in modern tooling.
The core problem is epistemological, not methodological. You genuinely cannot enumerate edge cases before implementation because the act of implementation is itself a discovery process.
The spec doesn’t just describe the domain — it reveals it.
Phase 1’s Edge Case Catalog asking “what happens with null, empty, maximum size, negative, Unicode, concurrent?” sounds exhaustive until you’re three weeks into implementation and discover that your “pure core” has a subtle interaction between concurrent access and your state machine that nobody could have predicted from first principles. Now you’re supposed to loop back to Phase 1, revise the spec, re-review with the Adversary, update Chainlink beads, and re-execute formal proofs. In practice, teams will either skip that loop (defeating the methodology) or drown in ceremony.
That said, the document isn’t wrong about everything — it’s wrong about sequencing, which is a significant but repairable flaw.