OpenSpec 值得用吗？规范驱动开发不会让 AI 写出更好的代码

发表于 更新于 分类于 ， 阅读次数： 本文字数： 7.8k 阅读时长 ≈ 7 分钟

OpenSpec 规范驱动开发框架实测：蓝图约束建造过程

OpenSpec 最近很火。我今天拉了一下数据：GitHub 62,622 个 Star，npm 上过去 30 天下载 1,167,577 次。中文社区里介绍它的文章也开始多起来，说法高度一致——轻量、brownfield 友好、告别 AI 乱写代码。

但我把它的官方文档、CHANGELOG、GitHub Issue 列表和几篇实测博客全部翻了一遍之后，结论和这些文章不太一样：OpenSpec 不会让 AI 写出更好的代码，它只能让 AI 少写你没要求的东西。 这两件事听起来像一回事，实际上决定了这套规范驱动开发流程对你是净收益还是纯亏损。

我在《Spec编程你了解吗? 还在用Vibe Coding吗?》里聊过 SDD 这个范式本身，那篇是概念层面的。这篇不一样，这篇要落到一个具体工具上，并且我会花很大篇幅讲它不行的地方——因为决定你要不要引入一个流程框架的，从来不是它的优点清单。

OpenSpec 解决的是对齐问题，不是能力问题

想清楚这个区分，你就能自己判断该不该用它了，剩下的都是细节。

AI 写代码写砸，其实是两类完全不同的失败。第一类是对齐失败：你要的是 A，它理解成了 A’，然后照着 A’ 一路写下去，你在第三轮对话才发现方向早就偏了。第二类是能力失败：它准确知道你要 A，但它就是做不好 A——架构品味不够、性能没考虑、UI 审美平庸。这两类失败看起来都是”AI 乱写代码”，治法完全不同。

规范层只能治第一类。OpenSpec 的做法是把需求写成带场景的 Markdown，一条 requirement 配至少一个 GIVEN-WHEN-THEN 的 scenario，本质上是把验收标准提前固化成一份可以 review 的文本。你在看 250 行提案的时候纠正方向，成本远低于在看 2000 行 diff 的时候纠正方向。这是它真实的、可靠的价值。

但它对第二类失败几乎无能为力。你可以在 spec 里写”按钮必须有 hover 态、必须支持键盘导航”，这些是可验收的；你写不出”这个配色要好看”——写了模型也不会因此突然长出审美。这一点后面我会用一个具体的失败实验来证明。

还有一层价值容易被忽略，我认为反而是它最值钱的部分：**openspec/specs/ 这个目录是给未来的 AI 会话读的项目记忆。** 一次变更 archive 之后，delta spec 会被合并进主规格库，跟着 git 一起版本管理。半年后你换了个新会话、甚至换了个 AI 工具来改同一块代码，它读到的不是你早就关掉的聊天记录，而是一份持续更新的、描述系统当前应该是什么样的文档。我之前写过《你的 AI 助手得了健忘症？这个工具让它拥有长期记忆》，讲的是用专门的记忆系统解决跨会话失忆；OpenSpec 走的是另一条路——不额外搭系统，就让规格文件本身当记忆，代价是这份记忆需要你在每次变更时付出维护成本。

这也意味着一个判断：如果你这个项目根本不打算长期维护，OpenSpec 的一半价值直接归零。 写完就扔的脚本、验证想法的原型、周末的玩具项目，规格沉淀给谁看？

三个关于 OpenSpec 的误解，官方文档里都写着，但没人读

误解一：brownfield-first = 它能给我的老项目逆向生成规格

这是我见过传播最广、也最容易让人失望的误解。很多介绍文章写”OpenSpec 专为已有代码库设计，不需要重写项目”，读者顺理成章地理解成：跑一下 init，它就能扫描我的代码库，把现有功能整理成规格文档。

它不做这件事，而且是明确拒绝做。 官方的 existing-projects.md 里原话是：”You do not document your whole codebase to start. You write specs only for what you’re about to change.”（一开始不要给整个代码库写文档，只给你即将改动的部分写规格。）文档里甚至专门有一条劝告：Resist the urge to back-fill everything——别想着把老代码统统补上规格，给你根本不打算改的代码写文档，”看着很有产出，其实多半没用”。

所以你 openspec init 之后看到 openspec/specs/ 是空的，那不是 bug，那是设计。这个目录从接近全空开始，靠你一次次真实变更慢慢累积。想要”读代码反向生成规格”这个功能的人不少，GitHub 上 #724 这个 issue 就是专门提这个的，攒了十几个赞，至今没实现。

