有一种痛，叫 AI 已经把代码写完了，我才发现它根本没理解需求。

---

一、那个 AI 没接住需求的下午

先承认一件事，让 AI 写代码，十次里有七次是顺畅的。

剩下三次，它写出一段能运行、但完全不是我要的东西。我没让它做的功能它加上了，我反复强调的边界它忘了。更难受的是，我根本说不清它在哪一步偏离了方向，因为所有需求都躺在聊天记录里，往上一翻就没了。

问题不在模型。需求这件事，一旦只存在对话框里，就会随上下文一起消失。

二、OpenSpec 是什么

为了解决这个问题，这半年出现一批叫 spec-driven development 的工具，中文叫规范驱动开发。GitHub 官方出的 Spec Kit 先流行起来。英国开发者 Dan Clarke 用过，没能坚持下来。他的理由很实在，Spec Kit 过于笨重，而且他对 "constitution" 这个词实在喜欢不起来。

于是他转向 OpenSpec。他自己的评价是 nice and lightweight，轻，易用，用了一个月，越来越觉得值得。

OpenSpec 想解决的就是这件事。它的口号很朴素，先对齐，再写代码。

概括地说，OpenSpec 是一个规范驱动开发框架，作者是 Tabish Bidiwale，开源，不绑定 API key，不绑定特定编辑器。它支持的 AI 助手超过二十五个，Claude Code、Cursor、Copilot 都在列。

它的仓库在 GitHub 上，数据截至 2026 年 8 月。

项目	信息
仓库	Fission-AI/OpenSpec
Stars	6.5 万
Forks	4.5k
Open Issues	174
License	MIT
语言	TypeScript
创建时间	2025 年 8 月
最近提交	2026 年 8 月
官网	openspec.dev

核心机制只有一条，动手写代码之前，让人类和 AI 在一份规格文档上达成一致。

这份规格不写在脑子里，它写进仓库。项目里会多出一个 openspec 目录，specs 放当前真相，changes 放每一次改动。改一次需求，就先写一份提案，AI 和人类评审通过后，再进入实现，最后归档，把改动合并回 specs。

听起来像瀑布开发，其实不是。它更像给 AI 配了一本可以翻页的合同。

三、Dan Clarke 的意外发现

英国开发者 Dan Clarke 用了一个月 OpenSpec，写了一篇很实在的文章。他没有把它说成银弹，反倒讲了个意外的结论。

他把结论写成了这句话。

"specs are an artifact of the workflow, not the starting point"

规格是产物，不是起点。

写规格这项工作由 AI 完成，人类只负责点头确认。整个过程里，人类不手写 PRD，先与 AI 讨论，让 AI 把需求、探索、设计写成规格文档。

这个反转值得琢磨。工具名叫"规范驱动"，转起来靠的是那场对话。

四、一条完整的学习路径

讲完理念，进入实操。整套流程走通，就五条命令。

第一步，装 CLI，Node 版本要 20.19 往上。

 npm install -g @fission-ai/openspec@latest

第二步，在项目里初始化。

 openspec init

它会问用哪个 AI 工具，选 Claude Code，自动生成技能和斜杠命令。

第三步，在聊天里输入斜杠命令。注意，是聊天框，不是终端。

 /opsx:explore   可选，把模糊需求理清楚
 /opsx:propose   写提案
 /opsx:apply     按提案实现
 /opsx:sync      合并增量 spec
 /opsx:archive   归档合并

完整路径走下来是这条线。

 /opsx:explore → /opsx:propose → /opsx:apply → /opsx:sync → /opsx:archive
    理清楚       写提案       按提案实现      合并增量     归档合并

必走的是 propose → apply → sync → archive 四步；explore 标着"可选"，但 Clarke 力荐不要跳过，实操时先执行它。

下面按 Clarke 的体验，把这几个阶段拆开讲。

五、explore，先对齐再动手

Clarke 点名的第一个 killer feature，是一个被官方文档冷落的功能，/opsx:explore。入门页只写了 propose → apply → sync → archive 四步，几乎没提 explore，他却给了 "brilliant" 这个评价，说是自己的默认起点。

触发方式很灵活。一段需求描述、一个 JIRA 工单或 GitHub issue、一张截图，甚至直接口述，都能触发，还能指向过去的 spec 作为上下文。

进入 explore 模式后，agent 先把需求彻底理清，再浏览代码库，用一连串追问补齐缺口，直到所有事项敲定。它会画出 ASCII 架构图和流程图，如果有几种解法，就逐个列出利弊，辅助决策。

有人会想，这不就是所有编码 agent 都自带的 plan mode 吗。Clarke 的结论是，explore 做得远超开箱的 plan mode。当然，不用 OpenSpec 也能自己写一段 prompt 促使 agent 多问几句，但 OpenSpec 把这套能力成套提供，还在探索结束后，顺带把下一节的产物和 spec 一并生成。

六、四个产物，AI 代写

explore 结束、双方都满意后，agent 通常会问一句，要不要生成 proposal。这是 OpenSpec 的术语体系，Clarke 专门列了一节来理清。

一次需求叫一个 change，就是磁盘上一个目录，相当于所有产物的容器。

agent 生成的文件统称 artifact，人类不用手写 PRD 和设计文档，AI 写完，不满意可以随时修改，主要是四类。

• proposal.md

  ，讲 what 和 why，这次要做什么、为什么做。

• design.md

  ，讲技术决策。

• tasks.md

  ，带勾选框的待办清单，agent 实现时逐条打勾。

• delta spec

  ，标记这次改动的增量规格，下一节会讲。

