Spec Driven Development

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 them.

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, which is what turns a pivot into a systematic regeneration rather than a manual rewrite.

Quick Start

1. /sdd:init — create constitution.md (once per project, before any feature spec)
2. /sdd:research [description] — map how the existing code works, cited file:line (skip on greenfield)
3. Surface and correct the AI's implicit assumptions before any AC is written
4. /sdd:specify [description] — generate spec.md with MoSCoW-prioritized ACs
5. Follow the gates: Clarify → Plan → Tasks → Implement → Validate, with human approval at each

Step-by-step detail: 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
• Feature touches auth, data model, API contracts, or database schema

Skip entirely for: one-line fixes, typos, disposable prototypes, and solo exploration spikes lasting less than a day.

Choosing the Ceremony Level

Not every change deserves the same process. Pick the lightest level that covers the risk.

Decision rule: start at M. Drop to S only if all of these hold — one session, ≤3 files, no contract or schema change, trivially revertible. Move to L if any of these hold — auth or payments, irreversible data migration, regulated domain, or code nobody on the call has read.

Two failure modes, equally costly: L ceremony on an S change is where "drowning in markdown" comes from, and S ceremony on an L change is the reason this skill exists. The tiebreaker is reversibility, not size.

Levels are per change, not per project. Moving up mid-flight is normal — promoting S to M once a schema change appears. Moving down is not: it discards a gate you already decided you needed.

Key Practice: Reframe Vague Requirements

Before writing any AC, convert vague requirements into measurable targets — "make it faster" becomes "LCP < 2.5s on a 4G connection". If you cannot write a failing test for an AC, the AC is not concrete enough. Worked conversions: references/artifact-templates.md → Writing Concrete Acceptance Criteria.

Directory Structure

constitution.md            # Immutable project principles (one per project)

specs/
  [feature-branch-name]/
    research.md        # How the system works TODAY, cited file:line   (0.5)
    spec.md            # Requirements — WHAT and WHY, MoSCoW           (1)
    plan.md            # Implementation strategy — HOW                 (2)
    data-model.md      # Entities, relationships, schemas              (2)
    contracts/         # Interfaces — LOCKED after Gate 2              (2)
    tasks.md           # Atomic executable task list                   (3)
    progress.md        # Optional: state across context resets         (4)
    validation.md      # Traceability matrix                           (5)
    walkthrough.md     # Optional: narration for reviewers             (5)
    decision_log.md    # Optional: rationale for key decisions
  archive/             # Completed specs, kept after the feature ships

Every artifact is also a compaction checkpoint — a phase's messy exploration distilled into the only text the next phase needs to see.

Phase 0 — Constitution (one-time per project)

Invoke: /sdd:init → constitution.md at the project root.

A versioned document of immutable constraints applying to every feature: architecture principles, technology stack, security constraints, naming conventions, and explicitly banned patterns. AI agents are forbidden from violating it, and it is included in full in every implementation prompt.

Update only when a fundamental project decision changes — never per-feature.

Phase 0.5 — Research (conditional, per feature)

Invoke: /sdd:research [feature description] → specs/[feature]/research.md

A compacted map of how the relevant part of the system works today, written before any requirement is drafted.

Run it when the feature touches code you did not write or do not remember, several valid architectures exist, or the work is a refactor or migration. Skip it on greenfield code, or when you can name every touchpoint from memory.

Four rules:

• Cite file:line for every claim. A finding without a citation is a guess.
• Dispatch the noisy work to subagents. Glob, grep, and full-file reads run in isolated contexts; only the compacted summary returns.
• Describe what exists, never what should exist. Requirements belong to Phase 1.
• Cap it at ~200 lines. Past that it is a raw dump, not a compaction.

Why this phase has the highest leverage: reviewing ~200 lines of research prevents thousands of wrong lines of code; reviewing the code prevents one wrong line at a time. Gate R is the one gate where reading the actual code yourself is worth the time.

Details: references/workflow-phases.md → Phase 0.5.

5-Phase Workflow (per feature)

Every gate is a human approval point. AI cannot approve its own output. Full checklists for Gates 0, R, 1–5 and C live in references/quality-gates.md, along with /sdd:checklist [domain] — generated per-feature checklists that test the spec rather than the software.

Rules that are objectively decidable should stop being requests: a pre-write hook can make the contracts/ freeze real, and constitution.md can be derived into an AGENTS.md that tools read automatically. See references/enforcement.md — including what must not be mechanized.

