spec-driven-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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:

Library-First Principle: Every feature starts as a standalone library
CLI Interface Mandate: All libraries must have text-based interfaces
Test-First Imperative: Tests must precede implementation
Simplicity and Anti-Abstraction: Minimize complexity
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

核心原则：

优先库原则： 所有功能均以独立库的形式启动
CLI接口强制要求： 所有库必须具备文本交互接口
测试先行准则： 测试代码必须先于实现代码编写
简洁与反过度抽象： 最小化复杂度
集成优先测试： 优先采用贴近真实场景的测试环境

版本管理： 语义化版本（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:

Duplications
Ambiguities
Underspecified items
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
```

检测维度：

内容重复
表述歧义
规范缺失项
与章程冲突

产出物： 带有严重程度分级的分析报告（最多列出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:

Phase 1: Project Setup
Phase 2: Foundational Prerequisites (BLOCKING - must complete before user stories)
Phase 3+: User Story Implementation (priority order: P1 → P2 → P3)
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： 项目搭建
阶段2： 基础前置任务（阻塞型 - 必须在用户故事开发前完成）
阶段3及以后： 用户故事实现（按优先级排序：P1 → P2 → P3）
最终阶段： 优化与跨领域关注点处理

核心原则：

按用户故事分组任务，支持独立实现
每个用户故事均可独立测试和交付
清晰的依赖关系跟踪
明确的并行标记
基础阶段未完成前不得启动用户故事开发

Phase 7: Implementation

阶段7：落地实现

Purpose: Execute implementation phase-by-phase with built-in validation

8-Stage Process:

Prerequisite Checking: Validate project readiness
Checklist Validation: Count completed/incomplete items, require confirmation if incomplete
Context Analysis: Read required artifacts (tasks.md, plan.md) and optional ones
Project Setup: Create/verify ignore files for detected technologies
Task Processing: Parse tasks, extract phases, dependencies, execution flow
Phased Implementation: Execute tasks phase-by-phase following TDD
Error Handling: Report progress, handle failures, provide debugging context
Final Validation: Confirm completion, validate implementation, check test coverage

Orchestration: Systematic multi-stage execution with built-in checks and balances

目标： 分阶段执行实现流程，内置验证机制

8步执行流程：

前置检查： 验证项目就绪状态
清单验证： 统计已完成/未完成项，若存在未完成项需确认后再继续
上下文分析： 读取必填产出物（tasks.md、plan.md）及可选产出物
项目配置： 为检测到的技术栈创建/验证忽略文件
任务解析： 解析任务、提取阶段、依赖关系和执行流程
分阶段实现： 遵循TDD流程分阶段执行任务
错误处理： 汇报进度、处理失败并提供调试上下文
最终验证： 确认任务完成、验证实现效果、检查测试覆盖率

编排机制： 系统化的多阶段执行流程，内置校验与平衡机制

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:

After constitution: All subsequent work must align with principles
After specification: Clarifications must be resolved before planning
After planning research: All unknowns must be resolved before design
After tasks: Analysis must validate before implementation
After foundational tasks: User story work can begin
Within implementation: Checklist validation blocks execution

并行工作流必须同步的关键节点：

章程制定后： 后续所有工作必须与原则对齐
规范编写后： 必须先解决所有澄清问题才能进入规划阶段
规划调研后： 必须解决所有技术未知点才能进入设计阶段
任务拆解后： 必须先完成一致性分析才能进入实现阶段
基础任务完成后： 才能启动用户故事开发
实现过程中： 清单验证不通过会阻塞执行

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

最佳实践

Establish constitution early to guide all subsequent decisions
Use clarify command to resolve ambiguities before planning
Run analyze command before implementation to catch issues early
Structure user stories for independent testability
Mark parallelizable tasks explicitly with
```
||
```
Complete foundational phase fully before user story work
Maintain constitution alignment throughout all phases
Use specific, measurable success criteria in specifications
Avoid implementation details in specification phase
Leverage multiple AI agents for different strengths

尽早制定章程，为后续所有决策提供指导
使用clarify命令在规划前解决规范中的歧义
在实现前运行analyze命令，提前发现问题
结构化用户故事，确保可独立测试
用
||
明确标记可并行的任务
完整完成基础阶段后再启动用户故事开发
在所有阶段保持与章程的对齐
在规范中使用具体、可衡量的成功标准
在规范阶段避免涉及实现细节
利用多个AI Agent的优势分配不同工作

Pitfalls to Avoid

常见陷阱

Skipping clarification phase leads to ambiguous specifications
Premature implementation details in specs reduce flexibility
Ignoring constitution causes inconsistent practices
Parallel work without proper dependency tracking causes conflicts
Incomplete foundational phase blocks all user story work
Not running analyze before implementation wastes effort on flawed plans
Over-specification in early phases limits AI agent creativity
Insufficient success criteria make validation subjective
Not using user story grouping limits parallelization potential

跳过澄清阶段会导致规范存在歧义
规范中过早加入实现细节会降低灵活性
忽视章程会导致开发实践不一致
无依赖跟踪的并行工作会引发冲突
基础阶段未完成会阻塞所有用户故事开发
实现前不运行analyze会在有缺陷的规划上浪费精力
早期阶段过度规范会限制AI Agent的创造力
成功标准不明确会导致验证主观化
未按用户故事分组会限制并行开发潜力

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。