Skip to content

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:proposeAI 对话窗口(就是你问 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 的全部思想浓缩成五句话,理解了它们,后面的流程只是细节:

#概念大白话
1Spec 是真相一份 spec 描述「系统此刻做什么」,由「需求(Requirement)」+「场景(Scenario)」组成
2Change 是一次工作单元想增/改/删一个功能 = 建一个改动文件夹,一个改动一个文件夹
3Delta 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 提案 ProposeAI把想法写成可审阅的计划
3 审阅 Review你在代码还没写之前,纠正计划
4 实施 ApplyAI照着任务清单逐条写代码
5 归档 ArchiveAI(你确认)更新主规范,把改动封存

下面逐步拆解,每一步都给出输入、输出、以及为什么这么做。


步骤 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/(增量规范)是价值最高的一份,它用三种段落描述这次要改什么:

markdown
## ADDED Requirements # 全新行为(之前没有)

### Requirement: 限流

系统 SHALL 在每 60 秒内对单个用户最多放行 100 次请求。

#### Scenario: 超限被拒

- GIVEN 一个已认证的用户
- WHEN 该用户在 60 秒内发出第 101 次请求
- THEN 系统拒绝该请求并返回 429 状态码

## MODIFIED Requirements # 已存在、要改的行为(写完整新版)

## REMOVED Requirements # 要删除的行为(附一句为什么删)

步骤 3:审阅(Review)—— 你在写代码前纠正计划 ​

这一步是干什么的?

在计划「还只是文字、什么都没建」的时候,你把它读一遍、改对。

为什么要有这一步?

因为现在改一个字,代价接近于零;等代码写完再改,代价就大了。

按这个顺序读三份文件:

  1. proposal.md:这是不是「对的问题」,尺寸是否合适(会不会太大)?
  2. specs/(最重要):这些需求,你认不认?——「如果这些都满足,我就算你做完了」这个标准,你同意吗?
  3. 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 里所有勾选框都勾上了,就归档。归档做两件事:

  1. 把这次改动的增量规范合并进主规范(specs/ 现在知道了「限流」的存在);
  2. 把改动文件夹移进存档目录(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 对齐理解」这一步,从写代码之后提前到写代码之前。流程只有五步:探索(想清楚)→ 提案(写计划)→ 审阅(纠计划)→ 实施(写代码)→ 归档(回写真相)。记住「先同意,再放心地建」,就抓住了它的全部精髓。