Understanding the Three Levels of Spec-Driven Development: Which is Right for Your Team?
Hey fellow devs!
When we talk about Spec-Driven Development (SDD), it’s easy to assume it’s just a single workflow: you write a spec, and the AI writes the code. But like most engineering practices, SDD has levels of maturity and automation.
In a recent article published on Martin Fowler’s blog, writer Brita Buckler categorized Spec-Driven Development into three distinct levels: Spec-First, Spec-Anchored, and Spec-as-Source. Understanding these variations is crucial for choosing the right approach for your codebase. Let’s break down each level and look at what is practical for engineering teams today.
Level 1: Spec-First
In the Spec-First approach, the specification acts as the initialization tool for the feature.
You write a clear natural language description of what you want to build (e.g., the parameters, business logic, and test cases), feed it to the AI agent to generate the initial source code files, and then you take over. From that point on, you manually edit, maintain, and debug the codebase. The specification is rarely updated after the initial generation.
This is the most natural way for developers to get started with AI. It requires no change to your deployment pipelines, and it fits perfectly into standard IDE setups.
Level 2: Spec-Anchored
The Spec-Anchored approach keeps the specification and the code synchronized throughout the lifetime of the project.
The specification file is checked into the repository alongside the source code. When you need to make changes, add features, or fix bugs, you update the specification file first. Then, you instruct the AI agent to read the updated spec and refactor the code to match. However, developers still have the freedom to jump in and write manual code adjustments when the AI gets stuck.
This hybrid approach is what most advanced developers use in their daily routine. On our podcast, Yugo explained how he uses this:
Yugo: “In my experience, the second and first is a mix that I do for my daily routine. The first one is very natural for any developer to get started—I write the specification and I use it to help me write the code. The second one, Spec-Anchored, is also fine: instead of writing a new specification for every change, I update the specification and have the AI update the code. That works well.”
Level 3: Spec-as-Source
This is the most extreme and highly automated level of SDD.
Under Spec-as-Source, the specification is the absolute source of truth. Developers never write or edit source code files directly. Any modification, design change, or bug fix is done exclusively in the natural language specification file. The compilation step consists of an AI agent reading the spec and regenerating the entire codebase from scratch.
While this sounds like the ultimate goal, it is highly impractical for most engineering teams today. It turns the codebase into a black box that is difficult to audit, and it requires highly deterministic AI agents that do not exist yet.
Pedro shared his skepticism on our podcast:
Pedro: “I couldn’t imagine using it. The third way looks to me like what we had before with MDD—Model-Driven Development. Do you remember that? When we were modeling and the code was generated behind the scenes? At the time it was just generating Java code, but now, using AI, I have never seen people using AI this way. I don’t think it is practical.”
Furthermore, as Yugo added:
Yugo: “The third one is for me quite heavy. It is just everything you manage over the specification documents. I haven’t tried this. I think it is still a very strong requirement to follow. We still need some way to validate and audit many of these systems we create… If it is a black box that no one knows how it works, with no documentation, you can’t figure it out. Someone has to validate what is written and check what is going on behind the scenes.”
Finding the Balance
For 95% of engineering teams, the sweet spot lies in a hybrid of Level 1 and Level 2.
Write your specifications first to lay down the architecture and generate the initial code. Then, keep the specifications anchored in the repository to guide future changes, but never hesitate to jump into the code directly to make precise edits, fix minor bugs, or optimize performance.
Purity in workflows often leads to friction. Choose the level that makes your team productive.
What level of SDD does your team use? Would you trust a codebase built entirely under Level 3 (Spec-as-Source)? Let me know in the comments below!
Watch the full video here to see our team’s discussion.
Happy coding!
Cheers,
Pedro Cavalero
