Key Takeaways
- Spec-driven development can turn into waterfall with better tooling if the spec gets written before anyone validates the problem with a real user.
- Waterfall didn't fail because planning was bad. It failed because it locked in decisions before anyone tested them against a real user.
- A more detailed spec can feel like more rigor while actually being less validation. Writing more isn't the same as checking with a user.
- The fix isn't fewer specs. It's a spec that describes a small, already-validated slice of work instead of a whole feature's worth of assumptions.
I've written twice now about what AI is doing to how we build software: first about end user validation becoming the bottleneck, then about why we need product-focused engineers instead of engineers who just take a ticket and build it. There's a third piece to this that I keep bumping into, and it's about specs.
Spec-driven development has become one of the go-to patterns for working with AI agents. Write a thorough spec, hand it to the agent, let it run for an hour or more without needing to check in every few minutes. The more complete the spec, the further the agent can run on its own before it needs you again. That efficiency is real, and I understand why teams are leaning into it.
But the more I write specs this way, the more it reminds me of something I thought we'd moved past. Waterfall didn't fail because planning was bad. It failed because it locked in a long list of decisions before anyone tested a single one of them against a real user, and by the time the software was built, the cost of being wrong was already spent. Agile broke that up on purpose. Small slices, shipped and checked with real users early, so a bad assumption got caught before ten more decisions got built on top of it.
A long, detailed spec written before anyone's validated the problem is the same move, just faster and with better tooling. The design and requirements phase is still happening, just compressed into a document an agent can execute against for an hour without stopping. The spec feels more disciplined than a vague backlog ticket, so it's easy to mistake writing a more thorough spec for doing more validation. A longer spec written before anyone talks to a user just means more gets built before anyone finds out the assumption was wrong.
None of this means specs are the problem. A good spec still speeds up the agent and cuts down on rework, and I'm not arguing for going back to loose tickets and hoping for the best. What matters is what's inside the spec and when it gets written. A spec that describes a small, already-validated slice of work is doing its job. A spec that locks in a whole feature's worth of assumptions because nobody wanted to slow down and check with a user first is waterfall with a better interface.
If your specs are getting longer and more detailed and nobody on the team has talked to a user in weeks, that's the same mistake we spent twenty years trying to build our way out of, just running at agent speed now instead of committee speed.