sdd

规范驱动开发（SDD）技能

引导用户使用 GitHub 的 Spec-Kit 进行规范驱动开发——这种方法颠覆了传统软件开发模式，使规范可执行，并可直接生成可运行的实现。

核心理念

规范驱动开发强调：

• 意图驱动开发：先定义“做什么”，再定义“怎么做”
• 创建丰富的规范：使用护栏和组织原则
• 多步迭代完善：不是一次性代码生成
• AI 原生：高度依赖先进的 AI 能力

请记住：这是一种 AI 原生开发。规范不仅仅是文档，而是可执行的产物，能够直接驱动实现。AI Agent 会根据规范中定义的意图生成可运行的代码。

快速决策树

这是一个新项目（从零开始）吗？

→ 请参阅 从零开始的工作流，了解完整的 6 步流程

这是一个现有代码库（棕地项目）吗？

→ 请参阅 棕地工作流，了解逆向工程和集成指南

需要安装帮助吗？

→ 请参阅 安装指南，了解设置和故障排除

快速开始安装

推荐方式（持久安装）：

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

一次性使用：

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

验证：

specify check

有关详细的安装选项、故障排除和环境变量，请参阅安装指南。

支持的 AI Agent

适用于：

• ✅ Claude Code
• ✅ GitHub Copilot
• ✅ Gemini CLI
• ✅ Cursor
• ✅ Qwen Code
• ✅ opencode
• ✅ Windsurf
• ✅ Kilo Code
• ✅ Auggie CLI
• ✅ CodeBuddy CLI
• ✅ Roo Code
• ✅ Codex CLI
• ✅ Amp
• ⚠️ Amazon Q Developer CLI（不支持为斜杠命令指定自定义参数）

产物摘要与反馈循环

关键工作流：任何 SDD 命令生成或修改产物后，都要自动执行以下反馈循环，以保持用户参与：

每条命令完成后

1. 检测产物变更

   • 确定创建或修改了哪些产物：
     • constitution.md（项目原则）
     • spec.md（需求规范）
     • plan.md（技术实施计划）
     • tasks.md（可执行的任务分解）
     • 棕地工作流生成的分析报告

2. 阅读并总结

   • 阅读相关产物
   • 提取关键信息：
     • 对于 constitution.md：核心原则、编码标准、约束
     • 对于 spec.md：主要需求、用户故事、成功标准
     • 对于 plan.md：技术栈选择、架构决策、里程碑
     • 对于 tasks.md：任务数量、主要任务类别、依赖关系
     • 对于分析报告：当前模式、技术债务、集成点

3. 提供结构化摘要（使用下面的 10 点模板）

   • 说明生成了什么以及原因
   • 突出最重要的决策及其理由
   • 包含质量指标和注意事项
   • 让摘要聚焦且可执行
   • 为各部分使用清晰的标题

4. 包含功能状态（混合方式）

   • 在每份摘要中简要说明状态
   • 按需通过 /speckit.status 查看详细状态
   • 请参阅下文的“功能状态跟踪”部分

5. 提供反馈选项

   • 选项 A：“看起来不错，继续下一步”
   • 选项 B：“我想修改[具体部分]”
   • 选项 C：“根据以下更改重新生成：[用户输入]”
   • 选项 D：“解释为什么做出了[具体决策]”

10 点摘要模板

任何 SDD 命令完成后，都使用以下结构化格式：

## ✅ [Command Name] Completed - Here's What Just Happened

### 🎯 Key Decisions Made (Top 3)
1. [Decision] - **Rationale:** [Why this was chosen]
2. [Decision] - **Rationale:** [Why this was chosen]
3. [Decision] - **Rationale:** [Why this was chosen]

### 📋 What Was Generated
- [Artifact 1]: [Brief description of content]
- [Artifact 2]: [Brief description of content]

### 🔍 Important Items to Review (Top 3)
1. [Critical item to check and why it matters]
2. [Important detail to verify and potential impact]
3. [Edge case to consider and how it affects the design]

