对话式 SDD 引导

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

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

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

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

OpenSpec 核心概念

概念	说明
Change（变更）	一次变更，对应 `openspec/changes/<name>/` 目录
Artifact（产物）	变更中的产物文件（proposal.md / specs / design.md / tasks.md）
Delta Spec（增量规格）	描述新增 / 修改 / 移除的需求
Schema（模式）	定义产物类型和依赖关系的配置（默认 `spec-driven`）
Archive（归档）	归档完成的变更，将增量规格合并到主规格

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 核心命令

命令	作用	输出
`openspec new change "<name>"`	创建新变更	`openspec/changes/<name>/`
`openspec status --change "<name>" --json`	查询变更状态	产物状态列表
`openspec instructions <artifact> --change "<name>" --json`	获取产物创建指导	模板 + 上下文 + 规则
`openspec list --json`	列出所有活跃变更	变更列表
`openspec archive "<name>"`	归档变更	合并增量规格、移入 archive

⛔ 铁律：先文档后编码

在 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）使用中文

核心原则

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

触发与意图识别

何时激活

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

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

初始评估

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

检查 openspec 是否已初始化
```
ls openspec/config.yaml
```
如果未初始化，告知用户并建议运行 openspec init。
检查是否有活跃变更
```
openspec list --json
```
如果存在活跃变更，询问用户：
- 是否要继续某个已有的变更？
- 还是要开始一个新的变更？

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

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

向用户展示评估结果：

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

让用户调整计划。

阶段流程

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

每个阶段遵循以下模式：

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

阶段 1：探索

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

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

具体操作：

提出开放性问题来理解问题：
- "你遇到的核心问题是什么？"
- "理想状态下应该是什么样的？"
- "有没有参考方案？"
调研代码库（如有需要）：
- 搜索相关代码、模式、已有实现
- 梳理与讨论相关的当前架构
- 使用 ASCII 图表来可视化发现
探索方案和权衡：
- 如果有多个方案，列出对比
- 构建对比表
- 突出风险和未知项
转场：当思路清晰后，总结发现并询问：

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

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

阶段 2：提案

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

步骤：

从用户描述中推导变更名称：
- 转换为 kebab-case（例如："用户关系查询" → user-relation-query）
- 与用户确认："我建议变更名称为 <name>，可以吗？"
创建变更：
```
openspec new change "<name>"
```

获取提案指导：

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

与用户讨论提案内容：询问以下方面：
- 意图：为什么要做这个变更？解决什么问题？
- 范围：包含什么？不包含什么？
- 方法：初步的技术思路？
- 影响：影响哪些模块/用户？
基于讨论和指导模板创建 proposal.md（内容必须使用中文）
展示摘要并确认：

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

约束：

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

阶段 3：规格

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

步骤：

检查状态并获取指导：

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

阅读 proposal.md 获取上下文
与用户讨论规格：
- 从提案中识别能力模块
- 针对每个能力讨论：
  - 有哪些需求（使用 RFC 2119 关键词：必须/应当/可以）？
  - 有哪些场景（前置条件/操作/预期结果）？
  - 有哪些边界情况？
  - 有哪些异常情况？
在 specs/<capability>/spec.md 下创建增量规格文件（内容必须使用中文）：
- 使用 ## 新增需求 描述新行为
- 使用 ## 修改需求 描述变更行为
- 使用 ## 移除需求 描述废弃行为
展示摘要并确认：

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

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

规格格式参考：

# <能力名称> 增量规格

## 新增需求

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

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

阶段 4：设计

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

步骤：

获取设计指导：

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

阅读提案和规格获取上下文
调研代码库：搜索相关模式、依赖项、集成点
与用户讨论技术方案：
- 架构决策及理由
- 数据流和组件交互
- 需要变更的文件
- 风险和应对措施
基于讨论和模板创建 design.md（内容必须使用中文）
展示摘要并确认：

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

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

阶段 5：任务

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

步骤：

获取任务指导：

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

阅读所有前置产物（提案、规格、设计）获取上下文
创建 tasks.md（内容必须使用中文），包含带复选框的任务清单：
- 按类别分组
- 使用层级编号（1.1、1.2 等）
- 每个任务粒度适中，能在一个专注会话内完成
- 包含验证步骤
展示任务清单并与用户确认：

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

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

任务格式：

# 任务清单

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

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

阶段 6：实现（编码）

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

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

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

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

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

步骤：

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

获取实现指导：

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

阅读所有上下文文件（来自实现指导输出）
逐个完成待办任务： a. 告知当前正在处理哪个任务 b. 实现代码变更 c. 将任务标记完成：- [ ] → - [x] d. 向用户简报完成情况 e. 询问："继续下一个任务？"（针对重要任务）
暂停条件：
- 任务不明确 → 询问用户 clarification
- 实现过程中发现设计问题 → 建议更新产物，征求用户意见
- 遇到错误或阻塞 → 报告并等待指导
全部完成时：

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

实现过程中的输出格式：

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

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

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

阶段 7：验证

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

步骤：

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

从三个维度验证：

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

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

展示验证报告：

## 验证报告: <change-name>

完整性: ✓ 12/12 任务已完成
正确性: ✓ 所有需求已匹配
一致性: ⚠ 1 个警告

严重: 0 | 警告: 1 | 建议: 2
可以归档: 是（有警告）

如果发现问题：协助修复，然后重新验证
验证通过时：

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

阶段 8：归档

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

步骤：

与用户确认：

"即将归档 <name>。这会将增量规格合并到主规格并将变更移入 archive。确认归档？"
展示即将发生的操作：
- 增量规格 → 合并到 openspec/specs/
- 变更目录 → 移动到 openspec/changes/archive/<date>-<name>/
执行归档：
```
openspec archive "<name>"
```

最终总结：

## 归档完成

**变更名称**: <name>
**归档位置**: openspec/changes/archive/<date>-<name>/
**已更新规格**: openspec/specs/<capability>/spec.md

恭喜！这个变更已完整走完 SDD 流程。
如果有新的需求，随时告诉我。

流程控制

跳过阶段

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

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

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

回退修改

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

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

示例：

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

恢复进度

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

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

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

交互指南

阶段转换模板

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

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

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

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

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

用户偏题时

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

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

用户想放弃时

如果用户想中途停止：

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

安全约束

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

openspec-sdd-guide