Spec-Driven Development (SDD) Skill

This skill integrates PRD (Requirements) and SA (Analysis) knowledge, defining a standard development workflow. The core principle is "No Spec, No Code".

Core Principles

1. •Spec-First: Specs come before code
2. •Traceability: Every requirement can be traced to design and implementation
3. •Acceptance-Driven: Every requirement has verifiable acceptance criteria
4. •Version Control: Spec documents are version-controlled with change processes
5. •Living Documentation: Code changes must sync with spec updates to maintain consistency

Workflow Overview

flowchart LR
    A[User Request] --> B[PRD Phase]
    B --> C{Review}
    C -->|Approved| D[SA Phase]
    C -->|Rejected| B
    D --> E{Review}
    E -->|Approved| F[Implementation]
    E -->|Rejected| D
    F --> G[Verification]
    G -->|Pass| H[Done]
    G -->|Fail| F

Configuration

⚠️ Required: Before using this skill, customize the spec directory path to match your project structure.

By default, this skill references /docs/specs/ as the documentation location. Update paths in:

• •This file (sdd/SKILL.md)
• •sdd/references/tasks.md

Recommended Directory Structure

your-project/
├── docs/
│   └── specs/              ← Customize this path
│       ├── feature/
│       │   └── ISSUE-101_feature-name/
│       │       ├── PRD_spec.md
│       │       └── SA_spec.md
│       └── fix/
│           └── ISSUE-102_bug-name/
│               ├── PRD_spec.md
│               └── SA_spec.md

Core Workflow

This workflow uses a three-phase development model. All artifacts are stored in a configurable specs directory.

Phase 1: Product Requirement (PRD)

• •Goal: Define "What" and "Why".
• •File Location: {SPECS_DIR}/{type}/{ID-PREFIX}_{desc}/PRD_spec.md
• •Reference Skill: prd (See ../prd/SKILL.md)
• •Quick Guide: sdd/references/requirements.md
• •Key Content:
  • •User Stories (US-XX)
  • •Functional Requirements (FR-XX, EARS syntax)
  • •Acceptance Criteria (Given-When-Then) ⭐ Required
  • •Success Metrics / Out of Scope
• •Version Control: Use Version field (e.g., v1.0)

Phase 2: System Analysis (SA)

• •Goal: Define "How". Transform business requirements into technical specs.
• •File Location: {SPECS_DIR}/{type}/{ID-PREFIX}_{desc}/SA_spec.md
• •Reference Skill: sa (See ../sa/SKILL.md)
• •Quick Guide: sdd/references/design.md
• •Key Content:
  • •Requirement Traceability Matrix ⭐ Required
  • •System Architecture (Mermaid)
  • •API Specifications / Data Models
  • •Test Impact Analysis ⭐ Required
• •Version Control: Note the corresponding PRD version

Phase 3: Implementation

• •Goal: Execute tasks defined in the SA phase.
• •Reference Guide: sdd/references/tasks.md
• •Prerequisites: Both PRD and SA must be in Approved/Frozen status
• •Actions:
  • •Code based on SA_spec.md
  • •Sync: If implementation reveals design adjustments needed, must update SA/PRD first
  • •Verify against Acceptance Criteria from PRD_spec.md

Naming Convention

Directory name format: {ID_PREFIX}_{short-description}

ID_PREFIX has three types:

1. •ISSUE (Standard): Corresponds to GitHub Issue ID.
   • •Example: ISSUE-123_tab-groups
   • •Use: General feature development and bug fixes.
2. •PR (External): Corresponds to Pull Request ID (if no Issue exists).
   • •Example: PR-456_typo-fix
   • •Use: PRs submitted directly by external contributors.
3. •BASE (Baseline/Historical): Project initialization or retrospective specs.
   • •Example: BASE-001_initial-architecture
   • •Use: Historical debt or foundational architecture documents without corresponding Issues.

Directory Structure Example

{SPECS_DIR}/
  ├── feature/
  │    └── ISSUE-101_tab-groups/   <-- Standard Flow
  │         ├── PRD_spec.md
  │         └── SA_spec.md
  └── fix/
       └── BASE-002_sync-bug/      <-- Legacy/Baseline
            ├── PRD_spec.md
            └── SA_spec.md

Agent Operation Guide

When receiving a user task:

1. •Check Requirements: Determine if the task warrants full SDD process.
2. •Scaffold: Use mkdir -p to create the correct folder path.
3. •Draft PRD: Write PRD_spec.md, must include Acceptance Criteria.
4. •Review Gate: Request User Review, wait for approval.
5. •Draft SA: Write SA_spec.md, must include Requirement Traceability.
6. •Review Gate: Request User Review, wait for approval.
7. •Code: After approval, begin implementation.
8. •Verify: Verify against Acceptance Criteria.

Spec Change Process

After a Spec enters Frozen status, any changes require:

1. •Create new version (e.g., v1.0 → v1.1)
2. •Record change reason in Revision History
3. •Re-obtain Reviewer approval
4. •Update related Traceability Matrix

Skill Contents

sdd/
├── SKILL.md                           # This file - Orchestration workflow
└── references/
    ├── requirements.md                # Quick PRD reference
    ├── design.md                      # Quick SA reference
    └── tasks.md                       # Implementation task template

References