One rule and one prohibition per phase

Phase 1 — Specify

Run the Assumptions Surface Prompt before generating spec.md, so implicit assumptions about roles, permissions, error behavior, and scope get corrected before they harden into acceptance criteria. If research.md exists, the spec must not contradict it.

spec.md carries: overview, user stories, Boundaries (Always do / Ask first / Never do), acceptance criteria in Given/When/Then with [MUST] [SHOULD] [COULD] [WONT], explicit out-of-scope items, and open questions. Error and edge-case ACs are required — the happy path alone never passes Gate 1.

Full spec or delta spec. Modifying behavior that already exists does not require respecifying it. A delta spec declares a baseline and then lists only what changes:

A delta spec's ACs are labelled [ADDED], [MODIFIED], [REMOVED], or [UNCHANGED] — the last one for behavior the change must not break. Its baseline is either a prior spec or, when none exists, the cited findings in research.md. A delta spec without a resolvable baseline is not reviewable — see references/workflow-phases.md → Delta Specs.

contracts/ freeze the moment Gate 2 passes. Step-by-step detail lives in references/workflow-phases.md; prompt formats (A for agents with file access, B for stateless interfaces) in references/prompt-patterns.md; formats for the traceability matrix, drift report, and walkthrough in references/output-formats.md.

Spec Drift

Drift occurs when AI makes "reasonable assumptions" that were never specified. Every rule above exists to remove one class of assumption: the constitution removes project-level ones, research removes assumptions about the existing system, clarify removes ambiguity before it becomes architecture, frozen contracts remove interface guesses, and one-context-per-task removes assumptions inherited from earlier work.

Two habits carry the rest: specificity beats verbosity — "returns 404 when the resource is not found" beats three paragraphs — and commit after every task, so drift is always one revert away.

Failure modes in detail: references/anti-patterns.md.

Context Is the Real Constraint

An AI agent is a stateless function: output quality is bounded by input quality. Every phase, gate, and artifact here is mechanically a decision about what enters that input.

• Every phase artifact is a compaction. research.md is what survives from reading forty files; plan.md is what survives from the research. Each is roughly a 95% reduction that keeps every decision-critical fact. Artifact length is therefore a quality signal — a 900-line spec has stopped compacting and started hoarding.
• Compact on purpose, not on overflow. Stay in the 40–60% utilization band. Auto-compaction triggered by exhaustion decides for you, under pressure, which details to lose.

Full model: references/ai-agent-patterns.md → Context Engineering.

Comprehension Debt

Specs defend against a failure mode unrelated to correctness: code that works and nobody understands. Agents generate code several times faster than humans read it, so teams merge sharply more pull requests while understanding measurably less of what they ship. The debt costs nothing until the first incident, onboarding, or refactor.

SDD only pays this back if the artifacts are actually read. Review the spec and plan rather than skimming the diff — that moves attention to ~400 high-density lines instead of ~2000 low-density ones. Keep specs in the same PR so the reviewer reads intent before mechanism, request a linear walkthrough after Phase 4, and archive specs instead of deleting them so the next person inherits the reasoning.

Gate C enforces this before merge.

Talking to the User

This workflow generates a lot of markdown, most of it for the next phase rather than the human. Confusing the two is how SDD earns its reputation for ceremony.

• Write artifacts to files. Show the human a verdict. Never paste a full artifact into the response when it was just written to disk.
• Verdict first, evidence second. Gate results, drift reports, and validation output all lead with pass/fail and the count, then the detail.
• Mark uncertainty as binary. [CONFIRMED] when verified against code or a cited artifact, [VERIFY] when inferred. Never invent a confidence percentage.
• Respect the line budgets. Every user-facing output in references/output-formats.md has one, along with its format.

Living Document

• When decisions change: run /sdd:amend — never patch files manually
• When code changed outside the workflow: run /sdd:reconcile
• Commit specs with code: spec files belong in the same PR as the implementation
• Version your specs: each spec.md carries a Status and Version header
• Archive when done: move completed specs to specs/archive/ after the feature ships

Three ways a spec and its code disagree

Confusing these is how specs quietly become fiction. The command differs, and so does which side gets edited:

/sdd:reconcile never edits anything on its own: it classifies each difference and proposes a direction, and a human approves each one. Auto-accepting its proposals turns it into a laundering machine for drift — see references/anti-patterns.md → Anti-Pattern 21.

Reference Index

All reference files are one level deep from here. Load only what the current phase needs.