Spec-Driven Development
Transcript
Made automatically from the video's sound, so it may contain mistakes. Click a line to play from there.
Welcome back to the Explainer series. Today we're unpacking spec-driven development in the AI era. Look, if you've been following our journey from agile to AI-native ways of working, you already know AI coding agents have completely flipped the script on how we build software.
But today, we're cutting through all that vendor hype. We want to see how engineers are actually steering these agents in the real world. Right, here's our roadmap for today. We're covering beyond vibe coding, the evolution of specifications, the AI spec-to-code loop, harnesses and living specs, and finally avoiding the waterfall trap.
Let's get straight into it. Beyond vibe coding, moving past those unpredictable AI experiments. To kick things off, let's anchor ourselves in what we learned in our previous explainer.
We know, thanks to hard data from Dora Metrics, that small batch, trunk-based CICD is the absolute foundation of fast, safe delivery. It is our safety net. But when we just throw a vague prompt at an AI, you know that thing people are calling vibe coding, we completely bypass that rigor.
We're essentially asking a language model to blind guess thousands of unstated requirements, and frankly, that is a recipe for disaster. It perfectly illustrates this brilliant insight from Fred Brooks in The Mythical Man Month.
He said the hardest single part of building a software system is deciding precisely what to build. This is exactly why just telling an AI to build an app falls flat on its face. Specifying the essential complexity, all those weird little edge cases, is a step we simply cannot skip.
Large language models, they are incredible at pattern completion, but they are absolutely rubbish at mind reading. If we don't specify the intent clearly, the AI just makes assumptions. And trust me, a lot of them will be dead wrong.
The evolution of specifications, going from static docs to executable contracts. So, how do we actually fix this mind-reading problem? Well, we need to completely rethink what a specification is. Forget about those massive static documents that gather dust the second coding begins.
A modern spec is an active living artifact. It's structured, it's behavior-oriented, and it's written in natural language, specifically to serve as direct guidance for AI agents. It doesn't just suggest how to implement something, it literally generates it.
Think about your own day-to-day workflow. Specifications really sit on a spectrum, don't they? On the left-hand side, we've got pragmatic human alignment documents. Think Google Design Docs or Michael Nygard's architecture decision records.
They're brilliant for getting the team on the same page. Then, way over on the far right, we have rigorous machine contracts, like OpenAPI schemas or Leslie Lamport's TLA plus state invariants. Those are built purely for automated verification.
No human fuzziness allowed. But what bridges that gap? That's where executable behavioural examples come in. This is the sweet spot where your documentation actually runs against the system to automatically check the behavior.
We're talking about things like Martin Fowler's specification by example, behavior-driven development, cucumber tests, and hypothesis property-based invariants. These are magic because they double as both human-readable requirements and machine-enforceable tests.
For an AI coding agent, this is the absolute perfect foundation. The AI spec to code loop, and structuring the agent workflow. Let's look at how this plays out in an actual repeatable daily workflow, using practitioner playbooks and tools like GitHub Spec Kit, or Anthropics Clawed.
Instead of treating AI like some glorified search engine, we use a very structured loop. First up, you specify. You lay out the high-level goals.
Second, you plan, providing strict architectural constraints. Third, you force the agent to break that plan into small, verifiable tasks, and only then, finally, you implement. By the time the agent actually starts writing code, it knows exactly what the rules of the game are.
And this is just such a stark contrast to the absolute chaos of vibe coding. With vibe coding, you're getting these massive, completely unverified code dumps based on what the AI guessed you wanted. But with spec-driven development, you've got clear intent, executable plans, and micro-tasks that a human can actually review.
The whole power structure is inverted here. The code serves the specification, not the other way around. Harnesses and living specs, choosing verification over vibes. Okay, so to make sure the AI doesn't just hallucinate our entire application into the ground, we have to talk about harness engineering.
Engineering leader Addy Osmani outlines this concept of an agent harness anatomy. Think of it like a set of reins for a powerful but totally blind beast. You set explicit constraints right inside the repository. You give it goals, and crucially explicit non-goals.
You define the system interfaces, and you use repository checklists, like adding a clawed.md or an agents.md file. This feeds the AI the exact context it needs without cluttering up your normal files.
But the absolute most important part of that harness, testing. Developer Simon Willison has a great rule for this. You must never, ever accept AI-generated code on faith. You have to force the agent to use red-green test-driven development.
You explicitly prompt the agent to write a failing test first, that's the red phase, and then, and only then, write the implementation to pass it, the green phase. This physically prevents the agent from hallucinating a fake green pass on code that doesn't actually work.
Bergita Becker from ThoughtWorks breaks this down beautifully into two types of controls. You blend feed-forward context, so your spec prompts and coding conventions with immediate feedback sensors.
We're talking structural tests, strict linters, and type checkers. By wrapping the AI in these controls, you're building a behavioral harness that mathematically guarantees the AI's output actually matches your intent. Finally, part five, avoiding the waterfall trap, the BDUF risk of AI specs.
Now for a really critical pivot. With all these multi-file markdown specs and super rigid harnesses, are we accidentally just reinventing the absolute worst methodology of the 1990s? To answer that, Bergita Berkeley gives us this brilliantly helpful three-level taxonomy.
There's spec first, where you dictate the full design before coding. Then there's spec anchored, where specs guide the agents but evolve dynamically alongside the code. And at the extreme end, spec as source, where markdown specs basically compile directly into the application.
Knowing where your team sits on this spectrum is absolutely vital. Because, look, there are some serious trade-offs here. Burkeller candidly warns that overusing these generation tools creates massive review fatigue.
Your team will just be completely exhausted reading giant markdown files. Plus, it causes context pollution in the AI's memory window. But worst of all, it leads to spec to code drift, pulling us right back into the rigid big design upfront or BDUF trap of the waterfall era.
You end up spending all your time updating documents instead of shipping actual value. You've got to step back and ask: are these specs helping us move faster or just dragging us down?
A good harness should never aim to fully eliminate human input. Think about it, an AI doesn't have social accountability. It doesn't have that aesthetic disgust at a badly written 300 line function. It doesn't have the intuition that says, hey, we just don't do it that way around here.
Ultimately, your role isn't just to steer the AI, it's to verify, to reflect, and to inject that crucial human experience that a coding agent simply does not possess. Which leaves us with a highly provocative question as we wrap up this explainer. If our new standard for fast safe delivery involves generating massive specifications and technical plans entirely up front before an agent even writes a single line of code, well, what exactly happens to Agile?
Are we literally witnessing the end of iterative development as we know it? Join us in episode six as we explore exactly that. Until next time, keep learning and keep asking the right questions. Cheers.