Back to Details

spec-driven-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec-Driven Development (SDD)

Spec-Driven Development (SDD)

This skill implements GitHub's SpecKit methodology for structured, AI-assisted software development. SpecKit transforms specifications into executable artifacts through a systematic, phase-based approach with built-in quality gates and multi-agent coordination.
本Skill实现了基于GitHub SpecKit方法论的结构化AI辅助软件开发流程。SpecKit通过系统化的分阶段方法，将规范转化为可执行工件，内置质量关卡和多Agent协调机制。

Core Philosophy

核心理念

"Specifications become executable, directly generating working implementations rather than just guiding them."
"规范即执行，直接生成可运行的实现，而非仅作为指导。"

When to Use This Skill

适用场景

  • Starting new projects that require structured development
  • Coordinating multiple AI agents or developers on complex features
  • Ensuring consistent quality through constitutional governance
  • Breaking down complex features into manageable, parallel work
  • Preventing premature implementation before clear specifications
  • Enterprise projects with strict governance requirements
  • Teams needing real-time visibility across multiple features
  • 启动需要结构化开发流程的新项目
  • 协调多个AI Agent或开发人员开发复杂功能
  • 通过章程治理保障一致的开发质量
  • 将复杂功能拆解为可并行处理的可管理模块
  • 避免在规范明确前过早开展实现工作
  • 有严格治理要求的企业级项目
  • 需要实时掌握多功能开发进度的团队

The 7-Phase Workflow

7阶段工作流

Phase 0: Project Initialization

阶段0：项目初始化

Purpose: Create project structure and configure development environment
Artifacts:
  • .specify/
    directory structure
  • Git repository
  • Automation scripts
  • Templates
Key Actions:
  • Set up directory structure
  • Initialize version control
  • Configure AI agent preferences
  • Generate script variants (bash/powershell)
目标： 创建项目结构并配置开发环境
产出物：
  • .specify/
    目录结构
  • Git仓库
  • 自动化脚本
  • 模板文件
关键动作：
  • 搭建目录结构
  • 初始化版本控制
  • 配置AI Agent偏好设置
  • 生成多版本脚本（Bash/PowerShell）

Phase 1: Constitution

阶段1：章程制定

Purpose: Establish project governance and development principles
Artifact: 
memory/constitution.md
Core Principles:
  1. Library-First Principle: Every feature starts as a standalone library
  2. CLI Interface Mandate: All libraries must have text-based interfaces
  3. Test-First Imperative: Tests must precede implementation
  4. Simplicity and Anti-Abstraction: Minimize complexity
  5. Integration-First Testing: Prioritize realistic testing environments
Versioning: Semantic versioning (MAJOR.MINOR.PATCH)
  • MAJOR: Backward-incompatible governance changes
  • MINOR: New principles or material expansions
  • PATCH: Minor clarifications or refinements
Orchestration: Interactive principle definition with validation across all artifacts
目标： 确立项目治理规则和开发原则
产出物： 
memory/constitution.md
核心原则：
  1. 优先库原则： 所有功能均以独立库的形式启动
  2. CLI接口强制要求： 所有库必须具备文本交互接口
  3. 测试先行准则： 测试代码必须先于实现代码编写
  4. 简洁与反过度抽象： 最小化复杂度
  5. 集成优先测试： 优先采用贴近真实场景的测试环境
版本管理： 语义化版本（MAJOR.MINOR.PATCH）
  • MAJOR：不兼容的治理规则变更
  • MINOR：新增原则或重大扩展
  • PATCH：细节澄清或微小调整
编排机制： 交互式原则定义，同步验证所有产出物的一致性

Phase 2: Specification

阶段2：规范编写

Purpose: Create detailed feature specifications focused on WHAT and WHY, not HOW
Artifact: 
specs/[feature]/spec.md
Required Sections:
  • Feature branch name (2-4 words)
  • User scenarios (P1, P2, P3 prioritized)
  • Acceptance scenarios (Given/When/Then format)
  • Edge cases
  • Functional requirements (FR-XXX)
  • Key entities
  • Success criteria (measurable, technology-agnostic)
