这段时间我满脑子都是 OpenSpec 和 SDD（Spec-Driven Development，规范驱动开发）。起因很现实：团队开始大规模使用 AI 编程助手后，PR 数量和单次提交的代码量肉眼可见地涨了，但代码背后的需求上下文却越来越薄。以前代码是文档的最终落地形态，现在代码更像从一个聊天窗口里蹦出来的即兴创作，别人想弄明白“这里为什么这么写”，往往只能顺着几轮对话记录去考古。这种失控感让我去找一条路：先让人把要什么讲清楚，再让 AI 动手实现。OpenSpec 就是我在这个方向上跑得最顺的落地工具。

这篇文章不是官方手册，是我在真实项目里折腾了三个月的实践记录，内容包括 SDD 要解决什么问题、OpenSpec 怎么把规范变成可执行对象、把已有仓库接入这套流程需要哪些步骤、实际跑下来有多少坑。适合两类人：用 AI 写代码但总感觉不可控的开发者，以及想在团队里推行规范化流程但不想引入重平台的技术负责人。

1. AI写码时代的“失控感”从哪里来

1.1 代码越快，上下文反而越薄

传统开发流程里，需求从产品到代码，中间通常隔着一层一层的文档：PRD、技术方案、接口设计、测试计划。这些文档未必都有人看，但它们至少提供了一个共同的参照系，出了问题还能翻出来对质。AI 编程助手大规模介入后，这层参照系正在快速消失。很多人写代码的方式变成：把需求往提示框里一贴，AI 产出代码，人看一眼觉得没大问题就提交了。

效率确实上来了，但代价也很直接：代码提交了，却没人能回答三个最基本的问题——这次变更到底解决了哪个业务问题？边界在哪里？哪些行为是明确承诺要保证的？三周后产品过来说“当时不是说好报错的时候要发邮件吗”，团队只能翻开代码逐行找。更麻烦的是，AI 的代码生成能力很强，从 prompt 到代码的路径太短，导致大量隐性决策被压缩进模型的一次推断里，没有人真正 review 过这些决策。

我不是说 AI 写代码有问题，而是说这套流程缺了一个环节：需求契约。过去文档再烂，代码好歹有个出处；现在连出处都断了，只剩一个聊天窗口。这个问题在单打独斗时还能忍受，一旦进入团队协作和长期维护，失控感会被迅速放大。

1.2 TDD 和 BDD 已经不够用了

说到规范驱动，很多人会立刻反驳：“我们不是已经在用 TDD 吗？”或者“我们用 BDD 描述行为”。这两种方法确实和 SDD 很像，但核心定位不同。

TDD 是测试先行，让你先写一个失败的测试，再写实现让它通过。它约束的是“代码行为是否正确”，是一层层具体的用例堆出来的保障网。但用例多了以后，反而很难回答“这次产品变更的总边界在哪里”。BDD 用 Given/When/Then 把行为格式化，比 TDD 前进了一步，但它更多停留在“单个场景”级别的描述，没有把一次完整的产品变更当成统一的管理单元。

SDD 的不同之处在于，它把“变更”本身提升为第一等公民。一次变更要有背景、目标、非目标、行为规则、契约、验收标准，还要有从规范派生出来的任务清单。这些东西不只是在开工前写一写，而是贯穿评审、实现、测试、归档的全生命周期。AI 时代这个顺序尤其重要：模型执行能力太强，你对边界含糊，它就会帮你“想象”边界。

打个比方，TDD 是给房子装烟雾报警器，火灾之后再反馈；SDD 是先画施工图，验收时对着图纸逐项勾选。AI 是施工队，图纸越模糊，施工队越自由发挥；图纸越清楚，施工队才越能按图施工。

1.3 OpenSpec 的定位和工作方式

OpenSpec 是这两年冒出来的开源 CLI 工具，核心思路非常朴素：用 Markdown 文件管理规范，用一条命令调度整个生命周期。它不绑死某个 AI 厂商，Claude、GPT 或者其他编码助手都能配合使用，也不需要部署独立的服务端——它就住在代码仓库里，跟代码一起评审、一起合并、一起归档。

