约 8 分钟
👁 0 次浏览

OpenSpec 入门：AI 时代的规范驱动开发

AI 编码助手指令模糊时会靠猜，OpenSpec 通过规范驱动开发（SDD）让 AI 先搞清楚要做什么，再动手写代码。

开篇

让 Claude 或 Cursor 写一段功能，体验过的人多半都遇到过同一种尴尬：

你说「加个注册登录页」，它噼里啪啦写了 800 行——多了个忘记密码、多了个三方登录、还顺手装了三个新依赖。你愣两秒说「我没让你做这些」，它回一句「我以为你需要」。

这是当前 AI 编码助手最大的灰色地带。指令模糊的时候，AI 必须靠猜。 猜对了你赚到，猜错了从头返工。

OpenSpec 想解决的就是这一件事：让你别再让 AI 猜。

第一层：三层工具各管什么？

要理解 OpenSpec 的价值，先得把它和已有的工具区分开。很多人第一次看会觉得「这不就是 CLAUDE.md 换了个名字」——其实是完全不同的层次。

第一层：CLAUDE.md — 行为风格

管的是 AI 写代码时该守哪些规矩：

  • 别过度设计
  • 别动没让你动的代码
  • 遵循项目的代码风格

它回答的问题是：「写代码的时候注意什么？」

第二层：Skill — 做事流程

管的是 重复任务的标准化步骤：

  • 改公众号文章该按哪几步走
  • 写 API 文档的固定模板
  • 发版前的 checklist

它回答的问题是：「这类任务怎么做？」

第三层：OpenSpec — 需求定义

管的是 这一次具体要做什么、做到哪算完、有哪些边界条件。

它回答的问题是：「这次我们要解决什么问题？」

举个例子。「加个注册登录页」这句话扔给 Claude：

  • CLAUDE.md 帮不了你——它只管 AI 怎么写代码，不管该写什么
  • Skill 也未必帮得上——这不是你重复在做的事
  • 你真正需要的是一份双方都点头同意的需求文档

这个空缺，就是 OpenSpec 想填的。

它的核心思想叫 SDD（Spec-Driven Development，规范驱动开发）。一句话讲清楚就是：

先把规范写清楚，再让 AI 按规范施工。

第二层：OpenSpec 具体干什么

OpenSpec 是一个开源 CLI 工具（Fission-AI/OpenSpec），免费、无需 API Key，支持所有主流 AI 编码助手（Claude Code / Cursor / Codex 等）。

它的产物是一组结构化的变更文件夹。每次做一个功能，就有一个独立的目录：

文件作用
proposal.md为什么做、做什么、影响什么
tasks.md实施的任务清单
design.md技术决策（可选）
specs/本次新增或修改的规范增量

这堆文件不是给人单独看的，是给 AI + 人一起看的合同。AI 看着它写代码，人看着它审查。等代码合并，规范增量也合并到项目主规范里。

目录结构

openspec/
├── project.md           # 项目整体约定（技术栈、风格）
├── AGENTS.md            # 给 AI 的工作流说明
├── specs/               # 主规范（项目当前的"唯一真相"）
│   ├── spec.md
│   └── design.md
└── changes/             # 变更提案
    ├── add-auth-pages/  # 一次具体的变更
    │   ├── proposal.md
    │   ├── tasks.md
    │   ├── design.md
    │   └── specs/       # 这次变更带来的规范增量
    └── archive/         # 已完成的变更归档

看一遍就懂了——每次变更都是一个可审计的小盒子，做完归档进档案柜。

第三层：一次完整的工作流

把「加个注册登录页」这个例子整段走一遍。

Step 1：起草提案

打开 Claude Code，丢一句话：

创建一个 OpenSpec 变更提案，用于添加一个注册登录页面

AI 不会立刻动手写代码。它会先反问。

因为 OpenSpec 的工作流要求它必须先把规范写清楚再说。通常它会问几个关键问题：

  • 认证方式是本地还是接 API？
  • 要不要忘记密码？要不要三方登录？
  • 路由用 Vue Router 还是别的？
  • 登录后跳到哪？

你逐条回答完，AI 才会生成 proposal.md、tasks.md、specs/ 这一整套提案文档，并自动调用 openspec validate 验证。这一步不通过，下一步走不了。

这个「被强制反问」的体验是 OpenSpec 最值钱的部分。很多模糊需求的坑，都是在这一步暴露出来的。

