OpenSpec完整使用流程笔记与SDD详解

什么是 OpenSpec？一文读懂 AI 辅助开发的结构化工作流

简单来说，OpenSpec 是一套专为 AI 辅助开发量身定制的结构化工作流工具。它的核心是一系列以 /opsx: 开头的斜杠命令，能够引导开发者与 AI 在需求探索、系统规划、代码编写、验证测试到归档总结的整个协作流程中高效配合。每个步骤都清晰可控，旨在消除沟通偏差，显著提升整体开发效率与交付质量。

其核心理念用八个字就能概括：先定规矩，再写代码。在实际动手编码之前，先与 AI 共同明确需求、商定设计规范、拆解为具体任务；代码实现后，再逐一验证是否符合最初约定，最后归档此次变更，形成可追溯的历史记录。遵循这套流程，那些“AI 写出来的东西不靠谱”的问题，基本能从源头得到有效控制。

快速上手：OpenSpec 安装与初始化指南

1. 安装 OpenSpec CLI 工具

安装过程极为简便，只需一行命令即可完成：

bash

npm install -g @fission-ai/openspec@latest

2. 在项目中完成初始化

进入你的项目根目录，然后执行初始化命令：

bash

openspec init

这一步会在项目中自动创建必要的目录结构（例如 openspec/、changes/ 等）以及一份基础配置文件。至此，项目根基就稳固地打好了。

配置工作流：解锁全部斜杠命令

默认情况下，OpenSpec 仅开启核心的几个命令，比如 explore、apply、archive 等四五个。若想解锁全部 11 个命令（如 new、continue、ff、verify、sync 等），则需要调整配置文件。

具体操作分为以下几步：

1. 切换 Profile 配置
   运行命令 openspec config profile，在弹出的选项中选择 Expanded Profile（即完整工作流模式）。

2. 手动选择 Workflows（可选）
   如果觉得 11 个命令过多，只想启用其中一部分，可在上一步选择 Workflows only，然后通过空格键勾选或取消你需要的命令。

3. 刷新配置使其生效
   执行如下命令：

   bash

   openspec update

4. 重启 AI 编辑器
   最后务必重启你的 Cursor 或安装了 Copilot 的 VS Code，新配置的斜杠命令才会正常显示。

现在，你的 AI 编辑器里应该能够看到全部 /opsx: 命令了。

核心概念详解

要深入理解 OpenSpec 的工作流，先要掌握几个基础概念：

• 变更（Change）：一次独立的开发任务，对应一个需求或功能点。每个变更都会在 changes/ 下拥有独立的目录，例如 changes/20250311-add-login/，用于存放所有相关产出物。
• 工件（Artifact）：变更过程中产生的各类产出，包括提案（proposal）、规范（specs）、设计（design）、任务清单（tasks）、代码实现、验证报告等。
• 规范（Specs）：记录项目全局或模块的设计约定，存储在 openspec/specs/ 中。这些规范可被复用，多个不同变更都能引用同一份规范。
• 快进（Fast-forward）：一种省时模式，能够一次性生成规划阶段的所有工件，跳过逐步创建的中间环节，大幅提升效率。

分阶段流程详解

完整的 OpenSpec 工作流可以拆解为六个阶段：探索 → 规划 → 执行 → 验证 → 同步 → 归档。每个阶段都有专门的命令配合使用。

1. 探索阶段：/opsx:explore

当你还在纠结需求、不确定技术选型时，先别急着写代码。使用 /opsx:explore 命令，可以与 AI 进行纯粹的讨论。它会进入“只读模式”，不会触碰你现有的任何文件，也不会创建新目录，只是根据你的提问生成分析性回答，帮助你梳理风险、探讨技术方案。整个过程相当于一次深度头脑风暴，输出结果可以手动保存到项目文档中供后续参考。

2. 规划阶段：从想法到任务清单

这一阶段的核心目标是搞清楚“要做什么”以及“怎么做”，产出清晰的提案、规范、设计和任务清单。

2.1 启动新变更：/opsx:new

使用 /opsx:new 命令创建新的变更。AI 会在 changes/ 下新建一个以时间戳命名的目录，并生成基础文件框架，例如 proposal.md、tasks.md 等占位文件。

2.2 逐步完善：/opsx:continue

如果你希望按顺序逐个创建工件，每一步都能审查和修改，那么使用 continue 命令最为合适。它会根据当前变更的进度，智能地生成下一个缺失的工件。举例来说：如果已有 proposal.md，运行 continue 会生成 specs/ 目录和初步规范；再运行一次生成 design.md；继续运行则生成 tasks.md。逐步推进，确保方向准确无误。

2.3 快速完成规划：/opsx:ff（快进模式）

如果需求明确、变更范围较小，且你经验丰富，不想在规划阶段花费太多时间，可以直接使用 /opsx:ff 一次性生成所有规划工件。它会自动产出 proposal.md、specs/、design.md、tasks.md，然后直接进入编码阶段。

规划阶段产出物

• proposal.md：描述变更的背景、目标及验收标准。
• specs/：存放与该变更相关的详细规范，涵盖接口设计、数据结构、UI 约定等。
• design.md：技术设计方案，涉及模块划分、关键算法、依赖关系等。
• tasks.md：拆解后的可执行任务清单（通常带复选框），供后续 apply 命令使用。

3. 执行阶段：/opsx:apply

