SDD workflow

Spec-Driven Development (SDD)

SDD turns a feature request into a chain of files reviewers can inspect: spec.md, design.md, tasks.md, and evidence.md. The point is not heavier process. The point is to stop humans and AI agents from coding against assumptions nobody reviewed.

Copy SDD templates Compare SDD tools

Last updated: May 11, 2026

/.specs/refund-retry/
  spec.md
  design.md
  tasks.md
  evidence.md

# spec.md
Goal:
- Retry provider timeouts without duplicate refunds.

Non-goals:
- No new payment provider.

Acceptance:
- Given the same idempotency key is replayed
  When the refund endpoint receives it again
  Then return the existing refund_id.

The SDD artifact chain

Intentspec.mdDefines goal, non-goals, acceptance criteria, edge cases, and release evidence before implementation starts.

Designdesign.mdRecords architecture choices, rejected alternatives, interfaces, rollout order, and operational constraints.

Executiontasks.mdBreaks work into reviewable slices with owners, allowed files, acceptance links, and test commands.

Proofevidence.mdConnects criteria to tests, screenshots, logs, metrics, manual checks, and rollout stop signals.

Why SDD improves AI-assisted delivery

Failure mode	What SDD changes	Review signal
Vague prompt becomes broad diff	The spec states non-goals and allowed behavior before the agent starts.	Out-of-scope code can be rejected without debate.
Architecture is invented mid-generation	The design doc names interfaces, constraints, and rejected alternatives.	Generated code must follow the approved shape.
Large PR is hard to review	Tasks split implementation by acceptance criterion and file ownership.	Reviewers can inspect smaller, testable slices.
Approval is treated as proof	Evidence logs tie criteria to tests, screenshots, metrics, and rollout gates.	Merge review has something concrete to verify.

Copy-ready SDD templates

Change Proposal

Turn a vague request into a reviewable spec with goal, non-goals, criteria, open questions, and evidence.

Open template

Design Doc

Capture architecture choices, interfaces, constraints, rejected alternatives, rollout order, and rollback.

Open template

Tasks Plan

Split implementation into reviewable tasks with owners, allowed files, acceptance links, and test commands.

Open template

Evidence Log

Record tests, screenshots, logs, metrics, manual checks, and release stop signals against the spec.

Open template

AI Coding Review

Review generated code for spec alignment, file drift, missing tests, and behavior added outside scope.

Open template

Engineering Constitution

Define team rules for spec gates, evidence standards, AI coding boundaries, and exceptions.

Open template

SDD, spec-first, TDD, and BDD

Method	Primary question	Best used for
Spec-first development	What behavior should exist before code is written?	Clarifying product and engineering decisions before implementation.
Spec-driven development	Which repo artifacts should guide planning, coding, and evidence?	Coordinating humans and AI agents through reviewable files.
TDD	Which tests should drive implementation?	Proving units, contracts, and regressions during coding.
BDD	Which examples describe user-visible behavior?	Writing shared examples in business-readable language.

What current SDD tools teach

OpenSpec pattern

Keep the proposed change reviewable before code generation starts. The valuable idea is explicit change intent, not tool lock-in.

Superpowers pattern

Give coding agents durable skills and repo rules so repeated work follows the same standards instead of a fresh chat each time.

Spec Kit pattern

Move from specification to plan to task execution so AI-assisted implementation has a visible decision trail.

For the detailed comparison, read OpenSpec, Superpowers, and Spec Kit: SDD Patterns.

FAQ

What is spec-driven development?

Spec-driven development is a workflow where product behavior, constraints, implementation tasks, and verification evidence are written as reviewable artifacts before major code changes begin.

How is SDD different from spec-first development?

Spec-first development is the broad principle of writing behavior before code. SDD is a more explicit repo workflow that usually includes spec, design, tasks, and evidence files.

Does SDD replace TDD or BDD?

No. SDD decides the behavior and constraints first. TDD and BDD can then provide tests and examples that prove the spec was implemented correctly.

Why does SDD matter for AI coding?

AI coding agents need narrow instructions, non-goals, allowed files, and evidence requirements. SDD gives the agent a reviewable source of truth before it changes code.

What is the smallest useful SDD packet?

A small SDD packet can be one folder containing spec.md, tasks.md, and evidence.md. Add design.md when architecture choices or trade-offs need review.

Use the SDD templates on one real ticket first. Keep the packet small enough to review, but specific enough to stop implementation drift.

Start with spec.md Open AI governance