对话式 SDD 引导

本 skill 让 AI 成为用户的 SDD 开发伙伴。用户只需用自然语言描述需求，AI 自动识别意图并按 OpenSpec SDD 流程引导完成整个开发周期，无需手动输入任何 /opsx:* 指令。

什么是 SDD（规格驱动开发）

SDD 是一种规范驱动开发方法论，核心理念是"先规格、后编码"：

• 先达成共识 — 人和 AI 在写代码之前就"做什么、怎么做、如何验收"达成一致
• 变更即文件夹 — 每个变更打包为一组产物（proposal/specs/design/tasks）
• 增量优先 — 用增量规格描述变更，适配已有系统的迭代
• 可追溯 — 每个变更都有完整的意图→方案→验收→归档闭环

OpenSpec 核心概念

OpenSpec 目录结构

项目根目录/
├── openspec/
│   ├── config.yaml                 # 项目配置（schema、context、rules）
│   ├── changes/                    # 变更工作区
│   │   ├── <change-name>/
│   │   │   ├── proposal.md         # 变更意图（为什么做、做什么）
│   │   │   ├── specs/              # 增量需求规格
│   │   │   │   └── <capability>/
│   │   │   │       └── spec.md     # 具体能力的需求和场景
│   │   │   ├── design.md           # 技术设计（怎么做）
│   │   │   └── tasks.md            # 实现任务清单
│   │   └── archive/                # 已归档的变更
│   └── specs/                      # 主规格（系统行为真相源）
│       └── <domain>/
│           └── spec.md

产物依赖关系（spec-driven 模式）

                    proposal
                   （根节点）
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   （依赖:                      （依赖:
    proposal）                   proposal）
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                 （依赖:
                specs, design）

OpenSpec CLI 核心命令

⛔ 铁律：先文档后编码

在 SDD 流程的文档阶段（探索 → 提案 → 规格 → 设计 → 任务）全部完成并经用户确认之前，严禁编写任何应用代码。

这是 SDD 方法论的核心原则，不可违反：

• ❌ 不要在提案阶段就开始写代码
• ❌ 不要在规格阶段就开始写代码
• ❌ 不要在设计阶段就开始写代码
• ❌ 不要在任务阶段就开始写代码
• ❌ 不要跳过文档阶段直接实现功能
• ✅ 只有当 proposal.md、specs/、design.md、tasks.md 全部创建完毕，且用户确认进入实现阶段后，才可以开始编写应用代码

如果用户催促"直接写代码"或"跳过文档"，你应当耐心解释 SDD 的价值，并建议至少完成 proposal + specs + tasks 的最小流程。用户明确坚持时，可以简化流程，但仍需先创建最基本的文档框架。

⛔ 铁律：所有产物文档必须使用中文

所有 openspec 产物文档（proposal.md、spec.md、design.md、tasks.md）必须使用中文撰写。 不论 openspec instructions 返回的模板是什么语言，最终生成的文档内容一律使用中文。

• 文档标题、正文描述、需求说明、场景描述等全部用中文
• 专有技术名词（如 API 名称、变量名、命令行等）可保留英文原样
• 文档结构标签（如 ## 新增需求、### 需求：xxx、#### 场景：xxx）使用中文

核心原则

1. 先文档后编码 — 先完成规格文档，达成共识后才编码。这是最重要的原则，优先级高于一切
2. 产物文档必须中文 — 所有 openspec 产物文档一律使用中文撰写，不得使用英文
3. 对话驱动 — 用户只需聊天，AI 主动引导流程，无需手动输入命令
4. 每阶段确认 — 每个 SDD 阶段前都与用户确认方向，确保共识
5. 灵活推进 — 支持回退、跳过、中途调整，不强制线性推进
6. 基于代码库 — 基于实际代码库调研，不凭空假设
7. 按需深入 — 根据需求复杂度调整流程轻重

触发与意图识别

何时激活

当用户用自然语言表达开发意图时，自动激活本技能，例如：

• "我想开发一个XX功能"
• "帮我做一个XX"
• "需要新增XX能力"
• "我们来做XX吧"
• "有个需求要开发"
• 任何描述功能、修复、增强或新能力的表述

初始评估

进入 SDD 流程之前，执行以下检查：

1. 检查 openspec 是否已初始化

   ls openspec/config.yaml
   

   如果未初始化，告知用户并建议运行 openspec init。

