AI编程返工率高？用OpenSpec+SuperPowers实现规范驱动开发

最近接手一个内部工具项目光需求澄清就花了三周。每次开发前问产品经理回答都是“就这样差不多”等代码写出来又发现完全不是那么回事。后来我把工作流切到SDDSpecification-Driven Development规范驱动编程配合OpenSpec管理规范、SuperPowers给AI助手补齐执行技能需求反复率下降非常明显。如果你也在用AI辅助编程或者团队里经常因为“理解不一致”导致返工这套思路值得你看看。开门见山说结论SDD不是什么灵丹妙药它更像一种“先写说明书再动手干活”的纪律。OpenSpec负责把说明书变成仓库里可版本管理、可评审、可验证的文档SuperPowers则负责把说明书翻译成AI助手能一步步执行的技能。三者组合起来解决的核心问题只有一个人和AI到底依据什么来写代码。1. SDD不是新概念从“靠嘴编程”到“规范先行”的范式切换1.1 为什么AI时代反而需要“规范驱动”很多人一听“规范驱动开发”第一反应是又多了层文档负担。我以前也这么想直到发现纯靠对话式编程Vibe Coding有个天然缺陷模型会把“你上一句话”当成最高优先级而上一句话往往不是完整需求。比如你让AI“给用户列表加一个导出按钮”它很可能会立刻写一个浮窗按钮导出全部数据。但真实需求可能是“只导出当前筛选条件下的数据而且只允许导出前5000条”。不把这些写清楚AI每次猜测的方向都可能不同代码自然反复返工。SDD的核心就是把需求从人的脑子里、聊天记录里搬到一个有结构的规范文件里让后续所有编码行为都向这份规范看齐。这个思路在传统软件工程里叫需求管理但过去太折腾没人愿意写几百页需求文档。现在不一样了AI催化出了一个新的开发节奏规范不用写得很长但必须写得可执行、可验证并且让AI能直接读取并遵守。这个节奏就是SDD。1.2 三级分类框架从“为什么”到“怎么做”的链路提到SDD绕不开ThoughtWorks杰出工程师Birgitta Böckeler提出的三级分类框架。她最大的贡献是把“规范”从一个笼统的词拆成了三个层级第一级方向规范Why说清楚项目或产品为什么要做这件事。它面对的是整个产品团队不需要写技术细节但要写清楚目标用户、核心痛点和预期收益。第二级功能规范What针对单个特性写清楚用户故事、业务规则、边界条件和验收标准。这一层是产品经理和开发沟通的桥梁。第三级任务规范How落到工程实现包括技术方案、文件改动范围、接口设计、测试策略。这一层直接给开发者和AI编码助手执行。我对这个框架的理解是没有第一级代码容易偏离方向没有第二级AI容易自作主张没有第三级团队内部无法高效协作。OpenSpec做的其实就是把这三层规范塞进一个项目目录让它跟着代码走。1.3 SDD和TDD、BDD到底有什么区别我经常被问“规范驱动开发和测试驱动开发不是一回事吗”这里必须掰开说清楚。TDD测试驱动开发是从测试用例推导出实现代码重心在“验证行为”BDD行为驱动开发用自然语言描述行为让业务和开发共用一套语法而SDD的层级更高它不只关心测试还关心需求来源、设计决策、任务拆分和验收标准。你可以把SDD理解成一把伞TDD、BDD都是伞下的一种执行手段。用OpenSpec写规范时里面照样会写“应该有测试覆盖”“验收条件要可自动化”但规范文件本身不是测试代码它更像开发工作的“合同”。2. OpenSpec的核心思路让规范成为可执行的单一起源2.1 为什么我选OpenSpec而不是直接用Markdown写规范刚开始我试过用普通的Markdown文档写需求但很快就乱了文档和代码是两套东西没人维护也脱节。OpenSpec最大的价值是把规范变更和代码提交绑定在同一个Git仓库里让规范变成项目的一部分而不是单独的Wiki页面。具体来说OpenSpec规定了一套目录结构和变更流程你每做一次功能开发先创建一个“变更Change”在里面写清背景、需求、任务清单和验收标准然后AI或者开发者按这个变更去写代码最后再根据实际改动更新规范文件。这样整个开发过程演进都有迹可循审代码时也能同时审“规范写得对不对”。2.2 一个标准项目的OpenSpec目录长什么样我目前的项目经过几轮调整后目录结构大概是这样的. ├── openspec/ │ ├── project.md │ ├── specs/ │ │ ├── 001-user-export/ │ │ │ ├── README.md │ │ │ ├── specification.md │ │ │ └── acceptance-criteria.md │ │ └── 002-report-scheduling/ │ │ ├── README.md │ │ ├── specification.md │ │ └── acceptance-criteria.md │ └── changes/ │ └── 2025-06-export-report/ │ ├── proposal.md │ ├── tasks.md │ └── status.md └── src/project.md项目级的方向规范对应第一级“Why”。specs/已经定稿的特性规范对应第二级“What”和第三级“How”。changes/进行中的变更草稿里面是待评审、待开发、待验收的内容。这个结构最关键的一点是一切可评审。以前文档藏在WIKI里现在每次改动都通过Pull Request评审评审内容包括规范和API设计。这相当于把“需求评审”和“代码评审”合并成了“变更评审”。2.3 规范和代码之间如何建立“可验证”的连接OpenSpec本身不会帮你自动跑测试但它提供的规范结构天然支持可验证。每个Change里的任务清单都会对应代码提交每个验收标准都能映射到一条测试用例或者一次手工验证步骤。我通常会在规范文件里给每条验收标准打上标记比如AC-001、AC-002然后在代码里写#AC-001注释或在测试用例名称里带上编号。这样当CI跑测试时如果某条验收标准挂了可以直接定位到规范文件里的对应描述。时间一长整个项目的“需求可追溯性”就建立起来了这在后期排查问题时特别有用。3. OpenSpec安装与初始化开箱即用之外的三件小事3.1 安装OpenSpec命令行工具OpenSpec目前的核心是一个命令行工具帮助你创建目录、生成变更模板、校验规范格式。安装方式很简单可以直接去官方仓库的Releases页面下载对应平台的二进制或者用包管理器安装。以macOS环境为例我用的是Homebrewbrew install openspec/tap/openspec如果你是Linux服务器或Windows环境建议直接下载二进制文件到本机然后加到PATH里。安装完成后验证一下openspec --version接下来在已有项目中初始化openspec init这个命令会创建上面说的openspec/目录结构并且在项目根目录生成一个配置文件比如.openspec.json里面可以指定哪些目录不被规范校验、默认的语言风格等。3.2 创建第一个变更命令背后的含义初始化完成后推荐从“变更”开始而不是直接写定稿规范。原因是变更可以反复修改定稿规范需要更多评审。openspec new change 添加用户导出功能执行后命令会创建openspec/changes/2025-06-add-user-export/文件夹里面有几个预设模板。我习惯把proposal.md分成这几段Context为什么做这个功能当前遇到了什么问题。Goals / Non-Goals列入目标的东西要重点保障不列入目标的东西要明确说出来避免AI发散。Requirements按编号列出的功能条目。Design Options记录可选的方案和取舍。Tasks拆解出的开发任务尽量小且独立。Acceptance Criteria可验证的验收标准。这些内容把第二级、第三级规范一次写完后续的编码过程就是“按图索骥”。3.3 让AI助手读懂规范的配置技巧工具装好只是开始真正麻烦的是让AI助手比如OpenCode、Codex CLI在生成代码前主动去读这些规范。我的做法是在AI助手的系统提示词或项目级指令文件里加一段类似这样的说明在开始任何编码任务之前先读取 openspec/ 目录下与当前任务相关的 specification.md 和 acceptance-criteria.md。 必须按照 tasks.md 中的任务顺序逐步实现。 每个任务完成后根据验收标准自检并在提交信息中引用变更编号。不要小看这段配置。很多AI助手不读规则是因为没人告诉它规则在哪里。加完之后整个编码行为就完全不一样了它会先找规范文件再动手写代码而不是直接凭上一句对话猜需求。4. SuperPowers到底补了什么把规范变成可执行的技能链4.1 superpowers skill是干嘛的OpenSpec解决了“规范从哪来、放哪里”的问题但AI拿到规范之后能不能高质量执行是另一回事。如果只把规范文档扔给AI它依然可能产出结构混乱、缺少测试、逻辑不全的代码。这时候SuperPowers就派上用场了。SuperPowers是一个skill集合可以挂载到支持Skills机制的AI编码工具上。它做的事情有点像给AI装了一套“行业老师傅的操作手册”比如“如何把一个规范拆成多个可执行任务”“如何按验收标准逐条自测”“如何写出更便于评审的提交信息”。我理解SuperPowers和OpenSpec的关系是OpenSpec是项目管理层的骨架SuperPowers是执行层的手脚。光有骨架AI不知道怎么动光有手脚AI不知道往哪走。两者搭配起来才能跑通从规范到代码的完整链路。4.2 在OpenCode里安装SuperPowers以OpenCode为例它支持通过命令直接安装Skill包。我用的安装方式如下不同版本命令可能有些差异但思路一致opencode skill add superpowers如果命令不可用也可以把SuperPowers的仓库克隆下来放到OpenCode的skills目录下例如~/.config/opencode/skills/superpowers/安装完成后在对话里试验一下。如果AI的回复中提到“我会使用SuperPowers的规范拆解技能”说明挂载成功。之后当你给出一个需求时它不再直接写代码而是先问清楚边界然后生成一个可执行的任务清单。4.3 常用技能规范拆解、任务生成、验收清单我自己最常用的三个技能规范拆解技能把一段比较模糊的需求描述拆成“目标、非目标、假设、问题清单”。这一步能逼着产品经理把需求想清楚。任务生成技能把规范文件转换成按依赖顺序排列的开发任务每个任务里附上涉及的文件路径、预计改动范围、自测方式。AI按这个任务列表执行不会东一榔头西一棒子。验收清单技能在代码写完之前先生成一份验收清单然后逐项对照代码和测试把不满足的项列出来这一步能大大减少“我以为我写完了”的错觉。有了这几个技能AI的表现更像一个有经验的后端工程师而不是一个“代码生成器”。5. 从“需求描述”到“验收通过的代码”一个完整工作流实例5.1 场景给现有项目加一个“导出报表”功能纸上谈兵太多来一个完整实例。假设你有一个订单管理后台现在需求是支持导出当前筛选条件下的订单报表格式为CSV最多导出5000条导出完成后发送站内通知。需求就这么一句话。如果直接让AI写大概率会出各种岔子。下面是我按OpenSpecSuperPowers流程走下来的完整操作。5.2 第一步用OpenSpec记录变更写清“为什么做什么”先创建变更openspec new change 订单列表导出CSV然后编辑proposal.md核心内容如下# 订单列表导出CSV ## Context 运营每天需要从订单后台导出数据给财务做对账。当前手动复制粘贴效率低且容易遗漏筛选条件。 ## Goals - 支持基于当前筛选条件导出CSV - 导出数量最多5000条超出时提示用户 - 导出完成后站内信通知 ## Non-Goals - 不增加PDF导出 - 不做定时自动导出 ## Requirements - R1: 导出按钮在订单列表页右上角 - R2: 点击后异步生成CSV文件 - R3: CSV文件名包含导出日期 - R4: 导出完成后发送站内通知 ## Acceptance Criteria - AC-001: 当前筛选条件为“状态已支付”导出的CSV只包含已支付订单 - AC-002: 当筛选结果超过5000条时不会生成CSV提示“最多导出5000条” - AC-003: 导出完成后当前用户收到站内通知这里最重要的一个技巧是规格越细AI的自主发挥空间越小结果越可控。特别是Non-Goals很多需求反复就是因为没写清“这次不做什么”。5.3 第二步让SuperPowers生成任务并驱动AI编码接着打开OpenCode在对话里对AI说请读取 openspec/changes/2025-06-order-export-csv/proposal.md 使用SuperPowers的任务生成技能生成可执行的任务列表并逐个实现。AI会先解析规范文件然后生成类似这样的任务调研当前订单列表页的筛选条件状态如何在前端维护。设计后端导出接口入参为筛选条件出参为异步任务ID。实现CSV生成服务加入5000条上限限制。接入站内信通知模块。编写对应单元测试覆盖验收标准AC-001到AC-003。之后AI会按顺序执行每完成一个任务还会汇报状态。遇到“筛选条件状态”不清楚的地方它会主动提问而不是自己猜测。这是因为SuperPowers的技能里包含“在信息不足时返回澄清问题”的规则这一点对真实项目太重要了。5.4 第三步用验收标准验证结果而不是相信感觉写完之后AI会引用规范文件中的验收标准逐条自检。但别完全信任它我会自己人工跑一遍关键路径。以AC-001为例我会在页面上先设置筛选条件为“已支付”再点击导出然后打开生成的CSV确认里面没有“未支付”的记录。如果发现AI漏了某个边界条件比如“5000条时正好等于上限应该允许”我会把这条补充到规范文件里并新建一个子任务让AI修复。这个“规范→编码→验证→补充规范”的闭环就是SDD的日常。这里也提醒一下规范和代码不是一次性生成的。每次验证发现新问题都要回到规范文件里更新。如果只改代码不改规范下次AI又可能犯同样的错。6. 踩坑实录提示词、规范版本和团队协作的几个教训6.1 规范写得太细AI反而不会干活刚开始接触OpenSpec时我犯过的最大错误是把规范写成了伪代码比如“使用OrderExportService.exportCSV(filter, limit)”这种。结果AI要么被束缚住不敢调整设计要么认为实现已经定了直接跳过必要的技术验证。后来我调整了写法规范只写“该做什么、边界是什么、验收标准是什么”至于用类还是函数、用HashMap还是List交给AI和代码评审去决定。规范和实现之间应该留一层设计空间否则你写的就不是规范而是代码草稿。6.2 变更和代码不同步把openspec目录当成纯文档另一个容易踩的坑是变更文件创建完后就不再去动它最后功能和规范对不上。这个问题尤其容易出现在“急需求”场景先在代码里改了一版等想起来要补规范时细节已经忘了。我现在给自己订了一条规矩任何一次行为变更必须先改OpenSpec变更再动代码。哪怕只改了按钮颜色也要在变更里对应调整验收标准。这样做的成本其实不高但换来的是三个月后看提交记录时能准确知道每一行代码是为什么变成这样的。6.3 如何让团队里的新人接受这个流程很多人不愿意用SDD不是因为它不好而是因为“写文档”这个动作让人本能抗拒。我的经验是不要强推而是从“验收标准”这个最小单元开始。先要求团队每开发一个功能在PR描述里写三条“验收标准”。过两周再把这三条验收标准挪到OpenSpec的规范目录里。再往后引入任务清单和背景说明。这样一步步来大家不会觉得是在增加工作量而是觉得“需求变清晰了”。等大家尝到甜头SDD流程自然就落地了。6.4 不适合SDD的场景最后说句公道话SDD不是所有项目都适用。原型探索类项目、一次性脚本、Demo演示这些场景讲究快速验证规范写得太重反而拖慢节奏。我现在的判断标准是只要这段代码会被维护三个月以上就值得用OpenSpec写规范如果明天就删那就直接用命令行一把梭。从“靠嘴编程”切换到“规范驱动”最难的不是工具而是习惯。工具可以装一天装完习惯则需要几个项目周期才能养成。但凡是坚持下来的项目几乎没人愿意退回原来的开发模式。这一点我算是亲测有效。