那 “brownfield-first” 到底什么意思？意思是 delta spec：每次变更只描述增量，用 ## ADDED Requirements、## MODIFIED Requirements、## REMOVED Requirements、## RENAMED Requirements 四种标记说明这次变了什么，archive 时按语义合并进主规格。它的对手是那种”必须先有完整系统规格才能开工”的重型流程——OpenSpec 不要求你先有完整规格，这才是它对老项目友好的地方。它友好的是流程门槛，不是文档存量。

误解二：用了规范驱动开发，AI 写出来的代码质量会更好

这个误解我要用一个真实的失败案例来拆，因为光讲道理没有说服力。

DEV Community 上有位开发者写了一篇《OpenSpec (Spec-Driven Development) Failed My Experiment》，做的是一个 .NET Razor Pages 二手车信息站，后端已经有了，任务是把前端从”基础、没有生气”的样子改成”看起来高级”。他严格走了完整流程：生成提案 → 审核规格 → 批准任务 → 执行。花了约 2 小时，烧了可观的 token，最后产出的界面”和原来几乎一模一样”。 他怀疑是模型问题，换成 GitHub Copilot + Claude Haiku 又跑了一遍，结果同样令人失望。最后他把整个框架扔掉，写了一个普通的 Instructions.md 直接告诉 AI 要什么——更快、更便宜，效果反而更好。他还顺手用同样的方式修了个图片上传的 bug，几乎瞬间就解决了。

很多人看到这个案例的反应是”这人不会用”。我的看法不一样：这个实验精准地暴露了规范层的边界。 “把 UI 改得高级一点”这个任务的失败模式是能力失败，不是对齐失败——AI 完全清楚你要什么（它甚至能把”高级感”拆解成规格条款：留白、层次、微交互），它只是做不出来。在这种任务上，你写多少页 spec 都是在给一个没有审美的模型下达更详细的没有审美的指令，中间还多插了提案生成、规格审核、任务规划三道消耗 token 和时间的工序。

反过来看什么任务适合：如果需求是”给结算流程加优惠券，不能影响现有退款逻辑和已有的满减规则”，那这就是纯对齐问题。这种需求口头说给 AI，它有八成概率会顺手把退款那块也”优化”一下；写成带场景的规格，你在动代码之前就能看到它打算碰哪些地方，这时候规范层是实打实的净收益。

所以判断标准很简单：先问自己这个任务砸掉的话，是砸在”没听懂”还是”做不好”上。 前者用 OpenSpec，后者别浪费那 2 小时。

误解三：轻量就意味着没有成本

“轻量”是 OpenSpec 最核心的宣传词，我认为它对，但这个”轻”是有明确参照系的——它是相对 spec-kit 轻，不是相对”直接跟 AI 说”轻。

最硬的证据来自官方 README 自己的 Usage Notes。那里写着两句话：一句是 “OpenSpec works best with high-reasoning models. We recommend Codex 5.5 and Opus 4.7”，另一句是 “OpenSpec benefits from a clean context window. Clear your context before starting implementation”。说人话就是：这套流程得配最贵的模型才跑得动，而且开工前你得先把对话清干净。 真要是零成本的工具，用不着叮嘱你这些。

成本具体花在哪？规格文件本身要占上下文，几千 token 的 proposal + specs + design + tasks 在实现阶段是要被读进去的；agent 的调用轮次也变多了，探索一轮、提案一轮、实现一轮、验证一轮。中文社区的实践反馈里，token 消耗在长会话中膨胀是被反复提到的问题，通行解法是开新会话再用 /opsx:continue <change-name> 接上——tasks.md 里的勾选状态就是断点续传的凭据。这个设计确实巧妙，但它存在本身就说明了问题的真实性。

这里有个反直觉的推论值得单独说：我在《CCX + CC Switch：让Codex接入DeepSeek、Kimi Coding的黄金组合》里介绍过怎么把便宜的第三方模型接进主流 AI 编程工具，很多人的思路是”用便宜模型跑更严谨的流程来弥补能力差距”。在 OpenSpec 上这个组合恰恰是最差解。 弱模型写出来的规格本身就模糊、场景覆盖不全，你还得花时间审这份低质量规格，审完再让同一个弱模型照着实现——省下的模型钱，加倍地花在你自己的时间上了。规范驱动开发放大的是模型的推理能力，而不是替代它。

OpenSpec vs Spec Kit：轻 68% 的代价是什么

既然”轻”是相对 spec-kit 而言的，那就得把这个对比说清楚。先摆两个容易被忽略的事实。

