第48课 · OpenSpec：规范驱动开发
本节要点
- OpenSpec 是什么：一个给 AI 编程加「协议层」的插件，让需求从「聊天里的一句话」变成「仓库里的一份文档」
- Spec 是什么：Specification（规范文档）的简称——你把需求写进文档，AI 照着文档干活，不再是「你说一句，AI 猜一句」
- 六个阶段一个闭环：Explore 探索 → Propose 提议 → Update 修订 → Apply 执行 → Sync 同步 → Archive 归档
- Update 是计划的「后悔药」：文档写完甚至代码写了一半，计划变了随时修订文档，保持各文档彼此一致——只改文档，不碰代码
- 归档是关键差异：相比第 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 → ✏️ Update → ⚡ 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：Update 修订（计划变了就回来）
计划不是一次定死的。文档写完、甚至代码写了一半，你随时可能改变主意：
- review 时发现设计有漏洞
- 执行中发现某个方案行不通
- 需求本身变了
这时候输入 /opsx-update，让 AI 修订变更文件夹里的文档——改了设计，任务列表跟着改；改了需求，设计文档也要对齐。它的职责就是让所有文档保持彼此一致，不留「自己打脸」的矛盾。
两条铁律：
- 只改文档，不碰代码——如果修订后的计划意味着代码要动，AI 会停下来指向
/opsx-apply - 只改已存在的文档，不新建文件（新建文档是 propose 的事）
一个简单的分工口诀：
计划落后于现实 → Update（改文档）；代码落后于计划 → Apply（改代码）。
阶段 4：Apply 执行
方案审查通过，输入 /opsx-apply。AI 按照 tasks.md 里的任务列表，一个一个去完成，做完了就打勾（✓）。
如果执行过程中发现方案有问题，可以随时 /opsx-update 更新文档继续编码——不是死板的阶段门禁。
阶段 5：Sync 同步
代码写完了，输入 /opsx-sync。这一步把实际实现的内容回写到主规范文档里。
为什么要同步？因为 AI 执行时可能跟计划有出入。Sync 把真实情况记录下来，保证主架构文档是最新状态。
💡 平时可以直接走 Archive——归档时会自动顺带完成同步。单独用 Sync 的场景是：change 还要继续活跃，但你想让主规范「先走一步」。
阶段 6：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（斜杠命令），正好对应六个阶段：/opsx-explore、/opsx-propose、/opsx-update、/opsx-apply、/opsx-sync、/opsx-archive。你在 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「自己打脸」——两个文档说了相反的话。
第三步：Update 修订
发现文档有问题，就轮到 Update 出场了。我让 AI 用通俗易懂的方式解释这个冲突，确认后让它修订文档——把矛盾的地方改一致。这就是 Update 的典型场景：不推倒重来，只把已有文档改对。
你也可以在 Apply 执行到一半时用 Update——发现方案行不通，改完文档接着编码，进度不丢。
第四步：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。
9. 进阶可选：用 /goal 插件驱动执行
本节是可选内容
不装这个插件，OpenSpec 的完整流程照样能跑完——Apply 阶段你盯着、每轮对话手动让它继续就行。Goal 解决的是「跑长任务时人不在旁边」的问题，属于锦上添花。
Apply 的痛点
OpenSpec 的 Apply 阶段，任务列表可能有几十项。AI 干活是以「轮」为单位的——一轮对话能做的事有限，干完一轮就停下来等你。
任务少的时候无所谓，你回一句「继续」就行。但任务多的时候：
- 你得守在电脑前不停地点「继续」
- 中途去吃个饭，回来发现它早就停了
- 换了个话题，它可能忘了原来干到哪了
Goal 是什么？
OpenCode Goal Plugin 给 OpenCode 加上了 Codex 风格的「目标模式」：
🎯 打个比方：OpenSpec 的文档是施工图纸，goal 就是给施工队（AI）派了个项目经理——目标不完成不下班，你不在场它也自己接着干。
它的核心机制：
/goal <目标>挂一个目标：目标写清楚做什么、验证标准是什么- 空闲自动续跑：一轮干完，会话空闲时自动开始下一轮，不用你催
- 完成必须给证据：AI 说「做完了」不行，必须附上验证证据（测试通过、文件确实改了、命令输出对得上）才能标记完成
- 干不了必须说明原因：被外部条件卡住（缺凭证、等你决策）要明确说阻塞在哪，不能装作完成了
- 安全阀：token 预算耗尽、连续几轮没实质进展，会自动暂停并给你一份交接总结——不会无限烧钱空转
安装
opencode plugin opencode-goal-plugin装完重启 OpenCode，输入 /goal 就能用了。目标会持续挂在会话上下文里（即使上下文压缩也不丢），空闲时自动续跑，状态可直接用 /goal 查看。
和 OpenSpec 怎么配合？
分工很清晰：
| OpenSpec | Goal | |
|---|---|---|
| 管什么 | 文档层——需求和计划怎么写 | 执行层——任务怎么跑完 |
| 回答的问题 | 「做什么、为什么、改哪里」 | 「干到哪了、还差什么、证据呢」 |
实战中最顺的用法：Propose 写好文档、你审查通过后，Apply 阶段不手动盯，直接挂一个 goal：
/goal 完成 openspec/changes/add-bank-reconciliation/tasks.md 里的全部任务，
每完成一项打勾，最后跑通测试再标记完成然后你就可以去干别的了。AI 会照着 tasks.md 一项一项推进，干完自动续跑，直到全部完成（附证据）或遇到真正干不下去的阻塞（它会停下来等你）。
目标措辞有个小技巧：写清楚范围、非目标和验证方式。比如「完成 tasks.md 全部任务」是范围，「不要动 config 目录以外的代码」是非目标，「跑通测试」是验证方式。写得越明确，AI 收工时给的证据越扎实。
常用命令
| 命令 | 作用 |
|---|---|
/goal <目标> | 设定一个新目标，开始长任务 |
/goal | 查看当前目标状态 |
/goal pause / /goal resume | 暂停 / 恢复 |
/goal <新目标> | 重新设定目标（覆盖当前） |
/goal clear | 清除目标 |
关键收获
TIP
OpenSpec = 给 AI 编程加一个「协议层」。
需求写进文档，不再散落在聊天记录里。每个功能走六个阶段：探索 → 提议 → 修订 → 执行 → 同步 → 归档。计划变了用 Update 修文档，代码欠账用 Apply 补齐。归档后主规范持续演进，历史变更完整保留。
三个核心好处：
- 告别模糊提示词——需求在文档里
- 可审查可追溯——每次变更都有完整记录
- 循序渐进——先对齐再编码，不浪费代码量
安装一行命令：
npm install -g @fission-ai/openspec@latest参考链接
- OpenSpec GitHub 仓库（61.6k ⭐）：https://github.com/Fission-AI/OpenSpec
- npm 包地址：@fission-ai/openspec
- 第 5 课：Superpowers 增强插件（功能相似，二选一）