spec-driven-development

规范驱动开发（SDD）

此技能实现了 GitHub 的 SpecKit 方法论，用于开展结构化的 AI 辅助软件开发。SpecKit 通过系统化、分阶段的方法，将 规范转化为可执行产物，并内置质量关卡和多 Agent 协作机制。

核心理念

“规范成为可执行内容，可直接生成可运行的实现，而不只是为实现提供指导。”

何时使用此技能

• 启动需要结构化开发的新项目
• 协调多个 AI Agent 或开发者开发复杂功能
• 通过宪法治理确保质量一致
• 将复杂功能拆解为可管理的并行工作
• 防止在规范尚不明确时过早开始实现
• 对治理要求严格的企业项目
• 需要实时查看多个功能进展的团队

7 阶段工作流

阶段 0：项目初始化

目的： 创建项目结构并配置开发环境

产物：

• .specify/ 目录结构
• Git 仓库
• 自动化脚本
• 模板

主要操作：

• 设置目录结构
• 初始化版本控制
• 配置 AI Agent 偏好设置
• 生成脚本变体（bash/powershell）

阶段 1：宪法

目的： 建立项目治理和开发原则

产物： memory/constitution.md

核心原则：

1. 库优先原则： 每项功能都从独立库开始
2. CLI 接口要求： 所有库都必须提供基于文本的接口
3. 测试优先要求： 测试必须先于实现
4. 简洁与反抽象： 尽量降低复杂性
5. 集成优先测试： 优先选择真实的测试环境

版本控制： 语义化版本（MAJOR.MINOR.PATCH）

• MAJOR：不向后兼容的治理变更
• MINOR：新增原则或重大扩展
• PATCH：细微澄清或改进

协调机制： 交互式定义原则，并对所有产物进行验证

阶段 2：规范编写

目的： 创建详细的功能规范，聚焦于 WHAT 和 WHY，而非 HOW

产物： specs/[feature]/spec.md

必需章节：

• 功能分支名称（2-4 个词）
• 用户场景（按 P1、P2、P3 优先级排序）
• 验收场景（采用 Given/When/Then 格式）
• 边缘情况
• 功能需求（FR-XXX）
• 关键实体
• 成功标准（可衡量且与技术无关）

主要约束：

• 聚焦业务价值，而非实现
• 面向利益相关者编写，而非开发者
• 对关键未知项最多使用 3 个澄清标记
• 每个用户故事都必须可独立测试

质量关卡：

• 内容质量验证
• 需求完整性检查
• 功能就绪度评估
• 成功标准的可衡量性

阶段 3：澄清

目的： 系统地识别并消除规范中的歧义

产物： 更新 specs/[feature]/spec.md

澄清维度：

• 功能范围
• 数据模型
• 用户体验（UX）
• 非功能属性（性能、安全性等）
• 集成点

主要约束：

• 每次会话最多提出 5 个问题
• 采用多选题或简答题格式
• 聚焦影响重大且对实现至关重要的不确定事项
• 每次只问一个问题，逐步完善

协调机制： 通过交互式提问工作流，在每次回答后增量更新规范

阶段 4：规划

目的： 制定技术实现策略并解决技术未知项

子阶段：

阶段 0 - 研究：

• 识别并研究技术未知项
• 输出：research.md，其中所有不确定事项均已解决
• 关卡： 对尚未解决的澄清事项报错

阶段 1 - 设计：

• 创建数据模型和 API 契约
• 输出：data-model.md、契约架构、Agent 专属上下文

产物：

• specs/[feature]/plan.md
• specs/[feature]/research.md
• specs/[feature]/data-model.md
• specs/[feature]/contracts/

计划章节：

• 功能摘要
• 技术背景（语言、依赖项、平台）
• 项目结构
• 代码库布局
• 非标准方案的复杂度跟踪

阶段 5：分析

目的： 在实现前验证各产物之间的一致性

分析的产物：

• specs/[feature]/spec.md
• specs/[feature]/plan.md
• specs/[feature]/tasks.md

检测轮次：

1. 重复项
2. 歧义
3. 规定不充分的事项
4. 与章程冲突

输出： 按严重程度排序的分析报告（最多 50 项高价值问题）

关键约束：

• 只读操作（无法修改文件）
• 必须在任务拆分后运行
• 优先遵循章程原则

阶段 6：任务拆分

目的： 根据计划生成可执行且按依赖关系排序的任务列表

产物： specs/[feature]/tasks.md

任务结构：

• 用于跟踪完成情况的复选框
• 顺序任务 ID
• 可选的并行化标记（||）
• 用户故事标签（适用时为 P1、P2、P3）
• 精确的文件路径
• 清晰的描述

阶段结构：

1. 阶段 1： 项目设置
2. 阶段 2： 基础前置条件（阻塞项——必须在用户故事开始前完成）
3. 阶段 3+： 用户故事实现（按优先级排序：P1 → P2 → P3）
4. 最终阶段： 润色与跨领域关注事项

关键原则：

• 按用户故事对任务分组，以便独立实现
• 每个故事都可独立测试和交付
• 清晰跟踪依赖关系
• 明确标记可并行执行的任务
• 基础阶段完成前，不得开展任何用户故事工作

阶段 7：实现

目的： 通过内置验证按阶段执行实现

8 阶段流程：