### ⚠️ Watch Out For (Top 2)
- [Potential issue or gotcha] - **How to avoid:** [Guidance]
- [Common mistake] - **How to avoid:** [Guidance]

### 🔄 What This Enables Next (2 Options)
- **Option 1:** [Next step] - Best if: [Condition]
- **Option 2:** [Alternative step] - Best if: [Condition]

📊 **Feature Status:** [Current Feature Name] ([Stage]) → Next: [Next Feature]
   Progress: [●●●○○] [X]% | Completed: [N] of [Total] features | Dependencies: [Status]

**Your options:** [A] Proceed [B] Modify [C] Explain more [D] Show full status

示例：/speckit.specify 完成后的增强摘要

```

✅ Specify 已完成——以下是刚刚完成的内容

🎯 已做出的关键决策

1. 身份验证：JWT 令牌 - 原因：无状态架构、可水平扩展、符合行业标准
2. 密码要求：12 个或更多字符，且具有复杂性 - 原因：兼顾安全性（NIST 指南）与易用性
3. 会话超时：24 小时 - 原因：适用于 Web 应用的标准设置，兼顾安全性与用户便利性

📋 生成的内容

• `.speckit/features/user-auth/specify.md`：完整的需求，包含 5 个用户故事、8 项成功标准和 3 个边缘案例

🔍 需要重点检查的项目

1. 密码重置流程 - 确认电子邮件要求与您的基础设施（SMTP 服务器、模板）相符
2. 多因素身份验证 - 目前标记为“未来增强功能”；可能需要纳入 MVP
3. 速率限制 - 设置为每 15 分钟最多尝试登录 5 次；请确认这是否符合您的安全策略

⚠️ 注意事项

• 未指定电子邮件服务依赖项 - 避免方法：将电子邮件服务添加到 plan.md 依赖项中
• 用户数据的 GDPR 合规性 - 避免方法：检查数据保留和用户删除要求

🔄 接下来可进行的操作

• 选项 1： 运行 `/speckit.plan` 设计技术实现 - 最适合：需求看起来没问题时
• 选项 2： 修改 specify.md - 最适合：需要调整需求或添加功能时

📊 功能状态： user-authentication（已指定）→ 下一项：profile-management 进度：[●●○○○] 40% | 已完成：5 项功能中的 1 项 | 依赖项：database-setup ✅

您的选项： [A] 继续规划 [B] 修改需求 [C] 说明选择 JWT 的原因 [D] 显示完整状态 ```

何时跳过摘要

仅在以下情况跳过摘要步骤：

• 用户明确要求“跳过摘要”或“自动运行所有步骤”
• 未更改产物而重新运行命令
• 命令失败或产生错误（改为排查问题）

此工作流的优势

• 消除“黑箱”感： 清楚说明生成了什么以及原因
• 支持及早反馈： 在实现之前发现理解偏差
• 保持敏捷： 以结构化格式快速检查，而非冗长的审批流程
• 建立信任： 用户可以看到 AI 的推理过程和决策依据
• 提供上下文： 功能状态帮助用户了解项目整体进度

功能状态跟踪

混合方式

每次 SDD 命令执行后，在摘要中附上一行简要功能状态。用户通过 /speckit.status 按需查看详细状态。

简要状态行格式

在每份摘要末尾添加以下内容：

📊 **Feature Status:** [Current Feature Name] ([Stage]) → Next: [Next Feature Name]
   Progress: [●●●○○] [X]% | Completed: [N] of [Total] features | Dependencies: [Dep] ✅/⏸️

阶段值：

• Specifying（完成 20%）
• Planning（完成 40%）
• Tasking（完成 60%）
• In Progress（完成 80%）
• Complete（完成 100%）

进度指示器：

• 已完成阶段使用实心圆（●）
• 待处理阶段使用空心圆（○）
• 根据阶段计算百分比

详细状态面板

用户请求完整状态（选项 D）或运行 /speckit.status 时，显示：

📊 Project Feature Status Dashboard

