OpenSpec：以规范驱动AI编程，终结需求模糊与代码烂尾

聊一个最近在开发者圈子里热度上升很快的词：OpenSpec。如果你这几周一直在刷 GitHub Trending，多少会看到它。我第一次刷到的时候，第一反应是“又一个 Open 开头的协议”，但真正花时间跑了一遍之后，我的判断改变了——OpenSpec 不打算发明什么新东西，它更像是一套把“需求描述”这件事规范化、工程化的工作流，让人类和 AI 代码助手在同一个施工图上协作。这篇博文我会从我自己试用的体会出发，不聊太多定义，重点讲清楚 OpenSpec 解决的根子问题、一份规范从创建到落地会走完哪些环节，以及真正推进过程中那些容易让人打退堂鼓的摩擦点。无论你是技术负责人，还是被 AI 生成的代码坑到半夜的开发者，这篇文章应该能给你一些有用的线索。

1. 为什么 AI 编程工具越强，需求描述反而成了最大瓶颈

先说一个我这几年很强烈的感受：AI 写代码的能力上升得飞快，但项目烂尾的速度并没有下降。代码生成越来越顺，出问题的地方越来越靠前——在需求理解那一环。你给 AI 一个模糊的任务，它会非常自信地生成一个结构漂亮的实现，可一旦交付时发现做错了，返工成本比手写还高。这不是模型的错，而是我们在用一个非常脆弱的机制传递需求。

1.1 施工队需要蓝图，AI 同样需要

打个比方，装修时你只跟施工队说“我要一个看着很舒服的客厅”，施工队大概率会按自己的理解装出一个样板间，你觉得不对，对方也委屈。可如果你给的是平面图、插座位置、灯光色温、柜体尺寸，施工队的产出就是基本可控的。OpenSpec 做的事，就是逼着我们把“看起来很舒服的客厅”翻译成可验收的条款，落到仓库里，作为唯一的事实来源。它解决的问题不是“用自然语言描述需求”，而是“让需求描述具备版本、有评审、能追踪”。

AI 编程工具的反馈回路天然是代码级的：你起一个 prompt，它给你生成函数、类、接口；你看到代码，下一步就要么接受要么打回。传统的技术方案文档在这种循环里其实已经被架空了——没人愿意写 Word 版的需求文档，也没人愿意读。OpenSpec 的价值在于，它把文档的生产和消费都改造成了工程师熟悉的模式：一部通过 git 管理的规范仓库，一份规范对应一次变更，AI 从规范文件里获取上下文后生成代码，从而实现“规范未定，代码不写”的工作纪律。

1.2 从“想清楚”到“写清楚”的断层

很多项目失败的真正原因是“想清楚了，没写清楚”。头脑风暴阶段大家都很兴奋，白板上画满了架构图，可落笔到执行时，任务描述往往退化成一行 Jira 标题：“优化搜索体验”“修一下支付报错”。这种描述等于在把不确定性传递到实现环节。OpenSpec 强制你回答几个问题，算是把规范流程中最关键的质检点固定住了：

• 这次变更要解决什么现状问题？
• 变更后用户或系统的预期行为是什么？
• 验收时用什么标准判断做完了？
• 这次变更明确不做哪些事？

这四个问题看起来朴素，写过的才知道有多难。尤其是第四点“不做哪些事”，几乎每次评审都能吵出新信息。一个优秀的规范，边界画得越清晰，后面的实现越省力。

2. 被 OpenSpec 重新定义的“文档”：一份规范文件里到底该装什么

很多团队不是没有文档，是文档离代码太远。需求文档在 Confluence 里，设计文档在 Figma 里，接口文档在 Swagger 里，代码在 GitHub 里——信息孤岛林立，AI 就算想读也无从下手。OpenSpec 最聪明的做法，是让规范文件住在代码仓库里，和你日常开发共用一套基础设施。

2.1 我习惯的规范仓库布局

根据这一段时间的调研和我自己的实际习惯，典型的 OpenSpec 风格目录看起来是这样：

repo-root/ ├── openspec/ │ ├── project.md │ └── changes/ │ ├── improve-search-relevance/ │ │ ├── spec.md │ │ ├── tasks.md │ │ └── metrics.md │ └── add-payment-refund/ │ ├── spec.md │ ├── tasks.md │ └── metrics.md

