spec-driven-development

---
name: spec-driven-development
description: >
  Use when starting features, projects, or refactors with AI coding agents and requirements feel
  informal, incomplete, or drift-prone. Triggers: AI generates code that ignores constraints,
  same prompt produces different implementations across sessions, team lacks shared technical
  understanding, complex features need traceable design decisions, or vibe-coding produces
  unreliable output. Keywords: spec-driven, SDD, specification-first, requirements.md, plan.md,
  tasks.md, constitution.md, design doc, PRD, acceptance criteria, MoSCoW, drift detection,
  AI planning, feature spec, context drift, hallucination, constrained generation,
  boundaries, risks-identification, assumption-surface, living-document.
---

# Spec-Driven Development

## Overview

SDD makes **specifications the source of truth** — code serves specs, not the other way around.
Instead of prompting an AI with vague descriptions and hoping for the right output, you define
precise specifications first, then let AI generate code strictly constrained by those specs.

Core principle: *"When specifications drive implementation, pivots become systematic
regenerations rather than manual rewrites."*

Why it works: without a spec, AI makes thousands of micro-decisions silently. With a spec,
those decisions are made by you — explicitly, before any code is written.

### Spec Levels

| Level | What it means | Best for |
|-------|--------------|---------|
| **Spec-first** | Write spec upfront, implement immediately | Most features |
| **Spec-anchored** | Maintain spec alongside code as it evolves | Long-lived features |
| **Spec-as-source** | Spec is primary; code is generated, never hand-edited | Experimental, high-compliance |

Start with spec-first. Move to spec-anchored when the feature stabilizes.

## Quick Start

New to SDD? Four steps to your first spec-driven feature:

1. **Create your constitution** (once per project):
   `/sdd:init` — run this first, before any feature specs

2. **Surface AI assumptions** (before specifying):
   Ask the AI to list its implicit assumptions about roles, permissions, error behavior,
   and scope — then correct them before any AC is written

3. **Specify your first feature:**
   `/sdd:specify [brief description]` — generates `spec.md` with MoSCoW-prioritized ACs

4. **Follow the gates:**
   Clarify → Plan → Tasks → Implement → Validate
   Human approval required at each gate before the next phase

For detailed step-by-step instructions, see `references/workflow-phases.md`.

---

## When to Use

Symptoms that signal SDD is needed:

- AI ignores constraints or generates code that doesn't match requirements
- Same prompt produces different implementations across sessions
- Requirements are complex with multiple stakeholders or cross-cutting concerns
- Team needs shared technical understanding before writing code
- Previous "just build it" attempts produced wrong architecture
- Feature touches auth, data model, API contracts, or database schema

**Skip SDD for:**

- One-line fixes, typos, trivial bugs
- Disposable prototypes where requirements will immediately change
- Solo exploration spikes lasting less than a day

## Key Practice: Reframe Vague Requirements

Before writing any AC, convert vague requirements into measurable targets:

| Vague | Concrete |
|-------|---------|
| "make it faster" | "LCP < 2.5s on a 4G connection" |
| "it should be secure" | "requires authenticated session; all inputs validated before processing" |
| "handle errors properly" | "returns 4xx with structured error code, never exposes stack traces" |
| "should scale" | "handles 1000 concurrent users at < 500ms p95" |
| "works correctly" | "Given X, When Y, Then Z — independently verifiable" |

If you cannot write a passing test for an AC, the AC is not concrete enough.

---

## Directory Structure

```
constitution.md              # Project-level: immutable principles (one per project)

specs/
  [feature-branch-name]/
    spec.md              # Requirements — WHAT and WHY (MoSCoW prioritized)
    plan.md              # Implementation strategy — HOW
    data-model.md        # Data entities, relationships, schemas
    contracts/           # API endpoints, events, interface definitions (LOCKED after Phase 2 approval)
    tasks.md             # Atomic executable task list
    research.md          # Optional: context and alternatives considered
    decision_log.md      # Optional: rationale for key decisions
  archive/               # Completed feature specs (move here after feature ships)
```

## Phase 0 — Constitution *(one-time per project)*