🎯 CURRENT FEATURE
├─ [feature-name] ([Stage] - [X]% complete)
│  ├─ ✅ Requirements specified
│  ├─ 🔄 Implementation plan in progress
│  ├─ ⏸️  Tasks not started
│  └─ ⏸️  Implementation not started
│  Blockers: [None | Description]
│  Dependencies: [feature-name] ✅

✅ COMPLETED FEATURES ([N])
├─ [feature-1] (100% complete)
└─ [feature-2] (100% complete)

📋 UPCOMING FEATURES ([N])
├─ [feature-3] (depends on: [current-feature])
└─ [feature-4] (depends on: [feature-3])

⚠️  BLOCKED FEATURES ([N])
[List any features that are blocked with reasons]

自然语言功能管理

Claude 应自动检测并处理自然语言功能管理请求：

用户说：“将功能 XYZ 移到 ABC 之前” Claude 执行：

1. 从 .speckit/features/ 读取当前功能列表
2. 显示带编号的当前顺序
3. 提出新的顺序
4. 请求确认
5. 更新宪章或计划中的功能优先级／顺序
6. 显示更新后的状态仪表板

用户说：“添加一个电子邮件通知功能” Claude 执行：

1. 检测到新功能请求
2. 提出澄清问题（优先级、依赖项、描述）
3. 生成功能规范大纲
4. 将其插入功能列表中的适当位置
5. 显示更新后的状态仪表板

用户说：“我们先做 profile-management” Claude 执行：

1. 确定当前功能顺序
2. 提议将 profile-management 移至最高优先级
3. 根据需要调整依赖项
4. 更新产物
5. 显示更新后的状态

检测模式：

• “将 [功能] 移到 [其他功能] 之前／之后” → 重新排序
• “添加 [功能]” → 添加新功能
• “我们先做 [功能]” → 将其移至最高优先级
• “暂时跳过 [功能]” → 标记为延期
• “我们完成了 [功能]” → 将状态更新为已完成 -“哪些功能依赖于 [功能]？”→ 显示依赖关系树
• “显示功能状态” → 显示完整仪表板

快速功能操作

在用户请求时，引导他们完成以下操作：

添加功能：

User: "Add a feature for admin dashboard"
Claude:
1. What's the priority? (High/Medium/Low)
2. What features does this depend on? (user-auth, profile-management, etc.)
3. Brief description?
[Creates outline, shows updated status]

重新排序功能：

User: "Reorder features"
Claude:
Current order:
1. user-authentication
2. profile-management
3. admin-dashboard
4. email-notifications
5. reporting

How would you like to reorder? (provide new numbers or describe changes)
[Updates order, shows new status]

移除功能：

User: "Remove the reporting feature"
Claude:
⚠️  Warning: This will remove 'reporting' feature.
Dependencies affected: None
Are you sure? (yes/no)
[If yes: removes, updates status]

进度计算

根据 SDD 工作流完成情况自动计算进度：

阶段	进度	指标
已编写规范	20%	存在 specify.md
已制定计划	40%	存在 plan.md
已分解任务	60%	存在 tasks.md
进行中	80%	已开始实现（代码文件已修改）
已完成	100%	实现完成，测试通过

依赖项跟踪

跟踪并可视化依赖项：

显示依赖项：

user-authentication
├─ Depends on: database-setup ✅
└─ Blocks: profile-management ⏸️, admin-dashboard ⏸️

检查是否就绪：

📊 Can we start profile-management?
   Checking dependencies...
   ✅ user-authentication (complete)
   ✅ database-setup (complete)

   All dependencies satisfied! Ready to proceed.

检测循环依赖：

⚠️  Warning: Circular dependency detected
   feature-A depends on feature-B
   feature-B depends on feature-C
   feature-C depends on feature-A

   Please resolve this before proceeding.

与工作流集成

对于 Greenfield 项目：

• 执行 /speckit.specify 后，询问是否有多个功能
• 如果有，列出这些功能并跟踪各项进度
• 每次命令执行后显示状态