1. 前置条件检查： 验证项目是否已就绪
2. 清单验证： 统计已完成和未完成项；如有未完成项，则要求确认
3. 上下文分析： 阅读必需产物（tasks.md、plan.md）及可选产物
4. 项目设置： 为检测到的技术创建或验证忽略文件
5. 任务处理： 解析任务，提取阶段、依赖关系和执行流程
6. 分阶段实现： 遵循 TDD 按阶段执行任务
7. 错误处理： 报告进度、处理失败并提供调试上下文
8. 最终验证： 确认完成情况、验证实现并检查测试覆盖率

编排： 通过内置检查和平衡机制进行系统化的多阶段执行

编排与并行执行

核心编排理念

按顺序推进各阶段；在依赖关系允许时，于阶段内并行执行。

协调机制

1. 基于阶段的关卡

• 每个阶段都必须完成并通过验证后，才能开始下一阶段
• 遇到错误或尚未解决的问题时，关卡会阻止继续推进
• 实现方式：模板验证、清单要求、章程一致性检查

2. 依赖关系跟踪

• 为任务标记依赖项，执行前必须先解决这些依赖
• 基础阶段会阻塞所有用户故事工作
• 任务会明确列出前置条件

3. 并行化标记

• 无依赖关系时，为可并行执行的任务明确添加标记
• 任务格式中可选的 || 标记
• 表示任务可以并发执行

4. 用户故事分组

• 按用户故事分组任务，以便独立并行实施
• 每个用户故事都可以独立测试和交付
• 支持多个 Agent／开发者同时工作

5. 宪章一致性

• 所有阶段都参考宪章，以保持实践一致
• 在所有命令中加载并验证宪章
• 确保并行工作流之间保持一致

并行执行模式

模式 1：用户故事并行化

基础阶段完成后，不同 Agent 可以并行实施用户故事（P1、P2、P3）

优点：

• 可独立测试
• 渐进式交付
• 减少阻塞
• 可扩展的团队协作

示例：

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

模式 2：任务级并行化

在一个阶段内，没有依赖关系的任务可以并行执行

示例：

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：多 Agent 协调

不同 AI Agent 可以使用共享的产物格式，分别处理不同方面

示例：

Feature "User Authentication":
├─ Claude: Generated spec.md and plan.md (reasoning strength)
├─ Copilot: Implemented auth endpoints (code generation)
└─ Gemini: Wrote integration tests (test coverage)

同步点

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

1. 宪章完成后： 后续所有工作都必须遵循原则
2. 规范完成后： 必须先解决所有待澄清事项，再进行规划
3. 规划研究完成后： 必须先解决所有未知事项，再进行设计
4. 任务完成后： 分析必须先完成验证，再开始实施
5. 基础任务完成后： 可以开始用户故事工作
6. 实施过程中： 清单验证未通过时，不得继续执行

Agent 协调模式

模式 1：模板驱动的交接

结构化 Markdown 模板可确保不同 AI Agent 使用一致的产物格式

优点： Agent 互操作性、文档一致性、减少歧义

模式 2：宪章对齐

宪章作为所有 Agent 和阶段共享的上下文

优点： 质量标准一致、行为可预测、团队／Agent 之间保持一致

模式 3：分阶段推进

按线性阶段推进，并在 Agent 之间设置明确的交接点

优点： 职责明确、减少混乱、设置质量关卡

模式 4：渐进式改进

在进入下一阶段前，迭代改进当前阶段的成果

优点： 产物质量更高、减少返工、及早发现错误

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

通过引用产物而非对话来传递上下文

优点： 无状态执行、恢复上下文、支持长周期项目

目录结构

.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

最佳实践

1. 尽早建立宪章，指导后续所有决策
2. 使用 clarify 命令，在规划前消除歧义
3. 在实施前运行 analyze 命令，及早发现问题
4. 组织用户故事，确保可独立测试
5. 使用 || 明确标记可并行执行的任务
6. 完整完成基础阶段，再开始用户故事工作
7. 在所有阶段保持与宪章一致
8. 在规范中使用具体、可衡量的成功标准
9. 在规范阶段避免涉及实施细节
10. 发挥多个 AI Agent 各自的优势

应避免的问题

1. 跳过澄清阶段会导致规范含糊不清
2. 在规范中过早加入实施细节会降低灵活性
3. 忽视宪章会导致实践不一致
4. 缺少适当的依赖跟踪就开展并行工作会引发冲突
5. 基础阶段不完整会阻碍所有用户故事工作
6. 实施前不运行 analyze 会导致在有缺陷的计划上浪费精力
7. 早期阶段过度规范会限制 AI Agent 的创造力
8. 成功标准不足会使验证流于主观
9. 不采用用户故事分组会限制并行化潜力

实施场景

场景 1：启动新项目

使用包含宪章治理的完整 7 阶段工作流，重点是在早期确立原则。

场景 2：拥有多位开发者 / Agent 的团队

强调用户故事的并行化和工作树隔离。使用仪表板实时查看进度。

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

制定全面的项目章程，纳入企业约束。强制要求在实施前进行分析。

场景 4：快速原型开发

通过详细规格说明统一愿景，但采用较轻量的规划。将用户故事拆分得较小，以便快速验证。

参考资料

基于 GitHub SpecKit（spec-kit）方法论，这是一个开源的规范驱动开发工具包，支持 15 种以上的 AI 编码 Agent，包括 Claude Code、GitHub Copilot、Gemini 和 Cursor。