**Invoke:** `/sdd:init`

Creates `constitution.md` at the project root — a versioned document of immutable constraints
that applies to every feature. AI agents are strictly forbidden from violating it.

Contains:

- Coding standards and architecture principles
- Technology stack decisions (languages, frameworks, libraries)
- Security constraints (authentication model, input validation rules, CWE baseline)
- Naming conventions, file structure rules
- Explicit anti-patterns banned from this codebase

**When to update:** Only when a fundamental project decision changes. Not per-feature.

See `references/artifact-templates.md` for the `constitution.md` template.

---

## 5-Phase Workflow *(per feature)*

### Phase 1 — Specify

**Invoke:** `/sdd:specify [feature description]`

**Surface assumptions first** — before generating spec.md, run the Assumptions Surface
Prompt (see `references/prompt-patterns.md`). This forces the AI to make its implicit
assumptions about roles, permissions, error behavior, and scope explicit for human review
*before* they get baked into acceptance criteria.

Creates `specs/[feature]/spec.md` containing:

- Feature overview (1–2 sentences, non-technical)
- User stories: `As a [role] I want [goal] so that [benefit]`
- Feature-level AI behavior constraints (Boundaries: Always do / Ask first / Never do)
- Acceptance criteria (Given/When/Then) with MoSCoW priority: `[MUST]` / `[SHOULD]` / `[COULD]` / `[WONT]`
- Explicit out-of-scope boundaries
- Open questions marked `[NEEDS CLARIFICATION]`

**Clarify step** — before Gate 1, run the clarify prompts (see `references/prompt-patterns.md`):

- Resolve every `[NEEDS CLARIFICATION]` item
- Add ACs for all identified edge cases and error scenarios
- Run automated spec validation (vague terms, missing error coverage, untestable ACs)

**Human gate — review before Phase 2:**

- [ ] Every `[MUST]` AC is independently testable
- [ ] No implementation details in the spec (no "use PostgreSQL", no function names)
- [ ] No `[NEEDS CLARIFICATION]` items remain open
- [ ] Scope boundaries explicitly listed
- [ ] Error and edge case ACs exist (not just happy path)
- [ ] Spec passes automated validation (no vague terms like "fast", "secure", "works correctly")

See `references/artifact-templates.md` for the `spec.md` template.

---

### Phase 2 — Plan

**Invoke:** `/sdd:plan` (reads `spec.md` + `constitution.md`)

Creates in `specs/[feature]/`:

- `plan.md` — Technical architecture, component breakdown, technology choices, tradeoffs, risks
- `data-model.md` — Entities, fields, relationships, constraints, indexes
- `contracts/` — API endpoint definitions, request/response schemas, error codes, events

*If a `research.md` exists (pre-generated via parallel subagents before Phase 1), `/sdd:plan`
reads it as additional context. It is not generated by this command.*

**Human gate — review before Phase 3:**

- [ ] Plan is traceable: every `[MUST]` AC maps to at least one component
- [ ] Plan respects all constraints in `constitution.md`
- [ ] Data model covers all entities mentioned in spec
- [ ] API contracts are complete (inputs, outputs, all error codes)
- [ ] Migrations defined for any database schema changes (in `data-model.md`)
- [ ] Risks identified with mitigations for each High-impact item
- [ ] No unnecessary abstractions (use framework features directly)
- [ ] Technology choices use existing stack unless justified

See `references/artifact-templates.md` for templates.

---

### Phase 3 — Tasks

**Invoke:** `/sdd:tasks` (reads `plan.md` + `contracts/`)

Creates `specs/[feature]/tasks.md`:

- Atomic tasks — each corresponds to a single PR or commit
- Explicit dependencies between tasks
- Parallelizable tasks marked `[P]`
- Each implementation task paired with a test task (test-first)
- Complexity estimate per task: `S` / `M` / `L`

**Human gate — review before Phase 4:**

- [ ] Tasks are small enough for a single AI session (~30–60 min of work)
- [ ] Test tasks appear before their implementation counterparts
- [ ] No task modifies more than 3 files (split if so)
- [ ] Dependencies form a valid DAG (no cycles)