tasks.md 还能手动加条目。比如"给三个环境配好 KeyVault 密钥"这种纯手工操作，写进去，它就成了这次 change 的验收项，不会遗漏。

七、apply 之后，归档合并

产物都存盘之后，进入实现。可以直接让 agent apply，也可以显式执行 /opsx:apply。这一步能在全新会话里完成，因为 proposal、design、tasks 都在磁盘上，不依赖原来的聊天记录。

agent 开始动手写代码，按 tasks.md 逐条实现、逐条打勾，可以实时观察它的推进。

实现完成后，agent 会问要不要归档，也就是 /opsx:archive。它把 change 目录移进 archive/ 留档，同时把 delta spec 合并回 specs/，这一步叫 sync，归档时通常自动完成。

delta spec 用三段标记这次改了哪些需求，## ADDED Requirements 是新增、## MODIFIED Requirements 是修改、## REMOVED Requirements 是删除。归档时 OpenSpec 把这些增量并入该功能的正式 spec，下次读它，能看到所有改动拼出的完整画面。

注意这会产生一批新的 Git 变更，宜在 PR 合并前完成，否则需要为归档再开一个 PR。

这也带出 Clarke 说的第二个大收益，规格是出色的上下文引导。下次处理相关的任务，直接把旧 spec 交给 AI，它就知道这功能当初为什么这么设计。代码记不住"为什么"，规格却记得住。

八、跟 Matt Pocock 的技能比一比

有人会问，这不就是又一套 AI 技能吗，跟 Matt Pocock 的那些技能有什么区别。

Matt Pocock 是 Total TypeScript 的作者，在 TypeScript 圈里名气不小。他把自己的 .claude 目录开源了，起名 "Skills for Real Engineers"。里面是一条完整的流水线，/grill-with-docs 负责拷问、一边追问一边建领域模型，/to-spec 把问出来的共识合成一份规格发布到工单系统，/to-tickets 再把规格拆成一张张带依赖关系的工单，最后 /implement 逐个实现、/code-review 收尾。

OpenSpec 和它同属一个物种，都以技能和斜杠命令的形式安装进 Claude Code，对准的都是同一件事，那个不思考就动手写代码的 AI。连步骤都能对上，/grill-with-docs 像 /opsx:explore，/to-spec 像 /opsx:propose，/to-tickets 像 tasks。

区别在规格的归宿。

Matt 的 spec 是中间产物。/to-spec 把当前对话合成一份 PRD，发布到 GitHub 或 Jira，随后拆成那些带依赖边的工单，驱动执行的其实是工单。文档会留在工单系统里，可以回头翻阅，只是它不会像 OpenSpec 那样，被主动送回给 AI 作为上下文。

OpenSpec 的 spec 是长期资产。每次改动只写增量，archive 时把增量合并回 openspec/specs/，规格和代码一起演进。下次做相关的任务，直接把旧规格交给 AI，它就知道这功能当初为什么这么定。

概括地说，Matt 管的是把任务拆成工单、以 TDD 推进，OpenSpec 管的是让意图累积成一份能回溯的档案。前者是施工图，后者是宪法修正案。

九、Spec-to-Code 这条路，OpenSpec 走不走？

其实这两者之间还能再细一层对照。Matt 在另一场演讲里专门批过一个叫 Spec-to-Code 的模式，写一份规格让 AI 生成代码，出现 bug 时不修改代码，而是回头改规格再重新生成，人全程不看代码。他称之为软件熵，每多跑一轮，代码质量就更差一分。

乍一看这像是在批评 OpenSpec。都是 spec-driven，都有规格和代码的接力。差在规格的定位。Matt 批的那个模式里，规格是人写的输入，代码是廉价输出，改需求就改规格、重新生成。OpenSpec 相反，规格是 AI 在 explore 和 propose 里生成的产物，apply 时 AI 逐条写代码、人在旁审阅，代码还是要写、要改、要审。

Clarke 那句话放在这里格外清楚，specs are an artifact of the workflow, not the starting point。规格是产物，不是起点。Matt 说的质量差的代码最贵、代码不是廉价的一次性产物，两句话说的是同一件事。

这两人其实是战友。Matt 的 Grill Me 和 OpenSpec 的 explore 几乎是同一个动作，写代码之前先拷问对齐。两人都不满意编码工具自带的 plan mode，嫌它过于急于产出计划、急于动手。共同要治的，是那个不思考就写代码的 AI。

不过 Matt 的警告对 OpenSpec 用户同样成立。

 spec 只解决对齐，解决不了代码质量。对齐之后撒手让 AI 生成、不再审阅代码，OpenSpec 就变成了他提醒的那种做法。TDD、模块设计、接口边界这些环节，仍须由人把关。

十、选 OpenSpec 还是 Matt 的 Skills？

这两者不必二选一。想给老项目做增量改动、又希望每次的"为什么"能沉淀下来，OpenSpec 更合适。想把一个任务拆成带依赖的工单、以 TDD 逐条完成，Matt 的方式更直接。两者叠着用也成立，把 Matt 拷问完生成的 spec 放进 OpenSpec 存起来，一份作为工单的种子，一份作为长期的档案。共同的那条底线不变，写代码之前，先对齐。

---

本文参考 Dan Clarke 的文章、OpenSpec 官网及 GitHub 仓库。

建议收藏，转给同样在和 AI 抢方向盘的朋友。

话题标签 #OpenSpec #规范驱动开发 #ClaudeCode #AI编程 #SpecDrivenDevelopment #AI写代码 #程序员 #开发者工具 #AICoding #开源工具