# 初识 OpenSpec:AI 时代规范驱动开发的开源起点
**作者**: 老金
**日期**: 2026-05-27T15:38:31.000Z
**来源**: [https://x.com/freeman1266/status/2059660529216720902](https://x.com/freeman1266/status/2059660529216720902)
---

让 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。
初始化完,跟着引导跑三句话就能上路:
1. "请阅读 openspec/project.md,根据我的项目情况帮我填一下"
2. "我想加 XXX 功能,请创建一个 OpenSpec 变更提案"
3. "请阅读 openspec/AGENTS.md,告诉我我们应该怎么协作"
整个学习曲线大约就在这三句话里。
## 它的边界
不吹不黑地说几句限制。
学习成本不是零。OpenSpec 引入了一套自己的目录结构和命令体系,第一次用得花十几二十分钟搞清楚 proposal / tasks / specs / archive 这几个概念之间的关系。如果团队里没有一个人当锚,很容易用着用着就乱。
小项目和一次性脚本不必上。写个爬虫、跑个数据清洗的 notebook、做个一周后就扔的内部工具,引入 OpenSpec 是杀鸡用牛刀。它的好处在中长期项目上才显现——做得久、规范积累得厚,回头读规范才省事。
OpenSpec 官方说自己"现有项目优先",因为老项目最痛的是"没人讲得清现状"。但我觉得 0→1 项目也值得用——前期把规范立起来,后面每次新增功能就是往规范上贴一块,至少不会出现代码飞起来但没人知道在干嘛的状态。
最容易踩的坑前面已经提过:实施时改了代码但没更新规范。这一步守不住,OpenSpec 就废了一半,因为下次新人来读 openspec/specs/ 看到的是错的真相。这件事得靠习惯,工具帮不了你。
## 最后
OpenSpec 本身不复杂,几条命令就能跑通。
以前"先想清楚再动手"是一句鸡汤,因为成本上没人逼你想。现在 AI 让 build 变得太便宜,前面少想一步的代价是后面 AI 帮你 build 出 10 倍的错东西。OpenSpec 把"想清楚"这一步从口号变成了一个有目录、有文件、有验证的环节,让你不得不走一遍。
如果你已经在做一个跑了三个月以上、还会继续做下去的项目,值得花一个下午把它装上跑一遍。
## 相关链接
- [@freeman1266](https://x.com/freeman1266)
- [1.3K](https://x.com/freeman1266/status/2059660529216720902/analytics)
- [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- [@fission](https://x.com/@fission)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [11:38 PM · May 27, 2026](https://x.com/freeman1266/status/2059660529216720902)
- [1,352 Views](https://x.com/freeman1266/status/2059660529216720902/analytics)
---
*导出时间: 2026/5/28 10:19:29*