Be Agile, Write Specs

A real text I got from a product-leader friend of mine yesterday:

Do you think spec-driven dev is waterfall?

He’s not the only one asking. The question has been working its way through the whole field this year — Martin Fowler and Kent Beck have weighed in , and a Hacker News post titled “Spec-Driven Development: The Waterfall Strikes Back”  pulled almost two hundred comments.

“Is this agile” debates always draw a lot of fire, and they’re often full of people assertively talking past each other from increasingly specific postures about what “real agile”  means. I think that’s part of what’s happening here; “is AI encouraging practitioners to develop in a more waterfall-like style?” is a valid question, but it’s mostly unrelated to whether you write down what the software does.

Waterfall vs. agile, simplified

Let’s start with an actually useful description of the distinction everyone’s arguing about. Strip away all the surface-level process differences that vary among companies and methodologies, and we’re mostly left with two things.

The first is batch size — how much work travels together before anyone gets to see the result. Waterfall moves in big batches: as big as a whole product, specified, then built, then tested, each stage finishing before the next begins. Lean and agile move in small ones: typically the littlest chunk that still draws meaningful feedback.

The second is phase gates — waterfall is characterized by strict “until step 1 is complete, step 2 cannot begin” discipline, often in the form of handoffs between roles. Agile collaborates across phases and functions, refining previous work as it goes.

If you’re shipping in small batches and the roles that handoffs used to separate (product, engineering, test) are working together throughout, it’s hard to argue you’re doing waterfall. If you’re shipping in big batches with hard handoffs between phases, it’s hard to argue you’re not.

Notice what isn’t on that list: whether you wrote down what the software does.

The spec is a different axis

You can write a spec in one giant up-front batch and freeze it, or you can write a small one and revise it every afternoon. You can throw it over a wall and walk away, or you can build it alongside the people — and agents — who’ll implement it. A spec is perfectly compatible with small batches and tight collaboration. Arguably it’s more at home there.

So “do you write a spec?” is simply a different question from “are you doing waterfall?” The two are independent. Spec-driven development inherits whatever batch size and collaboration discipline you bring to it; nothing about writing down what you intend to build forces the big-batch, over-the-wall version on you.

Why it keeps getting called waterfall

So uh, why all the arguing? Because people are noticing two things happening:

The first: small-batch discipline is legitimately harder with AI in the loop. Lovable will build you an entire app from a single sentence. That it can doesn’t mean it should — but the temptation to point an agent at an enormous batch and let it run is right there every time, in a way it never was when a human had to type all the code. The wrong response to that temptation is to write an enormous specification before the agent touches anything, because that just moves the big batch upstream and calls it planning. The right response is what it’s always been: decompose. “Agentic coding makes big batches easy” is an argument for decomposition, not against writing down your intent.

The second: a spec works far better as a collaboration artifact than as a handoff artifact, and a lot of spec-driven tooling assumes the latter. The BDD people worked this out fifteen years ago, and they were right about the part that matters: the goal was never the document, it was the shared understanding. Writing the spec down confirms that understanding exists — it doesn’t create it. The understanding gets created in conversations.

Unfortunately, there really are spec-driven frameworks shaped to push you toward big up-front specs and clean handoffs to an agent. (This makes commercial sense: “just tell AI what you want and it will auto-magically go build it” is a compelling pitch.) If that’s the version you’ve seen, “isn’t this just waterfall?” is a fair thing to say. It doesn’t have to be that way, though. (Yuval Yeret  is good on this — it’s only waterfall if you use it that way.)

Don’t be afraid to improvise

This whole conversation surfaces anxiety about the best way to sequence development work. The question, “if you have to write a spec first, isn’t that waterfall?” invokes a sequencing opinion: write the spec, write the code, write the tests.

But agile rejects the premise of a fixed, inflexible order of operations. What that means for spec-driven development is, if you want to prototype, spec, test, and build in one delicious, collaborative smoothie, a small batch at a time, with your customers tasting as you go — do that. Spec-code-test is also a fine way to make software. So is TDD first, then a prototype, then show it to someone, then revise the tests and the code, then write down what you built. The best order is probably different from one slice to the next, depending on what you need to learn when.

And AI doesn’t change that. It’ll code from a spec. It’ll iterate from a prototype. It thrives with TDD. And it makes executing and building upon each of those steps inexpensive enough that you can mix-and-match without guilt or even much patience.

The only things that have ever kept teams agile are a shared understanding of what their customers need and batches small enough to keep that understanding from going stale. Most of what’s being argued about is a question of whether new tooling changes that behavior, dressed up as a question of methodology.

So is AI nudging teams toward waterfall? Honestly, sometimes, yeah. Not by making anyone write a spec, but by making enormous batches appear effortless and letting one-shot agentic handoffs feel irresistible. Those temptations are amplified by the central, tantalizing promise of AI-driven development: that all you have to do is ask for what you want, and an LLM will build it for you. But it runs headlong, at agentic speed, into agile’s original question: how can you know what you want if you haven’t built anything or shown it to anyone yet?

Build. Incrementally. Write down what it does — before, during, or (soon) after. The spec doesn’t change your agile posture. The discipline that keeps you grounded and moving fast is the same as it’s always been.

“Write down what it does” is easy to say and hard to keep true. That’s what we built dot•requirements  for: requirements that live with the code, stay legible to humans and agents alike, and get checked against reality every time the tests run — so what you wrote down still matches what you shipped.