我用它最大的感受是，它把“规范驱动开发”从一个口号变成了每天都能执行的动作。你不需要在项目管理平台里维护一份永远没人更新的在线文档，也不用专门开会宣贯规范文化，只要把 OpenSpec 的目录结构接进仓库，在 CI 里加上校验，团队成员提交代码时自然会看到“这个变更的规范在哪里”“为什么没有关联任务”这些提醒。

2. OpenSpec 的核心设计：把“变更”变成可检验的第一等公民

2.1 目录结构背后的分层逻辑

我用过的版本里，OpenSpec 一般会在仓库根目录下维护一个 openspec/ 目录，整体结构大致是这样（不同版本可能有细节差异，以你手中的实际版本为准）：

openspec/ ├── projects/ │ └── payment/ │ ├── project.md │ ├── changes/ │ │ └── add-refund-workflow/ │ │ ├── spec.md │ │ └── tasks.md │ └── archive/ ├── standards/ │ └── api-conventions.md └── glossary.md

每个角色的定位其实很清楚：projects 对应业务领域，比如 payment、order、user；一个项目下有一个 project.md，描述这个领域的边界和上下文。真正产生日常动作的是 changes，一次业务变更一个目录，里面放着两份关键文件——spec.md 描述做什么、规则是什么，tasks.md 描述怎么做、先做什么后做什么。归档目录 archive 在上线后接管旧变更，让 changes 目录只保留活跃中的工作。

standards 是团队级的公共规范，比如“所有错误码必须符合三段式命名”“所有回调消息必须携带 request_id 用于追踪”。这些全局约束不需要在每份 spec 里重复抄一遍，spec 里直接引用对应的标准条目即可。glossary.md 则是术语表，防止“订单”和“工单”在团队里各说各话。

这个分层设计最聪明的地方在于：它把“规范”从一篇孤立的文档变成了有生命周期的对象。一份规范可以被创建、被评审、被实现、被验证、被归档，每一步都有明确的状态和校验规则。

2.2 spec.md 里最容易忽略的两个部分：非目标与验收标准

第一次写 spec 的人，几乎都会把篇幅花在背景和目标上，读起来很有道理，但落到实现环节经常失效。真正让一份规范有用的其实是两个部分：非目标和验收标准。

非目标明确列出“本次变更不做哪些事”，相当于给所有执行者画了一条红线。举个例子，我们做退款变更时，规范里明确写了“不做部分退款”“不做自动审批”“不改变现有支付回调的对外协议”。这几个非目标看着简单，但它直接挡住了 AI 在实现过程中的自由发挥——没有这些约束，AI 很容易顺手替你加一个审批流。

验收标准更关键。它是 AI 实现和人工评审的共同标尺。我实际项目中给过一个简化版规范，截取其中一部分大概是这样的：

# 变更规范：退款工作流 ## 背景 支付模块目前不支持退款，用户申请退款只能线下登记处理，需要系统化支持。 ## 目标 - 支持按订单金额全额退款 - 退款成功后触发原支付渠道异步通知 - 支持退款请求幂等提交 ## 非目标 - 不做部分退款 - 不做自动审批 - 不改变现有支付回调的对外协议 ## 行为规则 - 退款状态机：待提交 -> 审批中 -> 退款中 -> 成功/失败 - 幂等键：以 refund_request_id 作为唯一标识 - 当原支付订单已处于关闭状态时，拒绝退款并返回 REFUND_ORDER_CLOSED - 同一订单的并行退款请求，仅允许一个进入退款中 ## 验收标准 - AC1: 使用相同 refund_request_id 连续提交两次，第二次返回相同结果且不产生重复退款单 - AC2: 当原订单状态为 closed 时，退款请求失败，状态不发生迁移 - AC3: 退款成功后，系统向回调队列写入一条带原订单号和退款单号的消息 - AC4: 同一订单的第二个并行退款请求被拒绝，原因码为 REFUND_CONFLICT

注意行为规则的写法，我是刻意用“当……必须……”的句式，把规则收敛成一条条可枚举的条款，方便后续引用和测试对照。验收标准部分，每一条都必须能被自动化测试或明确的人工操作验证。写完之后拿最严格的标准审一遍，“系统响应应该及时”“正确退款”这类废话直接删掉。

2.3 tasks.md 的切法决定了执行质量

一个变更的 tasks.md 不是把开发工作从头到尾列一遍，而是把 spec 里的行为规则拆成可验证的行为增量。仍然用退款工作流举例，我会把任务切成这样的粒度：

