# 初识 OpenSpec：AI 时代规范驱动开发的开源起点

> OpenSpec 是开源免费的 SDD 工具——先把规范写清楚再让 AI 写代码。一篇讲清它干什么、和 CLAUDE.md / Skill 怎么分工、怎么装、什么场景别上。

- 原文链接: https://laojin.blog/blog/20260527_openspec_intro_sdd
- 作者: 老金
- 发布日期: 2026-05-27
- 标签: OpenSpec, SDD, Claude Code, AI 编程, 规范驱动开发

---

![初识 OpenSpec：AI 时代规范驱动开发的开源起点](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260527/00_cover.png)

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

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

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

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

## 它和 CLAUDE.md / Skill 不是同一层

先把概念分清楚，不然很容易混。

CLAUDE.md 解决的是"AI 写代码时该守哪些规矩"，比如别过度设计、别动没让你动的代码——管的是行为风格。

Skill 是另一类东西。你重复做的某一类任务，比如"改公众号文章"该按哪几步走，把这套流程沉淀下来给 AI 用——它管的是怎么做事。

OpenSpec 不在这两层上。它解决的是更前一步的问题：**这一次具体要做什么、做到哪算完、有哪些边界条件**。

![CLAUDE.md / Skill / OpenSpec 三层分工](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260527/01_three_layers.png)

举个例子。"加个注册登录页"这句话扔给 Claude，CLAUDE.md 帮不了你，因为它只管 AI 怎么写代码、不管该写什么；Skill 也未必帮得上，因为这不是你重复在做的事。你和 AI 之间真正需要的，是一份双方都点头同意的需求文档——这个空缺，就是 OpenSpec 想填的。

它的核心思想叫 SDD（Spec-Driven Development，规范驱动开发）。一句话讲清楚就是：先把规范写清楚，再让 AI 按规范施工。

## 它具体干什么

OpenSpec 是个开源 CLI 工具，GitHub 上叫 [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)。免费，无需 API Key，主流 AI 编码助手（Claude Code / Cursor / Codex 等）都能接。

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

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

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

整个目录结构大致这样：

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

看完这个结构其实就懂大概了——每次变更都是一个可审计的小盒子，做完归档进档案柜。

## 一次完整的工作流

把"加个注册登录页"这个例子整段走一遍，OpenSpec 的味道就出来了。

![提案 → 对齐 → 实施 → 归档 的闭环](https://pic-1258874139.cos.ap-hongkong.myqcloud.com/laojinblog/posts/20260527/02_workflow_loop.png)

### 起草提案

打开 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 及以上。

```bash
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 把"想清楚"这一步从口号变成了一个有目录、有文件、有验证的环节，让你不得不走一遍。

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