Is Spec-Driven Development Just Waterfall in Disguise?

There is a fair question people are starting to ask:

Is Spec-Driven Development just waterfall coming back with an AI badge on it?

At first glance, the suspicion makes sense.

Spec-Driven Development says: before writing code, define the intent, behaviour, constraints, scenarios, and acceptance criteria. Then let the team - and increasingly AI agents - use that specification to generate code, tests, tasks, and implementation plans.

For people who lived through heavy requirement documents, long analysis phases, sign-off ceremonies, and “change requests” for every small learning, this can sound uncomfortably familiar.

A big spec before coding? A document as the source of truth? Implementation following a pre-written plan?

That does sound like waterfall - if we stop thinking there.

But the real question is not whether a spec exists before code. The real question is what kind of relationship the team has with the spec.

That is where the difference lives.

Waterfall treats the spec as a contract

In waterfall thinking, the spec often becomes a contract. Someone writes it. Someone approves it. Someone else builds it. Change becomes expensive, politically awkward, or treated as a failure of planning.

The document becomes a control mechanism.

It says: “This is what we agreed. Now execute.”

That is the dangerous version of Spec-Driven Development. If SDD becomes a way for managers, product people, or architects to hand down detailed instructions to developers and AI agents, then yes - it is waterfall with better tooling.

Actually, it may be worse.

Because AI can produce code very quickly. A bad spec no longer creates slow failure. It creates fast failure. The team can generate an impressive amount of technically valid but strategically wrong software.

That is not agility. That is automated waste.

Agile was never against clarity

A lot of people misunderstand Agile as if it means: “Don’t write things down. Just start coding and adapt later.”

That was never the point.

The Agile Manifesto values “working software over comprehensive documentation”. It does not say documentation has no value. It says working software has more value than documentation when the two are in conflict.

The same is true for “responding to change over following a plan”. It does not mean plans are useless. It means the plan must not become more important than what we learn.

This distinction matters.

• Agile is not anti-spec.
• Agile is anti-frozen-spec.
• Agile is not anti-documentation.
• Agile is anti-documentation that replaces conversation, feedback, and learning.

A good user story is already a small spec. Acceptance criteria are specs. Examples are specs. API contracts are specs. Definition of Done is a spec. Design principles, non-functional requirements, security constraints, service boundaries - all of these are forms of specification.

So the idea of specifying before building is not against Agile. The problem starts when specification becomes a phase instead of a living conversation.

AI changes the economics of ambiguity

Before AI, ambiguity was already expensive. Teams built the wrong thing, misunderstood edge cases, missed constraints, or discovered late that the solution did not match the real user need.

But with AI, ambiguity becomes even more dangerous.

AI does not get tired. It does not pause and say, “Hang on, are we sure this is the right problem?” unless we design the workflow to make that happen. It will happily turn vague intent into confident output.

That is why SDD is becoming more important.

When an AI coding agent is involved, the spec is not just documentation for humans. It becomes the context that shapes the machine’s work. It tells the agent what matters, what must not be violated, what “done” means, and what trade-offs are acceptable.

In a human-only team, a lot of context lives in conversation, memory, culture, and informal judgement. That is already fragile. With AI agents, it becomes even more fragile because the agent does not share the team’s history unless we make the context explicit.

So SDD is partly a response to a new reality:

If AI is going to write more of the code, humans need to become much better at expressing intent.

That is not waterfall. That is a shift in where human judgement matters most.

The problem is not “spec first”. The problem is “learning last”.

A spec before code is not automatically waterfall.

The real waterfall smell is not the existence of a spec. It is the absence of feedback loops.

If the team writes a spec, disappears for three months, builds everything, and then discovers whether it works, that is waterfall.

If the team writes a spec, uses it to align quickly, builds a thin slice, tests assumptions, updates the spec, and continues learning, that can be deeply Agile.

The order is less important than the loop.

A healthy SDD loop might look like this:

Start with intent. Write the smallest useful spec. Generate or build a thin slice. Test it against reality. Learn what was wrong or missing. Update the spec. Continue.

