Spec-Driven Development: Is it a good idea?
Trying to resolve ambiguity in software development
I’m sure you’ve seen it over the past few months: Spec Driven Development.
The new frontier! From your Product Manager’s Specs to code implemented by an AI agent.
That’s the idea.
But let me ask you a question: Does Specs Driven Development take us back to the days of waterfall development?
First, let’s start with today’s learning.
📜 What is Spec Driven Development?
Spec-Driven Development (SDD) is about writing explicit specifications, executable or easily verifiable, before writing the code, and using those specs as the source of truth so that tools (including AI/LLMs) can generate, test, and validate the software.
In practice, GitHub proposes treating Markdown as a “programming language” for specifications: using sections, examples, and blocks that describe behavior, APIs, data, and tests.
Why is it gaining traction?
With the rise of code assistants, being able to precisely describe what you want becomes extremely valuable. The ability to write clear specifications, with examples, acceptance criteria, and test cases, is becoming increasingly important; it allows automatic tools to generate more reliable and reproducible code.
If I had to summarize it in 3 steps, they would be:
Write the spec in Markdown: goal, contracts (endpoints, payloads), input/output examples, and acceptance criteria.
Generate and test: use the spec to generate code with an AI agent or scaffolding tools; validate it against the examples and tests provided.
Iterate and version: the spec evolves and acts as living documentation and a test suite.
If you know how to write good specifications, you have the opportunity to get much more out of automatic tools and out of teams working at scale. Like a giant prompt, basically.
And that is, on paper, Spec-Driven Development. That’s today’s learning.
Now, back to the reflection I opened the email with.
🏞️ Are we going back to Waterfall?
SDD is not necessarily meant to take us back to waterfall, but it can if applied poorly.
Extensive specs? No, thanks.
SDD encourages writing complete specifications before implementing. If the organization requires “complete” specs, that reproduces the classic waterfall behavior: long analysis phases before any real, concrete delivery.
Can you imagine doing a code review of a full feature implemented by an AI Agent? For a POC, maybe. But for code going to Production? 😱
But we don’t have to do that! We can choose; we can choose to provide smaller specs so the AI Agent processes and develops more concrete, more controlled parts.
What do I recommend if you happen to have large specs?
Break those specs into smaller deliverables
And work on each small deliverable with the AI Agent
This will yield more effective results because AI Agents work better with a more concrete context.
When specs are executable, for example:
Automated tests
Contracts that can be validated
Implementing a data reader from Kafka
In those cases, they act as fast feedback loops. That fits with iterative cycles and continuous delivery, not with giant releases.
✨ Conclusion
What I want you to take away from today’s email is what Spec-Driven Development actually is:
A technique for AI Agents to develop software from a set of initial specifications.
From there, I wanted to spark a debate in your mind so you can approach this technique in a way that’s useful to you.
Someone once said (probably many times):
With great power comes great responsibility.
Spec-Driven Development is proposed as an attempt for AI Agents to take care of everything, and it’s up to you to define what “everything” really is.
Personally, I think that if you narrow and slice the specs, meaning, reducing scope so you can get small deliverables iteratively, it’s a technique that can help us a lot in our interactions with AI Agents.
I’d love to hear about your experience with Spec-Driven Development, whether you’re just starting out or you’re already a pro. You can reply to this email, comment if you’re on Substack, or send me a message on social media 👇🏻
Did you enjoy today’s edition? Share it with your friends 👇🏻