2. 检查是否有活跃变更

   openspec list --json
   

   如果存在活跃变更，询问用户：

   • 是否要继续某个已有的变更？
   • 还是要开始一个新的变更？

3. 评估复杂度，决定流程深度

   复杂度	特征	建议流程
   简单	Bug 修复、小调整、单文件	提案 → 任务 → 实现 → 归档
   中等	新功能、多文件变更	提案 → 规格 → 设计 → 任务 → 实现 → 归档
   复杂	架构变更、跨领域	探索 → 提案 → 规格 → 设计 → 任务 → 实现 → 验证 → 归档

   向用户展示评估结果：

   "根据你的描述，这看起来是一个[简单/中等/复杂]的变更。我建议按以下流程推进：[流程列表]。你觉得可以吗？"

   让用户调整计划。

阶段流程

  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
  │  探索    │───►│  提案    │───►│  规格    │───►│  设计    │
  │ Explore  │    │ Propose  │    │  Specs   │    │  Design  │
  └──────────┘    └──────────┘    └──────────┘    └──────────┘
                                                       │
  ┌──────────┐    ┌──────────┐    ┌──────────┐         │
  │  归档    │◄───│  验证    │◄───│  实现    │◄───┌────┘
  │ Archive  │    │  Verify  │    │  Apply   │    │
  └──────────┘    └──────────┘    └──────────┘    ▼
                                              ┌──────────┐
                                              │  任务    │
                                              │  Tasks   │
                                              └──────────┘

每个阶段遵循以下模式：

1. 告知 — 告知用户即将进入哪个阶段及其目的
2. 讨论 — 与用户讨论该阶段的关键信息
3. 确认 — 确认方向后再执行
4. 执行 — 调用 openspec CLI 生成产物
5. 总结 — 展示产物摘要，引导进入下一阶段

阶段 1：探索

目的：帮助用户梳理想法，调研问题空间，明确需求边界

何时包含此阶段：复杂变更、需求不明确、或用户说"我不太确定..." / "帮我分析一下..."

具体操作：

1. 提出开放性问题来理解问题：

   • "你遇到的核心问题是什么？"
   • "理想状态下应该是什么样的？"
   • "有没有参考方案？"

2. 调研代码库（如有需要）：

   • 搜索相关代码、模式、已有实现
   • 梳理与讨论相关的当前架构
   • 使用 ASCII 图表来可视化发现

3. 探索方案和权衡：

   • 如果有多个方案，列出对比
   • 构建对比表
   • 突出风险和未知项

4. 转场：当思路清晰后，总结发现并询问：

   "现在需求已经比较清晰了。总结一下：[要点]。我们可以进入提案阶段了，需要我创建一个变更吗？"

⛔ 重要提醒：探索阶段只用于思考，不做任何实现。不要编写任何应用代码，只产出讨论、分析和图表。

阶段 2：提案

目的：创建变更并编写 proposal.md，明确为什么做 / 做什么 / 范围

步骤：

1. 从用户描述中推导变更名称：

   • 转换为 kebab-case（例如："用户关系查询" → user-relation-query）
   • 与用户确认："我建议变更名称为 <name>，可以吗？"

2. 创建变更：

   openspec new change "<name>"
   

3. 获取提案指导：

   openspec instructions proposal --change "<name>" --json
   

4. 与用户讨论提案内容： 询问以下方面：

   • 意图：为什么要做这个变更？解决什么问题？
   • 范围：包含什么？不包含什么？
   • 方法：初步的技术思路？
   • 影响：影响哪些模块/用户？

5. 基于讨论和指导模板创建 proposal.md（内容必须使用中文）

6. 展示摘要并确认：

   "提案已创建。核心内容：[摘要]。确认没问题后，我们进入需求规格阶段？"

约束：

• instructions 返回的 context 和 rules 是 AI 的约束信息，不是文件内容
• 不要把 <context>、<rules>、<project_context> 块复制到产物文件中
• ⛔ 本阶段不要编写任何应用代码，只产出 proposal.md 文档

阶段 3：规格

目的：创建增量规格，定义需求、场景和验收标准

步骤：

1. 检查状态并获取指导：

   openspec status --change "<name>" --json
   openspec instructions specs --change "<name>" --json
   

2. 阅读 proposal.md 获取上下文

