Spec-Driven Development (SDD) Standard

Spec-Driven Development · PRD → spec.md → plan.md → task.md → code

In the AI era, the tech lead first turns a PRD into a clear spec, and the Agent then plans, breaks down, and executes code based on that spec.

Version: v1.0 ｜ Date: 2026-06-01 ｜ Status: Draft / Reviewable

1. Core Definition

In this document, SDD means Spec-Driven Development, not the traditional Software Design Document. It emphasizes: convert requirements into a reviewable, executable spec first, then let the Agent generate the plan, tasks, and code according to that spec.

The core of SDD is not "let the AI write code directly" — it's establishing a stable delivery chain:

1. The product manager or business side provides the PRD / requirement input.
2. The tech lead converts the PRD into spec.md, making clear what to do, why, the acceptance criteria, and the boundaries.
3. The Agent generates plan.md from spec.md, filling in architecture, data, interfaces, exceptions, and risk plans.
4. The Agent breaks plan.md into task.md, turning the plan into step-by-step executable tasks.
5. The Agent executes automatically per task.md, while developers review, build, and release at key checkpoints.

1.1 Role Boundaries

2. The "Truth" Inversion in the AI Era

The core idea: the tech lead writes the spec from the PRD, and the Agent generates code from the spec.

2.1 Key Principles

• The spec matters more than a one-off prompt. A prompt can trigger an action; the spec constrains the result.
• Code is not the first artifact — spec.md / plan.md / task.md are the reviewable, reusable, traceable deliverables.
• People own intent, boundaries, judgment, and acceptance; the Agent owns information gathering, plan generation, task decomposition, and repeated execution.
• Every stage must have a review point. When a review fails, go back to the previous stage and fix the spec, rather than hacking the code.

3. SDD Workflow

3.1 Standard Flow

3.2 Loop Rules

• Requirement unclear: return to intent definition, extend spec.md.
• Plan unstable: return to technical planning, extend plan.md.
• Task not executable: return to task decomposition, refine task.md.
• Code doesn't meet expectations: return to automated execution, fix per task; if a design error is found, update plan.md in sync.
• Anywhere implementation and docs diverge, the corresponding doc must be updated before merging.

4. The Four SDD Stages

4.1 Stage Descriptions

4.2 Definition of Done per Stage

5. Artifact Standards

Recommended unified directory:

docs/sdd/<feature-name>/spec.md
docs/sdd/<feature-name>/plan.md
docs/sdd/<feature-name>/task.md
docs/sdd/<feature-name>/review.md

5.1 spec.md: Intent Definition Doc

Purpose: answer "what to do, why, and to what extent". spec.md is the single requirement basis for the later plan.md and task.md.

• Must include: background, goals, non-goals, user scenarios, feature scope, acceptance criteria, constraints, risks, and open questions.
• Must not include: unconfirmed implementation details, subjective descriptions without acceptance criteria, ad-hoc verbal agreements.
• Quality bar: someone who didn't join the discussion can, after reading spec.md, judge whether the feature is built correctly.

5.2 plan.md: Technical Planning Doc

Purpose: answer "how to do it, why this way, and what to do on failure". plan.md is the design basis for task decomposition and code execution.

• Must include: overall architecture, module boundaries, data design, interface design, state transitions, exception/degradation, security/permissions, performance/capacity, deployment config, compatibility/migration, and rollback plan.
• Must state the reason for each technical choice — no empty phrases like "adopt an advanced architecture".
• Quality bar: another developer can independently break down tasks after reading plan.md.

5.3 task.md: Task Decomposition Doc

Purpose: answer "step-by-step how". task.md must be small enough, clear enough, executable, and verifiable.

• Each task achieves exactly one clear goal.
• Each task must state its input, files to modify, execution steps, acceptance criteria, and test command.
• Tasks must be ordered, and prerequisites must be written clearly.
• If the plan turns out unreasonable during execution, pause and write back to plan.md rather than forcing code through.

5.4 Code Artifacts: Execution Results

• Code commits must be traceable to a task number in task.md.
• Every PR must link spec.md, plan.md, task.md.
• When implementation and docs diverge, update the docs first, then merge the code.
• Must include the necessary tests, build results, and rollback notes.

6. Review Gates

6.1 Hard Rules

• No spec.md, no technical planning.
• No plan.md, no splitting task.md.
• No task.md, no automated code execution by the Agent.
• Docs that haven't passed review cannot be input to a downstream stage.
• Before going live, you must be able to trace code → task, task → plan, plan → requirement.

7. Agent Collaboration Standard

7.1 Input Package Requirements