简单解释一下这个结构：

• project.md是项目级背景，描述这个系统核心要解决的问题、总体架构直觉、关键约束。
• changes/下面每个子目录就是一次独立的变更，也就是一个独立的规范单元。
• 每个变更目录里，spec.md是需求正文，tasks.md是拆解后的任务清单，metrics.md是交付后的验收指标或埋点口径。

这种“一次变更一个目录”的组织方式非常像单测文件按模块组织，一颗瓜子一颗瓜子地嗑。你要评审一个功能，不必去翻几十页的 PR，只需要进到对应变更目录，读一份 spec.md 就足够了。

2.2 spec.md 的骨架

我在草拟第一个规范时参考的是开源社区常见写法，一份典型的 spec.md 大致包含这么几块：

# Improve Search Relevance ## Why 当前搜索按关键词命中排序，导致商品相关性差， 用户点开率低，需要引入向量语义检索。 ## What Changes - 搜索入口增加语义检索层 - 保留关键词倒排索引作为兜底 - 结果合并采用 RRF 融合排序 ## Scenarios - 用户输入“适合露营的轻便椅子”，返回的首屏结果应包含露营椅相关商品 - 用户输入“夏天穿的透气跑鞋”，不应返回篮球鞋 ## Out of Scope - 不做个性化推荐 - 不改搜索页 UI 交互

这里必须重点说明 Scenarios 这一节。在我试用过的几个项目中，场景描述是整个规范里最值钱的部分，因为它的可验证性最强。你不需要描述内部实现，你只需要写出“给定什么输入/状态，系统应该产出什么结果”。而这一点恰好是 AI 最擅长校验的东西——你把场景丢给它，它能用测试用例的方式去核对实现是否满足。

2.3 规范文件不是需求文档，更不是 README

很多团队把规范写成了另一种形式的 README，这是我对规范理解上最大的提醒：README 是解释“系统长这样”，spec 是论证“某次变化后系统应该长成什么样”。前者是描述现状，后者是指出目标差。如果你写出来的 spec 通篇都在介绍现有架构，那它就失去了作为评审对象的意义。

我把三者做了个对比，方便你一眼看清定位：

简单说，规范的目标读者除了人，还有 AI 上下文。一个结构良好的 spec.md，能成为你挂在 AI 编程工具侧边的“永久记忆”。

3. 一条规范从创建到合并的完整生命周期

理解了文件结构，接下来看核心的工作流。OpenSpec 并不只是文件组织规范，更关键的是它带了一条“创建 → 评审 → 批准 → 实现 → 复核”的生命周期。我用了大概几个迭代之后，把这条链路总结成了五个阶段。

3.1 创建 Change：给一次变更开个身份

流程起点是创建一次变更，我常用的命令大概是这样的：

openspec change add improve-search-relevance

这条命令会在openspec/changes/下生成一个目录和模板文件，相当于给一次变更开了个“户口”。这一步听起来很简单，但我建议想清楚变更边界再执行。如果一次 change 里塞了太多不相关的改动，接下来的评审会非常痛苦。好的 change 应该是单一职责的：优化搜索相关性归一个 change，支持退款归另一个 change，不要混着来。

3.2 编写与自查：先过机器这一关

模板填充完整后，第一版规范应该先跑一次校验。命令行工具的校验通常能查出结构性问题，比如缺少必填字段，或者引用的任务编号不存在。我习惯把校验理解为“编译器前端的检查”，它不判断你的需求好不好，它只保证你的格式让后续工具能消费。

openspec validate

很多团队在这一步容易不耐烦，觉得“我又不是写论文，搞这么严格的格式干嘛”。但恰恰是这种格式化，为后面的自动化打开了一扇门——当规范是结构化文本时，AI 能稳定地从里面提取信息，CI 能自动检查任务覆盖率，评审者也能更快定位变化。

3.3 人工评审：规范最核心的防线

格式校验通过后，进入真正有价值的部分：技术负责人和相关人一起 review 这份 spec.md。评审环节盯的不是代码质量，而是需求质量。在我的实际经验里，最高频的评审反馈集中在两个问题上：

• 场景描述不够闭合，大量使用“等”“等等”“相关”这类模糊词。
• 缺少 Out of Scope，导致实现方倾向于“顺手多做一点”，结果把一次小变更做成了大工程。

