这两年AI编程工具用下来最大的感受是AI不笨但它常常“自作聪明”。你让它做个功能它能把需求理解歪到十万八千里代码写得飞起结果根本不是你要的东西。后来我发现问题并不出在模型本身而是流程出了问题——我们太习惯当“甩手掌柜”需求一句话丢过去就指望AI化身资深工程师这不现实。直到我把SDD规格驱动开发和TDD测试驱动开发引入日常开发再配合OpenSpec和Superpowers这两个工具整个局面才彻底改观。简单说SDD负责把需求变成“白纸黑字的规格文档”TDD负责把规格翻译成“可执行的验收测试”AI在两边夹击之下想跑偏都难。这篇文章写的就是这套工作流的设计思路、工具安装与配置、一次真实需求的完整实操以及我踩过的那些坑和排查经验。读完你就能照着搭一套属于自己的AI辅助开发流水线。1. 先想明白为什么要给AI编程套上“规格测试”这层约束1.1 AI直接写代码的三大痛点先泼一盆冷水。很多人都试过把需求直接丢给AI让它“写一个XX功能”结果通常有两种要么AI交上来一坨能跑的代码但边界情况全没处理输入稍微不合法就直接崩溃要么AI非常热情地把整个项目重构了一遍你只想要个弹窗它却给你加了一整套状态管理。这种情况见得多了你就会意识到AI辅助开发真正的瓶颈其实不是“生成代码”而是“约束代码朝你要的方向走”。我总结下来直接让AI写代码有三个绕不开的痛点。第一个是需求理解偏差。人的脑子里有一种“理所当然”的背景知识但AI没有。你说“做一个用户列表”它不知道你要不要分页、要不要搜索、字段显示哪些、排序规则是什么。没有约束AI就只能靠猜而猜的结果往往跟你要的对不上。比如我早期让AI做一个订单导出功能它默认把所有字段都导出了包括内部备注这种“理解偏差”在真实业务里非常危险。第二个是缺少质量关卡。人写代码有代码评审、单元测试、人工验证层层把关但很多AI辅助开发流程里AI写完就完事了根本没人检查。代码能跑只是最低标准健壮性、可维护性、异常处理、边界条件如果没有明确的验证手段AI基本不会主动考虑。更麻烦的是AI写出来的东西表面看语法正确、结构完整但内在逻辑是否严密不跑测试根本发现不了。第三个是回归风险。项目越来越大之后改动一个地方经常导致另一个地方悄悄挂掉而且AI自己写代码更不会主动告诉你它这次改动影响了哪块老逻辑。举个真实例子我让AI优化了列表查询的SQL接口速度确实上来了但分页参数全乱了整个列表页白屏。如果没有自动化测试兜底这种回归问题只能靠人肉一个个页面点过去效率极低。这三个痛点说到底不是模型能力问题而是流程问题。就像你请了个手艺很好的师傅却连图纸都不给他当然只能自由发挥。指望一句话、一个文档就让AI产出可靠代码本质上是在赌而赌的结果十有八九是要返工。1.2 SDD的核心把“愿望”变成“合同”SDD全称Spec-Driven Development规格驱动开发。核心思想一句话在写代码之前先把“系统应该做什么”写清楚形成一份可验证的规格说明然后再让代码去实现这份规格。听起来很像“先写文档再写代码”但它和传统文档有几个关键区别。第一SDD的规格不是给客户看的那种一百页产品说明书而是给开发者和AI看的“行为契约”。它关注的是系统在什么输入下应该有什么输出、有哪些边界规则、有哪些业务约束每条都尽量具体、可验证。第二SDD的规格不是写一次就完事而是跟着代码一起演进。需求变了先改规格再改代码任何时候回看规格都代表当前系统的真实行为。第三也是最重要的一点在AI辅助开发时代SDD的价值被无限放大。因为AI不具备人类的“常识背景”你给它一份结构化的规格它就能按图索骥不会把需求理解歪。规格越清晰AI生成的代码就越贴近预期。反过来没有规格就像让AI在黑箱里猜猜多少次都可能偏离航向。打个生活化的比方装修房子。你直接跟施工队说“给我装得好看点”最后装出来的风格多半跟你想的不一样。但你先找设计师出一套完整的施工图哪儿放什么、什么尺寸、什么材质全部标得清清楚楚施工队照着做效果才可控。SDD就是软件开发里的“施工图”。有了它AI这个施工队才能稳定输出你想要的结果。1.3 TDD的核心把“合同”变成“验收单”TDDTest-Driven Development测试驱动开发。它的流程非常经典就三个词Red、Green、Refactor。先写一个会失败的测试跑一遍确认它是红的然后写最少的代码让测试变绿最后在测试的保护下优化代码结构。传统上TDD是给人类开发者用的方法论通过写测试来倒逼设计让代码天然具备良好的可测试性和清晰接口。但在AI辅助开发里TDD还有另一层更实际的意义测试就是一份可自动执行的规格说明书。SDD写的“用户输入负数时系统应提示错误”这句话没法自动验证但如果你把它翻译成一段测试用例断言接口返回400并携带错误码那么AI写完之后我们跑一遍测试就能立刻判断它有没有真正满足需求。我经常把二者的关系总结成一句话SDD负责约定“该做什么”TDD负责证明“做没做到”。规格是给人看的测试是给机器看的两边一对照AI就没法蒙混过关。对AI开发来说这个组合还有个额外的好处让AI先写测试等于在动手编码前强制它再次阅读规格、思考边界条件。实践中我发现很多AI“瞎写”的情况都是从先写测试这一步开始被纠正的——当AI发现自己必须先为规格里的每一条行为准备测试用例时它自然会对规格理解得更深代码质量也随之提升。2. OpenSpec和Superpowers在整套流程里的角色分工理念说完了接下来得落到工具上。OpenSpec和Superpowers这两个名字很多人听过但不一定清楚它们到底负责哪一环。我用一句话概括OpenSpec负责“管理规格”Superpowers负责“规范AI的干活方式”两者合起来才是一条完整的SDDTDD流水线。2.1 OpenSpec规格文档的“项目管理系统”OpenSpec是一个命令行工具它帮你在项目里建立一个结构化的规格目录。你不用自己发明规范它会用固定的目录和模板把规格文件、变更记录、任务拆分、验收标准全部组织好。这也是我团队后来能在多个项目里统一流程的关键——统一模板远比统一文档风格容易落地。以我的使用习惯为例初始化之后项目下会生成一个.specs目录里面主要分两类内容一类是项目全局规格描述系统整体架构和约束AI在开发任何功能时都会参考它另一类是“变更”每个变更对应一次独立的功能开发或问题修复。每个变更下面通常有四个核心文件Proposal提案说明这次要做什么、为什么做、Requirements需求规格逐条列出行为规则、Tasks任务清单把需求拆成可执行的开发步骤、Acceptance Criteria验收标准定义如何判断完成。这个结构本身就在给开发者以及AI立规矩没想清楚别动手。OpenSpec还有一个我很喜欢的能力把变更与Git提交关联起来让规格和代码改动对应上。当你需要回看“这个功能当初为什么这么做”时直接查变更记录就行不需要翻聊天记录。它还可以让AI工具读取这些规格文件作为生成代码的上下文。结合命令行操作业务需求从提出到实现的链路都被记录在案这在团队协作里价值极高。2.2 Superpowers给AI装上“流程大脑”Superpowers不是单一工具而是一组可以安装到AI编程工具里的“技能”英文里叫Skills。开源社区有不少这类技能集合项目Superpowers是其中比较成熟的一个。像Claude Code、Codex CLI、Cursor这类支持自定义技能的AI工具都能通过配置文件把Superpowers加载进去。装了Superpowers之后AI会获得一套系统化的工作能力它能在动手写代码之前先进入规划模式把需求和实现路径梳理清楚它会在开发时自动运用TDD流程先写测试再写实现它还能执行代码审查、复盘等动作。换句话说Superpowers把“一名优秀工程师的开发习惯”编译成了AI可以遵循的操作流程。我用一个可能不算太恰当的类比普通AI像一个刚毕业的实习生能力是有但完全没章法你给个大方向它就埋头写装好Superpowers的AI像一个带过多年团队的老工程师接手任务后心里有一套完整的作业顺序——先理解需求、再拆步骤、先写测试、再写实现、最后自己检查一遍。Superpowers干的就是这件事它让AI的行为从“随心所欲”变成“有章可循”。2.3 两者结合一条完整的SDDTDD流水线单独用OpenSpec你有了规格但AI不一定老老实实按规格走单独用SuperpowersAI有了很好的工作习惯但没有一份清晰的规格文档作为依据。两者合在一起才构成真正的闭环。我实际跑的流程大致是这样的需求来了先在OpenSpec里新建一个变更把提案、需求、任务、验收标准写清楚然后让AI读取这个变更目录先用Superpowers的规划技能把实现方案理一遍再让AI按TDD技能先写测试用测试对照规格里的验收标准测试通过后再做实现和重构最后全量回归并合入变更。这套流程跑稳之后AI写出来的代码和需求之间的偏差率大幅下降而且每个功能的验收有据可查——凡是测试通过的就是真的做完了而不是看起来做完了。这种确定性是直接甩需求给AI的方式给不了的。说到底AI越聪明越需要一套靠谱的“驾驶舱”否则它跑得越快方向偏得越远。3. 实操搭一套能跑的SDDTDD工作流理念和工具都讲完了这部分就是纯操作。我会从一个全新项目开始把搭建过程的每一步拆开给你看包含安装命令、目录结构、以及AI执行过程中的关键提示词。你只要照着做大概率能跑通。3.1 安装并初始化OpenSpec第一步自然是安装OpenSpec。它是以Node.js写的CLI工具因此本机需要准备Node环境建议版本在18以上太老的Node跑起来容易报错。安装命令很简单npm install -g openspec装完之后进入你的项目目录或者先新建一个项目目录再进去执行初始化命令openspec init命令执行完项目下会出现.specs目录。我第一次跑的时候还愣了一下心想“就这”因为屏幕上只显示了寥寥几行提示。是的初始化其实就做了两件事生成规格目录结构以及一个基础配置文件。但别小看这几行输出后续所有工作都建立在这个目录之上。刚初始化的.specs目录大概是这样的.specs/ ├── project.md └── changes/其中project.md用来写项目的整体描述、技术栈、架构约束AI开发时会把它当作全局上下文changes/目录专门放一个个变更。不同版本的OpenSpec生成的模板可能略有差异但核心思路一致——先有全局规格再按变更演进。如果项目是团队协作的建议把.specs目录提交到Git哪怕个人项目也强烈建议提交。规格本身就是项目资产变更历史对日后复盘、接手、交接都特别有价值。我见过很多团队项目代码写得很漂亮但问“当初为什么这么设计”时没人说得清楚有了规格历史这个问题就彻底解决了。3.2 安装Superpowers技能集Superpowers的安装方式取决于你用的AI工具。它本质上是一组markdown格式的技能说明文件只要放到AI工具指定的技能目录里AI启动时扫描到这些文件就算“学会”了对应的工作流程。所以核心就两步获取技能集、安装到正确目录。获取技能集的方式通常是从开源仓库克隆命令大致如下git clone https://github.com/obra/superpowers.git然后根据你使用的AI工具选择安装目录。比如在Claude Code里通常需要把相关技能复制到~/.claude/skills/在Codex CLI里是放到~/.codex/skills/Cursor和WorkBuddy也各有各的自定义技能目录具体路径请以对应工具的官方文档为准。这里有个通用原则安装到用户级目录别装到单个项目里否则换项目就失效了。有一点要提醒不同版本的Superpowers对技能的组织方式不太一样有的版本是多个独立的小技能有的版本是一个大技能内部细分动作。这些都不用纠结按照你下载的版本里的README说明去装就行核心技能规划、TDD、代码审查名称基本都是固定的。装完之后怎么确认生效你可以在AI工具里直接问“你有哪些技能”如果它能报出规划、TDD、代码审查之类的能力说明加载成功了。或者更直接一点丢给它一个需求看它是先问问题、先写计划还是立刻就开始甩代码。如果是后者说明技能大概率没装上。3.3 用一个真实需求走完整流程光说不练假把式。下面我用一个非常典型的功能需求把整个流程从头到尾走一遍你会看到OpenSpec生成的文件、写规格的技巧以及AI执行时的节奏。假设我手里有一个极简的TODO应用用户可以添加任务、标记完成、删除任务。现在要新增一个功能任务可以打标签并且支持按标签筛选。需求很简单但正好能把SDDTDD每一步都串起来。有了需求别急着写代码先在OpenSpec里创建变更openspec change new add-tag-filtering这条命令会在.specs/changes/add-tag-filtering/目录下生成模板文件。接下来逐个填充四个文件各司其职文件作用核心问题proposal.md说明背景与动机为什么要做requirements.md逐条列出行为规则系统该做什么tasks.md拆解开发步骤怎么一步步实现acceptance-criteria.md定义完成标准怎么判断做完了第一个是proposal.md写“为什么做”。我会这么写用户任务多了之后找不到重点希望用标签来组织任务并能快速筛选出某类任务。一句话讲清楚背景和价值不写具体实现。这个文件的意义在于让AI在开发时始终知道“我们为什么要做这件事”避免过度设计或做偏方向。第二个是requirements.md这是重头戏。我通常会写得很细每条尽量可验证比如用户可以在创建任务时添加一个或多个标签用户可以为已有任务添加、删除标签标签以文本形式存储标签名唯一去除首尾空格大小写不敏感列表页支持按标签筛选筛选后只显示包含该标签的任务筛选条件可以清除清除后恢复完整列表筛选与分页共存时分页应基于筛选结果计算。每一条都是行为规则不绑定具体技术实现。你让AI选数组、集合还是数据库表来存都不影响这些规则成立。规则写得越机械、越不可争议AI就越没机会自由发挥。第三个是tasks.md把上面的需求拆成开发步骤比如设计数据模型、实现标签增删改、实现筛选逻辑、补充列表页交互。任务拆解粒度不用太小以AI一眼就知道每一步做什么为准。第四个是acceptance-criteria.md写验收标准我会写成“新增任务时能输入多个标签并以逗号分隔”“按标签筛选后列表只显示匹配任务”“标签大小写不一致时仍能匹配”这样的条目。到这一步SDD的上半场就完成了一个模糊的“加标签”需求变成了四份结构清晰、逐条可验证的规格文件。接下来才是AI真正登场的时候。3.4 让AI按TDD流程执行提示词模板规格写好了现在把工作交给AI。给AI的提示词不需要多复杂关键是把“先读规格、先写测试、再实现”的节奏交代清楚。我常用的模板是这一段请先阅读 .specs/changes/add-tag-filtering/ 目录下的所有规格文件。 使用TDD方式开发 1. 根据 requirements.md 和 acceptance-criteria.md 编写测试用例 2. 运行测试确认它们失败红灯 3. 再编写实现代码让测试通过绿灯 4. 最后在测试保护下优化代码结构。 每个步骤完成后简要说明你做了什么以及依据的是哪条规格。看到这里你应该明白了我把TDD的节奏直接变成了给AI的明确操作指令。Superpowers在这时起到的作用是让AI收到这类指令后能按照经过验证的工程习惯去执行识别测试边界、先跑失败测试、再写最小实现而不是“直接开写”。拿这个TODO功能举例AI先写的测试大概会覆盖创建任务时添加多个标签、给已有任务新增和删除标签、标签去空格去重、大小写归一化、按标签筛选出正确任务、清除筛选后恢复完整列表。这批测试跑下来结论肯定是全红因为功能根本没有实现。然后AI开始写实现代码目标非常明确让刚才红掉的测试一个个变绿。等全部变绿这功能基本就成了。最后AI通常会做一轮快速重构比如把标签处理逻辑抽成独立函数让代码更干净。整个过程中我基本不需要盯着它的一举一动测试结果就是最好的监工。我自己实测下来这套流程最妙的地方在于你会非常清楚“什么时候算做完”。不是AI说“完成了”就完成而是测试数据摆在那里绿就是真绿。如果AI中途偷工减料只实现了部分规则、没处理边界情况测试立刻亮红灯它想糊弄都糊弄不过去。3.5 收尾合入变更与全量回归功能做完之后还差最后一步把OpenSpec里的变更收尾。正常流程是确认所有acceptance criteria都被满足然后把变更合入正式规格让这次需求成为项目文档的一部分。OpenSpec有对应的合入命令不同版本命令名略有差异以openspec --help输出为准。合入之后我习惯顺手把项目原有的测试全量跑一遍。这一步很多人会忽略但它极其重要。新增标签功能很可能影响原有的任务删除逻辑、列表接口、数据持久化方案跑一遍全量测试才能确认有没有回归问题。尤其在AI辅助开发里AI经常会为了完成新需求改动一些你意料之外的旧代码全量回归是最有效的兜底手段。如果全量测试通过了这次变更就算正式完成。我一般还会顺便看一眼AI生成的代码里有没有明显的坏味道比如把业务逻辑全堆在组件里、没有拆分函数等。这些问题可能不影响测试通过但会影响后续维护早发现早处理。4. 常见问题与排查技巧实录工具链搭起来其实不难真正让人头疼的是使用过程中各种“莫名其妙”的问题。这一节我把实际踩过的坑整理出来按问题现象、原因、解决方案组织你可以直接对照排查。问题常见原因快速排查openspec init 报错Node版本过旧升级Node到18重新安装技能未生效目录放错、会话未重启确认技能目录新开会话AI不按规格做AI未读取规格文件在提示词中明确规格路径测试形同虚设断言过于宽松要求断言具体行为结果4.1 OpenSpec初始化失败或版本不匹配我最早遇到的问题是openspec init执行报错翻来覆去查了很久最后发现是Node版本太老。OpenSpec依赖一些比较新的JavaScript语法Node 16以下经常跑不动。所以遇到初始化报错第一排查项永远是把Node升级到18以上重新全局安装。另一种情况是版本和文档对不上。OpenSpec迭代速度不慢命令名也会微调比如早期版本里创建变更的命令和现在版本里写的可能就不一样。这时候别再上网找旧教程直接运行openspec --help看看当前版本支持哪些命令再对着命令的提示操作反而更快。4.2 Superpowers技能加载不上装了Superpowers但感觉AI毫无变化这应该是我被问得最多的问题。原因大概率是技能目录放错了。不同AI工具的技能目录路径不一样Claude Code读的是~/.claude/skills/Codex CLI走的是~/.codex/skills/还有别的工具可能要求放在项目目录下的指定文件夹里。每个工具的搜索路径都不同装之前一定要先去对应工具文档确认路径。另一个容易被忽略的坑有些AI工具需要重启会话才能扫描到新技能。你装完了技能但当前会话是旧的AI自然感知不到。重启一个新会话再问一遍“你有哪些技能”通常就能看到变化。另外如果同时用多个AI工具别假设一套路径通吃逐个配置最稳妥。4.3 规格写了AI却不按规格做这种情况经常发生而且原因往往出乎意料不是AI不听话而是它压根就没读规格文件。很多AI工具不会自动扫描你项目里所有文件它只处理你明确放进上下文的内容。你规格写得再漂亮如果不告诉AI“先读.specs/changes/xxx/下的规格”它可能看都不会看一眼。我的习惯是每次丢任务给AI先把规格文件的路径明明白白写进提示词甚至要求它把requirements.md逐条复述出来确认理解后再动手。如果AI能准确复述需求说明它真读进去了如果含含糊糊那就是没读。这一步能拦截掉大量“AI跑偏”问题。4.4 测试写成“凑数”测试怎么避免AI写测试也会偷懒最典型的表现是断言过于宽松。比如只断言“返回结果不为空”“状态码是200”却不校验关键字段和数据内容。这种测试对功能是否真正实现几乎没有约束力红灯永远不亮TDD等于白做。我的做法是在提示词里明确要求测试需要覆盖规格中的每一条需求断言要具体到“行为结果”。同时把验收标准也写得具体比如“按标签筛选后返回的任务数组中每一项都包含该标签”测试和验收标准一一对应这样凑数测试就很难蒙混过关。还有个小技巧写完测试后先故意改坏一个实现逻辑看看测试会不会变红。如果不会那说明测试质量有问题需要加强断言。4.5 团队协作里的规范统一问题如果你不是一个人在用这套流程而是要推广给整个团队最大的难点通常是“大家愿不愿意按流程走”。老开发会觉得“我明明直接写更快为什么非要先写文档”新开发会觉得“这么多步骤太麻烦”。一个流程再好如果推行成本太高最后大概率会流于形式。我的经验是分两步走。第一步把规格文档模板定死尽量减少书写成本。有人觉得SDD烦是因为没人告诉他要写什么、写到什么程度。OpenSpec的模板已经框好了结构你只需要往里填内容这已经比从零写文档轻松太多。第二步把“AI必须遵循的流程”沉淀到团队共享的提示词或Superpowers技能配置里保证任何人调起AIAI都会先读规格、先写计划、先写测试。流程让AI来强制而不是靠人自觉推行阻力会小很多。结果导向也很重要。团队里只要有一个人通过这套流程明显减少了返工次数其他人自然会慢慢接受。我在实际推广中最大的心得就是不要急着让所有人一开始就完美执行先让少数人把效果做出来再逐步带动其他人比强行推制度管用得多。最后再分享一个我个人的小习惯。每次OpenSpec变更合入之后我会在proposal.md末尾补几行“复盘记录”写下这次开发中AI在哪些地方理解准确、哪些地方跑偏了。别小看这几行字它们会慢慢变成你和AI协作的“行为字典”下次写规格时你会下意识地针对AI容易跑偏的地方写得更细这是一个持续优化的过程。这套SDDTDD工作流用到现在我最深的感觉是它没有让开发变慢反而让我对AI生成代码的信任度大幅提升。每一个“完成”都有了客观判断标准AI在规格和测试的双重约束下从“爱自由发挥的实习生”变成了“按图施工的靠谱执行者”。如果你也在为AI生成代码的质量发愁不妨从今天这套实操步骤开始试试先把流程搭起来后续的开发体验会舒服很多。