• Requirement input: PRD, issue, user story, screenshots, or acceptance criteria.
• Code context: repo path, tech stack, key directories, existing interfaces, existing data structures.
• Constraints: what must not change, compatibility requirements, performance requirements, security requirements, launch deadline.
• Output requirement: this round outputs only one of spec.md / plan.md / task.md / code — no mixing across stages.

7.2 Staged Prompt Templates

# Stage 1: Generate spec.md
Generate spec.md based on the following PRD.
Requirement: clarify only "what to do" and "why"; do not write concrete code.
Must include: background, goals, non-goals, user scenarios, acceptance criteria, constraints, risks, open questions.

# Stage 2: Generate plan.md
Generate plan.md based on the confirmed spec.md.
Requirement: explain how to implement it and justify the technical choices.
Must include: architecture, modules, data, interfaces, state, exceptions, permissions, security, performance, deployment, rollback, test plan.

# Stage 3: Generate task.md
Break down task.md based on the confirmed plan.md.
Requirement: every task must be small, executable, and acceptable.
Each task includes: id, goal, input, files to modify, execution steps, acceptance criteria, test command, rollback notes.

# Stage 4: Automated execution
Execute top-to-bottom per task.md.
Rules: run one task at a time; run the corresponding tests after each; if plan.md is unreasonable, pause and state which design points need updating.

7.3 Agent Output Constraints

• On unclear requirements, ask first — never guess.
• When generating plan.md, list alternatives and the rationale for the trade-off.
• When generating task.md, avoid "mega-tasks" — e.g. "complete the entire backend" is not acceptable.
• When executing code, update task status and keep test results.
• Any automatic change must stay within the current task's scope; no incidental refactoring of unrelated modules.

8. Team Adoption Standard

8.1 Repository Layout

docs/
  sdd/
    <feature-name>/
      spec.md       # intent definition
      plan.md       # technical planning
      task.md       # task decomposition
      review.md     # review record, optional
src/
  ...
tests/
  ...

8.2 Naming Conventions

8.3 State Transitions

8.4 PR Rules

• The PR description must include the paths of the linked spec.md, plan.md, task.md.
• The PR description must list the completed task numbers.
• The PR must include the test commands and results.
• Changes involving databases, permissions, billing, payments, updates, or state machines must add a rollback plan.

9. SDD Review Checklist

9.1 One-Sentence Pass Bar

A developer who didn't join the early discussion can, after reading spec.md, plan.md, and task.md, know why it's being done, how, in what order, how to test, how to launch, and how to roll back on failure.

Appendix A: Templates

A.1 spec.md Template

# <feature-name> spec.md
Status: Draft / Reviewing / Approved
Author:
Linked PRD / Issue:
Created:
Last updated:

## 1. Background
- Current problem:
- Business impact:
- Why now:

## 2. Goals
- Goal 1:
- Goal 2:

## 3. Non-Goals
- Out of scope this cycle:

## 4. User Scenarios
- Scenario 1: As a <user>, I want <capability> so that <value>.

## 5. Feature Scope
- Features:
- Boundaries:

## 6. Acceptance Criteria
- AC1:
- AC2:

## 7. Constraints & Risks
- Constraints:
- Risks:

## 8. Open Questions
- Q1:

A.2 plan.md Template

# <feature-name> plan.md
Status: Draft / Reviewing / Approved
Input: spec.md

## 1. Overall Plan
- Summary:
- Tech choices:
- Trade-off rationale:

## 2. Architecture & Modules
- Module A: responsibilities / not responsible for
- Module B: responsibilities / not responsible for

## 3. Data Design
- Schema:
- Indexes:
- Migration:
- Rollback:

## 4. Interface Design
- API:
- Request params:
- Response structure:
- Error codes:

## 5. State Transitions
- State definitions:
- State machine:

## 6. Exceptions & Degradation
- Timeout:
- Retry:
- Degradation:

## 7. Security & Permissions
- Identity source:
- Permission rules:
- Privilege-escalation risks:

## 8. Test Plan
- Unit tests:
- Integration tests:
- Regression tests:

## 9. Launch & Rollback
- Launch steps:
- Monitoring metrics:
- Rollback plan:

A.3 task.md Template

# <feature-name> task.md
Status: Draft / Reviewing / Approved / Implementing / Done
Input: plan.md

## Execution Rules
- Run one task at a time.
- Run the corresponding tests after each task.
- If the design is unreasonable, pause and write back to plan.md.

## Task List

### T01 <task-name>
- Goal:
- Prerequisites:
- Input:
- Files to modify:
- Execution steps:
  1.
  2.
- Acceptance criteria:
- Test command:
- Rollback notes:
- Status: Todo / Doing / Done

### T02 <task-name>
- Goal:
- Prerequisites:
- Input:
- Files to modify:
- Execution steps:
- Acceptance criteria:
- Test command:
- Rollback notes:
- Status: Todo