Key Constraints:
  • Focus on business value, not implementation
  • Write for stakeholders, not developers
  • Maximum 3 clarification markers for critical unknowns
  • Each user story must be independently testable
Quality Gates:
  • Content quality validation
  • Requirement completeness check
  • Feature readiness assessment
  • Success criteria measurability
目标： 聚焦于WHAT和WHY而非HOW，编写详细的功能规范
产出物： 
specs/[feature]/spec.md
必填章节：
  • 功能分支名称（2-4个单词）
  • 用户场景（按P1、P2、P3优先级排序）
  • 验收场景（Given/When/Then格式）
  • 边缘情况
  • 功能需求（FR-XXX编号格式）
  • 核心实体
  • 成功标准（可衡量、技术无关）
关键约束：
  • 聚焦业务价值，而非实现细节
  • 面向利益相关者编写，而非仅面向开发人员
  • 关键未知点最多标注3个澄清标记
  • 每个用户故事必须可独立测试
质量关卡：
  • 内容质量验证
  • 需求完整性检查
  • 功能就绪度评估
  • 成功标准可衡量性验证

Phase 3: Clarification

阶段3：澄清优化

Purpose: Systematically identify and resolve ambiguities in specifications
Artifact: Updates 
specs/[feature]/spec.md
Clarification Dimensions:
  • Functional scope
  • Data model
  • User experience (UX)
  • Non-functional attributes (performance, security, etc.)
  • Integration points
Key Constraints:
  • Maximum 5 questions per session
  • Multiple-choice or short-answer format
  • Focus on high-impact, implementation-critical uncertainties
  • One question at a time for iterative refinement
Orchestration: Interactive questioning workflow with incremental spec updates after each answer
目标： 系统性识别并解决规范中的歧义点
产出物： 更新后的 
specs/[feature]/spec.md
澄清维度：
  • 功能范围
  • 数据模型
  • 用户体验（UX）
  • 非功能属性（性能、安全等）
  • 集成对接点
关键约束：
  • 每次会话最多提出5个问题
  • 采用选择题或简答题形式
  • 聚焦高影响、对实现至关重要的不确定性问题
  • 每次只提出一个问题，逐步迭代优化
编排机制： 交互式提问工作流，每得到一个答案后就增量更新规范

Phase 4: Planning

阶段4：规划设计

Purpose: Create technical implementation strategy and resolve technical unknowns
Sub-Phases:
Phase 0 - Research:
  • Identify and research technical unknowns
  • Output: 
    research.md
    with all uncertainties resolved
  • Gate: ERROR on unresolved clarifications
Phase 1 - Design:
  • Create data models and API contracts
  • Outputs: 
    data-model.md
    , contract schemas, agent-specific context
Artifacts:
  • specs/[feature]/plan.md
  • specs/[feature]/research.md
  • specs/[feature]/data-model.md
  • specs/[feature]/contracts/
Plan Sections:
  • Feature summary
  • Technical context (language, dependencies, platform)
  • Project structure
  • Repository layout
  • Complexity tracking for non-standard approaches
目标： 制定技术实现策略并解决技术未知点
子阶段：
子阶段0 - 调研：
  • 识别并调研技术未知点
  • 产出物：
    research.md
    （需解决所有不确定性）
  • 关卡： 若存在未解决的澄清问题则触发ERROR
子阶段1 - 设计：
  • 创建数据模型和API契约
  • 产出物：
    data-model.md
    、契约Schema、Agent专属上下文
产出物汇总：
  • specs/[feature]/plan.md
  • specs/[feature]/research.md
  • specs/[feature]/data-model.md
  • specs/[feature]/contracts/
规划文档章节：
  • 功能概述
  • 技术上下文（开发语言、依赖项、平台）
  • 项目结构
  • 仓库布局
  • 非标准实现方案的复杂度跟踪

Phase 5: Analysis

阶段5：一致性分析

Purpose: Validate cross-artifact consistency before implementation
Artifacts Analyzed:
  • specs/[feature]/spec.md
  • specs/[feature]/plan.md
  • specs/[feature]/tasks.md
