这两年做AI编程的真实体验用一个词形容就是“薛定谔的交付”同样一句提示词AI上一秒能一口气写完一整个模块下一秒修个小Bug就把别的功能改废了。我一开始以为是模型能力的问题后来踩了大半年的坑才明白问题往往出在我们给AI的“输入”上——需求太模糊、上下文太随意、验收标准全靠运气。所以后来我逐渐转向规范驱动开发Specification-Driven Development开始重度使用OpenSpec这套工作流配合Claude Code、Cursor这些AI编程工具把“一次性碰运气”变成“可预期、可追踪、可复盘”的工程行为。这篇内容就是我的实操笔记适合正在被AI“自由发挥”坑到崩溃、又不想退回纯手写代码的朋友。1. 为什么AI编程需要“规范驱动”1.1 AI编程的失控感从哪来现在用AI写代码表面上是“人提需求、AI实现”但你去回看对话记录就会发现绝大多数需求描述是非常口语化的比如“把用户列表改成卡片样式”“加一个导出功能”“这个接口不太对修一下”。这些描述在人与人之间能靠默契补全但AI没有默契它只能做模式匹配。结果就是你想要的和你描述的不一致AI实现的和它理解的又不一致。最典型的翻车现场有几个让AI“优化一下列表页加载”它把分页逻辑拆了让AI“加个过滤条件”它顺手改了数据源让它“重构一下模块”它把所有文件名都改了连 import 路径都动最后整个项目红一片。我并不是说模型不够聪明。恰恰相反现在的大模型特别会“脑补”——你给的信息不够明确它就自己编一套优先级把代码变成一个它自己觉得“合理”、但和你真实意图没关系的状态。这不是智力的失败是输入的缺失。就像装修房子你只跟工人说“弄好看点”工人按自己的审美装了你肯定不满意。你缺的不是更好的工人而是一张图纸。1.2 规范驱动到底在驱动什么规范驱动开发的核心是把“需求表达”和“代码实现”分开。先把需求写成一份清晰、结构化、可验收的契约再让AI照着契约去写代码。这个契约就是规范Specification。和一次性Prompt相比规范有几个本质区别持续存在。Prompt发完就没了规范文件留在仓库里AI每一轮对话、每次改动、每个后续需求都可以反复引用。结构化表达。规范不是一段话而是由背景、功能描述、验收标准、边界条件组成的条目化文档AI能逐条对照执行。可评审。规范在写代码之前就先给团队Review人和人先在“做什么”上达成一致再让AI处理“怎么做”大大减少返工。可追踪。一份规范对应一次代码变更代码合入后可以通过对照规范验收。说白了规范驱动就是给AI立了个“合同”。它不能随意发挥只能在这个范围内选择最优实现。这个思路在传统工程里其实很成熟比如软件工程里的需求规格说明书但过去太重了——写文档甚至比写代码还费劲。OpenSpec这类工具的价值就是把这个过程变得轻到可以日常用同时又能和AI编程工具无缝衔接。2. OpenSpec到底是个什么东西2.1 规范即代码的开发范式OpenSpec是我目前在用的规范驱动工作流中核心的骨架工具。它把“规范”当作一等公民来管理——不是随手写个Markdown丢进文件夹而是建立一套完整的规范生命周期。我在项目里维护一个专门的规范目录大致结构类似project/ ├── specs/ │ ├── 001-user-auth/ │ │ ├── spec.md │ │ └── tasks.md │ ├── 002-todo-crud/ │ │ ├── spec.md │ │ └── tasks.md ├── src/ ├── docs/每个功能需求对应一个独立的规范目录里面包含主规范文件和拆解出的任务清单。这种组织方式有几个明显好处一个规范目录就是一个独立的功能单元改动范围清晰不会出现“改A需求结果B功能崩了”的连锁问题。规范文件用Markdown写可以进Git做版本管理每次修改都有diff谁改了什么、为什么改全都有记录。AI工具可以直接读取这些文件不用你把整段需求贴进对话里。它的整体逻辑是人类负责定义“做什么、怎么验收”AI负责“怎么写、怎么实现”。规范是中间那个稳定的交接物两边都不含糊。2.2 为什么选Markdown而不是JSON或DSL可能有人会问为什么不用JSON、YAML这类结构化格式甚至搞个专门的DSL来写规范我的实际体验是Markdown在“可读性”和“可解析性”之间取得了最佳平衡。JSON/YAML虽然机器友好但人读起来太累了。一份规范如果写成了长长的嵌套JSON同事Review的时候根本不想看AI读起来倒是方便但团队协作就崩了。DSL就更不用说了学习成本直接劝退大多数人。Markdown的优势很明显门槛极低。会写文档就会写规范不用学新语法。能渲染。在Git仓库、IDE、文档平台里都能直接看干净清晰。AI友好。大模型对Markdown的理解非常强天然适合作为上下文输入。Diff可读。规范改动时Git的diff清晰展示每一处修改评审效率高。以我常用的规范文件写法为例一份规范通常包含几个关键字段功能名称、背景说明、功能需求列表、验收标准、非目标明确哪些是不做的、依赖关系。这些用Markdown标题和列表组织AI解析起来毫无压力人在Github上评审的时候也一目了然。其中最重要的是“非目标”这一项。我早期没写这项AI经常顺手把相关功能也改了后来每份规范都明确写上“本次不涉及XX”AI就老实多了。这个小小的字段直接让越界改动的情况大幅减少。3. 从零搭建OpenSpec环境准备与项目初始化3.1 前置条件和安装步骤开始使用OpenSpec前需要先准备几样东西。我的建议是不管你是用的是Claude Code、Cursor还是其他AI编程工具都可以先把这套规范体系建立起来。前置条件Git规范文件要纳入版本管理这是基础中的基础。Node.js环境如果使用OpenSpec的命令行工具通常需要基于Node运行也有纯脚本方式但命令行工具更省心。AI编程工具Claude Code、Cursor、Codex等任意一款本机至少装好一个。我用的是Claude Code为主Cursor辅助。安装上以我现在常用的版本为例可以直接通过npm全局安装装完验证一下版本能正常输出版本号就说明环境没问题。提示安装前先确认本机Node版本不要太老。我见过一个坑Node 14以下装不上最新的工具报错也很迷惑升级Node版本后一切正常。3.2 初始化规范仓库结构装好工具后进入项目目录执行初始化命令工具会自动生成上面聊过的那套specs/目录结构。如果你的项目是全新的建议先初始化规范骨架再写代码让规范从一开始就跟着项目走。初始化完成后第一步是用命令创建一个新规范。以“用户登录功能”为例执行命名命令并取一个能看懂的slug比如user-auth工具会自动生成对应的规范目录和模板文件。模板里会预置一份很简洁的规范框架我们只需要往里填内容就行。这里我强烈建议创建完规范后先别急着写内容先看一眼目录结构和模板字段理解它希望你用什么方式思考。因为规范驱动开发真正改变的不是写代码的动作而是写代码之前的思考方式。我自己的习惯是每一个新功能都先进specs/目录新建规范哪怕功能很小也要走一遍这个流程。任何一种工程方法只有形成肌肉记忆才能真正发挥价值。从创建规范到写完刚上手时可能多花10分钟但后面省下的返工时间远远不止半小时。4. 写出一份“AI不会误解”的高质量规范4.1 规范文件的核心要素这是整个工作流里最值得花时间的环节。规范写得好不好直接决定了AI交付质量的上下限。我打磨了十几份规范之后总结出五个关键要素要素作用反面教材背景告诉AI为什么要做这个功能只说“加个登录”没说清楚现在的鉴权方式功能需求列出具体的功能行为“用户能登录”太泛验收标准用可测试的方式定义“完成”“登录要快”完全不可验证非目标明确划清本次的改动边界不写范围AI顺手改别的依赖关系说明前置条件和关联模块不写依赖AI用了还没写的接口功能需求这一块尽量拆细。比如“用户登录”不应该只是一句话而应该拆成支持邮箱/用户名密码方式登录登录成功后返回JWT令牌并写入本地存储登录失败时在前端显示明确错误提示不暴露服务器内部信息连续失败5次后触发验证码校验登录状态过期后前端自动跳转到登录页每一条都是独立行为AI可以逐条对照实现每实现一条勾一条。验收标准更要有可操作性的指标类似“输入错误密码3次后第4次必须出现验证码”这种明确行为而不是“安全性要高”这种没有操作空间的形容词。4.2 把模糊需求翻译成规范语言大多数产品需求一开始都是模糊的——别说AI连人都不一定听得懂。我常用的方法是“三问澄清法”这个功能解决谁的什么问题做完之后用户在界面上能干什么什么情况算“做完了”拿一个真实场景举例。产品经理说“帮用户做一个导出报表的功能”直接丢给AI它大概率会做一个导出CSV的按钮。但用户真正要的可能是按筛选条件导出Excel还要包含汇总统计行、文件名带日期。通过三问澄清后规范就变成用户点击“导出”按钮将当前筛选条件下的数据导出为Excel文件导出的文件包含数据明细和汇总统计行文件名格式为“报表-20250101.csv”当数据超过1万行时分文件导出并打包为ZIP瞧需求一具体AI能自由发挥的空间就没了。它不再需要猜只需要按规范写代码。这里有个弯一定要绕开不要直接让AI帮你写规范。你让AI写规范它会把你的模糊需求写得看起来更正式但本质上还是模糊的。规范必须由人主导AI可以帮忙梳理格式、检查遗漏但需求本身的业务逻辑必须人自己想清楚。否则就是低质量需求换了一层漂亮的包装该翻车还是翻车。5. 把OpenSpec接进AI编程工作流5.1 与Claude Code的实战配合Claude Code这类Agent型AI工具是我目前的主力它和OpenSpec的配合非常顺手。我的一个标准工作流是拆分任务从规范文件生成任务清单通常一份规范拆出5~10个任务每个任务限定改动范围。我把规范目录里的tasks文件直接丢给Claude Code让它先读完整规范再按任务清单逐个实现。在项目根目录维护一份AGENTS.md或者项目说明文件里面明确写着一句很关键的话“在修改任何代码之前先读取specs/目录下对应的规范文件严格按规范实现不得超出范围。”这句话看起来简单但能极大减少AI的自由发挥。实测下来加了这句之后AI主动去读规范的频率明显更高代码越界改动的概率降低了不少。还有一个我踩过坑之后总结出来的经验对话轮次之间规范必须稳定。如果你在第一轮告诉AI“按这个规范实现”然后聊了20轮之后AI对早期上下文的记忆已经变淡了。正确的做法是每一轮涉及代码修改时都把规范文件重新提供给AI而不是指望它一直记着一开始读到的内容。5.2 与Cursor、Codex的协作方式如果你用的是Cursor这类编辑器型AI工具用OpenSpec的方式不太一样但逻辑相通。Cursor的特点是代码补全和行内修改很强它不太擅长长篇对话式推理。我的做法是把规范作为项目的背景文档放进来让Cursor在生成代码时照着规范来。具体做法在项目说明里加入指向规范目录的说明然后每个功能文件顶部注释中标注对应的规范编号例如// Spec: 001-user-auth。这样Cursor在编辑这个文件时能结合上下文看到这个文件属于哪个规范代码生成会更有针对性。Codex则更像一个可以跑命令行的Agent适合和OpenSpec的命令行集成比如自动读取规范清单、自动生成任务列表、逐个执行并验证。它的好处是能在终端里直接完成“读取规范-分解任务-写代码-跑测试”的完整链路适合喜欢全自动流程的人。5.3 搭配Superpowers等Skills库单独用OpenSpec已经能提升不少稳定性但最近我更推荐把OpenSpec和Superpowers这类AI Skills库结合起来用这也是社区里很多人说“三件套”的原因。Superpowers这类工具本质上是一套预先定义好的“技能包”。它指导AI按特定流程工作比如“先规划再写代码”“先写测试再实现”“自动检查规范一致性”等。OpenSpec负责定义什么Superpowers负责让AI怎么干二者结合威力很大。举个具体的例子当AI通过Superpowers的技能启动一个开发任务时它会自动读取OpenSpec的规范文件解析验收标准生成测试计划然后进入红绿循环先写失败测试再实现代码最后测试通过。整个流程下来AI几乎不需要人来催它会自己沿着技能预设的路径走。我的组合方式很朴素OpenSpec管规范Superpowers管执行路径Claude Code管具体实现。这个组合我用了三四个项目最大的感受是——“翻车”概率从“经常”降到了“偶发”而且每次翻车都能快速定位到是规范的问题还是生成的问题修复成本低了很多。6. 实战复盘用OpenSpec驱动一个功能落地6.1 一个小型全栈功能的完整路径为了把这些概念落到具体操作我完整复盘一个真实做过的功能为一个内部工具开发“待办事项管理”要求支持增删改查、状态流转、基础过滤。首先根据三问澄清拆成了三份规范而不是一份。001-todo-model定义数据结构、数据库表、API接口002-todo-crud实现前端列表、新增、编辑、删除交互003-todo-status实现状态流转待办→进行中→已完成和筛选逻辑这样分类的原因很简单每份规范对应一次独立的代码变更和PR。如果全部塞进一份规范里改动量大评审压力大出了问题也不好定位。6.2 从规范到代码的流转细节以001-todo-model为例规范里的功能需求列得非常细包括字段定义、接口路径、请求响应格式、错误码规范。AI拿到规范后先读取任务清单然后按以下顺序工作根据规范创建数据库表结构实现API路由和请求校验编写单元测试覆盖接口返回数据格式对照验收标准逐条自测每个阶段AI会输出一段说明对应规范中的某一条需求。我们在Review时不需要看AI的自说自话直接看它是否覆盖了规范里每一条。这个过程中最有价值的一个实践是“验收记录”。我在每个规范目录下放一个acceptance.md每完成一条需求AI就在表格里记录验证结果。这样最终评审时打开表格就能看到哪些完成了、哪些没完成、哪些卡住了一目了然。需求ID验收标准实现状态验证结果M-01能创建待办包含标题、描述、截止日期已完成通过接口测试验证M-02待办列表按创建时间倒序已完成数据库排序验证M-03删除待办时同步清理关联标签未完成关联表逻辑未处理正是这种表格化的验收跟踪让我从“凭感觉判断AI写得好不好”变成了“逐条对照标准判断”这是我觉得AI编程最需要的工程化进步。7. 常见问题与避坑清单7.1 规范写得太粗AI照样自由发挥这大概是最常见的问题。很多人一听“写规范”就粗略写两句“用户能登录”“用户能注册”然后发现AI行为跟以前没有本质区别。原因很简单规范不够具体等于没有规范。我的经验是每份规范的功能需求列表至少要能拆出8~10个可执行的条目。如果一份规范只有三句话说明需求还没想清楚不要开始写代码先继续澄清。宁可多花半小时完善规范也不要让AI浪费一上午写错方向。7.2 规范变更了但AI上下文还没跟上需求变更是常态但规范驱动的优势之一就是管理变更更清晰。改需求不是改代码而是先改规范再让AI按新规范改代码。这里有个需要特别留意的地方AI在后续对话中很容易读到旧规范并执行旧逻辑。解决办法是每次修订规范后明确告诉AI“规范文件已更新请先重新读取001-user-auth/spec.md以最新版本为准”。如果改动很大甚至建议新开一个对话窗口只让AI读取新版规范不要夹带着旧上下文。7.3 规范漂移代码和规范对不上规范写了代码也写了但过两周再看代码已经和规范不一致了。这通常是因为某个场合下临时改代码没有回去更新规范。规避方式只有一个硬规矩如果代码改动偏离了规范要么改代码回到规范要么先更新规范再继续实现没有第三种选择。我还有一个自动化的小技巧在CI流程里增加一个检查项扫描代码中的关键行为关键词是否和规范中的功能需求条目匹配。这个检查不用太复杂主要目的是提醒——当规范写着功能A但代码注释里完全没有对应关联时提示人工确认。7.4 多个AI工具并行时规范口径不一致在实际工作中我的一个项目里可能同时用到Claude Code和CursorAI聊天工具可能还会接到不同型号的模型它们的理解能力参差不齐规范的口径就变得至关重要。这时候规范的写作质量更加重要。描述越接近自然语言、越直白不同AI之间的理解差异就越小。一句话“所有接口统一返回格式为{code, data, message}code为0表示成功。”不管哪个模型读都能给出一致实现。但如果你写“接口返回统一的响应结构”不同模型可能猜成不同的字段命名。注意规范文件是团队协作的公共产物。不要用只有自己才懂的缩写或暗语所有表述都要让一个不熟悉你项目的人或AI能直接读懂。我第一次写规范时用了大量内部缩写结果换一个工具时对方完全看不懂规范形同虚设。8. 最后分享一点实际操作体会用OpenSpec这套流程做了几个项目之后我最大的体会是它没有让AI变得更强但让我能真正管住AI了——交付过程从听天由命变成了可控工程。以前的对话式编程翻车全靠人肉回滚现在代码出问题第一反应是看规范和代码哪一步对不上顺着线索修就行排查成本降了一个量级。还有一个值得分享的小技巧每次新功能开发我都会创建规范后先给规范写一小段“给下一位开发者/AI的留言”说明这个规范目前哪些地方还没完全定清楚、哪些边界只有我知道。这个方法用了几次之后我发现AI在实现时会主动规避那些不确定的点而不是自作主张去猜。所以如果你也在被“AI代码质量飘忽”折磨我的建议很简单不要急着换更强的模型先用OpenSpec这类方法把“你想让AI做什么”这件事彻底想清楚。这个转变一旦完成你会发现模型还是那个模型交付的稳定性却完全不一样了。