Spec-Driven Development vs Waterfall for AI Agents

Spec-Driven Development vs Waterfall for AI Agents

Spec-driven development is being pitched as the cure for vibe coding: write a detailed spec, get everyone to agree on it, and only then let an agent generate code against it as the single source of truth. The misconception, repeated in every Hacker News thread I've read on the subject, is that this is just Waterfall wearing a YAML hat. It isn't. But it also isn't as different as the vendors pitching it want you to believe.

IBM, GitHub, and Amazon are all pushing the same idea right now, and the timing is not an accident. The forcing function is agentic AI. When a human writes code, a loose prompt and a few iterations are fine. When an autonomous agent writes thousands of lines across a session it doesn't fully remember, ambiguity compounds into technical debt faster than any human could produce it. A spec is the control surface. The question nobody in those vendor explainers answers is what happens when the thing reading the spec is also the thing that wrote it.

What Is Spec-Driven Development?

Spec-driven development (SDD) is a methodology in which a detailed specification of implementation details is written and agreed upon before development begins, serving as what Anna Gutowska of IBM Think calls "a single source of truth for what to build and how to build it." The cleanest mental model: the agent treats the spec the way a compiler treats source. You don't argue with the output; you fix the input and recompile.

That's the snippet-length version. The interesting part is why this is happening now rather than five years ago.

The economics changed. Running an agent through a multi-step plan, generating code, running tests, and regenerating on failure used to be prohibitively expensive in tokens. Not anymore. I maintain the LLM price tracker on this site, and the thing raw per-token numbers hide is that spec-driven loops lean heavily on cache hits and retries. Price a workload by its sticker rate and you'll misjudge SDD's real cost by a wide margin. Once a full plan-generate-verify cycle costs cents instead of dollars, writing the spec up front stops being overhead and starts being the cheapest insurance you can buy against AI coding rework.

A spec is only a contract if something fails when the code drifts from it. Everything else is documentation nobody reads.

Gutowska names two failure modes specific to agent-generated code without a spec: context drift, where a fix in one area silently breaks functionality elsewhere, and fragmentation, where new agent-written features ignore the conventions already in the codebase. Both are symptoms of the same root cause. The agent has no durable contract to check itself against. SDD supplies one.

Spec-Driven Development vs. Waterfall: Not the Same Stage Gates

Here's the comparison none of the three leading explainers will make, because naming Waterfall makes SDD sound less novel. IBM's 2,145-word piece, published May 19, 2026, never says the word. Neither does GitHub's blog or Kiro's docs. So let's make it.

Waterfall's defining feature was never the spec. It was the sign-off. Requirements froze, stakeholders approved, and engineers were contractually downstream of a document they could not change without a change request. The spec was a governance artifact as much as a technical one.

SDD inverts this. In Spec Kit and Kiro, the spec is a living file edited mid-build, and in most agentic workflows the same model that will implement the feature also drafts and refines the spec. That's a genuine philosophical inversion, and it answers one of the sharpest questions skeptics ask: can AI agents write their own specs? Yes, and that's precisely the part that breaks the Waterfall analogy. There's no independent party standing between "what we agreed" and "what got built." The compiler is also writing the source. If you've worked in a regulated shop, that should make the hair on your neck stand up. I've written before about how plan-and-review workflows try to reinsert a human at exactly this gate.

The Spec Workflow: Requirements, Design, and Tasks

Amazon's Kiro IDE operationalizes SDD into three mandatory artifacts per feature, and this three-part shape has become the de facto standard across tools. First, requirements: user stories plus acceptance criteria, usually in a structured format. Second, a design doc with architecture notes and sequence diagrams. Third, a task list of trackable, individually verifiable implementation steps.

These run through a three-phase workflow, and Kiro supports optional parallel task execution so independent tasks can be built concurrently rather than one agent plodding through a queue.

The requirements-design-tasks split matters more than it looks. It forces the agent to commit to what and how before touching do, which is the entire point. An agent that jumps straight to tasks produces the fragmentation Gutowska warns about. The design doc is where architectural conventions get pinned down, and skipping it is how you end up with eight slightly different ways to handle errors in one repo. If you've watched an AI coding assistant repeat the same mistakes, a missing or thin design artifact is usually why.

The honest tradeoff: this adds latency. Does spec-driven development slow down AI coding agents? For a throwaway script, yes, and noticeably. For anything you intend to maintain, the up-front cost is recovered the first time the agent would otherwise have rewritten a module it misunderstood.

Spec-First vs. Spec-Anchored vs. Spec-as-Source

IBM frames specification work as a spectrum, not a binary, and this is the framing most worth stealing. The difference between the modes is how tightly the generated code must trace back to the written spec.

• Spec-first: You write the spec, the agent builds from it once, then the code and spec diverge like any normal project. The spec is a starting gun.
• Spec-anchored: The spec stays authoritative. Code changes are expected to trace back to a spec change, and drift between them is treated as a defect.
• Spec-as-source: The extreme. The spec is the program. You don't edit code; you edit the spec and recompile.

The gap between spec-first and spec-as-source is the gap between a blueprint you consult once and a blueprint the building regenerates itself from every morning. Tomas Vesely, an engineer at GitHub, demonstrated the spec-as-source extreme by writing an entire application as Markdown files and having Copilot compile the Markdown directly into Go. He reported cleaner specs and faster iteration than prompt-by-prompt vibe coding.

