为什么需要规约？

我之前做过一个 AI 代码助手的项目，遇到了这样的问题：

• 用户说"加个登录功能"，AI 噼里啪啦写了一大堆代码
• 结果用户说"不对，我要的是手机号登录，不是邮箱"
• AI 又噼里啪啦改，改完又有问题
• 来回五六次，代码变成了一锅粥

根本问题：需求只在对话历史里，没有形成共识。

💡 我的理解：规约的本质不是"写文档"，而是"形成共识"。当人和 AI 对"做什么"没有达成共识时，做得越多错的越多。OpenSpec 的价值在于：在动手之前，先让人和 AI 都确认"我们要做的是这个"。

OpenSpec 的核心设计

Artifacts 产物

每个变更产生四个产物：

proposal ──► specs ──► design ──► tasks
   why         what       how       steps

这不是传统的"需求文档→设计文档→开发"，而是四个视角，回答四个不同的问题：

• proposal：为什么做？（解决什么问题）
• specs：具体变什么？（用 Delta 的方式记录）
• design：打算怎么做？（技术方案）
• tasks：具体每一步是什么？

OPSX 工作流

这是 OpenSpec 最打动我的设计。它不像传统敏捷那样分"规划阶段"和"实现阶段"，而是允许任意顺序：

     ┌────────────────────────────────┐
     │  new ◄──► continue ◄──► apply ◄──► archive  │
     └────────────────────────────────┘

你可以先创建 proposal，然后直接 apply，发现 design 有问题再回去改。现实世界的工作本来就是迭代的，为什么要假装它是线性的？

💡 我的理解：这个设计解决了一个根本矛盾——"计划赶不上变化"。传统流程要求你在动手之前把所有东西都想清楚，但实际开发中这是不可能的。OPSX 允许你先做一部分，再根据实际情况调整，比硬撑着"计划阶段"要有意义得多。

Delta Specs 的精妙

传统的规格文档是"快照"——每次变更都要复制整个文档。OpenSpec 改成了"增量"：

## MODIFIED Requirements

### Requirement: pdf_merge_service
The system MUST support compress option during merge.
(Previously: 不支持压缩)

#### Scenario: 压缩合并
- GIVEN: 用户上传多个 PDF 并指定 compress=true
- WHEN: 调用 pdf_merge_service
- THEN: 返回压缩后的合并 PDF

这个设计的精妙之处在于：

• 明确意图：ADDED/MODIFIED/REMOVED 一目了然
• 便于 review：每次变更只关注"改了什么"
• 归档时直接应用：不需要复杂 merge

💡 我的理解：Delta Specs 本质上是一种" changeset 思维"。它不追求记录"完整状态"，而是记录"状态变化"。这对 AI 特别友好——AI 不需要理解完整系统，只需要理解"这次改变了什么"。

命令参考

核心命令

命令	功能
/opsx:propose	一站式创建所有 artifacts
/opsx:explore	探索问题，澄清需求
/opsx:apply	实现 tasks
/opsx:archive	归档变更

快速开始

# 安装
npm install -g @fission-ai/openspec@latest
openspec init

# 创建变更
/opsx:propose add-dark-mode

# 实现
/opsx:apply

# 归档
/opsx:archive

Verify 的价值

我之前写的代码经常被 review 出问题——要么遗漏了边界情况，要么实现和预期不一致。OpenSpec 的 verify 就是来解决这个的：

/opsx:verify

COMPLETENESS
✓ All tasks complete
✓ All requirements implemented

CORRECTNESS
✓ Edge cases handled

COHERENCE
✓ Design decisions reflected

💡 我的理解：verify 的价值不在于"检查"，而在于"强制停顿"。很多代码问题是因为我们太着急写代码，跳过了思考。verify 强制我们在实现后停顿一下，问自己"我真的做对了吗？"。这种强制停顿比任何工具都有价值。

我的思考与批判

1. OpenSpec 不是银弹

它解决的是"需求不确定"的问题，不是"代码写不好"的问题。

2. 对 AI 助手的真实价值

我之前以为 AI 助手可以"随便说需求，AI 自动完成"。实际用下来发现，AI 最怕的不是"不会做"，而是"不知道做什么"。OpenSpec 提供的正是后者——把模糊的需求变成清晰的规约。

3. 为什么我们借鉴了它

我们在做 spec-execute 技能时，完全借鉴了 OpenSpec 的设计：

• Step 0: 意图识别（借鉴了 /opsx:explore）
• Step 1-4: proposal / specs / design / tasks
• Step 5: apply（写代码）
• Step 6: verify（借鉴了 /opsx:verify）
• Step 7: archive

唯一的改进是把 verify 集成到 apply 过程中——每完成一个 task 就 verify，不会积压到最后被跳过。

4. AI 开发中不需要区分"紧急"场景

用 AI 开发，所有变更（fix / feature / refactor）都遵循同样的流程：

• 不需要区分"紧急"——AI 足够快，几分钟就能完成 fix + spec 生成
• delta spec 和代码是同一个 action 的两个输出，不是两个 action
• 不存在"来不及走流程"——AI 的工作速度让这个担忧变得不重要

所以"适合的场景"这个问题本身就不成立了。AI 开发中，所有变更都走同样的流程。

核心理念

→ fluid not rigid          # 流动而非僵硬
→ iterative not waterfall   # 迭代而非瀑布
→ easy not complex          # 简单而非复杂
→ built for brownfield      # 支持存量项目
→ scalable to enterprise    # 可大可小

总结

OpenSpec 解决的核心问题是：让 AI 和人对"做什么"达成共识。

它的价值不在于文档本身，而在于这个"达成共识的过程"。Delta Specs、OPSX 工作流、verify 验证，都是为了让这个过程更顺畅、更不容易被跳过。

如果你的团队经常遇到"AI 写完了但不是我要的"这个问题，OpenSpec 值得一试。

参考资料

• OpenSpec 官方仓库：https://github.com/Fission-AI/OpenSpec