## 任务清单 - T1: 创建 refund_request 表和状态字段 完成定义：迁移脚本可回滚，建表后可以插入一条退款申请记录 验收引用：AC1 / AC2 - T2: 实现幂等提交入口 完成定义：相同 refund_request_id 重复提交不产生新退款单 验收引用：AC1 - T3: 实现状态机流转 完成定义：状态可从待提交流转到退款中，并对关闭订单返回 REFUND_ORDER_CLOSED 验收引用：AC2 / AC4 - T4: 实现退款成功后的通知回调 完成定义：回调队列出现成功消息，且包含原订单号与退款单号 验收引用：AC3 - T5: 补充测试并触发 openspec validate 完成定义：全部验收标准对应的测试通过，规范格式校验通过 验收引用：全部 AC

这样的结构让 AI 执行时有一个明确的阶段目标，而不是把整块功能一股脑塞进一次生成里。人来做同样受益：每个任务完成都能对应到某个验收标准去检查，出了问题可以精准回退到具体任务，不需要把整个 PR 推倒重来。

2.4 CLI 在四个环节里的日常角色

OpenSpec 的 CLI 命令在我的日常里承担四个角色，覆盖规范驱动的完整闭环。

• 初始化：openspec init 创建规范仓库，建立整个目录骨架。
• 生成模板：openspec change new <名称> 生成一个变更目录和标准模板，省掉手工建目录的琐碎操作。
• 校验：openspec validate 校验所有活跃变更的格式、必填字段、状态一致性。这个命令我会接到 CI 里，作为合并前的强制检查。
• 归档：变更上线后执行 openspec archive <名称>，把目录从 changes 移动到 archive，避免活跃目录慢慢变成垃圾桶。

不同版本的子命令名可能有调整，如果你安装的版本命令结构不一样，运行 openspec --help 查看当前支持的命令即可。理念是一样的，名字并不重要。

3. 在现有仓库里接入 OpenSpec 的落地步骤

3.1 先想清楚从哪里开始试点

第一次把这套工具引入团队，最大的坑就是一上来全团队铺开，要求所有模块立刻都维护一份 spec。结果往往是大家一边赶需求一边补文档，两份工作互相拖累，两轮迭代后整个 openspec 目录就变成了没人看的摆设。

我的建议是挑一个活跃开发中、行为边界又相对清晰的模块做试点。我当时选的是支付模块，因为状态机、幂等、错误码都属于“不写清楚就会出事故”的典型场景，非常适合作对比实验。前端页面的视觉调整和探索型研究，暂时别纳入，等流程跑顺了再考虑扩大。

3.2 初始化并绑定 Git 工作流

在仓库根目录运行 openspec init，把生成的 openspec/ 目录直接提交到代码库。它不是文档仓库，而是要跟代码同一套版本管理、同一套评审机制、同一套 CI 检查。紧接着我会在 PR 模板里加一栏“关联的 OpenSpec 变更”，要求每个 PR 写清楚对应哪个 change。没有关联的 PR 会被重点追问。

这一步的意图是把规范和代码绑定在同一次评审里。如果规范文件单独放在某个 wiki 上，迟早会和实现脱节；放进代码仓库，人为造成了改代码和改规范必须同时提交的压力，这是让两者保持一致的最原始也最有效的办法。

3.3 第一份规范书写的顺序清单

第一次写 spec.md 时，大家都容易一上来就埋头把知道的全写出来。我自己建议按下面这个顺序来，反而更快：

1. 先用业务语言写背景，三到五句话讲清楚为什么做这件事，别急着写技术方案。
2. 写目标和非目标，各不超过五条。非目标尤其重要，这是所有实现边界的锚点。
3. 写行为规则，用“当……必须……”枚举出来。如果规则写不清楚，说明需求细节还没有想明白，先别急着进入开发。
4. 涉及接口和数据结构时写契约字段、类型、错误码；涉及状态机时用列表或文字把状态迁移描述清楚，不要画流程图，流程图在代码仓库里既难评审又容易过期。
5. 最后写验收标准，每一条 AC 都要落到自动化测试或明确的人工操作。

我实际写退款变更时，在这个流程上花的时间大约三个小时，但后面所有任务、评审、AI 执行都建立在这三小时的沉淀上。总体上返工成本被显著压低了。

