Spec Driven Development is a software engineering methodology where detailed, structured specifications serve as the primary source of truth, guiding AI coding agents to generate code, tests, and documentation instead of relying on loose, ad-hoc prompts.
Why use Spec Driven Development?
Spec Driven Development eliminates “Vibe Coding”
Vibe coding happens when you type a vague prompt and let the AI guess your architecture, resulting in hidden bugs and technical debt. SDD replaces guesswork with an explicit contract of what to build
How the SDD workflow works
Most frameworks—such as the open-source GitHub Spec Kit—follow a structured lifecycle:
- Constitution & Context: You define project-wide rules, tech stacks, dependencies, and style guidelines in a foundational markdown file.
- Specify: You write or co-author a feature specification detailing user journeys, inputs, outputs, and acceptance criteria.
- Plan: The AI or architect maps out technical boundaries, file structures, and data models.
- Tasks: The plan breaks down into small, isolated, reviewable engineering tasks.
- Implement & Verify: AI agents write the code and unit tests based strictly on the spec, and developers review the output against the acceptance criteria.
Open Spec vs Spec Kit
GitHub Spec Kit and OpenSpec are both spec-driven development (SDD) tools that help developers write structured requirements before handing them off to AI coding agents.
- GitHub Spec Kit is a heavyweight, greenfield-first toolkit that enforces a strict, multi-phase planning pipeline.
- OpenSpec is a lightweight, brownfield-first framework built around fast, change-led delta tracking.
For my use case I will be using the GitHub Spec Kit
Spec Driven Development with Claude Code
Claude Code is Anthropic’s agentic coding tool. It runs in your terminal, reads your whole repository and can plan, write and test code across multiple files. That makes it a natural fit for spec-driven development, because it can work from a spec stored alongside your code rather than a one-off prompt.
There are two main ways to use it. The first is with GitHub Spec Kit, which can be initialised for Claude Code. This adds the specify, plan and tasks steps as slash commands, so you move through each phase of the workflow without leaving the terminal.
The second is using Claude Code’s own features. A CLAUDE.md file in your repo acts as your project constitution, giving the agent standing context about your coding standards, tools and constraints. Plan mode lets Claude propose its approach for you to review before it changes any code, and Agent Skills let you package repeatable instructions, such as how your team structures Ansible roles or tests Python scripts.
Either way, the principle is the same. The spec defines what to build, Claude Code does the implementation, and you verify the result against your acceptance criteria.
If you haven’t set it up yet, start with my guide on how to install Claude Code.
Spec Driven Development Explained in Plain English
At its simplest, spec-driven development means deciding exactly what you want before anyone, or anything, starts building it.
Think about how you’d approach a network change. You wouldn’t log into a core switch and start typing commands, hoping it works out. You’d write a change request: what’s changing, why, which devices are affected, how you’ll test it and how you’ll roll back if it goes wrong. That document is a specification, and it’s what makes the change safe and repeatable.
Spec-driven development applies the same thinking to writing code with AI. Instead of typing a vague prompt like “write me a script to back up my switches” and accepting whatever comes back, you first write a short spec. It describes what the script should do, which platforms it supports, where the backups go, how errors are handled and what “done” looks like.
The AI coding agent then works from that spec rather than guessing. Because the requirements are written down, you can check the output against them, hand the same spec to a colleague, and come back six months later knowing exactly why the code works the way it does.
In short, the spec becomes the source of truth, and the code follows it.
Why Spec Driven Development Matters Now
Spec-driven development isn’t a new idea, so why is everyone suddenly talking about it? The short answer is AI coding agents.
Tools like Claude Code, GitHub Copilot and Cursor can now generate hundreds of lines of working code in minutes. That’s a huge productivity boost, but it has exposed a problem. An LLM only knows what you tell it, and when the context is thin, it fills the gaps with assumptions. You end up with code that looks right, runs in a demo and then falls over in production. This is the downside of vibe coding: you move fast, but you build up technical debt you don’t fully understand.
The bottleneck has shifted. Writing code is no longer the slow part. Being clear about what you want, and checking that you got it, is where the real work now sits.
A spec solves this by giving the AI agent the context it needs up front: requirements, constraints, edge cases and acceptance criteria. This is closely linked to context engineering, the practice of feeding a model the right information so it produces the right output.
That’s why GitHub, AWS and others have released dedicated spec-driven development tools since 2025. As AI writes more of our code, the spec becomes the most valuable thing a human engineer contributes.
The Core Workflow: Specify, Plan, Tasks, Implement
What Goes Into a Spec?
Spec Driven Development Tools
Benefits and Limitations
Spec Driven Development for Network Engineers
What is Spec Driven Development FAQ
Is spec-driven development only for AI coding?
No. Writing a specification before you build has been good engineering practice for decades, from API-first design with OpenAPI to network design documents and change requests. What’s new is that AI coding agents make the spec far more valuable, because the agent follows it literally. A clear spec works just as well for a human team, and it gives you the same benefits: fewer surprises, easier review and built-in verification against acceptance criteria.
Leave a Reply