评审完，如果通过，我在流程上会先让这个规范合并进主干分支，再让开发基于它建实现分支。这样规范文件就拿到一个正式的身份——它在 git 历史里留下了一条 commit，成为后续实现任务的锚点。

3.4 实现与任务拆解

规范合并之后，剩下的就是让 AI 或者人类开发者照着它写代码。此时 tasks.md 应该已经被拆成了可并行或串行的小步骤。把任务清单挂到 spec.md 旁边的好处是，实现过程中随时可以勾选进度，又快又稳。

## Tasks - [ ] 在搜索服务中引入向量检索依赖 - [ ] 实现 query embedding 生成模块 - [ ] 实现混合检索合并服务 - [ ] 添加 RRF 排序 - [ ] 更新线上配置开关

我试过一个很顺手的使用方式：把这个 tasks.md 原样粘给 AI 编程助手，让它按顺序推进任务。每完成一条，它自己会把勾选状态更新掉。这个体验有点像给外包团队发了张带验收标准的派工单，省掉了很多来回沟通。

3.5 复核：实现是否对得上规范

最后一个阶段是复核。代码完成提交 PR 时，reviewer 不再只是看代码逻辑好不好，而是对照 spec.md 里的 Scenarios 逐条核对：这个场景实现了没有？有没有动到 Out of Scope 里明确不做的东西？如果实现了不该做的事，即使代码写得很漂亮也要打回。

这个过程本质上是把“验收”从产品经理口头说说，变成了可执行的长效机制。长期跑下来，规范和实现的偏离度会明显缩小，代码评审的讨论焦点也从风格争夺转移到需求验证上。

4. 首次落地时最容易被低估的三类摩擦

实话实说，OpenSpec 的概念并不难懂，难的是在一个已有节奏的团队里把它推进下去。我见过不少团队兴致勃勃地建了规范目录，结果两周后目录就变成一片荒原。问题不出在工具上，而出在那些看起来很小、却又反复出现的摩擦上。

4.1 摩擦一：先写文档再写代码，感觉像在“延迟满足”

开发者的本能是一拿到需求就想开敲键盘。让团队先静下心来写规范，尤其是写场景和边界，这部分阻力比我预想中要大十倍。有人会觉得“这东西我脑子里明白，写出来纯浪费工夫”。

应对这个摩擦，我的建议是不要一上来就全员铺开。挑一个边界相对清晰的中型变更，让一位有经验的人完整走一遍流程，作为团队样例。其他人看到一份真实写好的 spec 之后，学习成本会低很多。示范效应永远比流程制度好使。

4.2 摩擦二：AI 生成的规范会产生新的“一致性幻觉”

OpenSpec 和 AI 工具结合紧密，很多教程会告诉你“让 AI 帮你写 spec”。这确实节省时间，但有一个隐蔽的坑：AI 写出来的 spec 结构工整，却可能建立在某个错误假设上。比如我让 AI 写搜索优化的规范，它生成了一条“应支持基于向量的相似度检索”的场景，但我们的生产环境根本没有向量库，这条场景就是空中楼阁。

这里的经验是：AI 可以当规范的起草员，不能当需求的确认人。凡是涉及系统现状、用户预期、范围边界的内容，必须由了解业务的人做最终确认。规范文件的严肃性，恰恰体现在对现状的敬畏上。

4.3 摩擦三：规范文件与代码脱节，沦为一次性文档

另一种常见情况是，开工时写了规范的 spec，实现之后却再也没人回来更新它。过了两个月，代码长成了另一副样子，规范文件成了过期地图。这会让团队更快对 OpenSpec 失去信任，比不写规范还要糟。

解决办法是把“更新规范”纳入完成的定义。每当你发现实现偏离了原始设想，先别急着说服自己“这就是实现细节”，停下来想想：是规范写错了，还是实现跑偏了。规范写错了就回去改 spec 并重新评审；实现跑偏了就校正代码。这看起来多一道工序，但它保住了长期的可维护性。

5. 把 OpenSpec 接进 AI 工作流的团队配方

聊完摩擦，再来聊点有用的落地配方。如果你已经决定在团队里尝试 OpenSpec，这一节的内容是我觉得优先级比较高的五件事，可以少走不少弯路。