第一，OpenSpec 不是这个领域最大的项目。GitHub 上 spec-kit 今天是 123,903 个 Star，正好是 OpenSpec 的两倍。国内不少文章把 OpenSpec 说成”最主流的 SDD 框架”，这个说法不准确——它是最轻的那个，不是最大的那个。第二，两者的差距是可量化的。Hashrocket 做过一次同任务对比（从导航栏移除一个 Team 标签页），实测结果是：同样走到规划阶段，OpenSpec 产出约 250 行、分布在 3 个文件里，spec-kit 产出约 800 行。安装阶段差距也类似，OpenSpec 是 npm 装完加 3 个 CLI 命令，spec-kit 要 Python 包管理器、8 个命令，还要先写一份 constitution（项目宪法）。

那少掉的这 550 行是什么？是 spec-kit 的显式角色分离和阶段门禁。它强制你在进入下一阶段前完成上一阶段的产物，文档更啰嗦，但啰嗦本身在特定场景是功能：团队里有初级工程师、需要留下可追溯的决策记录、需要多人分工评审不同阶段——这些场景下，spec-kit 的”仪式感”就是它的价值。Hashrocket 那篇的结论也是这么给的：小团队的资深开发者选 OpenSpec（快、简洁），需要角色分离和详尽文档的团队选 spec-kit。

我自己的选择框架更直接一点：

你的情况 选择 理由
个人开发者 / 2-3 人小团队 OpenSpec 250 行的提案你会认真读完，800 行的你会直接划到底点同意
老项目上增量加功能 OpenSpec delta spec 天然匹配”只改一小块”的工作方式
全新项目、要先定架构原则 spec-kit constitution 这一层 OpenSpec 没有对应物
团队有初级工程师需要流程约束 spec-kit 阶段门禁是给人用的护栏，不是给 AI 用的
要跨多个仓库统一规格 都不成熟 OpenSpec 的 Stores 还是 very early beta，慎入
只是想让 AI 别乱改文件 都不用 一个 AGENTS.md 加几条约束就够了

最后一行是认真的。如果你的痛点只是”AI 老是顺手改我没让它改的文件”，那不需要引入任何框架，写清楚项目约定就能解决八成问题。框架要解决的是跨会话、跨人、跨时间的对齐，不是单次对话的约束。

什么时候该用 OpenSpec，什么时候是纯亏损

把前面的分析收敛成一张可以直接用的表。这是我认为这篇文章里最值得截图保存的部分：

场景 用不用 关键判断
老项目加功能，怕碰坏现有逻辑 ✅ 用 典型对齐问题，规格能提前暴露”它打算碰哪些文件”
需求要跨好几天、多个会话完成 ✅ 用 tasks.md 的勾选状态就是断点，比翻聊天记录可靠
团队 review 时想先看意图再看 diff ✅ 用 审 250 行提案 vs 审 2000 行 diff
需求本身还很模糊，你自己没想清楚 ✅ 用 /opsx:explore 这个命令不产生任何文件，纯思考搭子，零负担
改一个文件就能修的 bug ❌ 别用 走完流程的时间够你修三遍
UI 美化、”做得更高级一点”类任务 ❌ 别用 能力失败，规格无解，前面那个 2 小时的实验就是证据
一次性脚本、验证想法的原型 ❌ 别用 规格沉淀没有下游消费者
预算有限只能用弱模型 ❌ 别用 官方推荐 Opus 4.7 / Codex 5.5，弱模型跑这套是负优化
需求每天都在变的探索期项目 ⚠️ 慎用 规格维护成本会超过收益，等稳定了再引入

有一个反例我想特别提醒。有人的用法是”小改动嫌麻烦就跳过流程，大改动才走 OpenSpec”，这听起来很务实，但恰恰漏掉了风险最高的一档：范围不清晰的小需求，才是 AI 幻觉最集中的地方。 “顺手把这个字段加上”这种需求，你觉得是 5 分钟的事，AI 觉得是重构三个模块的事。真正该跳过的是范围明确的小改动（改文案、调参数），而不是所有小改动。

上手 OpenSpec：命令，以及 6 个会让你静默失败的坑

安装和初始化本身没什么可说的，Node 20.19.0 以上：

1
2
3
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init          # 交互式选择你用的 AI 工具

然后在你的 AI 助手对话框里（不是终端）走流程：

1
2
3
4
/opsx:explore                    # 想不清楚就先聊，不产生文件
/opsx:propose add-coupon-support # 生成 proposal / specs / design / tasks
/opsx:apply                      # 照着 tasks.md 实现
/opsx:archive                    # 归档，delta spec 合并进主规格库

默认 profile 只有 explore 和 propose 两个入口，其余动作由 AI 根据当前产物状态自己判断。想要 /opsx:new、/opsx:continue、/opsx:ff、/opsx:verify 这些细粒度命令，得用 openspec config profile 切到扩展 profile，再 openspec update 生效。

