初识 OpenSpec：AI 时代规范驱动开发的开源起点
OpenSpec 是开源免费的 SDD 工具——先把规范写清楚再让 AI 写代码。一篇讲清它干什么、和 CLAUDE.md / Skill 怎么分工、怎么装、什么场景别上。
让 Claude 或 Cursor 写一段功能，体验过的人多半都遇到过同一种尴尬。
你说"加个注册登录页"，它噼里啪啦给你写了 800 行——多了个忘记密码、多了个三方登录、还顺手装了三个新依赖。你愣两秒说"我没让你做这些"，它回一句"我以为你需要"。
这是当前 AI 编码助手最大的灰色地带。指令模糊的时候，AI 必须靠猜。猜对了你赚到，猜错了从头返工。
OpenSpec 想解决的就是这一件事：让你别再让 AI 猜。
它和 CLAUDE.md / Skill 不是同一层
先把概念分清楚，不然很容易混。
CLAUDE.md 解决的是"AI 写代码时该守哪些规矩"，比如别过度设计、别动没让你动的代码——管的是行为风格。
Skill 是另一类东西。你重复做的某一类任务，比如"改公众号文章"该按哪几步走，把这套流程沉淀下来给 AI 用——它管的是怎么做事。
OpenSpec 不在这两层上。它解决的是更前一步的问题：这一次具体要做什么、做到哪算完、有哪些边界条件。
举个例子。"加个注册登录页"这句话扔给 Claude，CLAUDE.md 帮不了你，因为它只管 AI 怎么写代码、不管该写什么；Skill 也未必帮得上，因为这不是你重复在做的事。你和 AI 之间真正需要的，是一份双方都点头同意的需求文档——这个空缺，就是 OpenSpec 想填的。
它的核心思想叫 SDD（Spec-Driven Development，规范驱动开发）。一句话讲清楚就是：先把规范写清楚，再让 AI 按规范施工。
它具体干什么
OpenSpec 是个开源 CLI 工具，GitHub 上叫 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/ # 已完成的归档
看完这个结构其实就懂大概了——每次变更都是一个可审计的小盒子，做完归档进档案柜。
一次完整的工作流
把"加个注册登录页"这个例子整段走一遍，OpenSpec 的味道就出来了。
起草提案
打开 Claude Code，丢一句话：
创建一个 OpenSpec 变更提案，用于添加一个注册登录页面
AI 不会立刻动手写代码，它会先反问。因为 OpenSpec 的工作流要求它必须先把规范写清楚再说。
通常它会问几个关键问题：认证方式是本地还是接 API？要不要忘记密码？要不要三方登录？路由用 Vue Router 还是别的？登录后跳哪？
你逐条回答完，AI 才会生成 proposal.md、tasks.md、specs/ 这一整套提案文档，并自动调用 openspec validate 验证一遍。这一步不通过，下一步走不了。
这个"被强制反问"的体验是 OpenSpec 最值钱的部分。很多模糊需求的坑，都是在这一步暴露出来的。
审查对齐
提案生成出来，你扫一遍 proposal.md 和 tasks.md。这里没扫干净，后面 AI 写出来的就是你不想要的东西。
不满意当场补：
密码强度不要做客户端校验，挪到登录后端再校验
AI 会同步更新提案。改到你点头为止。
实施
提案对齐完，开始写代码：
实施 add-auth-pages 变更提案
AI 严格按照 tasks.md 一项一项做，做完一项打勾一项。
中间你看到样式不对、想换个交互方式，直接说就行——但说完之后，最好让它把改动同步更新到提案里，而不是只改代码不改规范。不然过几天再回来看，代码和规范对不上，OpenSpec 的复利就断了。
归档
归档变更 add-auth-pages
OpenSpec 会做两件事：把 changes/add-auth-pages/ 整个移到 changes/archive/ 下，加上时间戳；把这次变更带来的规范增量，合并到 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。
初始化完，跟着引导跑三句话就能上路：
- "请阅读 openspec/project.md，根据我的项目情况帮我填一下"
- "我想加 XXX 功能，请创建一个 OpenSpec 变更提案"
- "请阅读 openspec/AGENTS.md，告诉我我们应该怎么协作"
整个学习曲线大约就在这三句话里。
它的边界
不吹不黑地说几句限制。
学习成本不是零。OpenSpec 引入了一套自己的目录结构和命令体系，第一次用得花十几二十分钟搞清楚 proposal / tasks / specs / archive 这几个概念之间的关系。如果团队里没有一个人当锚，很容易用着用着就乱。
小项目和一次性脚本不必上。写个爬虫、跑个数据清洗的 notebook、做个一周后就扔的内部工具，引入 OpenSpec 是杀鸡用牛刀。它的好处在中长期项目上才显现——做得久、规范积累得厚，回头读规范才省事。
OpenSpec 官方说自己"现有项目优先"，因为老项目最痛的是"没人讲得清现状"。但我觉得 0→1 项目也值得用——前期把规范立起来，后面每次新增功能就是往规范上贴一块，至少不会出现代码飞起来但没人知道在干嘛的状态。
最容易踩的坑前面已经提过：实施时改了代码但没更新规范。这一步守不住，OpenSpec 就废了一半，因为下次新人来读 openspec/specs/ 看到的是错的真相。这件事得靠习惯，工具帮不了你。
最后
OpenSpec 本身不复杂，几条命令就能跑通。
以前"先想清楚再动手"是一句鸡汤，因为成本上没人逼你想。现在 AI 让 build 变得太便宜，前面少想一步的代价是后面 AI 帮你 build 出 10 倍的错东西。OpenSpec 把"想清楚"这一步从口号变成了一个有目录、有文件、有验证的环节，让你不得不走一遍。
如果你已经在做一个跑了三个月以上、还会继续做下去的项目，值得花一个下午把它装上跑一遍。