Step 2：审查对齐

提案生成出来，你扫一遍 proposal.md 和 tasks.md。这里没扫干净，后面 AI 写出来的就是你不想要的东西。

不满意当场补：

密码强度不要做客户端校验，挪到登录后端再校验

AI 会同步更新提案。改到你点头为止。

Step 3：实施

实施 add-auth-pages 变更提案

AI 严格按照 tasks.md 一项一项做，做完一项打勾一项。

中间你看到样式不对、想换个交互方式，直接说就行——但说完之后，最好让它把改动同步更新到提案里，而不是只改代码不改规范。不然过几天再回来看，代码和规范对不上，OpenSpec 的复利就断了。

Step 4：归档

归档变更 add-auth-pages

OpenSpec 会做两件事：

  1. 把 changes/add-auth-pages/ 整个移到 changes/archive/ 下，加上时间戳
  2. 把这次变更带来的规范增量，合并到 openspec/specs/ 主规范里

到这一步，「加注册登录页」这件事就在项目史里留下了完整的痕迹：提案在哪、为什么这么做、做了哪些任务、最后规范长成什么样。一年后新人接手，照着 openspec/specs/ 读就够了。

第四层：为什么这件事在 AI 时代特别重要

第一次看 OpenSpec 的时候，第一反应是：「这不就是把以前 PRD 的事情用 markdown 重做了一遍？」

后来想明白了，不太一样。

PRD 写完之后还得有人翻译成代码，中间有大量「我以为你懂」的损耗——产品经理觉得讲清楚了，工程师听到的是另一回事。OpenSpec 的规范直接给 AI 当输入，AI 拿着规范就开始写代码，中间不需要人当翻译。

翻译这层一消失，模糊性就藏不住了。

以前你可以靠「工程师会脑补」蒙混过关，现在 AI 也会脑补，只不过它脑补的方向你预测不了，最后给你写出 800 行你不想要的东西。

这就是 SDD 这个词最近在 AI 圈反复被提起的原因。AI 让 build 变快之后，最大的瓶颈从「会不会写」变成了「能不能讲清楚要写什么」。 讲不清楚的代价，从工程师摸鱼变成了 AI 一头扎进错的方向。

OpenSpec 把「讲清楚」这件事做成了一套有目录、有验证、有归档的流程。

人定义 What，AI 负责 How——这是它想要的分工。

第五层：避坑与边界

怎么装

前置条件：Node.js 20.19.0 及以上。

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

openspec init 会让你选 AI 工具（Claude Code / Cursor 等都支持），选完会在项目里生成对应的自定义命令，比如 /openspec:proposal、/openspec-apply、/openspec-archive。

初始化完，三句话就能上路：

  1. 「请阅读 openspec/project.md，根据我的项目情况帮我填一下」
  2. 「我想加 XXX 功能，请创建一个 OpenSpec 变更提案」
  3. 「请阅读 openspec/AGENTS.md，告诉我我们应该怎么协作」

整个学习曲线大约就在这三句话里。

坑一：学习成本不是零

OpenSpec 引入了一套自己的目录结构和命令体系，第一次用得花十几二十分钟搞清楚 proposal / tasks / specs / archive 这几个概念之间的关系。如果团队里没有一个人当锚，很容易用着用着就乱。

坑二：小项目不必上

写个爬虫、跑个数据清洗的 notebook、做个一周后就扔的内部工具，引入 OpenSpec 是杀鸡用牛刀。它的好处在中长期项目上才显现——做得久、规范积累得厚，回头读规范才省事。

坑三：改了代码没更新规范

最容易踩的坑就是实施时改了代码但没更新规范。这一步守不住，OpenSpec 就废了一半，因为下次新人来读 openspec/specs/ 看到的是错的真相。这件事得靠习惯，工具帮不了你。

总结

以前「先想清楚再动手」是一句鸡汤，因为成本上没人逼你想。

现在 AI 让 build 变得太便宜，前面少想一步的代价是后面 AI 帮你 build 出 10 倍的错东西。OpenSpec 把「想清楚」这一步从口号变成了一个有目录、有文件、有验证的环节，让你不得不走一遍。

如果你已经在做一个跑了三个月以上、还会继续做下去的项目，值得花一个下午把它装上跑一遍。

参考：@freeman1266 X Article