OpenSpec (opsx) 命令完全指南

一套结构化的代码变更管理工作流，让你从"想法"到"落地"全程有迹可循。

---

一、OpenSpec 是什么？

OpenSpec 是一个嵌入在 Cursor IDE 中的结构化变更管理工作流。它的核心理念是：每一次代码变更都应该有清晰的"为什么做"、“做什么”、"怎么做"的记录。

它通过一系列命令（opsx-*），引导你从探索想法 → 创建提案 → 编写规范 → 设计方案 → 拆分任务 → 实现代码 → 验证完成 → 归档存档，形成一个完整的变更生命周期。

---

二、核心概念

在了解命令之前，先理解几个关键概念：

变更（Change）

一个"变更"是 OpenSpec 中的工作单元，对应一次功能开发或 Bug 修复。它存放在 openspec/changes/<名称>/ 目录下，包含以下工件（Artifacts）：

openspec/changes/add-3d-matching/
├── proposal.md        ← 提案：为什么要做？做什么？
├── design.md          ← 设计：怎么做？技术方案是什么？
├── specs/             ← 规范：详细的需求定义（WHEN/THEN 格式）
│   └── <能力名>/
│       └── spec.md
└── tasks.md           ← 任务：实现清单（可勾选的 checkbox）

主规范 vs 增量规范

• 主规范（Main Specs）：openspec/specs/ — 项目的正式需求文档
• 增量规范（Delta Specs）：openspec/changes/<名称>/specs/ — 某次变更中新增或修改的需求

工件依赖链

默认的 spec-driven 工作流中，工件按以下顺序创建：

proposal → specs → design → tasks → [实现] → [归档]

每个工件依赖前一个工件的上下文。

---

三、命令详解

1. opsx-explore — 探索模式

一句话概括：开启自由思考模式，在动手之前把问题想清楚。

适用场景：

• 有一个模糊的想法，还不确定怎么做
• 遇到技术难题，需要调研和分析
• 想比较多种方案的优劣

特点：

• 只读模式 — 可以查看代码、搜索项目，但不会写代码
• 可视化思考 — 鼓励使用 ASCII 图表来梳理思路
• 无固定流程 — 没有步骤要求，跟着思路走
• 可衔接后续 — 想法成熟后，可以直接转入 opsx-new 或 opsx-ff

使用示例：

用户：opsx-explore
      我在考虑给项目加一个点云匹配功能

AI：[分析代码库，画出架构图，讨论方案选项]
    准备好了吗？可以用 opsx-new 创建一个变更。

---

2. opsx-new — 创建新变更

一句话概括：启动一个新变更，逐步创建工件。

适用场景：

• 开始一个新功能或修复
• 想一步步精心打磨每个工件

工作流程：

1. 提供变更名称（kebab-case 格式，如 add-point-cloud-matching）
2. 创建变更目录结构
3. 显示第一个待创建工件的模板
4. 停下来等你确认 — 不会自动往下走

与 opsx-ff 的区别：opsx-new 每次只创建一个工件，给你充分审查的机会；opsx-ff 则一口气全部生成。

---

3. opsx-continue — 继续推进变更

一句话概括：接着上次的进度，创建下一个工件。

适用场景：

• 用 opsx-new 创建了变更后，继续填充后续工件
• 中断后恢复工作

工作流程：

1. 选择要继续的变更
2. 检查当前进度（哪些工件已完成）
3. 找到下一个可创建的工件
4. 读取已完成的工件作为上下文
5. 创建一个工件后停下来

关键规则：每次调用只创建一个工件，保证质量控制。

---

4. opsx-ff — 快进模式

一句话概括：一次性生成所有工件，快速进入实现阶段。

适用场景：

• 对变更内容已经很清楚，不需要逐步审查
• 想快速开始编码
• 小型变更，不需要过多讨论

工作流程：

1. 提供变更名称或描述
2. 创建变更目录
3. 自动按依赖顺序生成所有工件（proposal → specs → design → tasks）
4. 完成后直接可以开始 opsx-apply

比喻：opsx-new + opsx-continue 是"手动挡"，opsx-ff 是"自动挡"。

---

5. opsx-apply — 实施变更

一句话概括：根据任务清单，逐个实现代码。

适用场景：

• 所有工件（至少 tasks）已创建完成
• 准备开始写代码

工作流程：

1. 选择变更
2. 读取所有上下文文件（提案、规范、设计、任务）
3. 显示当前进度（N/M 任务完成）
4. 逐个实现任务：
   • 宣布当前任务
   • 编写代码
   • 完成后在 tasks.md 中打勾 - [ ] → - [x]
   • 继续下一个
5. 遇到问题暂停并询问

暂停条件：任务不明确、发现设计缺陷、遇到错误。

---

6. opsx-verify — 验证实现

一句话概括：检查代码实现是否与规范一致，生成验证报告。

适用场景：

• 实现完成后，归档前的最后检查
• 想确认没有遗漏

验证三个维度：