5.1 先给 AI 编程工具配一块“规范提示卡”

OpenSpec 真正发挥威力的场合，是和 AI 编程工具配合的时候。我建议在仓库根目录放一份类似AGENTS.md的说明文件，把规则写清楚：请开发者不要直接修改代码，除非先看对应变更目录里的 spec.md；当实现与 spec.md 冲突时，停下来向用户提问，而不是猜测；每个任务完成后，对照 scenarios 更新勾选状态。

这件事做和不做差别很大。不配置的情况下，AI 仍然是走一步看一步的“单次响应者”；配置后，它就变成了“带着施工图干活的队员”，生成的代码在语义上会更贴合任务边界。

5.2 把规范评审做成代码评审的前置门禁

团队里可以设置一条约定：没有合并过的规范，不开始实现。这一点技术上可以靠 CI 脚本实现，也可以在 Git 分支模型里约定。关键是形成仪式感，让每个人都意识到“评审规范”和“评审代码”一样重要，甚至更重要。

我记得在一个团队里，团队负责人说过一句让我印象很深的话：“每次规范评审里吵出来一个 Out of Scope，省下来的可能是一整个迭代的开发量。”这话虽然有点绝对，但方向是对的——越早发现需求分歧，修正成本越低。

5.3 拿一次真实重构做“第一次试验”

不要拿一个全新的大型项目做 OpenSpec 的试验田。大型项目上下文复杂，变量太多，你很难判断问题是工具造成的还是项目本身就很复杂。我更推荐挑一个你正在规划的重构或中等规模功能，比如“把订单模块的异常处理统一化”这种。这样的变更边界清晰，又能体现 OpenSpec 的路径：写清现状问题的 Why，列出要改的模块，定义几条核心场景，再谈具体实现。

第一次跑通后，团队对流程的信任感建立起来了，之后推广其他项目就是自然增长的事。

5.4 适当做减法：规范密度比覆盖率重要

把“每个小改动都写成规范”连我都觉得太重。有些改动就是修复一个 typo、调一个颜色，这种变更如果能用一句话说清楚，就没必要开一个 change 目录。OpenSpec 这种模式最适合的是行为变化明显、验收标准可描述、影响面大于一次的变更。小改动完全可以走传统快速流程，不要为了规范性而规范性。

规范建设本质上是一种投资，收益来自后续实现与维护环节的节省。如果一次改动本身只有十分钟工作量，写规范的成本就很容易超过收益，这种开销是不划算的。

5.5 用“报错复盘”改良规范模板

最后一条是我个人最喜欢用的：把每一次“实现和期望不符”的事件，反向倒逼到规范模板的优化上。

举个例子，第一次项目里因为“用户输入是否包含同义词匹配”没写清楚，AI 实现的搜索逻辑和我预期不一致。复盘后，我在模板里加了一节Edge Cases，专门要求补充输入边界和例外情况。下次写规范时，AI 会主动先思考边界。这种持续迭代模板的做法，会让规范越来越贴合你团队的实际痛点。

写在最后的个人观察

OpenSpec 刚刚出现的时候，我看过一些人嘲讽说“这不就是让我们回去写文档吗”。我自己用下来的体会是，它和以前那些让人抗拒的文档工具确实不一样。不一样的地方在于它的读者不是只有人，还有 AI；它的载体不是人迹罕至的 Wiki，而是工程师每天都在打交道的 Git 仓库；它的产出不是一篇篇没人读的长文，而是一份份可以被校验、被评审、被追踪的行为契约。

如果你正烦恼于 AI 生成的代码“好看但不对”，或者团队里每次做需求对齐都要开两小时会，我建议你在下一个中等变更里试一试 OpenSpec。控制好第一个变更的边界，别贪大，把场景写清楚，让规范先于代码被合并到主干。等到你某天发现自己或队友做任务前不是去翻聊天记录，而是打开变更目录里那份 spec.md 的时候，你会理解这套工作流为什么能在社区里火起来。

这个方向后面再扩展的空间也很大，比如规范到测试用例的自动生成、规范覆盖率的可视化、规范历史与产品指标的关联分析，这些都是值得持续折腾的方向。先把基础循环跑通，你的团队才算真正把手搭在了 AI 辅助开发的正确姿势上。