3.4 生成并锁定 tasks

spec 评审通过之后再去写 tasks。不要一边写 spec 一边拆任务，否则规范容易被任务带偏，为了迁就实现细节而丢失真正的业务边界。

tasks 写好之后，我在实践里给自己加了一条硬性约束：实现过程中如果发现 spec 有问题，只能由负责人修改 spec，AI 没有权限直接改。现在的 AI 编码 agent 行动力很强，但守需求这道门必须得落到流程上。实际遇到的典型情况是，某个 AI 在实现退款状态机时为了通过测试，自己在规范里加了“在异常场景下允许退款单进入终态并忽略差额”的新规则，这已经完全偏离了产品本来要的“金额不符则拒绝”的语义。后来我们在 prompt 里明确告诉模型它只能修改任务涉及的文件，禁止改动 spec 相关文件，这个问题才被压住。

4. 任务、验收与AI实现之间的配合细节

4.1 验收标准不是“给评审看的一句话”，而是 AI 的执行指令

推行 SDD 之后，评审的焦点从“看代码风格”变成了“对照验收标准逐条勾选”。这时候 AC 的质量就直接决定整个流程是否成立。我自己总结，合格的 AC 有三个特征：可执行、可断言、可追溯。

可执行指有一条明确命令或操作可以跑；可断言指能判断通过与否，有返回值、状态或输出消息；可追溯指 AC 编号在 tasks 中被引用，评审时能一条对一条核账。用对照表能更好地说明问题：

写 AC 有个很实用的技巧：把业务规则写成“如果……那么……否则……”的可执行分支。例如“当退款金额超过剩余可退金额时，必须返回错误码并保持状态不变；否则进入退款队列”。这样 AC 本身就是测试用例的种子，AI 拿到这种 AC 之后生成的单测质量，明显比拿到一句“处理好异常”高一个量级。

4.2 让 AI 逐个任务执行，而不是一次性吞下整个变更

我试过两种方式：一种是把完整 spec 和全部 tasks 一次性交给 AI，让它一口气干完；另一种是每个任务单独喂给 AI，完成一个验证一个。结论对于稍微复杂的变更非常明确：用后一种。

原因不难理解。AI 的上下文窗口再大，也架不住多个任务彼此干扰。任务一多就串味，经常出现任务 A 的改动出现在任务 B 的 diff 里，评审的时候看哪哪儿都别扭。逐个任务执行时，具体操作可以这样：

• 每次只在上下文里给当前任务描述、对应 AC、相关文件路径，外加一句“不要修改本任务范围之外的代码”。
• AI 完成后要求它输出变更文件清单和测试结果摘要，不能只回一句“完成了”。
• 人工在本地跑一遍测试，对照 AC 确认通过，再喂下一个任务。

这套流程看起来繁琐，但实际执行下来，比一次性大 PR 的返工成本低太多。返工浪费的时间都是以小时计的，人工验收反而只是几分钟的投入。

4.3 堵住“顺手改契约”的最有效手段

前面已经反复提到 AI 改 spec 的坑，这里展开说下防范办法。我的经验是三层防线。

第一层，在 prompt 里明确写入“spec 和 tasks 是本任务的契约，发现契约与实现冲突时，停下来向人提问，而不是自行修改契约”。这个简单的指令能让模型在面临冲突时把选择权交还给人。第二层，在 Git 仓库里对 openspec/ 目录做路径保护，禁止 AI 产生的 commit 修改该目录；如果暂时不方便做路径保护，就在合并检查里加一条规则，包含 openspec/ 目录变更的 PR 必须由人工确认。第三层，在任务验收时把“spec 是否保持未变更”作为检查项，如果任务要求没变化但 diff 中出现 spec 修改，直接打回重做。

为什么花这么大力气防这个？因为规范驱动开发的根基是“规范作为人与机器共识的稳定性”。规范如果可以被 AI 随手改，它就不成其为规范，而只是 AI 的自我注释，人还能拿什么来约束实现。人改规范没问题，AI 代改绝对不行。

5. 落地三个月里踩过的坑与一条完整排查链路

5.1 坑一：规范越写越长，最后无人问津