Detection Passes:
  1. Duplications
  2. Ambiguities
  3. Underspecified items
  4. Constitution conflicts
Output: Analysis report with severity-ranked findings (max 50 high-signal issues)
Key Constraints:
  • Read-only operation (cannot modify files)
  • Must run after task breakdown
  • Prioritizes constitution principles
目标： 在实现前验证跨产出物的一致性
分析对象：
  • specs/[feature]/spec.md
  • specs/[feature]/plan.md
  • specs/[feature]/tasks.md
检测维度：
  1. 内容重复
  2. 表述歧义
  3. 规范缺失项
  4. 与章程冲突
产出物： 带有严重程度分级的分析报告（最多列出50个高价值问题）
关键约束：
  • 只读操作（不可修改文件）
  • 必须在任务拆解完成后执行
  • 优先遵循章程原则

Phase 6: Task Breakdown

阶段6：任务拆解

Purpose: Generate actionable, dependency-ordered task list from plan
Artifact: 
specs/[feature]/tasks.md
Task Structure:
  • Checkbox for completion tracking
  • Sequential Task ID
  • Optional parallelization marker (
    ||
    )
  • Story label (P1, P2, P3 when applicable)
  • Precise file path
  • Clear description
Phase Structure:
  1. Phase 1: Project Setup
  2. Phase 2: Foundational Prerequisites (BLOCKING - must complete before user stories)
  3. Phase 3+: User Story Implementation (priority order: P1 → P2 → P3)
  4. Final Phase: Polish & Cross-Cutting Concerns
Key Principles:
  • Tasks grouped by user story for independent implementation
  • Each story independently testable and deliverable
  • Clear dependency tracking
  • Explicit parallelization markers
  • No user story work until foundational phase complete
目标： 根据规划文档生成可执行、按依赖排序的任务列表
产出物： 
specs/[feature]/tasks.md
任务结构：
  • 完成状态复选框
  • 顺序任务ID
  • 可选并行标记（
    ||
    ）
  • 故事优先级标签（适用时标注P1、P2、P3）
  • 精确文件路径
  • 清晰的任务描述
阶段划分：
  1. 阶段1： 项目搭建
  2. 阶段2： 基础前置任务（阻塞型 - 必须在用户故事开发前完成）
  3. 阶段3及以后： 用户故事实现（按优先级排序：P1 → P2 → P3）
  4. 最终阶段： 优化与跨领域关注点处理
核心原则：
  • 按用户故事分组任务，支持独立实现
  • 每个用户故事均可独立测试和交付
  • 清晰的依赖关系跟踪
  • 明确的并行标记
  • 基础阶段未完成前不得启动用户故事开发

Phase 7: Implementation

阶段7：落地实现

Purpose: Execute implementation phase-by-phase with built-in validation
8-Stage Process:
  1. Prerequisite Checking: Validate project readiness
  2. Checklist Validation: Count completed/incomplete items, require confirmation if incomplete
  3. Context Analysis: Read required artifacts (tasks.md, plan.md) and optional ones
  4. Project Setup: Create/verify ignore files for detected technologies
  5. Task Processing: Parse tasks, extract phases, dependencies, execution flow
  6. Phased Implementation: Execute tasks phase-by-phase following TDD
  7. Error Handling: Report progress, handle failures, provide debugging context
  8. Final Validation: Confirm completion, validate implementation, check test coverage
Orchestration: Systematic multi-stage execution with built-in checks and balances
目标： 分阶段执行实现流程，内置验证机制
8步执行流程：
  1. 前置检查： 验证项目就绪状态
  2. 清单验证： 统计已完成/未完成项，若存在未完成项需确认后再继续
  3. 上下文分析： 读取必填产出物（tasks.md、plan.md）及可选产出物
  4. 项目配置： 为检测到的技术栈创建/验证忽略文件
  5. 任务解析： 解析任务、提取阶段、依赖关系和执行流程
  6. 分阶段实现： 遵循TDD流程分阶段执行任务
  7. 错误处理： 汇报进度、处理失败并提供调试上下文
  8. 最终验证： 确认任务完成、验证实现效果、检查测试覆盖率