维度	检查内容	问题级别
完整性（Completeness）	任务是否全部完成？需求是否都有实现？	CRITICAL
正确性（Correctness）	实现是否符合规范意图？场景是否覆盖？	WARNING
一致性（Coherence）	是否遵循了设计决策？代码风格是否统一？	SUGGESTION

输出示例：

## 验证报告: add-point-cloud-matching

| 维度     | 状态            |
|----------|-----------------|
| 完整性   | 7/7 任务完成    |
| 正确性   | 5/5 需求已覆盖  |
| 一致性   | 遵循设计方案    |

✅ 所有检查通过，可以归档。

---

7. opsx-sync — 同步规范

一句话概括：把增量规范合并到主规范，但不关闭变更。

适用场景：

• 代码还没写完，但想先把需求文档更新到主规范
• 需要让其他变更看到最新的需求定义

工作流程：

1. 选择包含增量规范的变更
2. 读取增量规范（支持 ADDED / MODIFIED / REMOVED / RENAMED）
3. 读取对应的主规范
4. 智能合并：不是简单替换，而是理解意图后精确合并
5. 变更仍然保持活跃

与 opsx-archive 的关系：opsx-archive 归档时也会触发同步，但 opsx-sync 让你在不归档的情况下提前同步。

---

8. opsx-archive — 归档变更

一句话概括：变更完成后，归档保存为历史记录。

适用场景：

• 所有任务完成
• 代码已经验证通过
• 准备收尾

工作流程：

1. 选择要归档的变更
2. 检查工件完成度 — 未完成的会给出警告（但不阻断）
3. 检查任务完成度 — 未完成的会给出警告
4. 评估规范同步状态 — 如果有增量规范，会询问是否先同步
5. 执行归档：移动到 openspec/changes/archive/YYYY-MM-DD-<名称>/

归档后：变更成为项目历史的一部分，你可以随时回顾"为什么当初这样设计"。

---

9. opsx-bulk-archive — 批量归档

一句话概括：一次性归档多个已完成的变更。

适用场景：

• 积累了多个已完成的变更
• 想一次性清理

特色功能：

• 冲突检测：如果多个变更修改了同一个能力的规范，会自动检测冲突
• 智能解决：通过搜索代码库，判断哪些变更实际上已经实现，按时间顺序合并
• 批量确认：一次确认，批量执行

---

10. opsx-onboard — 引导入门

一句话概括：手把手带你走完一个完整的工作流周期。

适用场景：

• 第一次使用 OpenSpec
• 想通过实操学习整个流程

完整流程（约 15-20 分钟）：

1. 🔍 扫描代码库，找一个小任务
2. 💡 用探索模式简单分析
3. 📦 创建变更
4. 📝 依次创建：提案 → 规范 → 设计 → 任务
5. 🔨 实现代码
6. 📦 归档完成

教学特色：每一步都有解释说明，让你理解"为什么要这样做"。

---

四、典型工作流

工作流 A：完整流程（适合重要功能）

opsx-explore        ← 1. 思考和探索
    ↓
opsx-new            ← 2. 创建变更
    ↓
opsx-continue ×3    ← 3. 逐步创建工件（proposal → specs → design → tasks）
    ↓
opsx-apply          ← 4. 实现代码
    ↓
opsx-verify         ← 5. 验证实现
    ↓
opsx-archive        ← 6. 归档

工作流 B：快速流程（适合小型变更）

opsx-ff             ← 1. 一步到位创建所有工件
    ↓
opsx-apply          ← 2. 实现代码
    ↓
opsx-archive        ← 3. 归档

工作流 C：项目清理

opsx-verify ×N      ← 1. 验证所有变更
    ↓
opsx-bulk-archive   ← 2. 批量归档

---

五、命令速查表

命令	阶段	读/写	功能
opsx-explore	前期	只读	探索想法、调研问题
opsx-new	规划	写入	创建新变更，展示第一个工件模板
opsx-continue	规划	写入	创建下一个工件（每次一个）
opsx-ff	规划	写入	一次性创建所有工件
opsx-apply	实施	写入	按任务清单实现代码
opsx-verify	验证	只读	验证实现与规范的一致性
opsx-sync	管理	写入	同步增量规范到主规范（不归档）
opsx-archive	收尾	写入	归档已完成的变更
opsx-bulk-archive	收尾	写入	批量归档多个变更
opsx-onboard	学习	写入	引导式完整流程教学

---

六、总结

OpenSpec 的核心价值在于：

1. 可追溯性 — 每个变更都有完整的决策记录（为什么做、怎么做）
2. 结构化思考 — 先想清楚再动手，减少返工
3. 渐进式深入 — 从模糊想法到具体代码，有清晰的路径
4. 灵活性 — 可以走完整流程，也可以快进跳过

对于个人开发者，它帮你养成"先设计后编码"的习惯；对于团队协作，它让决策过程透明、可回溯。

---

新手建议：先用 opsx-onboard 跟着做一遍，然后用 opsx-ff 处理日常小变更，重要功能用 opsx-new + opsx-continue 精细打磨。