What is Spec-Driven Development?
Relevant source files
The following files were used as context for generating this wiki page:Spec-Driven Development (SDD) is a methodology that inverts the traditional software development power structure. Instead of specifications being subordinate to code, SDD makes specifications executable artifacts that directly generate working implementations. The specification becomes the central source of truth, and code becomes its expression in a particular language or framework. This approach aims to eliminate the gap between intent and implementation by using AI to transform precise, structured specifications into code.
The core idea is to focus on "intent-driven development," where the team's creativity and critical thinking are applied to defining the "what" and "why" in natural language. The mechanical translation of these specifications into the "how" (code) is automated. This process supports not only initial "greenfield" development but also iterative enhancements and creative exploration of parallel implementations.
Sources: spec-driven.md:3-26, README.md:18-21, README.md:40-44
Core Philosophy and Principles
SDD is founded on a set of core principles that guide the entire workflow, from idea to production code.
Sources: spec-driven.md:100-113, README.md:33-38
| Principle | Description |
|---|---|
| Specifications as the Lingua Franca | The specification is the primary artifact. Maintaining software means evolving specifications, not just code. |
| Executable Specifications | Specifications must be precise, complete, and unambiguous enough for an AI to generate a working system from them. |
| Continuous Refinement | AI continuously analyzes specifications for ambiguity, contradictions, and gaps, rather than performing a one-time validation. |
| Research-Driven Context | Research agents gather technical context, investigate options, and apply organizational constraints throughout the specification process. |
| Bidirectional Feedback | Production metrics, incidents, and operational learnings are fed back into the specification for refinement in future generations. |
| Branching for Exploration | The same specification can be used to generate multiple implementation approaches to explore different optimization targets (e.g., performance, cost). |
The SDD Workflow
The SDD workflow is a structured, multi-step process that transforms a high-level idea into an implemented feature. It relies on a series of commands (/specify, /plan, /tasks) to guide the developer and AI agent through the phases of specification, planning, and implementation.
Sources: spec-driven.md:68-98, README.md:23-31, README.md:72-205
This diagram illustrates the high-level flow of the Spec-Driven Development process.
Streamlining SDD with Commands
The SDD methodology is operationalized through three primary commands that automate the workflow.
Sources: spec-driven.md:117-120, README.md:23-31
| Command | Purpose | Key Inputs | Key Outputs |
|---|---|---|---|
/specify | Transforms a natural language feature description into a structured specification. | User's feature description. | spec.md file in a new feature branch and directory. |
/plan | Converts the business requirements in spec.md into a technical implementation plan. | spec.md and user's tech stack choices. | plan.md, data-model.md, contracts/, research.md. |
/tasks | Breaks down the implementation plan into a list of discrete, executable tasks. | plan.md and other design documents. | tasks.md file with a numbered task list. |
The /specify Command
This is the first step. It takes a user's high-level feature description and bootstraps the entire feature development process.
Sources: templates/commands/specify.md, scripts/create-new-feature.sh
The flow of the /specify command execution.
The /plan Command
Once the specification is stable, the /plan command generates a detailed technical plan. It translates the "what" from spec.md into the "how."
Sources: templates/commands/plan.md, templates/plan-template.md:8-20
The flow of the /plan command execution.
The /tasks Command
After planning, the /tasks command creates an actionable, ordered list of implementation steps.
Sources: templates/commands/tasks.md, scripts/check-task-prerequisites.sh
The flow of the /tasks command execution.
Template-Driven Quality
SDD uses structured templates to guide the AI, ensuring high-quality, consistent, and complete output. These templates act as sophisticated prompts that constrain the LLM's behavior.
Sources: spec-driven.md:183-255, templates/spec-template.md, templates/plan-template.md
Key mechanisms include:
- Preventing Premature Implementation: The
spec-template.mdexplicitly forbids discussing "how" to implement, forcing a focus on user needs ("what" and "why").
Sources: templates/spec-template.md:19-21 - Forcing Explicit Uncertainty: Templates mandate the use of
[NEEDS CLARIFICATION: specific question]for any ambiguities, preventing the AI from making incorrect assumptions.
Sources: templates/spec-template.md:28-31, templates/spec-template.md:61-64 - Structured Self-Review: Checklists within the templates act as "unit tests" for the specification, forcing the AI to review its own output for testability, clarity, and completeness.
Sources: templates/spec-template.md:73-84 - Constitutional Compliance Gates: The
plan-template.mdincludes gates that check for adherence to architectural principles defined in the constitution, preventing over-engineering.
Sources: templates/plan-template.md:58-86, spec-driven.md:218-228
The Constitutional Foundation
At the core of SDD is a constitution.md file, which defines immutable architectural principles that govern all code generation. This ensures consistency, simplicity, and quality across the entire system, regardless of the feature being built or the AI model used.
Sources: spec-driven.md:257-349, memory/constitution.md
Key articles from the constitution include:
- Article I: Library-First Principle: Every feature must begin as a standalone, reusable library.
- Article III: Test-First Imperative (Non-Negotiable): No implementation code is written until failing tests have been created and approved.
- Article VII & VIII: Simplicity and Anti-Abstraction: The system must start simple, avoiding premature patterns and abstractions. Complexity requires explicit justification.
These principles are enforced through checklists and gates within the plan-template.md, making architectural compliance an automated part of the planning phase.
Sources: spec-driven.md:299-310, templates/plan-template.md:58-67
Summary
Spec-Driven Development is a methodology that elevates specifications from static documents to executable drivers of development. By combining structured templates, a core constitution, and a command-driven workflow, it channels the power of AI to automate the translation of intent into high-quality, maintainable, and architecturally sound code. This process amplifies developer effectiveness by allowing them to focus on creative problem-solving and product definition, rather than the mechanical aspects of coding.
Sources: spec-driven.md:351-359