第48课 · OpenSpec：规范驱动开发
本节要点
- OpenSpec 是什么：一个给 AI 编程加「协议层」的插件，让需求从「聊天里的一句话」变成「仓库里的一份文档」
- Spec 是什么：Specification（规范文档）的简称——你把需求写进文档，AI 照着文档干活，不再是「你说一句，AI 猜一句」
- 五个阶段一个闭环：Explore 探索 → Propose 提议 → Apply 执行 → Sync 同步 → Archive 归档
- 归档是关键差异：相比第 5 课讲的 Superpowers，OpenSpec 有完整的归档机制——做完一个功能，变更记录归档，主规范持续演进
- 兼容 30+ 主流 AI 编程工具：OpenCode、Claude Code、Cursor、GitHub Copilot……一套规范，所有工具通用
- 适合大型项目：小需求不用搞这么复杂，但如果你在做稍大一点的项目，用 Spec 驱动能保持主线不跑偏
1. 为什么需要 OpenSpec？
还记得第 5 课讲的 Superpowers 插件吗？它每次跟 AI 头脑风暴、探索需求后，会生成设计文档和任务文档。
用着用着你会发现一个问题——文档越积越多，但没有一个总纲。
Superpowers 的问题
- 每次对话需求，它都生成一个 Spec 文件
- 文件越攒越多，全部并列堆在一起
- 没有一个主框架把它们串起来
- 你不知道哪些是当前在做的，哪些是历史的
- 每次都相当于在全新的基础上做变更
OpenSpec 的思路不同：它有一个主架构文档，描述你整个系统的结构。每次你要做一个新功能或修一个 bug，它会创建一个变更（Change），走完一个完整生命周期后归档，然后把变更内容同步回主架构。
这样你的项目就有一个持续演进的主线，而不是一堆散落的碎片。
2. Spec 是什么？
如果你没接触过软件开发，可能没听过这个词。
Spec = Specification，中文叫「规范文档」或「规格说明」。
打个比方：
📋 你去装修公司装修房子，设计师会先出一份施工图纸——哪里放沙发、哪里开窗户、电线怎么走。这份图纸就是 Spec。施工队（AI）照着图纸干活，而不是凭感觉砌墙。
在 AI 编程里，Spec 就是你把想做什么、为什么这么做、具体改哪些地方，都写进一份文档。AI 读了文档再动手，而不是靠你聊天时的几句话去猜。
OpenSpec 的核心理念用一句话概括：
Agree First, Then Build —— 先对齐，再编码。
你跟 AI 先把「要做什么」在文档里讨论清楚、审查通过，然后再让 AI 去写代码。这样不会浪费代码量，也不会跑偏。
3. 五个阶段：一个功能的完整生命周期
OpenSpec 给每个功能（或 bug 修复）设计了一个五阶段闭环。每个功能都走同一条路：
🤔 Explore → 📝 Propose → ⚡ Apply → 🔄 Sync → 📦 Archive
探索 提议 执行 同步 归档阶段 1：Explore 探索
有一个需求，但还没想清楚怎么做？
输入 /opsx:explore，进入探索模式。AI 会读取你的代码、权衡不同方案，跟你聊清楚需求。这个阶段不写任何代码，纯粹是思考伙伴。
💡 第 5 课学的 Superpowers 里叫 brainstorm（头脑风暴），OpenSpec 里叫 explore，本质一样。
阶段 2：Propose 提议
需求聊清楚了，输入 /opsx:propose。AI 会自动在你的项目里创建一个变更文件夹，包含这些文档：
| 文件 | 作用 |
|---|---|
proposal.md | 需求文档——这次要解决什么问题 |
design.md | 设计文档——打算怎么解决 |
specs/ | 受影响的规范变更——跟主架构的差异 |
tasks.md | 任务列表——拆成一个个小任务，带编号 |
写完这些文档后，你先看一眼（或者让 AI 帮你 review），确认没问题再往下走。
阶段 3：Apply 执行
方案审查通过，输入 /opsx:apply。AI 按照 tasks.md 里的任务列表，一个一个去完成，做完了就打勾（✓）。
如果执行过程中发现方案有问题，可以随时更新文档继续编码——不是死板的阶段门禁。
阶段 4：Sync 同步
代码写完了，输入 /opsx:sync。这一步把实际实现的内容回写到主规范文档里。
为什么要同步？因为 AI 执行时可能跟计划有出入。Sync 把真实情况记录下来，保证主架构文档是最新状态。
阶段 5：Archive 归档
人工验证没问题后，输入 /opsx:archive。这一步把：
- 变更的差异合并到主规范
- 变更文件夹加上时间戳，移入
archive/目录存档
归档后，规范变成新的「客观真理」，准备做下一个功能。
📦 归档是 OpenSpec 和 Superpowers 的关键差异。 Superpowers 没有归档机制，所有 Spec 文档并列保存着，时间一长就很乱——你不知道哪些是当前在做的，哪些是历史的。OpenSpec 归档后，历史变更有条理地存在
archive/里，随时可以回看。
4. 安装 OpenSpec
前提条件
OpenSpec 通过 npm 安装，所以你需要先装好 Node.js（第 1 课的环境准备应该已经装了）。
安装步骤
打开终端，运行：
npm install -g @fission-ai/openspec@latest然后在你的项目文件夹里初始化：
# 基本初始化
openspec init
# 或者指定你用的 AI 工具（推荐）
openspec init --tools claude,opencode,codex初始化后，OpenSpec 会自动在你的 AI 工具配置里添加六个 Skill（斜杠命令），你在 AI 对话框里输入 /opsx 就能看到它们。
让 AI 帮你安装
如果你不想记命令，也可以直接把 GitHub 链接发给 AI，让它帮你安装：
帮我安装 OpenSpec 插件：https://github.com/Fission-AI/OpenSpec
AI 会自动执行安装和配置。
卸载 Superpowers（如果之前装了）
OpenSpec 和 Superpowers 功能相似，留一个就行。如果你想换成 OpenSpec，跟 AI 说：
帮我卸载 Superpowers 插件，包括 Skill 也一起卸载
TIP
两个插件同时装着会功能冲突，建议卸一个留一个。我个人用下来感觉 OpenSpec 更贴近需求，所以推荐它。
5. OpenSpec 的核心优势
① 告别模糊提示词
以前跟 AI 做事，需求写在聊天历史里。聊着聊着上下文满了，你压缩会话或开新会话，之前的细节就丢了。
用 OpenSpec，需求写进 Spec 文档。文档在仓库里，不在聊天里。 压缩会话、开新会话都不影响，因为文档还在。
② 可审查、可追溯
每次变更都有完整记录：方案文档、设计文档、任务列表。归档后加时间戳存档。
六个月后回头看，你知道当时为什么这么做、改了哪些东西、任务列表是怎么拆的。
③ 循序渐进
先定方案 → 审查通过 → AI 执行。不会一上来就猛写代码，写完发现方向不对又要推倒重来。
④ 保持上下文干净
讨论阶段可能会聊很久，上下文容易爆。但需求写进文档后，你就可以放心压缩会话了——文档是持久化的，压缩不影响。
AI 用文档继续推进，注意力不会因为上下文太长而涣散。
⑤ 主线推进，不跑偏
每次变更都跟主架构对齐。做完一个功能，Sync 回主架构，Archive 归档。然后开下一个变更，继续在主线上推进。
6. 兼容 30+ 主流 AI 编程工具
OpenSpec 不挑工具，一套规范框架覆盖所有主流 AI 编码 agent：
- 第一梯队：Claude Code、OpenCode、Codex
- 第二梯队：Cursor、Windsurf、GitHub Copilot
- 更多：Cline、Continue、Gemini CLI、Amazon Q、RooCode、Kiro、Qwen Code……还在持续增加
工作流完全一致——不管你用哪个工具，五个阶段、五条命令，用法一样。
7. 实战演示：修两个 Bug 的完整流程
视频里我用自己开发的一个 AI 审计工具箱做演示，还原了一个真实的开发过程。
发现问题
我在测试时发现了两个 bug：
- 流程模式中运行时，调用 Read 工具报错
- 运行过程中点「停止」按钮没有反应
第一步：Explore 探索
输入 /opsx:explore，把两个 bug 描述发给 AI：
目前在流程模式中运行时，调用 Read 的工具报错。另外，运行过程中点击停止，但是没有反应，并没有停止。帮我看一下这两个问题。
AI 进入探索模式，读代码、定位原因、跟你聊方案。
💡 关于 Sub Agent
探索过程中，AI 可能会派 Sub Agent 去做更细致的排查。在 OpenCode 里可以用 Ctrl+X + 方向下键查看 Sub Agent 的执行情况。
第二步：Propose 提议
方案聊清楚后，输入 /opsx:propose。AI 创建变更文件夹，写好需求文档、设计文档和任务列表。
重要：写完文档后先别急着执行，让 AI review 一下。
如果你装了 oh-my-opencode-slim 插件，它会派 oracle（用更好的模型）独立检查文档。新开的 Agent 没有当前上下文的干扰，能站在第三方角度发现文档里的问题。
比如我的演示里，oracle 发现了一个冲突：proposal 和 spec「自己打脸」——两个文档说了相反的话。我让 AI 用通俗易懂的方式解释冲突，确认后让它修改。
第三步：Apply 执行
文档确认没问题，输入 /opsx:apply。AI 按照任务列表（比如 1.1 到 4.3）逐个完成，做完了打勾。
⏱️ 执行时间取决于任务多少，可能几分钟，也可能跑几个小时。
如果你用的是 Electron 开发的桌面应用，还可以装一个 Electron MCP，让 AI 自己打开应用做功能测试，不用手动验证。
第四步：Sync 同步
代码写完、人工验证没问题后，输入 /opsx:sync。
这一步把本次变更的内容同步到主架构文档，保证主架构是最新的。
第五步：Archive 归档
最后输入 /opsx:archive。AI 把任务列表全部标记完成，变更文件夹加时间戳归档。
至此，一次完整的变更（或功能开发）就全部完成了。
又发现新问题？再开一个变更
演示最后，我又发现了一个新的 bug（任务列表显示顺序有点混乱）。没关系——归档完上一个变更后，重新 /opsx:explore，开启一个新的变更。
这就是 OpenSpec 的节奏：一个 Spec 一个 Spec 地小步前进。 每一步都有记录、有方向，不会跑偏。
8. 什么时候用 OpenSpec？
适用场景
做稍大一点的项目时用。 比如你从零开始搭一个工具、一个系统，功能不止两三个，可能会持续迭代——这时候用 OpenSpec 管理变更，效果最好。
如果你只是让 AI 帮你写个小脚本、处理个 Excel，不用搞这么复杂。OpenSpec 的价值在于管理持续演进的项目，让需求有迹可循、方向不跑偏。
一句话总结：小需求直接聊，大项目用 Spec。
关键收获
TIP
OpenSpec = 给 AI 编程加一个「协议层」。
需求写进文档，不再散落在聊天记录里。每个功能走五个阶段：探索 → 提议 → 执行 → 同步 → 归档。归档后主规范持续演进，历史变更完整保留。
三个核心好处：
- 告别模糊提示词——需求在文档里
- 可审查可追溯——每次变更都有完整记录
- 循序渐进——先对齐再编码，不浪费代码量
安装一行命令：
npm install -g @fission-ai/openspec@latest参考链接
- OpenSpec GitHub 仓库（61.6k ⭐）：https://github.com/Fission-AI/OpenSpec
- npm 包地址：@fission-ai/openspec
- 第 5 课：Superpowers 增强插件（功能相似，二选一）