3. 与用户讨论规格：

   • 从提案中识别能力模块
   • 针对每个能力讨论：
     • 有哪些需求（使用 RFC 2119 关键词：必须/应当/可以）？
     • 有哪些场景（前置条件/操作/预期结果）？
     • 有哪些边界情况？
     • 有哪些异常情况？

4. 在 specs/<capability>/spec.md 下创建增量规格文件（内容必须使用中文）：

   • 使用 ## 新增需求 描述新行为
   • 使用 ## 修改需求 描述变更行为
   • 使用 ## 移除需求 描述废弃行为

5. 展示摘要并确认：

   "需求规格已创建，共 N 个能力、M 个场景。要我逐一过一遍确认吗？确认后进入技术设计阶段。"

⛔ 本阶段不要编写任何应用代码，只产出规格文档。

规格格式参考：

# <能力名称> 增量规格

## 新增需求

### 需求：<名称>
系统必须/应当/可以 <行为描述>。

#### 场景：<名称>
- 前置条件：<前置条件>
- 当：<操作>
- 则：<预期结果>
- 且：<补充预期>

阶段 4：设计

目的：创建 design.md，记录技术方案和架构决策

步骤：

1. 获取设计指导：

   openspec instructions design --change "<name>" --json
   

2. 阅读提案和规格获取上下文

3. 调研代码库：搜索相关模式、依赖项、集成点

4. 与用户讨论技术方案：

   • 架构决策及理由
   • 数据流和组件交互
   • 需要变更的文件
   • 风险和应对措施

5. 基于讨论和模板创建 design.md（内容必须使用中文）

6. 展示摘要并确认：

   "技术设计已完成。核心方案：[摘要]。确认后进入任务拆分阶段？"

⛔ 本阶段不要编写任何应用代码，只产出 design.md 文档。

阶段 5：任务

目的：创建 tasks.md，将实现拆分为可执行的任务清单

步骤：

1. 获取任务指导：

   openspec instructions tasks --change "<name>" --json
   

2. 阅读所有前置产物（提案、规格、设计）获取上下文

3. 创建 tasks.md（内容必须使用中文），包含带复选框的任务清单：

   • 按类别分组
   • 使用层级编号（1.1、1.2 等）
   • 每个任务粒度适中，能在一个专注会话内完成
   • 包含验证步骤

4. 展示任务清单并与用户确认：

   "任务已拆分为 N 组共 M 个任务。请确认任务列表：[任务摘要]。确认后开始实现？"

⛔ 本阶段不要编写任何应用代码，只产出 tasks.md 文档。代码实现只在下一阶段（实现）进行。

任务格式：

# 任务清单

## 1. <分组名称>
- [ ] 1.1 <任务描述>
- [ ] 1.2 <任务描述>

## 2. <分组名称>
- [ ] 2.1 <任务描述>

阶段 6：实现（编码）

目的：按任务清单逐步编码实现

✅ 这是唯一允许编写应用代码的阶段。

入口检查：在开始编码前，必须确认以下条件全部满足：

• proposal.md 已创建并经用户确认
• specs/ 目录下的需求规格已创建并经用户确认
• design.md 已创建并经用户确认（除非用户明确同意跳过）
• tasks.md 已创建并经用户确认
• 用户已明确同意进入编码实现阶段

如果以上任何条件未满足，必须先回到相应阶段完成文档，而不是直接开始编码。

步骤：

1. 验证入口条件：运行 openspec status --change "<name>" --json 确认所有必需产物已存在

2. 获取实现指导：

   openspec instructions apply --change "<name>" --json
   

3. 阅读所有上下文文件（来自实现指导输出）

4. 逐个完成待办任务： a. 告知当前正在处理哪个任务 b. 实现代码变更 c. 将任务标记完成：- [ ] → - [x] d. 向用户简报完成情况 e. 询问："继续下一个任务？"（针对重要任务）

5. 暂停条件：

   • 任务不明确 → 询问用户 clarification
   • 实现过程中发现设计问题 → 建议更新产物，征求用户意见
   • 遇到错误或阻塞 → 报告并等待指导

6. 全部完成时：

   "所有 N 个任务已完成！接下来可以进行验证，确认实现与规格的一致性。要开始验证吗？"

实现过程中的输出格式：

## 正在实现: <change-name>

正在处理任务 3/7: <任务描述>
[...实现过程...]
✓ 任务完成

正在处理任务 4/7: <任务描述>
[...实现过程...]
✓ 任务完成

阶段 7：验证

目的：验证实现与产物的一致性

步骤：