See `references/artifact-templates.md` for the `tasks.md` template.

---

### Phase 4 — Implement

Execute tasks from `tasks.md` sequentially (or in parallel where marked `[P]`).

**AI prompt pattern for each task** *(abbreviated — see `references/prompt-patterns.md` for Format A
with file access and Format B for stateless/web interfaces)*:

```
Implement: [task title from tasks.md]

Constrained by:
- constitution.md (project-level rules — never violate)
- Acceptance criteria: specs/[feature]/spec.md → [section]
- Feature boundaries: specs/[feature]/spec.md → Boundaries (if present)
- Technical design: specs/[feature]/plan.md → [section]
- API contract: specs/[feature]/contracts/[file].md
- Data model: specs/[feature]/data-model.md

Do NOT:
- Add functionality outside the scope of spec.md
- Deviate from the API signatures in contracts/
- Introduce abstractions not in plan.md
- Violate any rule in constitution.md or the Boundaries section
```

**Session hygiene:**

- Clear context between tasks to prevent conflicting information accumulation
- Commit after completing each task before starting the next
- If the AI deviates from the contract, correct immediately — do not accumulate drift

See `references/prompt-patterns.md` for full prompt examples.

---

### Phase 5 — Validate

**Invoke:** `/sdd:validate` (compares implementation to `spec.md` + `contracts/`)

Checks for spec drift:

- Do all `[MUST]` acceptance criteria have test coverage?
- Do implemented API signatures match `contracts/`?
- Does the database schema match `data-model.md`?
- Are there any fields, endpoints, or behaviors outside the defined scope?
- Does the implementation respect all constraints in `constitution.md`?

**Drift indicators (immediate action required):**

- Function signatures that differ from `contracts/`
- Database columns not in `data-model.md`
- Acceptance criteria with no corresponding test
- Functionality that appears in code but not in `spec.md`
- Constitution constraint violated
- Boundaries rule violated (Always do / Never do from spec.md)

See `references/quality-gates.md` for CI/CD integration patterns.

---

## Spec Drift: Why It Happens and How to Prevent It

Drift occurs when AI makes "reasonable assumptions" that weren't specified. Without a spec,
AI makes thousands of micro-decisions silently — each one a potential divergence from intent.

Prevention:

1. **Constitution first** — project-level constraints prevent drift at the root
2. **Surface assumptions before specifying** — wrong assumptions become wrong ACs become wrong code
3. **Clarify before planning** — unresolved ambiguities in spec.md become wrong architecture
4. **Specificity beats verbosity** — "returns 404 when resource not found" beats 3 paragraphs
5. **Lock contracts before implementation** — never modify `contracts/` during Phase 4
6. **One context per task** — a fresh AI session per task eliminates accumulated assumptions
7. **Commit gates** — only proceed to next task after current task passes tests

See `references/anti-patterns.md` for detailed failure modes.

---

## Living Document

Specs are not write-once artifacts. Keep them current:

- **When decisions change:** run `/sdd:amend` — never patch files manually
- **Commit specs with code:** include spec files in the same PR as the implementation they drive
- **Reference in PRs:** link to `specs/[feature]/spec.md` in your pull request description
- **Version your specs:** each spec.md carries a `Status` and `Version` header for auditability
- **Archive when done:** move completed specs to `specs/archive/` after the feature ships

Treating the spec as disposable after implementation defeats its purpose — it becomes
the source of truth for future changes, onboarding, and drift detection.

---

## Reference Index

| Need | File |
|------|------|
| Templates for all artifacts (incl. constitution.md) | `references/artifact-templates.md` |
| Prompts for each phase interaction | `references/prompt-patterns.md` |
| Detailed phase-by-phase instructions | `references/workflow-phases.md` |
| Review checklists and CI/CD integration | `references/quality-gates.md` |
| Multi-agent orchestration patterns | `references/ai-agent-patterns.md` |
| Common failure modes and fixes | `references/anti-patterns.md` |
| One-page cheat sheet | `references/quick-reference.md` |
| Topic navigation | `references/INDEX.md` |