对话式 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 工具维护用户可见的进度
- 严格遵守阶段顺序 — 探索 → 提案 → 规格 → 设计 → 任务 → 实现 → 验证 → 归档。只有实现阶段才允许编写应用代码