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 等），需要调整配置。
操作步骤如下：
-
切换 Profile
执行openspec config profile，在弹出的选项中选择Expanded Profile（完整工作流）。 -
手动选择 Workflows（可选）
如果只需要部分命令，在上一步中选择Workflows only，然后用空格键勾选或取消所需命令。 -
刷新配置
运行：bash
openspec update -
重启 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/）复制或合并到 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
当多个已完成变更积压等待归档时，使用该命令批量处理。它会列出所有可归档的活跃变更，让你选择（支持多选），然后依次执行归档操作。若两个变更修改了同一规范文件，会提示手动解决冲突。最后自动更新变更日志。
命令速查表
| 命令 | 阶段 | 功能 |
|---|---|---|
/opsx:explore |
探索 | 只读模式讨论需求，不生成文件 |
/opsx:new |
规划 | 创建新变更目录及基础文件 |
/opsx:continue |
规划 | 按进度生成下一个工件 |
/opsx:ff |
规划 | 快进：一次性生成所有规划工件 |
/opsx:apply |
执行 | 根据任务清单编写代码 |
/opsx:verify |
验证 | 检查代码是否符合规范，生成报告 |
/opsx:sync |
同步 | 将变更中的规范合并到主规范库 |
/opsx:archive |
归档 | 归档单个已完成变更 |
/opsx:bulk-archive |
归档 | 批量归档多个变更 |
/opsx:onboard |
学习 | 交互式教程（约15分钟） |
最佳实践与典型场景
场景一：复杂功能开发（逐步推进）
对于逻辑复杂、风险较高的功能，推荐按以下十步执行：
/opsx:explore– 与 AI 深入讨论需求和技术选型，提前识别所有风险点。/opsx:new– 创建变更。/opsx:continue– 生成 proposal，审阅后继续。/opsx:continue– 生成 specs，审阅后继续。/opsx:continue– 生成 design，审阅后继续。/opsx:continue– 生成 tasks，审阅后定稿。/opsx:apply– 执行任务清单，生成代码。/opsx:verify– 验证代码一致性，修复问题。/opsx:sync– 将新增规范合并到主库。/opsx:archive– 归档变更。
场景二：小型快速迭代
若功能简单、需求明确，可跳过中间逐步生成步骤：
/opsx:ff– 快进生成所有规划工件。/opsx:apply– 编码。/opsx:verify– 验证。/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 辅助开发真正变得可控且高效。