Spec-Driven Development in Practice — A Development Workflow for the AI Agent Era
Introduction
Now that AI agents generating code has become commonplace, a new set of problems has emerged. "The AI's code doesn't match the requirements." "Frequent pivots cause constant rework." "Different people prompt the AI differently, producing inconsistent output."
The root cause of all these problems is the same: what to build isn't clearly defined before the code is written.
Spec-Driven Development (SDD) is a methodology where, instead of having AI agents jump straight into code, you first have them generate specifications, then build based on those specs. This article explains why this approach was born, how it differs from vibe coding, and how to put it into practice.
The Rise and Limits of Vibe Coding
What Is Vibe Coding?
In February 2025, former OpenAI researcher Andrej Karpathy coined the term "vibe coding" — an approach where you build software by giving AI rough, intuitive instructions without necessarily understanding the underlying code.
The rapid improvement of AI coding tools like Cursor and Claude Code made it possible for people with little programming experience to create applications. Karpathy himself described it as "forgetting that the code even exists and fully surrendering to the vibes."
The Problems with Vibe Coding
However, while vibe coding works for throwaway weekend projects, it has proven to carry serious risks for production software:
- Security vulnerabilities: Reports emerged of vibe-coded apps exposing personal data with no access controls
- Declining code quality: Code duplication roughly quadrupled, and "code churn" — code rewritten shortly after merge — nearly doubled
- Development without understanding: Developers who don't understand the AI-generated code can't detect bugs or security holes
- Unmaintainable output: Long-term maintenance becomes impractical as technical debt accumulates rapidly
Ironically, Karpathy himself later admitted that in subsequent projects, "I tried the AI agent several times but it was completely useless," and returned to writing code by hand.
This isn't a blanket rejection of vibe coding. It's valuable for prototyping and learning. The problem lies in applying this approach directly to production-grade development.
The Birth and Spread of Spec-Driven Development
Why It Emerged
Spec-Driven Development appeared in 2025 as the industry's answer to the limitations of vibe coding.
The idea of "generating code from specifications" predated LLMs, but earlier tools lacked the accuracy to produce usable code from natural-language specs. As LLM context windows expanded and natural-language comprehension improved dramatically, the spec-driven approach became practical for the first time.
OpenAI's Sean Grove put it this way: "The new scarce skill is writing specs that fully capture intent and values. Not prompts, not code — specs are becoming the fundamental unit of programming."
The Adoption Timeline
Since 2025, a series of tools supporting spec-driven development has appeared:
| Period | Tool / Development |
|---|---|
| July 2025 | Amazon previews Kiro with the slogan "From vibe coding to viable code," implementing a spec-driven workflow as an IDE |
| September 2025 | GitHub open-sources Spec Kit, providing CLI, templates, and prompts to standardize the spec-to-plan-to-task-to-implementation flow |
| Late 2025 | Thoughtworks features spec-driven development on its Technology Radar, calling it "one of the most important practices to emerge in 2025" |
Current Adoption
As of 2026, spec-driven development is not yet a fully mature methodology, but awareness is growing rapidly. Major AI development tools — Kiro, GitHub Spec Kit, Claude Code, Cursor — have all begun supporting spec-driven workflows, and Thoughtworks expects "even bigger shifts in 2026."
From Vibe Coding to Spec-Driven Development
What changes in practice?
Comparing the Workflows
Vibe coding:
Developer: "Build a user auth feature"
AI: Generates code
Developer: "Not quite — use JWT"
AI: Modifies code
Developer: "Add refresh tokens too"
AI: More modifications... (loop continues)
Spec-Driven Development:
Developer: "Build a user auth feature"
AI: Generates a requirements doc (functional, non-functional, constraints)
Developer: Reviews and approves
AI: Generates a technical design doc (architecture, API design, data model)
Developer: Reviews and approves
AI: Generates a task list (prioritized implementation steps)
Developer: Reviews and approves → moves to implementation
The key point of SDD is the division of labor: AI writes the specs, humans review them. Humans focus on validating requirements and making design decisions, while AI handles the structuring and documentation work.
Workflow
The basic flow of spec-driven development is straightforward:
Developer describes requirements → AI generates specs → Human reviews → Implementation
The developer describes requirements in natural language, and the AI produces structured specification documents. While output formats vary by tool, the following artifacts are typically generated:
Requirements Document
A summary of what to build. Functional requirements, non-functional requirements, and constraints are listed. Each requirement gets an ID for cross-referencing from design docs and tasks.
## Functional Requirements
- FR-001: Login via email + password
- FR-002: Session management with JWT
## Non-Functional Requirements
- NFR-001: Response time under 200ms
- NFR-002: Passwords hashed with bcryptTechnical Design Document
A summary of how to build it. Covers architecture, API design, data models, security design, and more. Includes references to requirement IDs, making the rationale behind each design decision explicit.
Task List
A summary of the build order. Prioritized implementation steps are output as a checklist.
Humans review the generated specs and request changes where needed. Once specs are finalized, implementation proceeds based on the agreed-upon specifications.
The power of SDD lies in locking down specs before coding begins. When specs are settled first, instructions to the AI during implementation become far more specific, dramatically reducing rework.
Tool-Specific Approaches
Each tool supporting spec-driven development takes a slightly different approach:
- Amazon Kiro: Create a "Spec" inside the IDE, and it generates requirements, design, and tasks in sequence. Code generation begins after human review and approval
- GitHub Spec Kit: Standardizes the spec-to-plan-to-task flow via CLI + templates. Designed to work with existing editors and AI agents
- Claude Code / Cursor: Leverage Plan Mode and rule files to build a workflow that generates specs first, then implements
The common principle across all of them: write specs before code.
Adopting SDD in Team Settings
Introducing Spec Reviews
Add "spec reviews" before code reviews:
Requirements → Spec review → Design → Spec review → Implementation → Code review
Catching misalignments at the spec stage dramatically reduces post-implementation rework. Since specs are Markdown files managed in Git, your existing pull-request-based review workflow applies directly.
Managing Specs in Git
.specs/
├── user-auth/
│ ├── requirement.md
│ ├── design.md
│ └── tasks.md
├── payment/
│ ├── requirement.md
│ ├── design.md
│ └── tasks.md
└── ...
Managing specs in the same repository as code prevents drift between specification and implementation. When implementation changes require spec updates, both can be handled in the same PR.
Standardization via Agent Skills
Spec-driven workflows can be standardized as Agent Skills. By defining the process as a skill, any team member can generate specs of consistent quality.
Our open-source agent-skills repository includes spec generation along with additional extensions:
- spec-generator: Automatically generates specs (requirements, design docs, task lists)
- spec-inspect: Automatically validates spec quality (detects ID inconsistencies, ambiguous language, design contradictions)
- spec-to-issue: Automatically creates GitHub Issues from specs
While spec validation and issue creation aren't part of SDD's core definition, they're practical additions for running spec-driven development in a team setting. See the announcement post for details.
Summary
Spec-Driven Development shifts how we use AI agents — from "jump straight into code generation" to "write specs first, review them, then implement."
- AI generates requirements, design docs, and task lists in a structured format
- Humans review specs and request corrections where needed
- Implementation proceeds based on agreed-upon specifications
Taking the age-old principle of "write specs before code" and making it practically achievable with the power of AI agents — that's the essence of Spec-Driven Development.
At ZenChAIne, we've added validation and issue-creation workflows on top of this spec-driven approach and published them as Agent Skills.
