Spec-Driven Development: From Vibe Coding to Production-Ready AI Code
Learn how to guide AI coding agents with structured specifications instead of improvised prompts. Used by GitHub, Amazon, and leading AI-native teams.
- Move from "vibe coding" to production-ready AI development
- Master the four-phase spec-driven workflow
- Use GitHub Spec Kit with Claude Code, Cursor, GitHub Copilot, Windsurf, and more
- Build consistent, high-quality code with AI agents
Spec-Driven Development (SDD) is a methodology where you write detailed specifications BEFORE generating code, making the spec—not the code—your source of truth. Think of it as the evolution of Product Requirements Documents (PRDs) for the AI age.
The Problem It Solves
"Vibe coding" (coined by Andrej Karpathy, Feb 2025) works great for prototypes, but fails for production systems. You describe what you want, get code back, and… it compiles but doesn't match intent, has wrong architecture, or introduces security holes.
The Solution
Instead of treating AI agents like search engines, treat them like literal-minded pair programmers. They need unambiguous instructions, not vague prompts.
Traditional Workflow:
Requirements → Design → Coding → Testing
Spec-Driven Workflow:
Requirements → Detailed Spec → AI Generation → ValidationImagine you're building with LEGO but blindfolded. "Vibe coding" is like someone describing what to build piece-by-piece as you go ("add a blue brick… now a red one…"). Sometimes it works, often it doesn't.
Spec-driven development is like having the complete LEGO instruction booklet FIRST. You know exactly what you're building, what pieces you need, and how they fit together. Then you hand that booklet to a really fast builder (the AI) who follows it perfectly.
The instruction booklet is your "spec." The AI is your builder. You focus on designing what to build; the AI focuses on building it exactly as specified.
Why This Matters
If you're building with Claude Code, Cursor, or GitHub Copilot, you've experienced this: the code looks great, but doesn't quite work. Security requirements were missed. The architecture isn't what you'd choose. Tests are incomplete.
Spec-driven development solves this by:
Use spec-driven when:
- ✅Building production systems (not prototypes)
- ✅Working with existing codebases
- ✅Team collaboration required
- ✅Complex architectures
- ✅Security/compliance matters
- ✅Greenfield projects that need to scale
Stick with vibe coding when:
- ❌Quick prototypes and experiments
- ❌UI-heavy work needing visual iteration
- ❌Small bug fixes
- ❌Exploring ideas
- ❌Learning new technologies
Real-World Example: Building a SaaS Dashboard
Vibe coding approach:
- → "Build me a dashboard with login"
- → AI generates something generic
- → "Add billing"
- → Code conflicts with existing auth
- → "Add analytics"
- → Architecture becomes messy
- → Spend days debugging
Spec-driven approach:
- 1. Write spec: Auth (OAuth2 + JWT), billing (Stripe), analytics (PostHog), architecture (Next.js + Supabase)
- 2. AI generates plan breaking this into tasks
- 3. AI implements each task following spec
- 4. Review focused changes, not thousand-line dumps
- 5. Ship production-ready code
SDD follows a structured process (from GitHub Spec Kit):
1Specify
Write your specification document covering:
- • What you're building and why
- • Functional requirements (what it does)
- • Non-functional requirements (performance, security, etc.)
- • Technical constraints
- • Success criteria
2Plan
AI generates a technical plan from your spec:
- • Architecture decisions
- • Technology stack
- • Component design
- • Integration points
- • Risk assessment
3Tasks
AI breaks the plan into concrete, testable tasks:
- • Small, reviewable chunks
- • Each task solves a specific piece
- • Includes acceptance criteria
- • Can be implemented in isolation
4Implement
AI implements tasks one by one:
- • You review focused changes (not giant code dumps)
- • Each task is validated against spec
- • Iterative refinement
- • Spec remains source of truth
Key Innovation: The Constitution
A constitution.md file defines non-negotiable principles:
- • Testing approaches (e.g., "always write unit tests first")
- • Conventions (e.g., "CLI-first for all tools")
- • Security requirements
- • Design system rules
- • Opinionated stacks
This ensures organizational standards are baked into every project.
GitHub Spec Kit ⭐ (Primary Tool)
- Open source toolkit for SDD
- CLI tool to initialize projects
- Works with multiple AI agents
- Templates for specs, plans, tasks
- Active development (v0.0.79+ as of Oct 2025)
Supported AI Agents
Related Tools
Amazon Kiro IDE
New VS Code-based IDE with built-in "Spec Mode"
Cursor Plan Mode
Auto-generates plans before coding
spec-coding-mcp
MCP server for spec-driven development
Installation
# Using uvx (recommended)
uvx --from git+https://github.com/github/spec-kit.git specify init my-project
# Choose your AI agent during setup
# Creates folder structure with templatesBest Use Cases
1. Greenfield (Zero-to-One)
Starting a new project? Small upfront investment in specs ensures AI builds what you intend, not generic patterns.
2. Legacy Modernization
Original intent lost to time? Capture essential business logic in modern spec, design fresh architecture, let AI rebuild without technical debt.
3. Team Collaboration
Multiple developers, different AI tools? Shared spec becomes single source of truth everyone works from.
4. Enterprise Applications
Security requirements, compliance, design systems? These are specification constraints, not afterthoughts.
Current Limitations
Example 1: Den Delimarsky's GitHub Brain MCP Server
Built entire project by writing specs in Markdown, letting GitHub Copilot compile to Go code. Rarely edits Go directly—works at the specification level.
Example 2: Legacy System Modernization
Company had 10-year-old monolith. Wrote spec capturing business logic, generated modern microservices architecture, validated against original behavior. Shipped in weeks vs. months of manual rewrite.
Example 3: Multi-Platform App
Wrote single spec for mobile app features, generated iOS (Swift), Android (Kotlin), and Web (React) implementations from same spec. Consistency across platforms, single source of truth.
Pick Your First Project
Choose a greenfield project or well-defined feature. Don't start with complex legacy code.
Install Spec Kit
uvx --from \ git+https://github.com/github/spec-kit.git \ specify init my-first-spec-projectWrite Your Constitution
Define your non-negotiables: Testing philosophy, security baseline, code style, technology preferences
Create Your First Spec
Use the template. Be specific: What problem? Who are users? What features? What constraints? How measure success?
Let AI Plan
Use your AI agent to generate the technical plan from spec.
Review and Iterate
The plan probably needs refinement. This is normal. Update spec, regenerate.
Generate Tasks
Break the plan into concrete implementation tasks.
Implement
Let AI implement tasks. Review each one. Validate against spec.
Test and Ship
Run tests, validate behavior, deploy.
SDD vs Vibe Coding
| Aspect | Vibe Coding | Spec-Driven |
|---|---|---|
| Starting point | Prompt | Specification |
| Structure | Ad-hoc | Systematic |
| Best for | Prototypes | Production |
| Quality | Variable | Consistent |
| Team use | Individual | Collaborative |
SDD vs TDD (Test-Driven Development)
- •TDD: Tests are specifications for behavior
- •SDD: Specifications cover entire system (architecture, tests, requirements)
- •They're complementary, not competing
- •SDD can include TDD as part of the spec
SDD vs Traditional PRDs
- •PRDs: Static documents that get outdated
- •SDD: Living specifications that drive implementation
- •PRDs inform humans; specs are executed by AI
- •SDD makes PRD-like thinking executable
Trends to Watch
1. IDE Integration
Tools like Amazon Kiro show SDD moving into IDEs natively. Expect VS Code, Cursor, etc. to build this in.
2. Model Improvements
As context windows grow (200K+ tokens now), models handle increasingly complex specifications.
3. Specification Languages
Projects like SpecLang and Plain show movement toward formal spec languages.
4. Multi-Agent Orchestration
Specs become contracts between multiple AI agents working together.
5. Visual Spec Tools
Next generation may combine visual design tools with spec generation.
"We're moving from 'code is the source of truth' to 'intent is the source of truth.' This isn't because documentation became more important. It's because AI makes specifications executable."
— Den Delimarsky, GitHub PM
Community Growth
- • Active GitHub discussions
- • Community contributions to Spec Kit
- • Companies building on the framework
- • Conference talks and tutorials emerging
What is spec-driven development?
Spec-driven development is a methodology where you write detailed specifications before generating code, making the specification—not the code—your source of truth for AI agents to follow.
How is spec-driven different from vibe coding?
Vibe coding uses ad-hoc prompts to generate code iteratively. Spec-driven development uses structured specifications upfront, resulting in more consistent, production-ready code.
What tools support spec-driven development?
GitHub Spec Kit is the primary toolkit, supporting Claude Code, GitHub Copilot, Cursor, Gemini CLI, and 10+ other AI coding agents.
When should I use spec-driven development?
Use SDD for production systems, team collaboration, complex architectures, and when code quality matters. Use vibe coding for prototypes and experiments.
Is spec-driven development compatible with Agile?
Yes, specs can be iterative within sprints. SDD focuses on working software, not documentation for its own sake.
Who coined the term "vibe coding"?
Andrej Karpathy coined the term "vibe coding" in February 2025 to describe the ad-hoc, prompt-driven approach many developers use with AI coding assistants.