聊一个最近在开发者圈子里热度上升很快的词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 通篇都在介绍现有架构那它就失去了作为评审对象的意义。我把三者做了个对比方便你一眼看清定位文档类型回答的问题读者更新时机README系统现在是什么新加入的开发者代码变化时同步技术方案/设计稿我们打算怎么做评审者设计阶段OpenSpec spec.md这次变更为什么做、做什么、验收什么AI 与人类评审者每个变更开工前简单说规范的目标读者除了人还有 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 辅助开发的正确姿势上。