Spec-Driven Development (SDD)
IMPORTANT
Spec-Driven Development is the transition from “Vibe Coding” to “Agentic Engineering.” It treats documentation as the primary source of truth and a formal contract for AI agents.
Overview
Spec-Driven Development (SDD) is a software development methodology where a detailed specification document is authored before any code generation occurs. In the context of Agentic Coding, SDD serves as the anchor that prevents “context drift” and ensures the AI agent adheres to architectural constraints and business requirements.
SDD vs. Vibe Coding
| Feature | Vibe Coding | Spec-Driven Development |
|---|---|---|
| Approach | Conversational / Experimental | Structured / Engineering-first |
| Source of Truth | Chat History | Specification Document |
| Predictability | Low (trial and error) | High (contract-based) |
| Scalability | Small scripts / UI tweaks | Complex, production systems |
| Control | AI-led (reactive) | Human-led (proactive) |
The SDD Lifecycle
- Specification: Creating a
spec.mddefining requirements, constraints, and acceptance criteria. - Technical Planning: Using an agent to generate a technical design (architecture, data flow) based on the spec.
- Task Decomposition: Breaking the design into modular, actionable steps.
- Execution: The agent implements tasks sequentially, referencing the spec at each step.
- Verification: Testing the output against the defined Acceptance Criteria.
Key Components in AI Environments
CLAUDE.md: Project-level rules and conventions that guide the agent’s behavior across all tasks.- Specification Files: Version-controlled Markdown files (e.g., in
/specs/) that document individual features. - Plan Mode: A state where the agent analyzes requirements and proposes changes without immediate execution.
- SubAgent Dispatch: Each task in the task list maps to a subagent invocation. The orchestrator assigns one subagent per spec task, keeping execution isolated and cost-bounded.
Benefits
- Traceability: Every code change can be traced back to a specific requirement.
- Consistency: Prevents the agent from hallucinating or ignoring established coding standards.
- Maintainability: The specifications serve as living documentation that stays in sync with the code.