OpenSpec is not Waterfall, dang it!

The other morning, I was making breakfast for my family. When I’m the only one up and about, I’ll usually watch some YouTube videos while I’m at it, and this day I chose to go through the more popular videos about OpenSpec. What I saw were some absolutely terrible arguments against the practice.

These videos described spec-driven development as a process that requires us to completely think through a project up front and to describe it unamgibuously in natural language (e.g., English), resulting in such a detailed and fully thought-through spec that our agents can one-shot a large project with no errors or ambiguity.

To which I say: wut?

Now, there was a time in our profession when we thought about specs that way. That era was already coming to an end thirty years ago. It’s what gave rise to the Agile Manifesto, and regardless what you think about “Agile,” the Manifesto’s assertion that working software is to be valued over comprehensive documentation is not longer a matter of serious debate. Spec-driven development is not a return to the early 90s, because that kind of spec is something that essentially no one wants to return to. I am legitimately curious whether anyone offering that criticism has actually applied the practice in anger.

OpenSpecs “specs” are lightweight guardrails that help organize my thinking throughout an agentic workflow. In the case of the simplest specs I’ve proposed, I actually have gotten a solid design and spec on my first try, and sometimes I’ve even gotten a working implementation in one shot. Just as often, my proposal has been ambiguous and incompletely thought-out, and my interaction with the spec workflow (usually OpenSpec’s explore command) has led me to consider tradeoffs I didn’t see at first, helped correct assumptions that were not explicit in my original prompt, and generally kept me focused on delivering a particular feature I wanted to deliver.

In its normal state, SDD is a very lightweight, iterative process. Critiques of it that compare it to 20th century methods are, in my view, not terribly well-informed. More about this soon…