编排机制： 系统化的多阶段执行流程，内置校验与平衡机制

Orchestration & Parallel Execution

编排与并行执行

Core Orchestration Philosophy

核心编排理念

Sequential phase progression with parallel execution within phases where dependencies allow.
按阶段顺序推进，在阶段内允许无依赖的任务并行执行。

Coordination Mechanisms

协调机制

1. Phase-Based Gates

1. 阶段关卡

  • Each phase must complete and validate before next phase begins
  • Gates block on errors or unresolved issues
  • Implementation: Template validation, checklist requirements, constitution alignment checks
  • 每个阶段必须完成并通过验证后才能进入下一阶段
  • 关卡会因错误或未解决问题而阻塞流程
  • 实现方式：模板验证、清单要求、章程一致性检查

2. Dependency Tracking

2. 依赖跟踪

  • Tasks marked with dependencies that must be resolved before execution
  • Foundational phase blocks all user story work
  • Tasks reference prerequisites explicitly
  • 任务标记有必须先解决的依赖项
  • 基础阶段会阻塞所有用户故事开发任务
  • 任务明确引用前置依赖

3. Parallelization Markers

3. 并行标记

  • Tasks explicitly marked for parallel execution when no dependencies exist
  • Optional 
    ||
    marker in task format
  • Indicates tasks can run concurrently
  • 无依赖的任务会被明确标记为可并行执行
  • 任务格式中使用可选的
    ||
    标记
  • 表示任务可同时执行

4. User Story Grouping

4. 用户故事分组

  • Tasks grouped by user story for independent, parallel implementation
  • Each user story is independently testable and deliverable
  • Enables multiple agents/developers to work simultaneously
  • 任务按用户故事分组，支持独立并行实现
  • 每个用户故事均可独立测试和交付
  • 支持多个Agent/开发人员同时工作

5. Constitutional Consistency

5. 章程一致性

  • All phases reference constitution to maintain consistent practices
  • Constitution loaded and validated across all commands
  • Ensures alignment across parallel work streams
  • 所有阶段均参考章程以保持实践一致性
  • 章程会在所有命令中加载并验证
  • 确保并行工作流的对齐

Parallel Execution Patterns

并行执行模式

Pattern 1: User Story Parallelization

模式1：用户故事并行

After foundational phase completes, user stories (P1, P2, P3) can be implemented in parallel by different agents
Benefits:
  • Independent testability
  • Incremental delivery
  • Reduced blocking
  • Scalable team coordination
Example:
Foundation: ✓ Project setup, database schema, auth framework

Parallel Work:
├─ Agent 1: P1 Story - User registration flow
├─ Agent 2: P1 Story - User login flow
└─ Agent 3: P2 Story - Profile management
基础阶段完成后，不同Agent可并行实现用户故事（P1、P2、P3）
优势：
  • 独立可测试性
  • 增量交付
  • 减少阻塞
  • 团队协作可扩展性
示例：
基础阶段：✓ 项目搭建、数据库Schema、认证框架

并行工作：
├─ Agent 1: P1 故事 - 用户注册流程
├─ Agent 2: P1 故事 - 用户登录流程
└─ Agent 3: P2 故事 - 个人资料管理

Pattern 2: Task-Level Parallelization

模式2：任务级并行

Within a phase, tasks without dependencies can execute concurrently
Example:
Phase 3: P1 User Registration
├─ [ ] T3.1 || Create user model (tests/models/test_user.py)
├─ [ ] T3.2 || Create registration endpoint (tests/api/test_register.py)
└─ [ ] T3.3 || Create validation service (tests/services/test_validation.py)
在同一阶段内，无依赖的任务可同时执行
示例：
阶段3：P1 用户注册
├─ [ ] T3.1 || 创建用户模型 (tests/models/test_user.py)
├─ [ ] T3.2 || 创建注册接口 (tests/api/test_register.py)
└─ [ ] T3.3 || 创建验证服务 (tests/services/test_validation.py)