对于 Brownfield 项目：

• 执行 /speckit.reverse-engineer 后，根据发现的功能创建功能列表
• 将新功能与已有文档记录的功能分开跟踪
• 显示对状态的集成影响

如需完整的功能管理指南，请参阅 功能管理指南。

如何使用此技能

用户询问 SDD 时

1. 说明核心理念：可执行规范、意图驱动、AI 原生
2. 确认先决条件：`uv`、Python 3.11+、Git、AI Agent
3. 确定项目类型：新项目（Greenfield）或现有项目（Brownfield）
4. 引导用户使用相应工作流：
   • Greenfield → Greenfield 工作流
   • Brownfield → Brownfield 工作流

用户想要启动新项目时

1. 引导安装 → 安装指南
2. 初始化项目： ```bash specify init my-project --ai claude ```
3. 遵循 Greenfield 工作流 → Greenfield 工作流
4. 每个步骤之后：总结产物并征求用户反馈

用户已有代码库时

1. 检查是否存在 `.speckit/` 目录
2. 如果不存在 → 引导用户完成 Brownfield 工作流：
   • 分析现有代码
   • 根据现有模式生成宪章
   • 选择产物生成策略
   • 使用 SDD 添加新功能
3. 如果存在 → 根据当前进度确定下一步
4. 每个步骤之后：总结产物并征求用户反馈

当用户想要添加功能时

对于全新项目：

1. 前往 全新项目工作流
2. 按照步骤 3-6 操作（指定 → 规划 → 任务 → 实现）
3. 在继续之前总结每项产物

对于棕地／现有项目：

1. 前往 棕地工作流
2. 按照步骤 6-7 操作（指定 → 集成规划 → 任务 → 实现）
3. 在继续之前总结每项产物

当用户遇到问题时

1. 安装问题 → 查看安装指南中的故障排除部分
2. 工作流问题 → 查看相应的工作流指南：
   • 全新项目故障排除
   • 棕地项目故障排除
3. 功能检测 → 设置 `SPECIFY_FEATURE` 环境变量（参见安装指南）

工作流概览

全新项目（新项目）

``` specify init → /speckit.constitution → [SUMMARIZE] → /speckit.specify → [SUMMARIZE] → /speckit.plan → [SUMMARIZE] → /speckit.tasks → [SUMMARIZE] → /speckit.implement ```

完整详情： 全新项目工作流

棕地项目（现有项目）

``` specify init --here → /speckit.brownfield → [SUMMARIZE] → /speckit.analyze-codebase → [SUMMARIZE] → /speckit.reverse-engineer → [SUMMARIZE] → /speckit.specify → [SUMMARIZE] → /speckit.integration-plan → [SUMMARIZE] → /speckit.tasks → [SUMMARIZE] → /speckit.implement ```

完整详情： 棕地工作流

支持的开发阶段

从 0 到 1 的开发（“全新项目”）

从高层需求入手，从头生成规范，规划实现步骤，构建可用于生产环境的应用。

→ 全新项目工作流

迭代式增强（“棕地项目”）

在现有代码库中逐步添加功能，改造旧系统，使流程适应不断变化的需求，并将现有代码逆向工程为 SDD 格式。

→ 棕地工作流

创意探索

并行探索多种解决方案，支持多种技术栈和架构，尝试不同的 UX 模式。

→ 全新项目工作流 - 多技术栈探索部分

关键命令参考

安装与设置

```bash specify init # 新项目 specify init --here --force # 现有项目 specify check # 验证安装 ```

全新项目工作流

``` /speckit.constitution # 项目原则 → SUMMARIZE /speckit.specify # 定义需求 → SUMMARIZE /speckit.plan # 技术规划 → SUMMARIZE /speckit.tasks # 拆分任务 → SUMMARIZE /speckit.implement # 执行 ```

棕地项目工作流

``` /speckit.brownfield # 分析现有代码 → SUMMARIZE /speckit.analyze-codebase # 深入分析并制定原则 → SUMMARIZE /speckit.reverse-engineer # 记录现有功能 → SUMMARIZE /speckit.integration-plan # 规划新功能集成 → SUMMARIZE ```

