Spec-Driven Development: It Looks Like Waterfall (And I Feel Fine)

We’ve been talking a lot about agentic engineering, how software is now getting built with AI. As I look to see how design can complement this new development paradigm, a newish methodology called spec-driven development caught my eye. The idea is straightforward: you write a detailed specification first, then AI agents generate the code from it. The specification becomes the source of truth, not the code.

My first reaction when I started reading about SDD was: wait, isn’t this just waterfall?

Seriously. You gather requirements. You write them down in a structured document. You hand that document to someone (or something) that builds to spec. That’s the waterfall pattern. We spent two decades running away from it, and now it’s back wearing a blue Patagonia vest and calling itself a methodology.

The Speed Changes Everything

But there is a difference.

In classic waterfall, the cost of building was so high that you had to get the specs right the first time. Six months of requirements gathering, six months of development, then you find out your assumptions were wrong. That’s why agile won. Shorter cycles. Faster feedback. Accept that you’ll be wrong and course-correct quickly.

Spec-driven development keeps the “write a spec” part of waterfall but compresses the build cycle from months to minutes. You write a tight spec. An AI agent generates the implementation. You evaluate it. You revise. You regenerate. The whole loop might take an afternoon.

That’s not waterfall. That’s agile wearing a trench coat.

Early adopters are already testing this. One developer documented building a transit-tracking web app using SDD: around 6,000 lines of code, eight features, roughly three days from spec to deploy. Two weeks later he came back and added new features without re-learning the codebase. He credits the specs.

ThoughtWorks frames SDD as a synthesis of older ideas: mathematical verification, API contracts, test-driven development, generating code from models. All adapted to an AI toolchain where agents can execute specs directly. Martin Fowler’s team has been exploring the tooling around this, identifying three patterns: spec-first (the spec guides AI but code stays primary), spec-anchored (the spec persists as a governing contract), and spec-as-source (the spec is the source, code is disposable). That last one is the most radical. Code as a regenerable byproduct. Something you throw away and rebuild from the spec whenever requirements shift.

When execution is fast and cheap, the spec-then-build loop stops being a liability. You get the clarity of upfront thinking without the rigidity of committing to a plan you can’t afford to change.

So Where Does Design Fit?

In most traditional workflows, design lives in its own silo. Designers make mockups in Figma, hand them off, and hope the implementation matches. In agile shops, designers embedded with sprint teams do better, but the fundamental pattern is the same: design produces artifacts that developers interpret.

SDD changes this. GitHub’s spec-driven development toolkit captures user journeys, UX goals, and interaction patterns before any technical plan or code gets generated. Tools like Spec Kit Pro go further, embedding user flow diagrams, information architecture, and component hierarchies directly into the document as machine-readable contracts.

Design stops being a separate phase. It becomes part of the specification. In practice, a spec is usually a structured Markdown file (or a set of them) that lives in the same repo as the code. It reads like detailed acceptance criteria: who the user is, what they’re trying to do, what happens at each step, and how success is measured.

Designers co-author the spec. They’re the ones saying “here’s what the user should experience,” and that description becomes the thing AI agents and engineers build against. The InfoQ writeup on SDD describes plugging your design system (tokens, components, accessibility rules) into the spec so agents generate UI that conforms to the system by construction, not via manual pixel-pushing after the fact.

Instead of designers polishing at the end, they’re drawing the boundaries at the beginning. The spec becomes the arbiter when behavior and design drift apart.

What This Actually Demands of Designers

There’s a catch, and it’s a big one. For design to live inside the specification, the ask is for designers to think structurally. You can’t encode “make it feel premium” into a machine-readable specification. You can encode user flows, interaction states, component hierarchies, edge cases, and success criteria.

The idea is that designers structure design intent as documented behaviors and constraints that can be version-controlled, reviewed in pull requests, and treated with the same rigor as code. That’s a long way from dragging rectangles in Figma. It’s closer to how developers think, and that’s the point.

I don’t think this kills Figma. You still need to explore and iterate visually, and mockups can accompany the spec as reference. But the mockup isn’t the deliverable anymore. The output of that visual exploration needs to be translatable into spec language.

Here’s an example: You design a checkout flow in Figma. The annotation says “show error state if payment fails.” That’s testable, but it leaves room for interpretation. Which error state? Where does it appear? What happens to the form data? The spec version closes those gaps: “If payment fails, the user stays on the payment step. Their form data is preserved. An error message appears above the card fields explaining what went wrong. The submit button re-enables so they can retry.” Same intent, less guesswork. What you’re really doing is moving your annotations out of Figma and into the spec, where they stop being suggestions and start being enforceable. If you can’t express your design intent in terms a system can enforce, you’re back to tossing mockups over the wall and hoping for the best.

The Waterfall That Isn’t

So yes, spec-driven development looks like waterfall if you squint. Spec first, build second. But the cycle time has collapsed from months to minutes, and that collapse changes everything. You’re not betting the farm on a single document. You’re writing disposable specifications, evaluating results, and iterating. That’s the agile feedback loop with better documentation.

And for designers, the promise is real: design decisions encoded in the spec have teeth. They’re not suggestions that get lost in translation between Figma and code. If the implementation drifts from the spec, the build can fail. That’s more power than a red-line annotation in Figma ever had.

To be clear, this is still early. Most of the experience reports are solo developers on greenfield projects. One developer found that specs ate 50% of his total project time and eventually moved away from pure SDD as he scaled up. The evidence thins fast for team-based work and large codebases. But the direction is interesting, and the feedback loops are only getting faster.