任务清单准备就绪后，就可以让 AI 根据 tasks.md 编写代码了。/opsx:apply 命令会逐个读取任务，生成对应的代码文件，并自动放置到项目中的正确位置。每完成一个任务，AI 都会向你请求确认或提供解释，你也可以中途打断，修改任务列表后再继续执行。

4. 验证阶段：/opsx:verify

代码实现后，必须检查其是否完全符合当初制定的规范和设计。/opsx:verify 命令会分析变更中的所有代码，对照 specs/ 和 design.md 进行一致性审计，最终生成一份验证报告（通常存放在变更目录下，命名为 verify-report.md）。报告会清晰列出符合项与不符合项，并指出潜在问题及建议的修复方案。发现问题后，可以手动修改代码或调整规范，然后再次运行 verify 直至全部通过。

5. 同步规范：/opsx:sync

在变更过程中，你可能会产生一些新的、可复用的规范，例如通用的组件接口或 API 设计模式。这些宝贵的成果不能只留在变更目录里，应该合并到项目的主规范库中，供未来其他变更使用。/opsx:sync 命令会将当前变更中新增或修改的规范文件（位于 changes//specs/）复制或合并到 openspec/specs/ 中。需要注意的是，此命令不会归档变更，变更本身仍然处于活跃状态。

6. 归档阶段：/opsx:archive 与 /opsx:bulk-archive

当变更的所有工作（编码、验证）全部完成，且规范已同步到主库后，最后一步就是归档。

6.1 单个归档：/opsx:archive

使用 /opsx:archive 归档单个变更。它会将变更目录从 changes/active/ 移动到 changes/archived/（按日期组织）；再次运行 sync 确保最新规范已合并；更新变更日志 CHANGELOG.md；并将变更状态标记为“已完成”。

6.2 批量归档：/opsx:bulk-archive

当多个已完成变更积压等待归档时，使用此命令批量处理。它会先列出所有可归档的活跃变更，让你选择哪些需要归档（支持多选），然后依次执行归档操作。如果两个变更修改了同一个规范文件，系统会提示你手动解决冲突。最后自动更新变更日志。

命令速查表

最佳实践与典型应用场景

场景一：复杂功能开发（逐步推进）

对于逻辑复杂、风险较高的功能，建议按照以下十步稳健推进：

1. /opsx:explore – 先与 AI 深入讨论需求与技术选型，摸清所有潜在问题。
2. /opsx:new – 创建变更。
3. /opsx:continue – 生成 proposal，审阅后继续。
4. /opsx:continue – 生成 specs，审阅后继续。
5. /opsx:continue – 生成 design，审阅后继续。
6. /opsx:continue – 生成 tasks，审阅后定稿。
7. /opsx:apply – 执行任务清单，生成代码。
8. /opsx:verify – 验证代码一致性，修复问题。
9. /opsx:sync – 将新增规范合并到主库。
10. /opsx:archive – 归档变更。

场景二：小型快速迭代

如果功能简单、需求明确，可以跳过中间的逐步生成步骤，直接采用高效路径：

1. /opsx:ff – 快进生成所有规划工件。
2. /opsx:apply – 编码实现。
3. /opsx:verify – 验证质量。
4. /opsx:archive – 归档完成。

场景三：规范先行，团队协作

团队合作时，可以在项目启动初期先通过 /opsx:explore 和 /opsx:new 建立一套全局规范，例如代码风格、API 设计原则，并将其存储在 openspec/specs/ 中。后续每个功能变更都从这套主规范派生，开发完成后通过 /opsx:sync 更新主规范。这样一来，团队的知识库就能始终保持同步与积累。

常见问题解答

Q1：命令在编辑器中不显示怎么办？

这个问题通常有四个检查点：确保你已经运行过 openspec update；重启编辑器（Cursor 或 VS Code）；确认项目根目录下存在 .openspec/ 和 openspec/ 这两个文件夹；确认你使用的是支持斜杠命令的 AI 工具（如 Cursor、Claude Code）。

Q2：/opsx:ff 和 /opsx:continue 有什么区别？

简单概括就是：速 vs 稳。ff 一次性生成所有规划工件，适合需求明确、变更简单的场景；而 continue 则是逐个生成，适合需要逐步审阅、风险较高的变更。

Q3：如何查看当前变更的进度？

最直接的方法：查看变更目录下的文件。例如，如果 tasks.md 已经存在，说明规划阶段已经完成。AI 也会在对话中记录当前的变更状态，方便你随时了解进展。

Q4：sync 和 archive 都涉及更新规范，有什么区别？

关键区别在于变更的状态。sync 只合并规范，变更本身仍然活跃，可以继续开发；而 archive 在归档前会自动执行一次 sync，确保规范已被合并，然后整个变更会被标记为“已完成”并移至归档目录。

总结

OpenSpec 通过这套结构化的命令和工作流，将 AI 从一个单纯的“代码生成器”转变为“遵循规范的协作者”。熟练掌握这些命令，你可以实现以下目标：

• 在探索阶段利用 AI 进行深度分析，有效避开常见陷阱。
• 在规划阶段与 AI 共同构建清晰的设计蓝图，大幅减少返工。
• 在执行阶段让 AI 按照任务清单精准编码，显著提升效率。
• 在验证阶段自动检查一致性，确保代码质量可靠。
• 在归档阶段沉淀规范，让团队的知识库不断积累、复用。

立即开始使用 OpenSpec，让 AI 辅助开发变得真正可控、高效且可追溯。