That is not “big design up front”. That is “clear thinking before fast execution”.

And in an AI-native world, that difference matters.

A good spec should reduce control, not increase it

This may sound strange, but a good spec should not be used to micromanage the team.

A good spec gives people and AI agents enough clarity to move independently without constantly asking for permission.

It should answer questions like:

What problem are we solving? Who are we solving it for? What behaviour matters? What are the important edge cases? What must never happen? What trade-offs are acceptable? How will we know it works? What is outside the scope for now?

That kind of spec does not kill agility. It enables it.

The team can move faster because they are not guessing. Developers can make better local decisions. AI agents can generate more relevant code. Testers can challenge the right behaviours. Product people can see whether the implementation still matches the intent.

The spec becomes shared context, not a command-and-control document.

The Agile risk: specs can become a hiding place

There is still a real danger.

Some teams will use SDD to avoid hard conversations. They will spend too much time polishing the spec because it feels safer than putting working software in front of users. They will confuse completeness with understanding. They will create impressive documents that nobody challenges. They will ask AI to generate delivery plans from assumptions that were never validated.

That is where SDD becomes anti-Agile.

Not because it has documentation.

Because it delays contact with reality.

The moment a spec becomes a substitute for user feedback, it has gone wrong. The moment the team protects the spec from learning, it has gone wrong. The moment people say, “That is not what the spec says,” instead of asking, “What have we learned?”, the spec has become a trap.

Agile teams should be especially alert to this.

A spec should be strong enough to guide action, but weak enough to be changed by evidence.

The better question: what should remain human?

The deeper issue behind SDD is not process. It is responsibility.

If AI can write code, generate tests, produce documentation, refactor systems, and even propose architecture, what is left for humans?

The answer is not “nothing”.

The human work moves upstream and outward.

Humans are responsible for judgement. For deciding what matters. For understanding the user’s world. For spotting ethical, commercial, operational, and organisational consequences. For asking whether the solution is worth building at all.

AI can produce output. Humans must protect intent.

That is why Spec-Driven Development is interesting. Not because it gives us another methodology, but because it forces a serious question:

Can we express what we want clearly enough for humans and machines to build the right thing together?

Many teams cannot. Not yet.

They have backlogs full of vague tickets. User stories that describe UI changes, not user outcomes. Acceptance criteria that are either missing or mechanical. Technical constraints trapped in people’s heads. Product decisions scattered across Slack, Jira, Figma, meetings, and memory.

In that environment, adding AI does not magically create leverage. It amplifies the mess.

SDD is one possible response to that mess.

So, is SDD against Agile principles?

No - not if it is done well.

Spec-Driven Development is against Agile only when:

• The spec becomes a fixed contract.
• Documentation replaces conversation.
• Planning replaces feedback.
• AI output replaces product judgement.
• The team optimises for compliance with the spec rather than learning from users.

But SDD can support Agile when:

• The spec is lightweight enough to change.
• It captures shared understanding.
• It makes assumptions visible.
• It connects intent to tests and working software.
• It helps the team learn faster.
• It gives AI agents better context without removing human judgement.

The difference is not in the word “spec”. The difference is in the mindset.

The mature view

Spec-Driven Development is not a return to waterfall.

But it is a warning.

It reminds us that speed has changed. AI can now produce software faster than many organisations can think clearly. That creates a new bottleneck. The bottleneck is no longer only coding capacity. It is clarity of intent.

For Agile practitioners, this should feel familiar. We have always cared about shared understanding, feedback, working software, and adapting to change. SDD does not replace those ideas. At its best, it updates them for a world where AI agents are becoming part of the delivery system.

The future will not belong to teams that write the longest specs.

It will belong to teams that can turn real human needs into clear, testable, adaptable intent - and then learn quickly when reality disagrees.

So maybe the right answer is this:

Spec-Driven Development is waterfall if the spec is used to stop change. It is Agile if the spec is used to make learning faster.