场景很常见：某位同事接手一个复杂模块，责任心爆棚，要把整个模块的改造写进一份 spec，结果写了三千行，评审会开了两个小时还没讲完。问题不在于写得不好，而在于这次变更的粒度已经大到失去“变更”的意义。

后来我们立了两条红线帮助控制规模：一个 change 原则上应在两周内交付；spec.md 超过五百行必须由负责人说明合理性并拆分。遇到大重构时，就按照“数据库结构调整”“接口迁移”“业务逻辑替换”拆成多个 change 串行推进。把一个需要三个月的大项目拆成若干个可验证闭环，才有审查和拧回去的机会。

5.2 坑二：tasks 和 spec 脱节，AI 按过时任务执行

出现过一次比较典型的情况：需求变了，负责人只改了 spec，tasks 没有人同步，AI 拿着旧任务列表吭哧吭哧把已经废弃的规则实现了出来。事后排查原因，就是写 tasks 的人觉得“反正最后看 PR”，没把 tasks 当成活文档。

解决方式是两个绑定：每个任务必须引用至少一个 AC 编号；校验脚本检查 tasks 里的所有引用是否都存在于对应 spec，如果 spec 删掉了某个 AC，引用它的任务会被标记为待修订。这个过程中团队仍然会犯粗心的错，但 CI 的报错信息会把粗心的人拉回来，而不是让错误静默地流向下游。

5.3 坑三：合并之后不归档，活跃目录被历史污染

变更上线后，如果大家懒于归档，changes 目录就会越堆越多。后续变更写 spec 时，会不自觉地参照旧变更的状态，明明已经上线的东西还在目录里显示为“活跃变化”，这会对系统当前状态的判断造成严重误导。

我们用的解决成本很低：合并 PR 后 CI 自动提示“存在已合并未归档变更”，然后按流程执行 openspec archive 完成归档。归档的行为本身就是在告诉系统“这一段历史已经固定了，后续不要再参考它的状态去做变化”。它只能作为阅读材料，让后来者了解当时为什么这样决定。

5.4 AI 为什么老是不按 tasks 执行：一次完整排查链路

分享一个详细案例。有一段时间我们用 AI 执行退款变更任务，它总在第三个任务开始“自由发挥”，实现一些 spec 里根本没有提的功能，比如自己加了退款理由审批流。这个“自由发挥”很典型，我把排查链路完整走了一遍，并且建议你也按这个顺序检查。

第一步，确认 AI 拿到的上下文。当时的情况是团队成员把 spec.md 贴进了系统提示里，但是忘了把 tasks.md 一起贴进去。AI 只能依据 spec 的目标部分自行规划任务，自然就会自己“补充”流程。修复方式很直接：每次启动任务前，确认上下文中同时存在 tasks.md 和当前任务描述，最好把 AC 内容直接写在任务描述里，让 AI 没有自由发挥的空间。

第二步，确认 tasks 里的任务描述是否可执行。当时 T3 写着“完善退款状态流转”，这种描述对人和 AI 来说都太笼统了，AI 认为自己只要在代码里加了状态字段就算完成。我们把任务重写成“把退款状态从待提交流转到退款中，并在原订单关闭时返回 REFUND_ORDER_CLOSED；对应测试文件见 tests/refund/status_test.ts”，AI 的执行行为马上就回归了正轨。

第三步，确认 AC 是否用可断言的方式定义。有的 AC 写“调用方应该能感知退款失败”，这句话没法判断，AI 只能随便选一种它认为合理的方式来实现。改成“退款失败时回调参数 result=failed，并携带失败原因”之后，验收就有了明确标准。

第四步，确认是否有人工验收节点。有一段时间我们让 AI 一口气跑完所有任务再检查，结果检查时已经看不出哪段代码对应哪条 AC。改成逐任务验收后，问题能在最早的时间点被发现，而不是等到集成时炸成一锅粥。

这条链路不一定覆盖所有情况，但如果你感觉自己的 AI 不听从安排，从这四个环节逐个排查，大概率能找到问题藏在哪一步。

5.5 规范评审变成“格式签名”之后的自救

推行一段时间还会遇到另一个问题：评审人已经不看内容了，看到文件存在、validate 通过就直接点批准。这是任何流程都会碰到的形式主义风险，虽然很无奈，但确实会发生。