Pattern 3: Multi-Agent Coordination

模式3：多Agent协作

Different AI agents can work on different aspects using shared artifact format
Example:
Feature "User Authentication":
├─ Claude: Generated spec.md and plan.md (reasoning strength)
├─ Copilot: Implemented auth endpoints (code generation)
└─ Gemini: Wrote integration tests (test coverage)
不同AI Agent可基于统一的产出物格式，负责不同的工作环节
示例：
功能「用户认证」：
├─ Claude: 生成spec.md和plan.md（擅长逻辑推理）
├─ Copilot: 实现认证接口（擅长代码生成）
└─ Gemini: 编写集成测试（擅长测试覆盖）

Synchronization Points

同步节点

Critical points where parallel work must synchronize:
  1. After constitution: All subsequent work must align with principles
  2. After specification: Clarifications must be resolved before planning
  3. After planning research: All unknowns must be resolved before design
  4. After tasks: Analysis must validate before implementation
  5. After foundational tasks: User story work can begin
  6. Within implementation: Checklist validation blocks execution
并行工作流必须同步的关键节点：
  1. 章程制定后： 后续所有工作必须与原则对齐
  2. 规范编写后： 必须先解决所有澄清问题才能进入规划阶段
  3. 规划调研后： 必须解决所有技术未知点才能进入设计阶段
  4. 任务拆解后： 必须先完成一致性分析才能进入实现阶段
  5. 基础任务完成后： 才能启动用户故事开发
  6. 实现过程中： 清单验证不通过会阻塞执行

Agent Coordination Patterns

Agent协作模式

Pattern 1: Template-Driven Handoffs

模式1：模板驱动交接

Structured markdown templates ensure consistent artifact format across different AI agents
Benefits: Agent interoperability, consistent documentation, reduced ambiguity
结构化Markdown模板确保不同AI Agent产出的格式一致
优势： Agent互操作性、文档一致性、减少歧义

Pattern 2: Constitutional Alignment

模式2：章程对齐

Constitution acts as shared context across all agents and phases
Benefits: Consistent quality standards, predictable behavior, alignment across team/agents
章程作为所有Agent和阶段的共享上下文
优势： 一致的质量标准、可预测的行为、跨团队/Agent的对齐

Pattern 3: Phased Progression

模式3：分阶段推进

Linear phase progression with clear handoff points between agents
Benefits: Clear responsibilities, reduced confusion, quality gates
线性阶段推进，Agent间有明确的交接节点
优势： 清晰的职责划分、减少混乱、质量关卡保障

Pattern 4: Incremental Refinement

模式4：迭代优化

Iterative improvement within phases before moving forward
Benefits: Higher quality artifacts, reduced rework, early error detection
在进入下一阶段前，在当前阶段内进行迭代改进
优势： 更高质量的产出物、减少返工、提前发现错误

Pattern 5: Artifact-Driven Context

模式5：产出物驱动上下文

Context passed through artifact references rather than conversation
Benefits: Stateless execution, context recovery, long-running projects
通过产出物引用传递上下文，而非依赖对话
优势： 无状态执行、上下文可恢复、支持长期运行的项目

Directory Structure

目录结构

.specify/
├── memory/
│   └── constitution.md          # Project governance and principles
├── scripts/
│   ├── *.sh                     # Bash automation scripts
│   └── *.ps1                    # PowerShell automation scripts
├── specs/
│   └── [feature-name]/
│       ├── spec.md              # Feature specification
│       ├── plan.md              # Technical implementation plan
│       ├── tasks.md             # Actionable task breakdown
│       ├── research.md          # Research findings (optional)
│       ├── data-model.md        # Data structure design (optional)
│       ├── quickstart.md        # Getting started (optional)
│       └── contracts/           # API/interface definitions (optional)
└── templates/                   # Command and artifact templates
.specify/
├── memory/
│   └── constitution.md          # 项目治理规则与原则
├── scripts/
│   ├── *.sh                     # Bash自动化脚本
│   └── *.ps1                    # PowerShell自动化脚本
├── specs/
│   └── [feature-name]/
│       ├── spec.md              # 功能规范
│       ├── plan.md              # 技术实现规划
│       ├── tasks.md             # 可执行任务拆解
│       ├── research.md          # 调研结果（可选）
│       ├── data-model.md        # 数据结构设计（可选）
│       ├── quickstart.md        # 快速入门指南（可选）
│       └── contracts/           # API/接口定义（可选）
└── templates/                   # 命令与产出物模板