可选增强命令

``` /speckit.clarify # 澄清模糊的需求 /speckit.analyze # 检查各产物间的一致性 /speckit.checklist # 生成质量检查清单 ```

分析脚本

SDD 技能包含用于深入质量验证和进度跟踪的分析脚本：

scripts/phase_summary.sh

生成 tasks.md 文件中所有阶段的综合进度报告：

• 显示每个阶段的完成百分比
• 列出每个阶段的待办任务
• 突出显示已简化／修改的任务
• 提供整体进度统计
• 支持任何 SDD 功能的 tasks.md 文件

用法：

~/.claude/skills/sdd/scripts/phase_summary.sh specs/003-keyboard-shortcuts/tasks.md

**输出：**按阶段划分的 Markdown 格式进度报告，包含：

• 每个阶段的完成百分比
• 待办任务列表（每个阶段最多 5 项）
• 简化任务警告
• 整体功能进度摘要

使用时机：

• 检查任何 SDD 功能的进度
• 快速了解已完成和待办事项
• 找出需要关注的阶段
• 为利益相关方生成状态报告

scripts/analyze-requirements.py

分析 spec.md 和 tasks.md 中的需求覆盖情况：

• 将功能需求（FR-001、FR-002 等）映射到实现任务
• 找出未覆盖的需求（任务覆盖缺口）
• 标记缺少可衡量标准的模糊需求
• 计算覆盖百分比

用法：

python3 ~/.claude/skills/sdd/scripts/analyze-requirements.py

**输出：**包含覆盖指标、未覆盖需求和模糊需求的 JSON

scripts/analyze-success-criteria.py

分析成功标准的验证覆盖情况：

• 将成功标准（SC-001、SC-002 等）映射到验证任务
• 验证每项标准是否可衡量
• 找出没有对应验证任务的标准
• 按指标类型分组（性能、无障碍、可用性）

用法：

python3 ~/.claude/skills/sdd/scripts/analyze-success-criteria.py

**输出：**包含覆盖摘要和验证任务映射的 JSON

scripts/analyze-edge-cases.py

分析规格说明中的边界情况覆盖情况：

• 将边界情况映射到明确覆盖它们的任务
• 找出隐式覆盖的情况（由通用逻辑处理）
• 标记需要关注但尚未覆盖的边界情况
• 按覆盖类型分类（EXPLICIT、IMPLICIT、UNCOVERED）

用法：

python3 ~/.claude/skills/sdd/scripts/analyze-edge-cases.py

**输出：**包含覆盖情况细分和未覆盖边界情况详情的 JSON

使用时机： 这些脚本会在 /speckit.analyze 期间自动调用，以进行深入的一致性验证。它们有助于找出：

• 未被任务覆盖的需求
• 未经过验证的成功标准
• 需要测试覆盖的边界情况
• 需要澄清的模糊需求

验证命令（已有代码库）

/speckit.validate-reverse-engineering  # 验证规格说明的准确性
/speckit.coverage-check                # 检查文档覆盖情况
/speckit.validate-constitution         # 验证章程的一致性
/speckit.trace [feature]               # 将规格说明映射到代码

详细文档

• 安装指南：安装方法、故障排除、环境变量
• Greenfield 工作流：新项目的完整 6 步工作流
• Brownfield 工作流：现有代码库的完整 7 步工作流

与其他技能集成

此技能适用于与以下技能搭配使用：

• project-memory：记录 SDD 决策和模式
• design-doc-mermaid：将 plan.md 中的架构可视化
• github-workflows：自动验证 SDD 工件
• code-quality-reviewer：审查生成的实现

资源

• GitHub Spec-Kit 仓库：https://github.com/github/spec-kit
• 问题／支持：https://github.com/github/spec-kit/issues
• 许可证：MIT

维护者

• Den Delimarsky (@localden)
• John Lam (@jflam)