Spec-driven development doesn’t kill ambiguity

If you’ve worked in software development long enough, you’ve probably encountered spec-driven development pitched as the answer to ambiguity. Get the requirements right, document them precisely, then hand them to your developers (or, increasingly, to your AI agents) and watch the code materialise. It sounds professional. It sounds rigorous. It sounds like the kind of thing that should work.

It also sounds like it would speed things up. But here’s what actually happens.

The work doesn’t disappear, it moves

A colleague approached recently, asking for tips on implementing spec-driven development with a client team. The conversation quickly surfaced the real friction. Spec-driven development promises to accelerate delivery by pinning down requirements upfront. The theory goes: no ambiguity in the spec means no wasted development cycles.

Except the benefit doesn’t materialise as it’s sold. What actually happens is a redistribution of labour, not a reduction of it. The friction that used to surface in code review now surfaces earlier, in the documentation cycle. You’ve swapped debugging miscommunication for writing a specification detailed enough that a developer, or an LLM, can follow it without wandering off into the weeds.

The frustration is understandable. You haven’t sped up delivery, you’ve just moved the problem. You now have a team writing pedantic requirements documentation instead of teams shipping incrementally and learning from what breaks.

The cost stays roughly the same. It just gets invoiced differently.

The impossible balance

Here’s where spec-driven development gets really tricky. A good specification has to walk a knife-edge between two contradictory requirements.

First, it needs to be clear enough that someone else can follow it reliably. If the spec is vague, a developer or an AI model will fill the gaps with their own assumptions. You’re back to ambiguity, just relocated to a later stage.

But second, the spec has to be loose enough to allow judgment. If you over-specify, you create brittleness, locking in assumptions about implementation details that won’t age well. You’ve also, paradoxically, created more work for the person following the spec, because they now have to parse not just what you wanted but why you wanted it that specific way.

In practice, this balance is nearly impossible to strike. Specs either under-specify, so the agent or developer wanders, or over-specify, and become documentation nobody quite trusts. Most teams end up somewhere in the middle, which means there’s still ambiguity, you’ve just codified it into a document that needs its own review cycle.

It sells certainty it doesn’t deliver

The appeal of spec-driven development is largely psychological. The name carries authority. It suggests rigour, professional discipline, and control. It sounds like it should eliminate surprises.

But what you’re actually buying is the appearance of certainty, not certainty itself. You’ve moved ambiguity out of the developer-to-product-owner conversation and into a document, where it becomes someone else’s job to decode.

This matters because false certainty is dangerous. If your team believes the spec has eliminated ambiguity when it hasn’t, you end up with discovery late. In testing, or in production, or when your AI-generated code doesn’t quite do what you meant it to do.

What actually works (and it’s more complicated)

None of this is to say that thinking hard about requirements is a waste of time. Quite the opposite, in fact. The issue is that spec-driven development implies a neat, linear process that doesn’t reflect how software actually gets built.

A more robust approach looks something like this:

Build a research corpus. Start by gathering and organising everything you know about the problem space: domain knowledge, similar solutions, patterns, constraints. This corpus becomes your reference point. It also self-improves. As you learn, the corpus grows.

Write behaviour-driven development scenarios. Define the actual behaviour you want in fine-grained detail using scenarios. BDD makes the spec testable from the start. It also forces specificity without brittle over-specification. You’re describing what the system does, not how to build it.

Map tickets to scenarios, grouped in epics. Each scenario translates into tasks. Epics contain goals that build against the specification. The goal of completing an epic is to fully satisfy the set of scenarios it contains.

Use TDD within each epic. Write the tests first, then code to pass them. This isn’t just a code quality habit. It’s a way of catching ambiguity before it becomes a bigger problem.

The discipline here is iterative, not one-and-done. You’re not writing a spec once and handing it off, you’re continuously refining your understanding of what ‘good’ looks like, and continuously checking whether the code actually meets it.

Why this matters with AI in the loop

The temptation to lean harder on spec-driven development is only going to grow as more teams put autonomous agents into the delivery pipeline. The thinking goes: if I specify the requirements precisely enough, I can prompt an LLM to generate reliable code.

It doesn’t quite work that way. LLMs, and developers, can follow a spec closely, but they can also get lost in it. They can miss the signal in the noise of over-specification, and they can make assumptions about under-specified requirements that are different from your own assumptions.

The balance between describing the thing you want clearly and describing it so tightly that the model gets constrained or confused is real. It’s also not a technical problem to be solved once and delegated. It’s a judgement problem that lives in conversation between the people who want the thing and the people building it.

A better question than “is the spec good enough?”

If you’re currently committed to spec-driven development and it’s not delivering, the move isn’t to abandon written requirements. It’s to stop treating the specification as the endpoint, and start treating it as the start of a conversation.

Ask your team: are we writing specs to avoid ambiguity, or to avoid having difficult conversations? If it’s the latter, you’ve probably over-specced, and codified assumptions that should have been questioned earlier.

Ask yourself: is this level of specification detail a guardrail, or a cage? Guardrails keep people from going off a cliff. Cages keep people from going anywhere interesting.

And most importantly: accept that getting this balance right is difficult, and requires judgement from people who understand both the problem space and the implementation space. There’s no format or framework that eliminates that conversation. Spec-driven development markets itself as an alternative to judgment. The honest truth is it’s just a different place where judgment gets tested.

—

If your team is caught between the appeal of spec-driven development and the messiness of real delivery, Waracle works with organisations building ambitious software in regulated sectors. We’ve helped teams navigate this balance across healthcare, financial services, and complex engineering domains. Get in touch if you’d like to talk through what good looks like for your context.