OpenSpec：用规范驱动开发，破解AI编码的黑箱危机

这两年我用AI辅助编码的时间越来越长但心里那股不踏实的感觉也越来越强。AI生成代码的速度确实快可它到底有没有真正理解需求漏掉边界条件怎么办如果业务逻辑理解错了几百行代码跑起来没问题上线之后才爆雷那时候责任算谁的这就是我常说的AI编码“黑箱危机”——代码是由概率模型生成的它没有内在机制保证“需求→实现”的一致性。OpenSpec就是在解决这个问题它的思路很直接不要猜先立契约。把需求、规则、验收标准写成一份人和AI都能读懂的规范让AI在契约约束下写代码。这篇文章我就结合自己的实践讲讲OpenSpec到底是什么、怎么用它把AI编码从“猜谜”变成“契约”。先说我适合谁看。如果你用Cursor、Codex、Copilot这类工具写代码却总在Code Review阶段对着AI生成的一堆代码发愁不知道怎么评判它对不对这篇文章你能直接抄作业。如果你是团队负责人正在想办法把AI编程纳入正规开发流程OpenSpec这套“规范驱动开发”的思路也值得参考。我尽量少说废话直接讲原理、讲实操、讲踩坑。1. “黑箱危机”AI编码时代最扎心的痛点1.1 代码能跑但真的对吗AI编码工具刚出来那会儿大家的兴奋点都是“代码生成速度”。一个函数、一个组件、一条SQL敲个注释它就给你写出来了确实爽。但用了一段时间问题开始浮现——“能跑”和“是对的”是两回事。我举个例子。我让AI写一个用户积分到期提醒功能它很快生成了一段定时任务代码编译通过、单测也通过。但我后来仔细看逻辑发现它把“积分到期时间”理解成了“积分最后使用时间”整整错了一轮业务概念。代码本身没Bug但需求理解错了这比Bug更可怕——Bug会报错理解错了只会静默地产生错误结果。为什么AI会这样因为大语言模型的本质是“根据上文预测下文”。你给它一句“帮我实现积分到期提醒”它生成的下文大概率是最常见的编程模式而不是最符合你业务语义的实现。它没有“需求一致性”的内在机制除非你明确把约束喂给它并且有一套方法验证它是否遵守了这些约束。这就是黑箱危机的第一个层面AI写出来的代码你无法从代码本身判断它是否符合真实业务需求。传统开发里需求是人提的代码是人写的出了问题可以问人可以在Review时追问“你这个分支为什么这么写”。AI生成的代码你去问谁1.2 传统验证手段为什么失灵有人会说我们有代码评审、有测试用例、有打断点调试怕什么说实话这些手段在AI编码时代都有点“跟不上”。先看代码评审。以前一个工程师一天写200行代码Reviewer一行行看没问题。现在用AI辅助一个人一天能产出2000行甚至更多Reviewer不可能保持同样的逐行审查密度。而且AI生成的代码通常风格统一、命名规范表面上挑不出毛病真正的问题藏在业务逻辑理解上这恰恰是逐行看代码看不出来的。再看测试用例。问题在于测试用例也是人写的而且是基于人对需求的理解写的。如果写测试的人本身对需求理解就有偏差那测试通过只能说明“代码符合测试”不能说明“代码符合需求”。很多团队的单测覆盖率很高但业务事故该出还是出原因就在这里——测试验证的是你写下的断言而不是你没写下的那部分需求。打断点调试就更局限了。调试只能验证你走的某一条路径而AI生成代码的边界情况、异常分支、并发场景你不可能全靠断点一条条去试。更别提那种“看起来一切正常但将来数据量上来才暴露”的性能隐患。这些传统手段的共性问题是它们都在实现阶段之后去做验证。而AI编码恰恰是把实现阶段变成了一台“高速印刷机”下游验证再努力也弥补不了上游需求契约缺失的问题。我们需要的是一个在实现开始之前就立好的、机器可读的“契约”。2. OpenSpec的解法一切从“契约”而不是“猜谜”开始2.1 OpenSpec是什么OpenSpec不是某个大厂的商业产品也不是一个IDE插件它是一套面向AI编码工作流的规范驱动开发框架。核心思想用一句话说就是AI开始写代码之前先把“做成什么样”定义清楚定义成结构化、可校验、人和AI都能读懂的文本契约然后让AI在这个契约的约束下工作。我在实际使用中接触到的核心概念主要是三个Proposal提案描述“为什么要做这个改动”。它回答的是背景和动机类似一份简短的立项说明让AI和人理解上下文。Spec规格把提案细化成具体的要求包括功能需求、规则约束、边界条件。这是契约的主体部分里面每一条都应该能被验证。Validation验证标准明确“怎样才算做完了、做对了”。这是OpenSpec里最有价值的部分它把验收动作前置了。你可以把OpenSpec理解成一套“给AI编码用的需求模板”。但它跟以往的需求文档有个本质区别它的格式是严格设计过的不是给人看的散文而是人和AI都能执行的半结构化文本。所以它不叫文档叫契约。我对这套东西的定位是AI编码时代的“接口文档”。以前我们开发为了多人协作会先定接口再并行开发OpenSpec则是在“人—AI协作”这个新场景下把需求从“模糊意图”变成“明确接口”。2.2 为什么是纯文本/Markdown第一次接触OpenSpec的人大概率会问为什么规范要用Markdown用数据库不好吗用专门的配置格式不好吗我自己用过之后的理解是Markdown恰好站在“人类可读”和“机器可读”的交汇点上。先说人这一侧。业务方、产品经理、测试、后端、前端大家多多少少都能看懂Markdownreview门相对低。如果你用一套专有的配置格式光教团队成员怎么编辑就得费不少劲。再说AI这一侧。大语言模型对Markdown的语义理解本身就很好因为训练语料里Markdown非常多。你给它一份标题清晰、列表分明的Markdown规范它提取约束的准确率比给它PDF或者网页要高得多。再加上纯文本天然适合Git管理每一条规范的变更都能被追踪、被Diff、被Code Review。这一点在团队协作里价值极大——需求变化不是一句“按最新说的来”而是有历史记录的。我用一个装修的类比来解释就更清楚了。传统文档方式就像你口头告诉装修师傅“我想要个温馨点的客厅”师傅自由发挥最后你可能面临返工OpenSpec的方式是先把设计图、材料清单、验收标准定下来师傅照着图纸施工做完按验收标准逐项检查。AI是那个执行力超强的装修师傅而OpenSpec就是那份消除歧义的设计图纸。2.3 OpenSpec与AI agent的分工实际写代码时OpenSpec和AI Agent的分工很明确AI负责“怎么做”OpenSpec负责“做成什么样”。不要指望AI自己就能写出良好的规范。AI生成代码的能力很强但让它自主分析业务需求、穷举边界条件它做得远远不够。原因很简单AI没有对业务的“ownership”它不会像你一样在意这个需求背后的用户场景和历史包袱。所以OpenSpec强调的是人先定义契约AI再实现契约。在这一点上OpenSpec其实是在给AI编码“套笼子”。有人会觉得套笼子是限制但我的体会正好相反——没有笼子的AI是失控的有笼子的AI反而可以放心交办复杂任务。因为契约越清楚AI的自由度就越有边界生成结果的可预期性就越强。3. 实操教程从零到第一个“规范驱动”任务3.1 环境准备OpenSpec目前是以命令行工具的形式提供的。常见的安装方式是通过包管理器你可以根据自己的环境选择合适的安装命令。装完之后在项目根目录执行初始化命令它会在项目里生成一个规范的目录结构。# 安装 OpenSpec 命令行工具以通用包管理器为例 npm install -g openspec # 验证是否安装成功 openspec --version # 在项目根目录初始化 OpenSpec 结构 openspec init初始化完成后项目里会多出一个类似openspec/的目录里面按约定分成几个子目录。不同版本细节略有差异但大框架一致specs/存放所有规范的目录按项目或模块分子目录。proposals/存放提案的目录每一项改动先有提案后有规格。templates/提供提案和规范的模板降低上手门槛。我在macOS和WSL里都跑过这套流程没遇到什么问题。如果你是在WSL的Ubuntu环境里操作建议终端字体选等宽且中英文混排不糊的字体比如JetBrains Mono配合合适的fallback字体体验会接近macOS的终端观感。这个细节看着不起眼但规范文档里中英文混排多的时候显示清晰度直接影响你的阅读效率。3.2 第一步写提案Proposal很多人一上来就想直接写需求列表这是不对的。OpenSpec的工作流要求你先写一个提案目的很简单先把“为什么做”说清楚。提案应该回答三个问题当前存在什么问题为什么需要现在解决解决到什么程度算完成我拿一个实际项目来演示。假设我有一个博客系统用户反馈文章列表页不能按标签筛选运营人员每次找文章都特别痛苦。我想用OpenSpec来驱动这个功能的开发第一步新建提案# 创建一份新提案 openspec proposal new add-tag-filtering运行之后系统会生成一个提案模板文件。我需要填的内容大概是这样的# 提案文章列表页新增标签筛选 ## 目标 为文章列表页增加按标签筛选功能允许用户点击标签后快速过滤文章。 ## 当前问题 - 文章数量超过500篇时运营手动翻页找文章效率极低。 - 用户无法按兴趣主题浏览文章跳出率高。 ## 范围明确做什么、不做什么 - 做标签筛选交互、筛选后的URL可分享。 - 不做标签管理后台、标签推荐算法。 ## 完成标准 - 用户可点击标签列表刷新为对应标签下的文章。 - 筛选状态通过URL参数体现刷新页面不丢失状态。你看提案阶段不涉及具体的代码实现细节它更像是一份团队内部对齐认知的文档。但在AI编码场景下这份文档还有一个作用——提前把AI可能会乱猜的“业务背景”喂给它。3.3 第二步生成规范Spec提案被确认后下一步是把提案细化成规范。这一步是整个OpenSpec的核心因为规范才是AI真正遵守的契约。执行下面的命令根据提案生成规格文件openspec spec generate add-tag-filtering它会根据提案自动生成一份规格草稿里面包含几个关键部分需求列表Requirement、规则约束Rule、验收标准Validation。但这只是一个起点真正的好规范需要你亲手打磨。以“标签筛选”为例我最终打磨出来的规范会长这样# 规格文章列表页标签筛选 ## 需求 - R1: 文章列表页顶部展示所有可用标签。 - R2: 点击某个标签后文章列表仅展示带有该标签的文章。 - R3: 当前选中的标签在UI上有明确高亮状态。 - R4: 筛选条件反映在URL query参数 tag 上页面刷新后筛选状态保持。 ## 规则 - RU1: 标签筛选操作不能触发整页刷新只能局部更新列表区域。 - RU2: 若标签筛选结果为空页面展示空状态提示不能白屏。 ## 验收标准 - V1: 当URL包含 ?tagAI 时首屏请求应直接返回标签为AI的文章列表。 - V2: 点击“OpenSpec”标签后列表请求URL应携带 tagOpenSpec。 - V3: 点击“全部”标签后URL中的 tag 参数应被移除。 - V4: 空状态下显示文案“该标签下暂无文章”。 - V5: 筛选过程中的请求若前一个请求晚于后一个请求返回结果以后一个为准竞态保护。请注意这里的验收标准V5是AI不会主动想到的。这是典型的竞态场景如果不在规范里写清楚AI大概率只会实现“点击→请求→渲染”的朴素逻辑然后在高延迟网络下埋一个隐藏Bug。写规范需要投入多少精力我的经验是规范写得越细后期返工越少。这件事本来就是一次性成本——在你开始写业务代码之前把它做掉比之后调试大半天再回头补规范要省事得多。3.4 第三步让AI基于契约写代码规范写完了怎么让它真正约束AI关键是把你写的规范目录作为上下文交给AI编码工具。我自己常用的模式是打开AI编码助手告诉它“请阅读openspec/specs/add-tag-filtering/下的规范文件严格按其中需求和验收标准实现功能。如果有无法满足的验收标准请列出偏离项并说明原因。”这一步非常关键。很多人在用AI编码时只是把需求一股脑贴在对话里AI生成完就结束。但OpenSpec的工作流要求你把validation标准当成AI的“考试大纲”——它不仅要写代码还要对照验证标准逐条自测。一个实用的做法是让AI在完成代码后生成一份“自测报告”逐项列出它对每条验收标准的落实情况。这样你在Code Review时不再需要逐行看代码来猜逻辑而是拿着自测报告去核对需求契约即可效率完全不一样。提示如果说AI生成的代码相当于“工程队的施工结果”那OpenSpec里的Validation就是“监理的验收清单”。没有验收清单施工质量全凭施工队自觉有了验收清单合不合格一项项对就行。4. 把OpenSpec嵌进日常开发流程4.1 IDE集成与终端工作流命令行固然高效但实际开发中我们大部分时间还是泡在IDE里的。OpenSpec在这方面的问题不大因为它在磁盘上就是一组Markdown文件IDE天然能识别和编辑。我个人的习惯是在IDEA或VS Code里把openspec/目录固定加入收藏夹改代码之前翻一翻规范改完之后对照验证标准自查。这个习惯坚持下来能明显感觉到代码质量的稳定性在提升。近期我也注意到一些IDE插件开始提供OpenSpec集成能力比如直接扫描项目里的OpenSpec文件、高亮不合规的路径、提供快速跳转等等。这些插件的思路和我不谋而合——把规范文件从一个“静态文档”变成开发流程中的“活指南”。如果你在日常开发中用终端比较多还有一个值得一提的小技巧是把常用的OpenSpec命令写成shell脚本别名。比如每次新建功能输入一个简短命令就能自动创建提案模板并用默认编辑器打开省去反复敲长命令的麻烦。4.2 把规范检查加进CIOpenSpec的规范文件是文本而文本天然适合做静态检查。我们可以把“规范质量”这个环节纳入CI流水线在PR阶段自动检查这次改动涉及的规范文件是否格式正确、编号唯一、验收标准是否覆盖需求。在CI配置里加一个检查任务本质上非常轻量# 伪代码示例在CI中增加规范检查步骤 lint-specs: script: - openspec validate这条命令会扫描项目里的所有OpenSpec文件检查结构和引用关系是否合规。我实际跑下来它最大的价值不是“检查格式”而是强制团队在规范阶段就发现遗漏。比如某条需求没有对应的验收标准或者规范里引用了不存在的文件这些错误当天就会被拦下而不是等代码写完才发现“原来这里没定义清楚”。很多人以为CI只是用来跑测试、搞构建的但OpenSpec给了CI一个新的角色契约的守门员。人在写AI在写机器在全程盯着规范的一致性。4.3 多Agent协作下OpenSpec的价值如果说一个人用OpenSpec是给自己上保险那人多了之后OpenSpec的价值是指数级上升的。我最近在做一个前后端分离的项目前端、后端、AI生成的代码三路并行。如果没有接口约定乱成一锅粥是必然的。但我们让三个方向都以OpenSpec目录里的规范为共同依据后端按规范实现数据接口前端按规范消费接口AI生成的工具函数也按规范命名和约束。这个模式下每个Agent都不需要去猜另一个Agent的上下文因为契约已经在文件里写死了。所有参与方——无论人还是AI——都以同一份规范为准。这就避免了最常见的那种问题前端说“后端接口没按时给”后端说“前端没说要这个字段”AI在旁边一脸无辜——到最后谁都不觉得自己有错。当然OpenSpec不是银弹它不能替你设计一个好的系统架构。但当你同时面对多个AI工作流和多人协同时它是目前我见过最实用的“共识机制”。5. 常见问题排查与实操心得5.1 常见问题速查表用OpenSpec这段时间我陆陆续续踩过不少坑身边同事也问过不少相似问题。我把典型的整理成一个速查表症状根本原因解决方法写了规范但AI完全不看规范文件没有作为上下文传给AI工具在Prompt中显式指定规范目录路径并要求AI遵守规范写得很厚但AI执行时经常偏离规范中的需求表述过于模糊含大量形容词把“响应要快”改成“首屏接口P95耗时300ms”这类可量化描述验收标准列了一堆但和需求对不上需求和验收标准是两拨人/两个阶段写的未做关联每条需求编号与验收标准编号一一对应缺失时用工具检查规范文件更新频繁团队总在看旧版本缺少变更记录或者PR里没有同步规范变更规范变更要作为独立Commit并在PR描述中说明影响范围AI一次只实现了一部分需求一个规范过大包含过多需求条目拆分规范每次改动聚焦一个完整可交付的功能切片项目经理抱怨“写规范太费时间”把规范写成了冗长的需求文档砍掉背景论述只保留需求、规则、验收标准三件套5.2 几条实打实的避坑建议第一不要写完代码再补规范。我有一次偷懒让AI先写了代码再“顺手”补一份规范。结果是规范看起来完美代码实际上跟规范几条都对不上。因为规范一旦最后写它就会不自觉地变成“对代码的总结”而不是“对开发的指引”这完全失去了意义。OpenSpec的正确姿势永远是先契约、后实现。第二验收标准不要写形容词要写可测量的事实。像“页面应该流畅”“界面应该好看”“数据应该准确”这类话人和AI都会产生巨大的理解分歧。改成“列表滚动帧率不低于50fps”“搜索请求在1秒内返回”“订单金额与明细总和一致”之后验收才有操作性。规范里出现形容词就说明设计还不够成熟。第三规范的粒度宁小勿大。一个规范对应一个完整可交付的小功能这是最佳实践。如果规范太大AI很难在一次对话中完整实现中途还会因为上下文被截断而丢失约束。把大需求拆成几个小规范每个都走一遍“提案→规格→实现→验证”的循环整个过程会丝滑很多。第四团队初期使用OpenSpec务必要有人工review规范的环节。不要以为AI写得好代码就能写好规范。AI写的规范往往流于表面缺少深刻的业务洞察和边界情形。我的做法是第一版规范人写AI只做格式整理和查漏补缺。等团队里有几个人都建立了“契约感”再慢慢让AI承担更多规范生成工作。还有一个很多人容易忽略的地方规范的版本要和代码版本关联起来。每次发版都要能说清楚“这个版本是根据哪个规范的哪个版本做的”。否则过两个月需求回溯的时候你会发现代码仓库里躺着一堆“历史遗留”却找不到对应的契约依据。写在最后的一点体会说句实在话OpenSpec刚出来的时候我也觉得它不过是“AI时代的另类需求文档”心里嘀咕过这到底是不是多此一举。但真正用下来我才意识到它解决的问题不是“文档缺失”而是“AI编码中信任缺失”。当你发现自己开始相信一份规范文件而不是相信AI的“自觉”你其实已经跨过了一个重要的心理门槛——AI编码开始变成一件可管理、可预期、可追责的事。我有一个小习惯每次新开一个功能先把Validation写出来再回头写需求和规则。因为这个顺序逼着你先想清楚“什么算完、什么算对”而不是先有一堆模糊的想法。这个习惯让我受益匪浅也推荐你试一试。