OpenSpec — 规格驱动开发工作流指南

OpenSpec 相比于Spec-Kit、Superpowers这些来说，算比较轻量的，实战下来效果也很不错~

跟 Spec-Kit 不一样的思路

Spec-Kit 是七道门的流水线，一步不能跳。OpenSpec 的思路完全不同，它把「阶段」变成了「动作」。

啥意思呢？传统工作流把你锁在阶段里，规划完了才能实现，实现了不能回头。但真实开发哪是这样的？你写着写着发现方向不对，得回去改需求，太正常了。

OpenSpec 不拦着你

传统（阶段锁定）：
  规划 ──────────► 实现 ──────────► 完成
      │                 │
      │   "不能回头"     │
      └─────────────────┘

OpenSpec（流动动作）：
  proposal ──► specs ──► design ──► tasks ──► implement

命令是你可以做的事，不是困住你的阶段。依赖关系是告诉你「接下来可以做什么」，不是「你必须做什么」。

这个设计理念我是真的觉得挺聪明的。

安装后默认给你什么

新装好的 OpenSpec 默认是 core 配置，四个命令

/opsx:propose ──► /opsx:apply ──► /opsx:archive

加上一个 /opsx:explore，够用了。

propose 是提案，apply 是执行，archive 是归档。三步走完一个变更。简单直接。

如果你需要更细粒度的控制，比如逐步创建产物、验证实现这些，可以通过配置开启扩展模式

openspec config profile
openspec update

扩展模式多了 /opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync、/opsx:bulk-archive、/opsx:onboard 这些命令。

几种典型玩法

快速功能

需求明确，知道要做什么，直接上

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

实际用起来的体验是这样的

你: /opsx:new add-logout-button

AI: 已创建 openspec/changes/add-logout-button/
     准备创建: proposal

你: /opsx:ff

AI: 正在创建所有规划产物...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     准备实现！

你: /opsx:apply

AI: 正在执行任务...
     ✓ 在头部添加了登出按钮
     ✓ 实现了会话清理
     ✓ 添加了确认对话框
     所有任务完成！

你: /opsx:archive

AI:  ✓ 已合并 specs
     ✓ 已归档变更

/opsx:ff 是 fast-forward 的意思，一口气把所有规划产物全生成出来。适合你已经想清楚要做什么的场景。

探索式开发

需求不明确的时候，别急着 propose，先 explore

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

举个例子。我跟它说想提升页面加载性能，但不确定瓶颈在哪

你: /opsx:explore

AI: 你想探索什么？

你: 我想提升页面加载性能，但我不确定瓶颈在哪。

AI: 让我帮忙调查...
     [分析打包大小，识别慢查询，审查组件渲染模式]

     我发现了三个主要瓶颈：
     1. 大量未优化的图片
     2. ProductList 中的同步数据获取
     3. 上下文变更导致的重渲染

     你想先处理哪个？

你: 我们先解决数据获取问题。

你: /opsx:new optimize-product-list-fetching

先探索，再创建变更，然后逐步推进。/opsx:continue 是一个产物一个产物地创建，每步你都能审查和调整。跟 /opsx:ff 的一口气全生成正好互补。

经验法则是，如果你能 upfront 描述完整范围，用 /opsx:ff。如果你边做边摸索，用 /opsx:continue。

并行变更

这个功能我是真的喜欢。你正在做暗黑模式，突然来了个紧急 bug 要修。在 OpenSpec 里，你直接新建一个变更去修 bug，修完了回来继续暗黑模式，进度还在。

变更 A: /opsx:new ──► /opsx:ff ──► /opsx:apply（进行中）
                                         │
                                    上下文切换
                                         │
变更 B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

你: 我在做 add-dark-mode，但被拉去修一个 bug

你: /opsx:new fix-login-redirect

你: /opsx:apply

AI: 正在处理 fix-login-redirect...
     所有任务完成！

你: /opsx:archive

你: 我们回到 dark mode 吧

你: /opsx:apply add-dark-mode

AI: 恢复 add-dark-mode...
     从任务 2.3 继续: 更新 Header...

多个变更都完成后，可以用 /opsx:bulk-archive 批量归档。它会自动检测多个变更之间有没有 spec 冲突，有的话会检查代码库来解决。

完成变更前，先验证

/opsx:verify 是归档前的质量检查，从三个维度验证实现跟产物是否一致

你: /opsx:verify

AI: 正在验证 add-auth...

     完整性 (COMPLETENESS)
     ✓ tasks.md 中所有 12 个任务已勾选
     ✓ specs 中所有需求都有对应代码
     ⚠ 场景"空闲后会话超时"未测试

     正确性 (CORRECTNESS)
     ✓ 实现符合 spec 意图
     ✓ 来自场景的边界情况已处理

     一致性 (COHERENCE)
     ✓ 设计决策反映在代码结构中
     ⚠ 设计提到"事件驱动"但实现使用了轮询

     严重问题: 0
     警告: 2
     可归档: 是（带警告）

它不会阻止你归档，但会暴露你可能想先处理的问题。我自己一般看到警告都会先处理掉再归档，毕竟养成好习惯。

维度 验证内容
完整性 所有任务完成、所有需求已实现、场景覆盖
正确性 实现匹配 spec 意图、边界情况已处理
一致性 设计决策反映在代码中、模式一致

什么时候该更新，什么时候该新建

这个问题我一开始也挺纠结的。做到一半发现方向变了，是改原来的变更还是重新开一个？

后来想明白了一个判断标准

       这还是同一个工作吗？
              │
   ┌──────────┼───────────┐
   ▼          ▼           ▼
 意图相同？  >50% 重叠？  原始变更能
 问题相同？  范围相同？   不含这些变更
   │          │          就标记"完成"？
  是 → 更新   是 → 更新   否 → 更新
  否 → 新建   否 → 新建   是 → 新建

举个例子。「添加深色模式」做到一半

  • 「还需要支持自定义主题」→ 新建变更，范围膨胀了
  • 「系统偏好检测比预期复杂」→ 更新，意图没变
  • 「先发布切换功能，偏好设置后续再加」→ 更新然后归档，再新建变更

几个实用建议

保持变更聚焦。 每个变更一个逻辑工作单元。「添加功能 X 同时重构 Y」这种事，拆成两个变更。审查更清楚，归档历史更干净，回滚也更简单。

命名要有意义。 add-dark-mode 比 feature-1 强一百倍。openspec list 的时候你能一眼看出每个变更在干嘛。

不明确的先探索。 别急着 propose，先用 /opsx:explore 搞清楚问题空间。花 10 分钟探索，能省你 2 小时返工。

命令速查

命令 用途 何时使用
/opsx:propose 创建变更 + 规划产物 快速默认路径
/opsx:explore 思考想法 需求不明确
/opsx:new 启动变更脚手架 扩展模式
/opsx:continue 创建下一个产物 逐步创建
/opsx:ff 创建所有规划产物 范围明确
/opsx:apply 实现任务 准备写代码
/opsx:verify 验证实现 归档前
/opsx:sync 合并 delta specs 扩展模式
/opsx:archive 完成变更 所有工作完成
/opsx:bulk-archive 归档多个变更 并行工作

完整命令详情见 OpenSpec Commands。