Best Practices

最佳实践

  1. Establish constitution early to guide all subsequent decisions
  2. Use clarify command to resolve ambiguities before planning
  3. Run analyze command before implementation to catch issues early
  4. Structure user stories for independent testability
  5. Mark parallelizable tasks explicitly with 
    ||
  6. Complete foundational phase fully before user story work
  7. Maintain constitution alignment throughout all phases
  8. Use specific, measurable success criteria in specifications
  9. Avoid implementation details in specification phase
  10. Leverage multiple AI agents for different strengths
  1. 尽早制定章程，为后续所有决策提供指导
  2. 使用clarify命令在规划前解决规范中的歧义
  3. 在实现前运行analyze命令，提前发现问题
  4. 结构化用户故事，确保可独立测试
  5. 用
    ||
    明确标记可并行的任务
  6. 完整完成基础阶段后再启动用户故事开发
  7. 在所有阶段保持与章程的对齐
  8. 在规范中使用具体、可衡量的成功标准
  9. 在规范阶段避免涉及实现细节
  10. 利用多个AI Agent的优势分配不同工作

Pitfalls to Avoid

常见陷阱

  1. Skipping clarification phase leads to ambiguous specifications
  2. Premature implementation details in specs reduce flexibility
  3. Ignoring constitution causes inconsistent practices
  4. Parallel work without proper dependency tracking causes conflicts
  5. Incomplete foundational phase blocks all user story work
  6. Not running analyze before implementation wastes effort on flawed plans
  7. Over-specification in early phases limits AI agent creativity
  8. Insufficient success criteria make validation subjective
  9. Not using user story grouping limits parallelization potential
  1. 跳过澄清阶段会导致规范存在歧义
  2. 规范中过早加入实现细节会降低灵活性
  3. 忽视章程会导致开发实践不一致
  4. 无依赖跟踪的并行工作会引发冲突
  5. 基础阶段未完成会阻塞所有用户故事开发
  6. 实现前不运行analyze会在有缺陷的规划上浪费精力
  7. 早期阶段过度规范会限制AI Agent的创造力
  8. 成功标准不明确会导致验证主观化
  9. 未按用户故事分组会限制并行开发潜力

Implementation Scenarios

落地场景

Scenario 1: Starting a New Project

场景1：启动新项目

Use full 7-phase workflow with constitutional governance. Focus on establishing principles early.
采用完整的7阶段工作流和章程治理，重点是尽早确立原则。

Scenario 2: Team with Multiple Developers/Agents

场景2：多开发人员/Agent团队

Emphasize user story parallelization and worktree isolation. Use dashboard for real-time visibility.
重点关注用户故事并行和工作区隔离，使用仪表盘实时掌握进度。

Scenario 3: Enterprise with Governance Requirements

场景3：有治理要求的企业项目

Comprehensive constitution with enterprise constraints. Mandate analysis phase before implementation.
制定包含企业约束的全面章程，强制要求在实现前执行分析阶段。

Scenario 4: Rapid Prototyping

场景4：快速原型开发

Detailed specifications to align on vision, but lighter planning. Small user stories for quick validation.
编写详细规范对齐愿景，但简化规划流程，采用小型用户故事快速验证。

References

参考资料

Based on GitHub SpecKit (spec-kit) methodology - an open-source toolkit for Spec-Driven Development supporting 15+ AI coding agents including Claude Code, GitHub Copilot, Gemini, and Cursor.
基于GitHub SpecKit（spec-kit）方法论构建，这是一个支持规范驱动开发的开源工具包，兼容15+ AI编码Agent，包括Claude Code、GitHub Copilot、Gemini和Cursor。