22 - Spec Driven Development
The landscape of software development is undergoing a rapid, AI-driven transformation.
Competing philosophies — Vibe Coding, AI assisted coding and Spec Coding (or Spec-Driven Development) are emerging.
- Vibe-Coding is a new approach to software development that focuses on the emotional and social aspects of coding. Usually no technical background is required.
- AI-assisted coding is a more traditional approach to software development, where AI is used to assist developers in writing code. Ask Questions, simple agent usage.
- Spec-Driven Development is a new approach to software development that focuses on the technical aspects of coding. It is a more structured approach to software development, where the developer writes a specification for the code they want to write, and then the AI writes the code for them.
Most developers write code first and document later. Spec-driven development inverts this approach.
In traditional development, your code is the source of truth. Writing specs is something you do later (often as an afterthought).
Spec-driven development flips the script. Your spec becomes the source of truth, and you let AI handle the implementation details and write the code. This way, your specifications become executable, thanks to AI coding agents.
A spec is a structured, behavior-oriented artifact - or a set of related artifacts - written in natural language that expresses software functionality and serves as guidance to AI coding agents. Each variant of spec-driven development defines their approach to a spec’s structure, level of detail, and how these artifacts are organized within a project.
Crucially, your role isn’t just to steer. It’s to verify. At each phase, you reflect and refine. Does the spec capture what you actually want to build? Does the plan account for real-world constraints? Are there omissions or edge cases the AI missed? The process builds in explicit checkpoints for you to critique what’s been generated, spot gaps, and course correct before moving forward. The AI generates the artifacts; you ensure they’re right.
Tools
There are several tools available to help you with spec-driven development:
- BMAD
- Spec-Kit
- OpenSpec
and some others...
- SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) — from the Agentics Foundation community. Most mature of the alternatives. Has tooling for Claude Code, Cursor, and Cline via claude-flow. Multi-agent orchestration with dedicated agents per phase. Decent GitHub presence.
- Agent OS (buildermethods.com) — lighter-weight. Focuses on extracting existing coding standards from a codebase and injecting them as context for agents. More about maintaining consistency than full spec authoring. Complements rather than replaces the others.
- Pre.dev — mentioned frequently as a spec management layer that sits outside any specific IDE. The spec lives in the repo, agents become interchangeable. Interesting from an architecture perspective — separation of spec authoring from spec execution.
- superpowers - https://github.com/obra/superpowers
- gsd (get shit done) - https://github.com/gsd-build/get-shit-done https://github.com/punal100/get-stuff-done-for-kilocode
- Taskmaster - https://github.com/eyaltoledano/claude-task-master
So it is: intent → spec → plan → execution — difference is where the human gate is, how specs are versioned, and how multi-agent orchestration works.
Specs as source of truth
Practically works today:
- BMAD — explicitly designed for this. The whole point of its multi-agent pipeline is that specs + architecture docs are comprehensive enough to regenerate. People have demonstrated delete-and-regenerate workflows with it.
- Spec-Kit — spec + plan + tasks structure is meant to survive code deletion. The spec is the contract, code is the artifact.
- SPARC — same deal. Each phase produces durable markdown artifacts. Code is the last phase output.
Where it breaks down in practice:
- You won't get identical code. LLMs are non-deterministic. You'll get functionally equivalent code — different variable names, different implementation choices, maybe different libraries.
- The more complex the app, the more your specs need to capture edge cases, integration details, and architectural constraints. Vague specs = drift on regeneration.
- Database migrations, external service configs, deployment specifics — these are the things specs often underspecify. The "boring plumbing" is where regeneration fails.
- If the original specs were AI-generated (common in these workflows), they may have captured what was built rather than what was intended. Subtle but critical difference.
Spec-Kit
GitHub Spec-Kit: The "Keep It Simple" Option.
Spec-Kit is ideal for developers or small teams who want to improve the quality of AI-generated code by adding more structure; it's straightforward, uses your existing tools, and is backed by GitHub. It works best for small to medium-sized projects or features where you need a clear, structured way to define new functionality without the overhead of a full project management system.
Use Spec-Kit if:
- You're building something new from scratch
- You want structure but don't want to spend a week learning a framework
- You're already using Copilot, Claude Code, or similar tools
- You're just one dev or a small team
- You've never tried spec-driven dev before and want to ease into it
OpenSpec
OpenSpec: The "I Have Legacy Code" Option.
OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs, and is designed to work with the AI tools you already use through custom slash commands where supported and context rules everywhere else. OpenSpec is purpose-built for brownfield (existing codebases), with its lightweight, change-centric design avoiding the friction of imposing greenfield workflows on legacy code.
Go with OpenSpec if:
- You're working with an existing codebase (this is the big one)
- You want to move fast without a ton of ceremony
- You need good change tracking and versioning
- You hate bloated tooling
- Your workflow is basically: propose change → implement → done
BMAD
BMAD: The "I'm Building the Death Star" Option.
BMAD-Method is a comprehensive framework for agentic agile AI-driven development that uses specialized AI agents and personas to transform domains beyond just software development, built on agentic collaboration principles and known as the Breakthrough Method of Agile AI-Driven Development. BMAD is a multi-agent framework that acts like an entire AI development team, representing a very different philosophy from lightweight toolkits.
This is the nuclear option. BMAD doesn't just help you write specs—it simulates an entire development team.
BMAD makes sense if:
- You're working on a massive, complex project
- You need enterprise-level project management
- You're managing multiple repos
- You have time to invest in learning it (it's not trivial)
- You need it to work across different domains, not just code
- Your project is complicated enough that having AI agents debate architecture actually helps
So Which One Should I Pick?
For pioneering greenfield projects, choose between BMAD's deep role-planning and spec-kit's structured rigor: for complex domain logic and early architecture debates, BMAD excels, while for straightforward architecture but strict compliance, spec-kit is safer; for modernizing legacy systems, OpenSpec is purpose-built for brownfield with its lightweight, change-centric design.
| OpenSpec. | Spec-Kit. | BMAD | |
|---|---|---|---|
| Setup Time | 5 minutes | 30 minutes. | "Why did I do this" |
| Best For. | Existing codebases | New projects | Enterprise stuff |
| Complexity | Low. | Medium. | High. |
| Workflow. | 2 steps | 4 steps. | Multi-agent chaos |
| Who's in Charge | You | You. | You + AI agents. |
| Overhead. | Almost none. | Manageable. | Significant |
Pick OpenSpec if:
- You've got legacy code (this is 90% of us, let's be real)
- You want to try this spec-driven thing without committing your life to it
- Fast iteration > comprehensive process
- You just want it to work
Pick Spec-Kit if:
- You're starting something new
- You want something GitHub-official that won't disappear
- You're cool with a bit more structure
- You're new to this whole spec-driven thing
- You want good documentation and community support
Pick BMAD if:
- Your project is legitimately huge
- You need full project management, not just spec management
- You have time to learn a complex system
- You're tired of coordinating between multiple repos
- You work at a place that actually uses words like "comprehensive framework"
Multiple implementation levels
- Spec-first: A well thought-out spec is written first, and then used in the AI-assisted development workflow for the task at hand. Spec is deleted, code is source of truth. Plan/Arcitect mode aproach.
- Spec-anchored: The spec is kept even after the task is complete, to continue using it for evolution and maintenance of the respective feature.
- Spec-as-source: The spec is the main source file over time, and only the spec is edited by the human, the human never touches the code.
Read Martin Fowler's (or is it Birgitta Böckeler) article on SSD