This page documents the foundational philosophy and core concepts underlying Spec-Driven Development (SDD) as implemented in Spec Kit. It covers the theoretical principles, the workflow pipeline structure, and how specifications transform into executable implementations through AI-assisted processes.
For detailed information about specific workflow commands, see /speckit.specify, /speckit.plan, and /speckit.tasks. For the constitutional system that enforces architectural discipline, see Constitutional Governance System. For practical implementation details, see /speckit.implement.
Sources: README.md39-41 spec-driven.md1-19
Spec-Driven Development inverts the traditional relationship between specifications and code. Instead of treating specifications as temporary scaffolding that guides developers toward writing code, SDD treats specifications as the primary artifact that directly generates implementations.
This inversion fundamentally changes how development teams think about software:
Sources: spec-driven.md4-16 README.md39-41
SDD introduces the concept of intent-driven development, where teams express what they want to build using natural language, design assets, and organizational principles rather than writing code directly.
| Artifact Type | Location | Purpose | Natural Language Content |
|---|---|---|---|
| Constitution | .specify/memory/constitution.md | Immutable architectural principles | "Every feature MUST begin as a standalone library" |
| Specification | .specify/specs/NNN-feature/spec.md | Feature requirements (the "what" and "why") | "Users can create projects, add team members, assign tasks" |
| Implementation Plan | .specify/specs/NNN-feature/plan.md | Technical translation (the "how") | "Using .NET Aspire with PostgreSQL database" |
| Task List | .specify/specs/NNN-feature/tasks.md | Execution sequence | "Create Task model in src/Models/Task.cs" |
The lingua franca of development moves to a higher abstraction level. Developers focus on:
AI agents handle the mechanical translation from these intents to working code.
Sources: spec-driven.md13-17 README.md277-285
A specification is executable when it contains sufficient precision, completeness, and structural constraints to generate working implementations without human intervention during the translation phase.
Executable specifications must eliminate ambiguity through:
[NEEDS CLARIFICATION: specific question] forces acknowledgment of unknownsThe specification must address:
Templates enforce structure that guides LLM behavior:
templates/spec-template.md # Feature specification structure
templates/plan-template.md # Implementation plan structure
templates/tasks-template.md # Task breakdown structure
These templates contain YAML frontmatter and structured sections that constrain how AI agents generate specifications.
Sources: spec-driven.md10-12 spec-driven.md165-205 README.md408-489
The SDD workflow follows a strict phase progression where each phase produces artifacts consumed by the next phase:
| Phase | Command | Reads | Writes | Validation |
|---|---|---|---|---|
| 0 | /speckit.constitution | User prompt | memory/constitution.md | 9 articles present |
| 1 | /speckit.specify | templates/spec-template.md | specs/NNN-feature/spec.md | No tech stack mentioned |
| 2 | /speckit.clarify | specs/NNN-feature/spec.md | Updated spec.md | All [NEEDS CLARIFICATION] resolved |
| 3 | /speckit.plan | spec.md, constitution.md, templates/plan-template.md | plan.md, data-model.md, contracts/* | Constitutional gates passed |
| 4 | /speckit.tasks | plan.md, data-model.md, contracts/*, templates/tasks-template.md | tasks.md | Tasks dependency-ordered |
| 5 | /speckit.implement | tasks.md | Source code files | All tasks completed |
Sources: README.md93-135 spec-driven.md73-163 Diagrams 1-2
Templates act as sophisticated constraints that guide LLM behavior toward higher-quality specifications. Rather than allowing free-form generation, templates enforce structure, completeness checks, and explicit acknowledgment of uncertainties.
The specification template prevents premature implementation details:
# From templates/spec-template.md
✅ Focus on WHAT users need and WHY
❌ Avoid HOW to implement (no tech stack, APIs, code structure)
This constraint keeps specifications stable across technology changes. If implementation technologies evolve (e.g., React → Svelte), the specification remains valid because it never mentioned React.
Both specification and plan templates mandate explicit uncertainty acknowledgment:
When creating from a user prompt:
1. Mark all ambiguities with [NEEDS CLARIFICATION: specific question]
2. Don't guess - if unspecified, mark it
This prevents the common LLM failure mode of making plausible but incorrect assumptions. Instead of guessing authentication method, the LLM must write:
[NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
Templates include comprehensive checklists that function as "unit tests for specifications":
These checklists force systematic self-review by the LLM, catching gaps before they propagate to implementation.
The plan template enforces proper information architecture:
IMPORTANT: This implementation plan should remain high-level.
Detailed algorithms and code samples must go in implementation-details/ files
This prevents specifications from becoming unreadable code dumps. The LLM learns to maintain appropriate abstraction levels at each document.
Sources: spec-driven.md165-272 README.md408-489
At the core of SDD lies memory/constitution.md - an immutable document defining nine architectural principles that constrain all generated implementations.
The constitution enforces principles through three mechanisms:
The templates/plan-template.md includes Phase -1 pre-implementation gates:
When gates fail, justified exceptions must be documented:
The /speckit.plan command explicitly validates constitutional compliance by reading memory/constitution.md and checking the plan against each article before writing plan.md.
The constitution is designed to be immutable with a formal amendment process:
Section 4.2: Amendment Process
Modifications require:
- Explicit documentation of rationale
- Review by project maintainers
- Backwards compatibility assessment
This ensures consistency across time (code generated today follows same principles as code generated next year) and across LLMs (different AI models produce architecturally compatible code).
Sources: spec-driven.md274-407 Diagram 6, README.md574-575
The following diagram shows how different artifacts depend on each other and which code entities create or consume them:
| Artifact | Format | Owner | Mutability | Version Control |
|---|---|---|---|---|
memory/constitution.md | Markdown | Project maintainers | Immutable (amendable) | Yes |
templates/*.md | Markdown + YAML | Template maintainers | Evolving | Yes |
specs/NNN-*/spec.md | Markdown | Product/LLM | Versioned per feature | Yes (feature branch) |
specs/NNN-*/plan.md | Markdown | LLM | Versioned per feature | Yes (feature branch) |
specs/NNN-*/tasks.md | Markdown | LLM | Generated from plan | Yes (feature branch) |
| Agent context files | Markdown/TOML | Init/scripts | Generated | Yes (main branch) |
| Source code | Language-specific | LLM/Human | Generated + manual | Yes (feature branch) |
Sources: README.md441-459 README.md500-529 Diagram 1
SDD rejects one-shot code generation in favor of deliberate, multi-step refinement where each phase adds precision and reduces uncertainty.
Each phase serves a distinct purpose in reducing uncertainty:
Phase 1 (Specification): Captures intent without technical bias. Separating "what" from "how" prevents premature optimization and allows technology pivots without rewriting requirements.
Phase 2 (Clarification): Surfaces assumptions and ambiguities. Structured questioning by LLM identifies gaps that humans might overlook.
Phase 3 (Planning): Translates intent to architecture with constitutional validation. Technical decisions are made deliberately with documented rationale.
Phase 4 (Tasks): Decomposes plan into executable units. Dependency analysis ensures correct implementation order and identifies parallelization opportunities.
Phase 5 (Implementation): Executes tasks with test-first discipline. Incremental verification catches errors early.
| Aspect | One-Shot Generation | Multi-Step Refinement |
|---|---|---|
| Input | Single prompt | Structured phases |
| Quality Control | Post-generation review | Gates between phases |
| Error Detection | After full implementation | At each phase boundary |
| Rework Cost | High (entire regeneration) | Low (phase-specific fixes) |
| Constitutional Compliance | Hope and pray | Enforced at Phase -1 gates |
| Testability | Add tests after code | Tests before implementation |
| Traceability | Requirements → code gap | Requirements → plan → tasks → code chain |
Sources: spec-driven.md19-32 README.md408-615 Diagram 2
SDD incorporates continuous research to inform specifications with real-world technical constraints, performance characteristics, and organizational policies.
The specs/NNN-feature/research.md file captures:
Research occurs during planning when:
The LLM can spawn parallel research tasks to investigate specific questions without blocking main specification work.
Sources: spec-driven.md25-27 README.md530-557
SDD creates a continuous feedback loop where implementation reality informs specification evolution, closing the traditional gap between design and operation.
Metrics → Specifications:
Incidents → Plans:
plan.md: "Input validation middleware required"data-model.md with constraint validationsUser Feedback → Specifications:
This bidirectional flow transforms specifications from static documents into living artifacts that evolve with operational reality.
Sources: spec-driven.md30-32 spec-driven.md56-58
SDD supports generating multiple parallel implementations from the same specification, enabling creative exploration of different technical approaches without duplicating specification work.
This enables:
The specification remains the shared source of truth while implementations diverge based on different technical constraints or optimization targets.
Sources: spec-driven.md59-60 README.md288-293
Spec-Driven Development represents a fundamental shift in how software is built:
From Code-Centric to Spec-Centric: Code becomes the generated output that serves specifications, not the source of truth that specifications attempt to document.
From One-Shot to Multi-Step: Deliberate refinement through phases (constitution → specify → clarify → plan → tasks → implement) with validation gates replaces prompt-and-hope code generation.
From Guess-and-Fix to Explicit-Uncertainty: Templates force LLMs to acknowledge ambiguities with [NEEDS CLARIFICATION] markers rather than making plausible but incorrect assumptions.
From Hope-for-Quality to Constitutional-Enforcement: Nine immutable articles enforced through Phase -1 gates ensure generated code follows architectural principles.
From Static-Docs to Living-Artifacts: Specifications evolve continuously as operational reality (metrics, incidents, feedback) informs requirements.
From Single-Implementation to Parallel-Exploration: Same specification generates multiple implementations targeting different optimization goals or platforms.
The methodology transforms AI from creative code generators into disciplined specification engineers that respect constraints, acknowledge uncertainties, and produce architecturally sound implementations through structured transformation pipelines.
Sources: spec-driven.md1-73 README.md277-293 spec-driven.md408-413
Refresh this wiki