Spec-Driven Development:From Code to Contract in the Age of AI Coding Assistants
This paper presents a comprehensive guide to Spec-Driven Development (SDD), outlining its principles, three levels of specification rigor, and supporting tools to demonstrate how treating specifications as the primary artifact can effectively leverage AI coding assistants across diverse software domains.
Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer
Imagine you are hiring a very talented, incredibly fast, but slightly literal-minded robot chef to cook a complex meal for you.
The Old Way (Code-First):
You walk up to the robot and say, "Make me a delicious dinner."
The robot, eager to please, immediately starts chopping vegetables and heating pans. It guesses you want pasta. It guesses you want it spicy. It guesses you want to use the expensive truffle oil you didn't mention.
Ten minutes later, you have a plate of spicy truffle pasta. You wanted a salad.
Now you have to tell the robot to stop, throw away the pasta, and start over. This is what the paper calls "vibe coding"—relying on vague prompts where the AI has to guess your intent. The result is often a mess that requires constant fixing.
The New Way (Spec-Driven Development):
Instead of shouting orders, you first write a recipe card (the Specification).
You write down exactly: "I want a salad. Use spinach, tomatoes, and feta. No nuts. Dressing on the side. Serve at room temperature."
You hand this card to the robot. The robot reads it, checks its understanding, and then starts cooking.
If the robot tries to add nuts, it stops because the card says "No nuts." If it tries to serve it hot, it stops.
In this scenario, the recipe card is the boss. The food (the code) is just the result of following the recipe. If the food tastes wrong, you don't blame the chef; you check if the recipe was clear.
The Three Levels of Strictness
The paper explains that you don't always need a 50-page contract. There are three ways to use this "recipe card" approach, depending on how serious you are:
Spec-First (The "Sketch"):
- What it is: You write the recipe before you start cooking to make sure everyone agrees on what you're making.
- When to use it: Great for trying out a new idea or a one-off project.
- The Catch: Once the meal is cooked, you might throw the recipe card away. If you change the recipe later, the card might not get updated. It's good for starting, but not for long-term maintenance.
Spec-Anchored (The "Living Menu"):
- What it is: The recipe card is kept on the fridge next to the stove. Every time you change the dish (add more cheese, change the dressing), you must update the card immediately.
- When to use it: This is the sweet spot for most professional kitchens (production software).
- The Magic: The kitchen has a robot inspector. If the chef changes the dish but forgets to update the card, the inspector sounds an alarm. This ensures the menu (documentation) always matches the food (software).
Spec-as-Source (The "3D Printer"):
- What it is: This is the most extreme version. You never touch the food directly. You only edit the recipe card. A machine then automatically prints the food based only on that card.
- When to use it: This is used in high-stakes fields like building car engines or medical devices, where a mistake could be dangerous.
- The Rule: If you want to change the car's brakes, you don't reach under the hood with a wrench. You change the blueprint, and the machine rebuilds the brakes perfectly. You are never allowed to manually edit the generated parts.
Why AI Makes This Necessary
The paper argues that AI coding assistants are like that talented but literal robot chef. They are amazing at following instructions, but terrible at "mind-reading."
- Without a spec: You ask the AI to "add a login feature." The AI guesses the password rules, the database type, and the security level. It often gets it wrong.
- With a spec: You give the AI a clear contract: "Login requires a 12-character password, uses email, and locks the account after 3 failed attempts." The AI follows the rules perfectly.
The Workflow: A Four-Step Dance
The paper suggests a simple rhythm for this process:
- Specify: Write the "What." (The Recipe).
- Plan: Write the "How." (The shopping list and kitchen layout).
- Implement: Build it. (The cooking).
- Validate: Check it. (Taste testing). If the taste doesn't match the recipe, you fix the cooking or update the recipe, but you never ignore the mismatch.
When to Use It (And When Not To)
The paper provides a simple decision guide:
- Use it when: You are building something big, working with a team, using AI, or building something where mistakes are expensive (like banking or cars).
- Don't use it when: You are making a quick prototype to throw away, or you are a solo developer building a simple to-do list app where the requirements are obvious. In those cases, writing a detailed recipe is just a waste of time.
The Big Takeaway
For decades, software developers wrote code first and wrote the "recipe" (documentation) later, if they wrote it at all. This paper says: Flip the script.
Make the Specification the primary thing you create. Treat the Code as just the automatic output of that specification.
By doing this, you stop guessing, you stop fighting with your AI tools, and you ensure that what you build is exactly what you intended to build. The code becomes a shadow of the specification, not the other way around.
Drowning in papers in your field?
Get daily digests of the most novel papers matching your research keywords — with technical summaries, in your language.