OpenSpec:给 AI 编程加一份可审查的工程契约
当我把一个功能直接交给 AI Coding Agent 时,最常见的问题并不是它完全不会写,而是它写得太快:需求还没有说清楚,它已经选好了技术方案;边界条件还没有讨论,它已经改了十几个文件;等我发现理解偏了,代码、测试和上下文已经缠在一起。
OpenSpec 想补的,就是“说完需求”和“开始改代码”之间这一小段空白。
第一次看 OpenSpec 的目录,我其实有点疑惑:就这些?proposal.md、spec.md、design.md、tasks.md,再加一个 CLI 和几组 Agent Skill。本质上确实只是几份 Markdown 文件,没有新的运行时,也不会替项目自动获得正确需求。
但它关键的地方也恰好在这里。过去散落在聊天记录里的决定,现在有了固定位置;Agent 准备写代码之前,我可以先打开文件,把“这里理解错了”直接改掉。OpenSpec 所说的 Spec-Driven Development(规格驱动开发),落到日常开发里并不玄学,就是先把一次变更的原因、行为、设计和任务留在仓库中,再开始实现。
为什么只写 Prompt 还不够
假设我对 Agent 说:
给登录接口加限流,防止别人暴力破解。
这句话有方向,但还不能直接成为可靠的实现依据:
- 按 IP、账号,还是两者组合限流?
- 多长的时间窗口?允许多少次失败?
- 成功登录后是否清空计数?
- 达到阈值后返回哪个状态码?
- 多实例部署时,计数放内存还是 Redis?
- Redis 暂时不可用时,是放行、拒绝,还是降级?
普通对话会把这些决定留在上下文里。对话一长,前面的约束可能被压缩、忽略,甚至被后来的实现细节覆盖。OpenSpec 的做法是把信息拆成不同职责的文件:需求回答“系统必须表现成什么样”,设计回答“准备怎样实现”,任务回答“落地时具体做什么”。
flowchart LR
I[模糊想法] --> P[proposal<br/>为什么做、做什么]
P --> S[specs<br/>可观察行为与场景]
S --> D[design<br/>技术方案与取舍]
D --> T[tasks<br/>实施清单]
T --> C[代码与测试]
C --> V{实现是否符合规格}
V -->|否| P
V -->|是| A[归档并更新主规格]
所以,OpenSpec 确实是在“多写几份文档”。区别只是这些文档离代码足够近,而且正好卡在 Agent 大规模改代码之前。写完不看当然没有意义;愿意花几分钟修改,它们才会变成有用的中间产物。
OpenSpec 的核心模型:当前事实与待发生变更
初始化后,项目中会出现一个 openspec/ 目录。最关键的是 specs/ 和 changes/:
openspec/
├── specs/ # 当前系统已经承诺的行为
│ └── auth/
│ └── spec.md
├── changes/ # 正在讨论或实施的变更
│ └── add-login-rate-limit/
│ ├── proposal.md
│ ├── design.md
│ ├── tasks.md
│ └── specs/
│ └── auth/
│ └── spec.md # 相对当前规格的增量
└── config.yaml
可以把它理解成两条时间线:
flowchart TB
B[openspec/specs<br/>系统现在如何工作] --> C[openspec/changes/add-login-rate-limit<br/>系统准备怎样改变]
C --> I[实现与验证]
I --> M[同步增量规格]
M --> N[更新后的 openspec/specs]
C --> H[archive<br/>保留这次变更的历史]
specs/ 是当前行为的 source of truth;changes/ 则采用 delta spec 描述这次变更新增、修改或删除了什么。这个设计对已有项目尤其合适:我不需要先为整个旧系统补写一部百科全书,只需要从眼前这次变更开始,把受影响的行为说清楚。
四类产物分别解决什么问题
| 产物 | 回答的问题 | 不应该塞进去的内容 |
|---|---|---|
proposal.md |
为什么做、范围是什么、影响哪些能力 | 详细到类和函数的实现步骤 |
specs/ |
用户或下游系统能观察到什么行为 | 框架选择、内部数据结构 |
design.md |
技术上怎样实现、有哪些取舍与风险 | 模糊的业务口号 |
tasks.md |
需要完成哪些可勾选的实施项 | 无法验收的“大致优化一下” |
这四类产物看起来有点像“小型需求文档套装”,用不好也确实会变成形式主义。它们真正有用的前提,是每个文件只回答自己的问题。最典型的错误,是在规格里直接写“创建 RedisRateLimiter 类”。类名是实现,外部真正依赖的行为应该是“同一账号在时间窗口内连续失败达到阈值后,系统拒绝后续登录请求”。前者将来可以重构,后者才值得长期保留。
一段最小的增量规格可以写成:
## ADDED Requirements
### Requirement: Failed login rate limit
The system MUST temporarily reject login attempts when the same account
has failed authentication five times within ten minutes.
#### Scenario: Threshold is reached
- **GIVEN** an account has four failed attempts in the current window
- **WHEN** the next login attempt also fails
- **THEN** the system records the fifth failure
- **AND** later attempts are rejected for the remainder of the window
#### Scenario: Successful login resets the counter
- **GIVEN** an account has failed authentication fewer than five times
- **WHEN** the account logs in successfully
- **THEN** the failed-attempt counter is cleared
Requirement 写稳定的行为契约,Scenario 用 Given / When / Then 把正常路径和边界条件变成可以测试的例子。至于 Redis key 如何设计、是否用 Lua 保证原子性、怎样设置 TTL,应当放进 design.md。
一个更贴近真实开发的最小过程
OpenSpec 由两个部分组成:
- 终端里的
openspecCLI,负责初始化、查看、校验和管理文件; - AI 助手聊天框里的工作流命令或 Skill,负责让 Agent 生成产物、实施和归档。
安装和初始化通常只做一次:
npm install -g @fission-ai/openspec@latest
cd your-project
openspec init
初始化时选择正在使用的 AI 工具。这里最容易搞混的是:openspec init、openspec list 这类命令在终端执行;/opsx:propose 这类命令在 AI 助手的聊天框执行。
不同工具对工作流的叫法也不完全一样。官方文档统一写成 /opsx:...;Codex 使用安装在 .agents/skills/ 中的 $openspec-propose、$openspec-apply-change 等 Skill,Desktop 里也可以直接从 Skills 面板选择。没必要硬背,以 openspec init 完成后的提示为准。
下面继续用“给登录接口增加失败限流”这个需求。真实开发中,我不会输入四条命令然后等它全自动结束,大致会这样做。
第一步:先让 Agent 读项目,暂时别写代码
我会先开功能分支,然后让 Agent 调查现状:
git switch -c feat/login-rate-limit
先不要修改代码。阅读登录接口、现有 Redis 封装和认证测试,告诉我:
1. 登录失败目前在哪里处理;
2. 项目有没有可复用的计数与过期能力;
3. 加限流会影响哪些接口和测试;
4. 目前还缺哪些产品决定。
这一步可以使用 explore,也可以只是普通对话。重点不是一定要走某个命令,而是让后面的规格基于真实代码,而不是让 Agent 凭经验虚构一个 RateLimiterService。
调查后可能会发现:项目已经有 Redis Client,登录失败统一从 AuthService 返回,但“连续失败五次后锁十分钟”和“Redis 故障时怎么处理”还没有答案。这时先把两个决定补上,再创建 change。
第二步:创建 change,但先审文件
确认基本边界后,再让 Agent 生成变更:
/opsx:propose add-login-rate-limit
背景:复用现有 Redis Client;按账号计数;10 分钟内失败 5 次后限制登录;
成功登录清空计数;本次不做全站 API 限流,也不改注册和找回密码接口。
在 Codex 中,对应的是选择或提及 $openspec-propose Skill。生成之后我不会马上 apply,而是先确认它创建了哪些文件,再逐个打开:
git status --short
find openspec/changes/add-login-rate-limit -type f
这一遍通常真的能抓出问题。比如 Agent 可能顺手把 IP 限流也写进范围,可能没有定义被限流时的状态码,也可能只写“添加测试”,却没说测试阈值、过期和计数重置。
我会直接编辑这些 Markdown,至少确认:
proposal.md写清这次做什么,以及明确不做什么;spec.md包含达到阈值、成功后清零、时间窗口过期等可验证场景;design.md复用真实存在的模块,并说明 Redis 异常时的处理策略;tasks.md把实现、单元测试、接口测试和回归检查列开。
这其实是 OpenSpec 最关键、也最容易被跳过的一步。完全接受 Agent 生成的四份文件,再让同一个 Agent 按它们写代码,只是把“一次性生成代码”变成了“一次性生成文档和代码”,可靠性并不会凭空提高。
第三步:实施,然后用项目自己的检查验收
规格确认后再执行:
/opsx:apply add-login-rate-limit
或者在 Codex 中使用 $openspec-apply-change。Agent 会按 tasks.md 工作,但我还是会看代码 diff,并亲自确认项目原本的检查有没有通过:
git diff --stat
git diff
openspec validate
# 再运行项目自己的单元测试、接口测试和静态检查
tasks.md 被全部勾选,只能说明清单被勾选了,不代表测试真的通过。最终验收仍然要回到仓库自己的命令和运行结果。
第四步:实现改变了计划,就回头改
真实开发很少完全按第一版设计前进。比如写到一半发现登录成功事件是异步消费的,无法在原来的位置可靠清零计数。这时不应该悄悄让代码偏离 design.md,也不必推倒重来,而是先更新设计和任务,再继续实施。
stateDiagram-v2
[*] --> ReviewArtifacts
ReviewArtifacts --> Apply: 计划可实施
Apply --> RunChecks
RunChecks --> Apply: 测试失败,修复实现
Apply --> UpdateArtifacts: 发现需求或设计有误
UpdateArtifacts --> ReviewArtifacts
RunChecks --> Archive: 实现与规格一致
Archive --> [*]
这一步有点麻烦,但很实际:文档不是圣旨,它只是当前共识。代码里的新证据比最初设想更可靠,计划应该跟着改。
第五步:验证完成后再归档
代码、测试和规格都确认后,再执行 /opsx:archive;Codex 中对应 $openspec-archive-change。归档会把 delta specs 同步进主 specs/,并把变更目录移动到带日期的 changes/archive/ 下。最后再像平常一样检查 git status、提交代码、发起 PR。
这才是我理解的最小闭环:
读现有代码 → 补齐关键决定 → 生成并人工修改规格 → 实现 → 跑真实检查 → 归档
OpenSpec 没有替换 Git、测试或 Code Review,只是在它们前面多放了一层可编辑的变更说明。
说到底,它管理的是上下文
OpenSpec 当然可以被理解成“AI 帮我写文档”。再往里看一层,它做的事情是把一次开发过程中不同阶段需要的上下文分开保存:
需求讨论需要:目标、用户、限制、非目标
规格审查需要:行为、输入输出、错误与验收场景
技术设计需要:现有代码、依赖、数据流、风险与取舍
代码实施需要:已确认的设计、任务、相关源码与测试
这样做不能让模型突然变聪明,但能减少三类浪费:
- Agent 在模糊目标下过早写代码;
- 长对话中关键约束逐渐丢失;
- 人只能在大段代码完成后才发现方向错误。
规格、设计和任务都只是文本文件,所以可以跟普通代码一样参与 diff、review、分支协作和历史追踪。这很朴素,但确实比回头翻一段很长的聊天记录方便。
OpenSpec 不替你保证什么
OpenSpec 希望提高“需求—设计—实现”之间的一致性,但它不是正确性的自动证明,也不一定适合每个项目。
首先,规格也可能写错。如果输入目标本身有误,Agent 只会更有条理地实现错误需求。人仍然要对业务规则、范围和风险负责。
其次,任务打勾不等于功能正确。tasks.md 全部变成 [x],只能说明清单被标记完成;真正的证据仍然来自测试、静态检查、运行结果、接口契约和人工验收。
再次,Verify 也不是形式化验证。它能够帮助检查实现与产物的对应关系,但如果判断主要来自模型阅读,就不能代替可重复执行的测试和业务数据验证。
最后,不是每次改动都需要四份完整产物。改一个文案错字、升级一个无风险 patch 版本,硬套完整流程只会增加噪音。OpenSpec 更适合这些场景:
- 需求存在多种解释,写错方向的返工成本较高;
- 改动跨越多个模块、接口或数据结构;
- 有明确的边界条件、兼容性或迁移风险;
- 多个人或多个 Agent 需要共享同一份实施依据;
- 希望未来能解释“为什么当时这样改”。
而对于高风险变更,还应该在 OpenSpec 之外继续增加安全评审、迁移演练、回滚方案、权限控制和独立验收。
我会怎样在个人项目里使用
我不会要求每个需求都先写一篇长文档,而会按风险决定规格密度:
| 变更类型 | 建议做法 |
|---|---|
| 文案、样式微调 | 直接修改并验证,不必创建 change |
| 边界清楚的小功能 | 用 propose 快速生成轻量规格,审查后实施 |
| 需求模糊或需要读旧代码 | 先 explore,把调查结论沉淀后再 propose |
| API、权限、数据迁移 | 补全错误场景、兼容策略、回滚与验证任务 |
| 多条并行变更 | 每项 change 独立目录,避免共享一份含糊计划 |
我也会坚持一个原则:规格写行为,设计写实现,测试提供证据。
如果把三者混在一起,OpenSpec 最终只会变成另一套文档模板;只有当它们各自承担不同责任时,才真正形成工程闭环。
写在最后
AI 编程把“写出代码”的成本降得很低,却放大了另一个问题:我们能否在代码大量产生之前,确认 Agent 正在解决正确的问题。
说到底,OpenSpec 没有什么魔法:安装完以后,仓库里就是多了一些目录、几份 Markdown,以及教 Agent 如何读写它们的 Skill。团队不看规格、测试跑不起来、需求没人拍板,这些问题它一个也解决不了。
但对我来说,这几份文件仍然值得保留。它们让我在 Agent 开始大改之前有机会停一下:范围是不是多了,异常路径是不是漏了,所谓“完成”到底要看到什么证据。发现问题时,我改的是几行 Markdown,而不是等十几个文件写完后再返工。
这可能就是 OpenSpec 最合适的位置:不是一套新的开发信仰,而是 AI 写代码越来越快之后,一个不算昂贵的减速带。