Most teams should live in spec-anchored territory. Spec-as-source is seductive and real, but it bets your entire codebase on the spec language being expressive enough to capture everything that matters, and it rarely is at the edges.

In Practice: GitHub Spec Kit, Kiro, and Copilot

Spec-driven development is having a genuine platform moment, and the adoption numbers back it up rather than just the press releases. GitHub's open-source Spec Kit has grown to 149,116 stars and 13,391 forks since launching on August 21, 2025, reaching release v1.3.3 on November 9, 2026, roughly 14 months after launch. That's a steep curve for a dev-process tool, and it's a harder adoption signal than any of these vendors cite about their own products.

Spec Kit gives AI agents a structured process layered on top of whatever model you're using, Copilot included, and leans on Markdown as the spec format. Kiro takes the opposite posture: the spec structure is baked into a dedicated IDE, with the requirements-design-tasks artifacts as first-class objects. The difference comes down to whether you want a portable toolkit or an opinionated environment.

Here's IBM Technology's explainer if you want the vendor framing in motion:

The freshest wrinkle is scope creep, in a good way. Kiro's own engineering team has started extending specs past functional correctness into security. A post dated October 30, 2026 by Rajdeep Mukherjee titled "Spec it safe" frames writing security requirements directly into the spec as a shift-left practice for agent-built software. That's SDD quietly absorbing the compliance-traceability job Waterfall's heavyweight docs used to own. This resonates with something I learned the hard way building a SOC 2 scaffolding CLI at Rise People: compliance baked into the scaffold beats compliance reviewed at PR time, every single time. A security requirement the agent reads on every run is worth ten it gets reminded about in review. If you care about AI security, this is the part of SDD to watch.

Where Spec-Driven Development Breaks With Real Agents

Now the part the vendor explainers skip entirely. SDD was conceived with a human reading the spec. Hand it to an autonomous agent and new failure modes appear.

Context-reset spec drift. A long-running agent that compacts or resets its context re-reads its own spec and can reinterpret ambiguous acceptance criteria differently than it did on the first pass. This isn't classic Waterfall spec rot, where a stale doc drifts from live code over months. This happens within a single build, because the reader changed its mind between sessions. The spec didn't drift. The interpreter did.

Ambiguous acceptance criteria. A human reads "handle errors gracefully" and applies judgment. An agent reads it and does something plausible but possibly wrong, and does it with total confidence. Every soft phrase in a spec is a coin flip the agent will resolve without telling you. The fix is brutal specificity, which pushes you toward the next trap.

Cross-surface tooling gaps. Spec tooling maturity is still fragmented across agent surfaces. Per Kiro's own documentation, property-based "Correctness" testing is IDE-only, not available in the CLI, Web, or Mobile clients. "Analyze Requirements" is available in the IDE and the CLI, but still not on Web or Mobile. So the depth of spec enforcement you get depends on which client you happen to be in, and a spec that's rigorously verified in the IDE is a weaker contract the moment you move to another surface. This is the kind of gap that bites teams after rollout, exactly the pattern that surfaces during broader team adoption of AI coding tools.

None of these are reasons to skip SDD. They're reasons to treat the spec as a thing you test, not a thing you trust.

The Over-Engineering and Spec-Maintenance Trap

IBM names the over-engineering trap directly, and it's real: given a spec to satisfy, an agent will happily gold-plate, adding abstraction and configurability nobody asked for because the spec didn't explicitly forbid it.

The subtler trap is maintenance burden. A spec detailed enough to eliminate ambiguity for an agent can grow longer and harder to maintain than the code it describes. When your spec maintenance exceeds your code maintenance, you've recreated Waterfall's documentation overhead with none of the sign-off discipline that justified it. The worst of both worlds.

The rule of thumb that holds across agentic AI workflows: specify intent and invariants, not implementation. Pin down the acceptance criteria, the architectural conventions, and the things that must never happen. Leave the rest to the agent and catch mistakes in review. A spec that tries to describe every line is just slower code.

Getting Started With a Real Example

Want to try spec-driven development for AI coding agents without buying into a whole IDE? Start minimal and spec-anchored:

1. Pick one feature small enough to finish in a session but real enough to have edge cases.
2. Write a requirements file: three to five user stories, each with explicit, testable acceptance criteria. No soft verbs.
3. Write a one-page design note naming the files, the data flow, and the conventions to follow.
4. Break it into a task list where each task is independently verifiable.
5. Let the agent build task by task, and after any context reset, make it re-state its understanding of the acceptance criteria before continuing.
6. Treat every divergence between code and spec as a bug in one of them, and decide which.

That last step is where spec-anchored discipline lives. It's also where you'll find most of your ambiguous criteria, because the agent will interpret them in ways you didn't intend. Tools like Claude Code and Spec Kit make the mechanics easy; the judgment about what to pin down and what to leave open is still yours.

The bet I'd make: within a year, the sign-off problem gets solved not by a human reapproving specs but by a second, independent agent whose only job is to verify the implementing agent against the spec it was given. That's the piece Waterfall had and SDD threw away, and it's the piece the tooling will quietly rebuild. The methodology isn't new. The reader is. Build for the reader you actually have.

Photo by Nangialai Stoman on Unsplash.