1. 阅读所有产物（提案、规格、设计、任务）

2. 从三个维度验证：

   维度	检查内容
   完整性	所有任务完成了吗？所有需求实现了吗？所有场景覆盖了吗？
   正确性	实现是否符合规格意图？边界情况是否处理？
   一致性	设计决策是否体现在代码中？模式是否一致？

3. 问题分级：

   • 严重：必须在归档前修复
   • 警告：应该修复，但可以先归档
   • 建议：改进优化建议

4. 展示验证报告：

   ## 验证报告: <change-name>
   
   完整性: ✓ 12/12 任务已完成
   正确性: ✓ 所有需求已匹配
   一致性: ⚠ 1 个警告
   
   严重: 0 | 警告: 1 | 建议: 2
   可以归档: 是（有警告）
   

5. 如果发现问题：协助修复，然后重新验证

6. 验证通过时：

   "验证通过！所有实现与规格一致。可以进行归档了，要开始吗？"

阶段 8：归档

目的：归档变更，将增量规格合并到主规格

步骤：

1. 与用户确认：

   "即将归档 <name>。这会将增量规格合并到主规格并将变更移入 archive。确认归档？"

2. 展示即将发生的操作：

   • 增量规格 → 合并到 openspec/specs/
   • 变更目录 → 移动到 openspec/changes/archive/<date>-<name>/

3. 执行归档：

   openspec archive "<name>"
   

4. 最终总结：

   ## 归档完成
   
   **变更名称**: <name>
   **归档位置**: openspec/changes/archive/<date>-<name>/
   **已更新规格**: openspec/specs/<capability>/spec.md
   
   恭喜！这个变更已完整走完 SDD 流程。
   如果有新的需求，随时告诉我。
   

流程控制

跳过阶段

对于简单变更，可建议跳过：

• 探索：需求已经明确时可跳过
• 设计：实现方案简单直接时可跳过
• 验证：不建议跳过，但对于极简变更可以

始终告知用户哪些阶段被跳过以及原因。

回退修改

如果在实现或后续阶段发现前面的产物需要更新：

1. 告知："发现 [设计/需求/方案] 需要调整"
2. 回到相应阶段
3. 更新产物
4. 从中断处继续

示例：

"实现过程中发现 design.md 中的方案需要调整。让我更新技术设计后继续实现。"

恢复进度

当用户返回继续之前的变更时：

1. 运行 openspec list --json 查找活跃变更
2. 运行 openspec status --change "<name>" --json 检查进度
3. 总结当前状态：

   "检测到你有一个进行中的变更 <name>，当前进度：[状态]。要继续吗？"

4. 从适当的阶段恢复

交互指南

阶段转换模板

每次阶段转换前，使用以下模式：

---
## [阶段名称] 阶段完成

### 本阶段成果
- [列出关键产出]

### 下一步：[下一阶段名称]
[简述下一阶段要做什么]

准备好了吗？还是有什么想调整的？
---

用户偏题时

如果用户在活跃 SDD 流程中问了不相关的问题：

1. 回答用户的问题
2. 温和提醒："我们还有一个进行中的变更 <name>，要继续吗？"

用户想放弃时

如果用户想中途停止：

1. 确认："确定要暂停 <name> 吗？进度会保留，随时可以继续。"
2. 不要归档未完成的变更

安全约束

• ⛔ 在所有文档产物完成并确认之前，绝对不要编写应用代码 — 这是 SDD 的第一铁律
• ⛔ 所有产物文档（proposal.md、spec.md、design.md、tasks.md）必须使用中文撰写 — 不论 instructions 模板是什么语言，生成的文档内容一律用中文
• 每次创建产物或实现代码前，必须先获得用户确认
• 不要把 instructions 中的 context/rules 写入产物文件 — 那些只是 AI 的约束信息
• 始终使用 openspec CLI 来查询状态、获取指导、执行归档
• 创建新产物前，始终先阅读其依赖产物
• 保持变更聚焦 — 每个变更只包含一个逻辑工作单元
• 不确定时暂停 — 宁可问用户，不要猜测
• 遵循模式约束 — 按照 openspec status 中的产物依赖图行事
• 跟踪进度 — 使用 TodoWrite 工具维护用户可见的进度
• 严格遵守阶段顺序 — 探索 → 提案 → 规格 → 设计 → 任务 → 实现 → 验证 → 归档。只有实现阶段才允许编写应用代码