新手最容易卡住的地方是命令打在哪。 官方为此专门开了一整页 How Commands Work，开篇原话是：”If you ever type /opsx:propose into your terminal and nothing happens, this page is why.”

  • openspec init、openspec list、openspec status 是 CLI，打在终端里
  • /opsx:* 是 slash 命令，打在 AI 助手的对话框里
  • 写法还因工具而异：Claude Code 用冒号式 /opsx:propose，Cursor / Windsurf / GitHub Copilot 用短横式 /opsx-propose，CodeArts、Kimi CLI 走 skill 式 /openspec-propose。拿不准就在对话框里打个 /，看补全提示给的是哪种。

下面这 6 个坑是我从官方 CHANGELOG、troubleshooting 文档和 issue 里挖出来的，共同点是它们不会给你明显的报错，你以为一切正常，实际上东西没生效：

坑 1：不规范的三级标题会被静默跳过。 在 ## ADDED Requirements 区块里，只有 ### Requirement: 这个格式的标题才会被解析。你要是随手写了个 ### Documentation Requirements 当分隔符，解析器直接忽略它管辖的内容。1.6.0 才加了 INFO 提示，而且 CHANGELOG 里明确写了这条提示在 --strict 下也不会让校验失败。

坑 2：SHALL / MUST 必须写在正文行，不能只写在标题里。 ### Requirement: 系统必须支持优惠券 这样写，正文里没有 SHALL/MUST 关键词，会被判定为不合规。正确写法是标题写名字，正文写 “The system SHALL …”。这是 issue #361 拖了很久才修的问题。

坑 3：Scenario 必须是四级标题 ####。 写成 ### 或者 bullet list，不会解析成场景，而 “requirement 没有场景” 是最常见的校验失败原因之一。

坑 4：配置文件必须叫 openspec/config.yaml，不能是 .yml。 官方 troubleshooting 把这个列为配置不生效的头号原因。

坑 5：1.6.0 之前，openspec archive 校验失败也返回 exit code 0。 如果你把它写进了 CI，脚本会以为归档成功了，实际上什么都没改。这个 bug 在 1.6.0（PR #1311）才修掉——所以如果要在 CI 里用，先确认版本。

坑 6：Codex 用户没有 /opsx:* 命令文件。 Codex、Kimi CLI、CodeArts 等几个工具走的是 skill 机制，去 .codex/skills/openspec-* 下面找，别以为是 init 失败了。

还有一条不算坑但值得知道的：产物之间有依赖顺序，proposal 先行，它解锁 specs 和 design，两者齐备才解锁 tasks。看到 “No artifacts ready” 的时候，跑 openspec status --change <name> 就能看到卡在哪一环。

我的建议

写到这里，我的判断应该已经很清楚了，收个尾。

OpenSpec 值得试，但要带着正确的预期去试。 它是一个把”你和 AI 对需求的共识”从聊天记录里搬到 git 里的工具，仅此而已。它不会提升 AI 的编码能力，不会自动整理你的老项目，也不是免费的——它要你付出最贵的模型、额外的 token 和审阅规格的时间。这些成本换来的是：跨会话不失忆、改老代码时能提前看清会波及哪些地方、团队 review 时看意图而不是看 diff。这笔交易在什么时候划算，上面那张决策表已经写清楚了。

如果你要开始，我建议这么走：挑一个你本来这周就要做的、范围中等的真实需求——不要挑玩具任务，也不要挑重构级的大工程——用 /opsx:explore 起头，走完一个完整的 propose → apply → archive 循环，然后回头看 openspec/specs/ 里留下了什么。如果那份文件让你觉得”三个月后我会庆幸它存在”，就继续用；如果你觉得那就是一堆没人会读的 Markdown，那就说明你的项目还不到需要它的阶段，扔掉不可惜。

最后提醒一句：你真正该珍惜的资产是 openspec/ 目录里那堆纯文本，不是 /opsx: 这套命令。 这个项目 10 个月出了 41 个版本，中间做过一次把全部命令删掉重来的大重构，跨仓库共享规格的 Stores 功能至今还标着 very early beta——我在《AI墓地：1592个死掉的AI工具》里统计过 AI 工具的存活率，这种迭代速度的项目该按”还在剧烈演化的实验品”对待，而不是按”基础设施”。所以别把团队的强制流程绑死在它的命令上；而带场景的 Markdown 规格，换任何 AI 工具都能直接读。绑定前者是风险，积累后者是资产。

参考资料

文中 Star 数、下载量、版本号数据采集于 2026 年 7 月 26 日。