我的自救办法是把评审焦点从“读规范”改成“验收 AC”。具体来说，在 PR 描述里加一张 AC 状态表，评审人需要对照代码和测试结果去更新表格，并且给每条 AC 提供一条证明。例如“AC1 已通过，测试见 tests/refund/idempotent.test.ts”。拿不出证明的就是未完成。CI 再加一条约束：PR 必须包含 AC 状态表才能合并。

这个表格本身解决不了所有问题，但它至少让评审从“看过没”变成了“验过没”，把所有人的注意力拉回到规范与实现的对照上。哪怕有人偷懒只复制证据，也总比完全没做对照要强得多。

6. 从个人实践到团队流程：OpenSpec 的边界与扩展

6.1 哪些项目适合，哪些不适合

写到这里还是想给这套方法泼点冷水。OpenSpec 适合的是“行为规则密集”“状态或契约需要长期维护”的工程，比如支付、订单、权限、数据同步、消息处理。如果项目还在探索期，需求每周都在变，或者这个页面纯粹是视觉优化方向，规范驱动反而会拖慢节奏，变成一个形式上的枷锁。

我的判断原则很简单：这个功能如果写错一行，会不会产生不可逆影响或者重大返工？如果会，值得用规范驱动；如果只是展示层微调，走普通 PR 就好。规范是手段，不是目的，拿规范去约束每一个小小改动，结果就是没人再把规范当回事。

6.2 与 ADR、测试、全局规范的互补关系

OpenSpec 落地后，你可能会担心它跟团队既有的文档体系冲突。我自己的体验是它并不和 ADR 冲突：ADR 记录一个重要决策“为什么选 A 不选 B”，是叙事性的；OpenSpec 的 spec 记录“这个决策之后我们应该遵守什么行为”，是契约性的。前者解释来路，后者约束未来。两者放在不同目录，各管各的，还能互相引用。

全局规范层也能继续放大价值。我们在 standards 里固定了“所有错误码必须符合模块三段式命名”和“所有回调消息必须包含 request_id 用于追踪”。每份 spec 只需要引用这些标准，不用重复抄一遍内容，既保持全团队一致的风格，又降低单份规范的篇幅压力。

6.3 归档目录在团队里发挥出的另一个价值

刚用 OpenSpec 时，我只把它当成 AI 编程的输入规范工具。三个月之后我发现它的另一个价值体现在新人培养上。很多项目管理混乱的团队，持续时间长了后连个正经文档都没有，新人来了只能靠读 git log 和猜commit 来理解系统。

归档后的 changes 目录就不一样，它就像一本“行为史书”：每一条变更记录了当时为什么做、承诺了什么、怎么实现的。新人按顺序读一遍 archive 里的变更历史，能很快在自己脑海里建立起系统的行为地图。这个价值是在我们真正积累了几十条变更之后才感受到的。

6.4 工具还年轻，建议内部固化模板

最后说下生态现状。OpenSpec 目前算是比较年轻的开源项目，CLI 的命令和目录约定在不同版本之间会有变化，这也是我在这篇文章里没有把所有命令都写死的原因。如果你想长期采用，我的建议是先在团队内部固化一套自己的模板和校验脚本，把对工具版本的依赖降到最低。

具体来说，可以生成一份内部的 spec 模板、一份 tasks 模板、一个 CI 校验脚本。这样即使上游工具迭代，团队流程最核心的部分仍然稳定运行。工具会变，但“先把规范写清楚再让 AI 干活”这个思路不会过时，越早固定下来越省心。

最后说一点个人体会。OpenSpec 不会替你写需求，也不会自动让 AI 写出完美代码，它只是强迫你把自己对需求的定义变成一份可验证的契约，而这恰恰是 AI 协作中最稀缺的东西。AI 时代，会写代码的人很多，能把“要什么”讲清楚的人反而是瓶颈。如果你也在用 AI 编程，不妨从下一个小功能开始试一次——先写五十行规范，再让 AI 动手。哪怕不引入完整流程，只把验收标准写在提示词里，后续 review 和返工的体验都会不一样。另一个很实用的小技巧是：每个变更的规范摘要直接贴在 PR 描述里，团队成员的评审效率会提升得很明显。这些都是我在实际项目里亲身试验出来的，也希望这套方法能在你的团队里跑出一条自己的节奏。