OpenSpec使用流程笔记：SDD精选指南

OpenSpec 究竟解决了什么问题？

OpenSpec 本质上是一套专为 AI 辅助开发定制的结构化工作流工具。其核心是一组以 /opsx: 开头的斜杠命令，覆盖从需求探索、规划、编码到验证、归档的完整协作链条。每一步都设定了清晰的控制点，目的就是消除沟通歧义，从根源提升开发效率与产出质量。

核心理念可以用八个字概括：先定规矩，再写代码。在落笔编码之前，先与 AI 一起明确需求、敲定设计约定、拆解为可执行任务；代码产出后，逐条验证是否符合最初约定，最后归档变更，形成可追溯的记录。这套机制能有效遏制“AI 生成内容不可靠”的常见痛点，从流程上保障结果的可控性。

快速上手：安装与初始化

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（可选）
   如果只需要部分命令，在上一步中选择 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 进行纯讨论。该命令进入“只读模式”，不修改任何现有文件，也不创建新目录。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 辅助开发真正变得可控且高效。

来源：互联网