OpenSpec 完整工作流程
一句话看懂:OpenSpec 是一层架在你和 AI 之间的「约定层」——先商量清楚要做什么,再让 AI 动手写代码。它的核心信念只有五个字:先同意,再放心地建(agree first, then build confidently)。
一、概念说明:OpenSpec 到底是什么
1.1 一句话定义
OpenSpec 是一个「轻量级的规范框架」,用来解决一个很现实的问题:
你让 AI「帮我做个用户登录」,AI 二话不说开始写代码,写到一半你发现——它漏了验证码、密码没加密、还多做了一堆你没要的东西。你被迫边改边返工。
OpenSpec 的做法是:先让 AI 把「要做什么、做到什么程度算完成」写成一份人人都能读懂的文档(规范 / Spec),你确认无误之后,AI 才照着这份文档写代码。
可以这样理解这个对比:
| 方式 | 过程 | 风险 |
|---|---|---|
| 直接写代码 | 「帮我做登录」→ AI 直接写 | 边写边发现理解错了,反复返工 |
| OpenSpec | 「帮我做登录」→ AI 先出计划 → 你审 → 再写 | 错误在「还是文字」的阶段就被拦下,成本极低 |
1.2 为什么叫「规范驱动开发」
OpenSpec 属于 SDD(Spec-Driven Development,规范驱动开发) 这一类方法论:用一份结构化文档(Spec)来约束和引导 AI 生成代码,而不是靠一句模糊的口头描述。
在上一章(Basic01)我们讲过 SDD 的理念——「先写 Spec,再写 Code」。OpenSpec 就是把这套理念工程化落地的一个具体工具。
1.3 它最独特的一个设计:Delta Spec(增量规范)
这是 OpenSpec 区别于其他工具的关键,务必先理解:
- 传统做法:每次改功能,可能要把整个系统文档重写一遍,很累。
- OpenSpec 做法:每次只写**「这次变了什么」的增量**,不动整份文档。
打个比方:整份 Spec 就像一本「系统使用说明书」,每次改功能,你只递一张「修订便签」,上面写着「新增了某条、修改了某条、删掉了某条」。等这次改动完成,把便签上的内容合并进说明书正文即可。
这张「修订便签」就叫 Delta Spec(增量规范),是后面整条工作流的核心。
二、前置理解:开始之前必须弄懂的三件事
2.1 第一件事:OpenSpec 有两个「半」,别混用
这是新手最容易栽跟头的地方。OpenSpec 的命令分两种,打字的地方完全不同:
| 类型 | 长什么样 | 在哪里输入 | 谁来做 |
|---|---|---|---|
| 终端命令 | openspec init、openspec validate | 终端(Terminal) | 你手动敲,或让 AI 帮你敲 |
| 斜杠命令 | /opsx:explore、/opsx:propose | AI 对话窗口(就是你问 AI 写代码的那个框) | 发给 AI,AI 照着执行 |
记忆口诀:带
openspec的是「终端里的工具」,带/opsx:的是「说给 AI 听的话」。 混用一次,就会卡住一次。
2.2 第二件事:它会在你项目里建一个 openspec/ 目录
运行 openspec init 之后,你的项目根目录会多出一个 openspec/ 文件夹,结构大致如下:
openspec/
├── specs/ # 系统的「真相」——当前系统是什么样
│ └── <领域>/ # 按领域分,如 auth/、payments/、ui/
│ └── spec.md
├── changes/ # 「提案」——想改什么,每次改动一个文件夹
│ └── <改动名>/
│ ├── proposal.md # 为什么改、改什么
│ ├── design.md # 怎么改(技术方案,只有需要时才写)
│ ├── tasks.md # 任务清单(带勾选框)
│ └── specs/ # 增量规范(这次具体增/改/删了什么)
│ └── <领域>/
│ └── spec.md
└── config.yaml # 项目配置(可选)只需要记住两个文件夹的含义:
specs/= 真相:描述「系统现在是什么样」。changes/= 提案:描述「我想把它变成什么样」。- 归档(archive) 这一步,就是把「提案」合并进「真相」,提案文件夹被移入存档。
2.3 第三件事:五个核心概念
把 OpenSpec 的全部思想浓缩成五句话,理解了它们,后面的流程只是细节:
| # | 概念 | 大白话 |
|---|---|---|
| 1 | Spec 是真相 | 一份 spec 描述「系统此刻做什么」,由「需求(Requirement)」+「场景(Scenario)」组成 |
| 2 | Change 是一次工作单元 | 想增/改/删一个功能 = 建一个改动文件夹,一个改动一个文件夹 |
| 3 | Delta Spec 只描述「变了什么」 | 不重写整个文档,只写 ADDED/MODIFIED/REMOVED 三小段 |
| 4 | 产物层层递进 | proposal(为什么) → specs(改什么) → design(怎么改) → tasks(步骤) → implement(动手) |
| 5 | 归档把改动折回真相 | 完成后归档,增量合并进主 spec,改动文件夹进存档,循环闭合 |
2.4 术语小词典
| 术语 | 中文 | 含义 |
|---|---|---|
| Spec | 规范 | 描述系统行为的文档 |
| Requirement | 需求 | 一条「系统应当做什么」的行为陈述,含 SHALL/MUST 等关键词 |
| Scenario | 场景 | 用「给定/当/那么」写的具体例子,能验证这条需求是否成立 |
| Delta | 增量 | 只记录「变化部分」的片段,而非全量 |
| Change | 改动 | 一次独立的增/改/删功能的工作单元 |
| Archive | 归档 | 把完成的改动合并进主规范并封存的过程 |
| Proposal | 提案 | 说明「为什么改、改什么」的文档 |
| Design | 设计 | 说明「技术方案、架构决策」的文档(可选) |
| Tasks | 任务 | 带勾选框的实现清单 |
三、逐步流程:五个步骤的完整循环
OpenSpec 的每一次改动,都走同一条 五步循环。用一张图看全局:
1 · 探索 Explore ──► 2 · 提案 Propose ──► 3 · 审阅 Review ──► 4 · 实施 Apply ──► 5 · 归档 Archive
(可选) AI 起草计划 你纠正计划 AI 逐条实现 spec 吸收改动
▲ │
└───────────────────────── 下一个改动(回到起点)◄──────────────────────┘每一步的职责一句话:
| 步骤 | 谁主导 | 一句话 |
|---|---|---|
| 1 探索 Explore | 你和 AI 一起 | 把模糊想法想清楚(可选,但强烈建议) |
| 2 提案 Propose | AI | 把想法写成可审阅的计划 |
| 3 审阅 Review | 你 | 在代码还没写之前,纠正计划 |
| 4 实施 Apply | AI | 照着任务清单逐条写代码 |
| 5 归档 Archive | AI(你确认) | 更新主规范,把改动封存 |
下面逐步拆解,每一步都给出输入、输出、以及为什么这么做。
步骤 1:探索(Explore)—— 把模糊想法想清楚
这一步是干什么的?
它是「思考模式」。AI 去读你的代码库、问关键问题、给出几个方案、挑战你的假设。它绝不写代码,也默认不写任何文件。
为什么要有这一步?
因为 AI 面对一句模糊的需求(「帮我做个限流」),往往会「自信地做出错误的东西」。先花几分钟把「到底要什么」想清楚,是最划算的习惯。
输入(你对 AI 说):
帮我一起想想,这个应用里的「限流」应该怎么设计。输出: 一个更清晰的想法(也许还有几个候选方案)。
什么时候跳过? 你心里已经非常清楚要什么的时候,可以直接跳到步骤 2。
如果探索后想落地,直接说一句「把刚才讨论的那个改动提出来(Propose)」,它会自动带着讨论结果进入下一步。
步骤 2:提案(Propose)—— AI 把想法写成计划
这一步是干什么的?
AI 把想法变成一个「可审阅的计划」,写进一个改动文件夹。
为什么要有这一步?
关键点:到这一步为止,还没有一行代码。 计划只是文字,改起来几乎没有成本——这是整条流程里「纠错最便宜」的节点。
输入(你对 AI 说):
提出一个改动:给系统加限流。输出: 一个改动文件夹,内含几份产物:
openspec/changes/add-rate-limiting/
├── proposal.md # 为什么改、改什么
├── specs/ # 增量规范:什么才算「完成」(可测试的需求)
├── design.md # 技术决策(只有需要时才写)
└── tasks.md # 实现清单其中 specs/(增量规范)是价值最高的一份,它用三种段落描述这次要改什么:
## ADDED Requirements # 全新行为(之前没有)
### Requirement: 限流
系统 SHALL 在每 60 秒内对单个用户最多放行 100 次请求。
#### Scenario: 超限被拒
- GIVEN 一个已认证的用户
- WHEN 该用户在 60 秒内发出第 101 次请求
- THEN 系统拒绝该请求并返回 429 状态码
## MODIFIED Requirements # 已存在、要改的行为(写完整新版)
## REMOVED Requirements # 要删除的行为(附一句为什么删)步骤 3:审阅(Review)—— 你在写代码前纠正计划
这一步是干什么的?
在计划「还只是文字、什么都没建」的时候,你把它读一遍、改对。
为什么要有这一步?
因为现在改一个字,代价接近于零;等代码写完再改,代价就大了。
按这个顺序读三份文件:
proposal.md:这是不是「对的问题」,尺寸是否合适(会不会太大)?specs/(最重要):这些需求,你认不认?——「如果这些都满足,我就算你做完了」这个标准,你同意吗?tasks.md:任务是否覆盖了 specs,而且没有多做?
要改,两条路任选:
- 自己直接编辑文件——这些产物都是纯 Markdown,文件本身就是计划;
- 告诉 AI 哪里不对(例如「spec 漏了『未登录用户』这个情况」),让它改产物。
步骤 4:实施(Apply)—— AI 照清单逐条写代码
这一步是干什么的?
AI 读改动文件夹,按 tasks.md 逐条实现,每完成一条就勾掉一个勾选框。
为什么要有这一步?
计划已经过你确认,AI 现在可以「照着做」而不是「边猜边做」。
输入(你对 AI 说):
实施 add-rate-limiting 这个改动。输出: 代码,以及 tasks.md 里被逐条勾掉的勾选框。
小技巧:实施最好另开一个新的对话窗口,因为干净的上下文写代码更稳。
几个实用规则:
- 被打断 / 上下文用完了? 新开一个会话,再说一次「实施这个改动」,它会从第一个未勾选的任务接着做。
- 发现计划错了? 回到步骤 3 改产物(自己改或让 AI 改),再继续实施。
- 进度在哪里? 就在
tasks.md的勾选框里。没有隐藏状态。
步骤 5:归档(Archive)—— 让 spec 吸收这次改动
这一步是干什么的?
当 tasks.md 里所有勾选框都勾上了,就归档。归档做两件事:
- 把这次改动的增量规范合并进主规范(
specs/现在知道了「限流」的存在); - 把改动文件夹移进存档目录(
changes/archive/<日期>-<改动名>/)。
为什么要有这一步?
因为只有归档了,你的 specs/ 才真正反映「系统现在是什么样」。不归档,主规范就一直是旧的、和现实脱节。
输入(你对 AI 说):
归档 add-rate-limiting 这个改动。输出(AI 汇报的大致样子):
归档 add-rate-limiting...
✓ 已合并 specs 到 openspec/specs/ui/spec.md
✓ 已移动到 openspec/changes/archive/2026-01-24-add-rate-limiting/
完成!可以开始下一个功能了。归档后:changes/ 清空了,等下一个改动;specs/ 是「系统现在做什么」的真相;archive/ 是「它是怎么一步步变成这样的」的历史。
四、每步输入 / 输出速查表
把五步的输入、输出、主导方汇总成一张表,方便随时对照:
| 步骤 | 命令(AI 对话里说) | 输入 | 输出 | 谁主导 |
|---|---|---|---|---|
| 1 探索 | /opsx:explore | 一句模糊需求 | 更清晰的想法 + 候选方案 | 你 + AI |
| 2 提案 | /opsx:propose <改动名> | 明确的需求 | 改动文件夹(proposal/specs/design/tasks) | AI |
| 3 审阅 | (你读文件,不改命令) | 提案产物 | 确认或修改后的计划 | 你 |
| 4 实施 | /opsx:apply | 已确认的计划 | 代码 + 勾掉的任务清单 | AI |
| 5 归档 | /opsx:archive | 已完成的改动 | 更新的主规范 + 存档 | AI |
完整路径记忆(默认 core 档位):
/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive (可选) (同步,可选)
五、注意事项:新手最容易踩的坑
5.1 别混用两类命令
再强调一次:openspec ... 在终端敲,/opsx:... 在 AI 对话里说。这是官方文档明确标注的「几乎每个人都会绊一次」的地方。
5.2 增量规范的三种段落别用错
## ADDED Requirements—— 全新的行为;## MODIFIED Requirements—— 已存在、要改的行为(写完整新版,附一句改动说明);## REMOVED Requirements—— 要删除的行为(附一句为什么删)。
归档时:ADDED 追加进主规范,MODIFIED 替换旧版,REMOVED 从主规范删除。
5.3 删光最后一个需求 = 退役整个能力
如果一个能力(capability)的最后一个需求也被 REMOVED 删掉了,归档会删除 openspec/specs/<能力>/spec.md 这个文件(而不是留一个空文件)。
因为这是唯一会「删文件」的归档动作,所以需要你在改动的 .openspec.yaml 里显式加上 retire_capabilities: true;不加,归档会中止并提示你。
5.4 需求要「可观察、可测试」
一条好需求的标准是:一个没看过代码的人,能不能判断它是否成立?
- ✅ 「上传超过 10MB 时,系统 SHALL 显示错误横幅」——可观察;
- ❌ 「系统 SHALL 优雅地处理大文件上传」——没法验证。
5.5 关键词强度要选对
OpenSpec 沿用 RFC 2119 的关键词,强度不同:
| 关键词 | 强度 | 用法 |
|---|---|---|
MUST / SHALL | 硬性要求 | 默认用这个,没得商量 |
SHOULD | 强烈建议 | 除非有充分理由否则要遵守 |
MAY | 真正可选 | 可做可不做 |
5.6 好场景要覆盖「坏情况」,而不只是正常路径
正常登录谁都会写;真正藏 bug 的是空输入、过期 token、连点两次、出错的那条路径。审阅前问自己一句:「哪个情况坏了我会最生气?」——确保有一个场景点名了它。
5.7 计划可以随时回头改
proposal → specs → design → tasks 是「层层递进」的关系,但不是不能回头。实现过程中发现新情况,随时可以回头改前面的产物。
六、常见疑问(FAQ)
Q1:我完全不知道要建什么,从哪开始?
从 /opsx:explore 开始。它是一个「零风险的思考伙伴」,帮你把模糊点子磨成一个具体计划。这是对抗「AI 自信地做错东西」的最佳习惯。
Q2:我已经很确定要做什么,能跳过探索吗?
能。直接 /opsx:propose <改动名> 即可。探索是可选的,但默认档位里始终可用。
Q3:OpenSpec 和普通「让 AI 直接写代码」到底差在哪?
差在「约定发生在动手之前」。普通方式里,AI 的第一次理解偏差要等到代码写完才暴露;OpenSpec 把「对齐理解」这一步提前到「还是文字」的阶段,纠错成本最低。
Q4:我有很大的已有代码库,是不是要把全部代码都写成 spec?
不用。OpenSpec 支持「棕地项目」渐进式落地——只给你正在改的那部分写规范,不必一次性把整个系统文档化。
Q5:AI 写到一半上下文用完了怎么办?
新开一个会话,再说一次「实施这个改动」。它会从 tasks.md 第一个未勾选的任务接着做,因为没有隐藏状态,进度全在勾选框里。
Q6:为什么归档很重要,不归档会怎样?
不归档,specs/(真相)就一直是旧的,和系统实际行为脱节。归档让「真相」追上「现实」,也让这次改动留下可追溯的历史。
Q7:终端命令都有哪些?
常用的几类(带 openspec 前缀,在终端敲):
| 类别 | 命令 | 作用 |
|---|---|---|
| 初始化 | openspec init | 在项目里初始化 OpenSpec |
| 更新 | openspec update | 更新已安装的指令文件 |
| 查看 | openspec list / show / view | 列出/查看改动或规范 |
| 校验 | openspec validate | 检查改动和规范的结构问题 |
| 归档 | openspec archive | 把完成的改动归档并更新主规范 |
校验常用参数:openspec validate --all --strict --json(严格校验、JSON 输出,适合 CI)。归档常用:openspec archive <改动名> --yes(自动确认)。完整清单见官方 CLI 文档。
(待补充:本文按 OpenSpec 官方文档(openspec.dev、GitHub Fission-AI/OpenSpec)整理;具体命令名与目录结构随版本可能略有调整,以你安装版本的
openspec --help和官方文档为准。)
七、一句话总结
OpenSpec 的价值不在「多一个工具」,而在把「你和 AI 对齐理解」这一步,从写代码之后提前到写代码之前。流程只有五步:探索(想清楚)→ 提案(写计划)→ 审阅(纠计划)→ 实施(写代码)→ 归档(回写真相)。记住「先同意,再放心地建」,就抓住了它的全部精髓。