去年我在一个中大型项目里被AI生成的代码坑了几次——不是功能不对而是代码风格、边界处理、模块划分和团队规范完全脱节。后来我琢磨出一套组合拳用SDD规范驱动开发的思路把OpenSpec当作规范管理框架再让SuperPowers给AI助手补上执行技能。这套方式让我从“反复改prompt”切换到“先定规范、再让AI照着做”整体效率提升非常明显。这篇文章就把这套工作流完整拆开聊聊想尝试规范驱动开发的开发者尤其是每天和AI编码助手打交道的人应该能直接拿走用。1. 规范驱动开发SDD的核心思路1.1 SDD、OpenSpec、SuperPowers三者到底是什么关系很多人第一次看到SDD会联想到TDD测试驱动开发或者BDD行为驱动开发它们的确同属“先定义、后实现”的流派但SDD的覆盖面要更宽。SDD强调把需求、接口设计、验收标准这些“规范”作为开发流程的源头代码只是规范的落地结果。在AI辅助编程的场景下这个源头尤其重要因为大模型生成代码时如果没有明确的约束很容易“自由发挥”。OpenSpec和SuperPowers在这套工作流里的分工很清晰OpenSpec负责管理规范文件让规范的创建、变更、版本追踪都变得结构化SuperPowers则是一组预定义的AI技能库相当于给AI助手装了“行业标准操作手册”。两者配合起来OpenSpec解决“我们到底要做什么”的问题SuperPowers解决“AI该怎么高效地把事情做出来”的问题。如果用一句话概括SDD是方法论OpenSpec是规范层SuperPowers是执行层。你不需要三样都用但组合起来才能最大限度地减少AI编程中的“偏移风险”。1.2 为什么SDD能提升AI编程的准确性直接让AI写代码哪怕你给了一段很详细的描述也经常会出现“看起来对、实际有坑”的结果。原因很简单描述是线性的而软件系统是状态化的。比如你让AI“实现用户注册接口”它可能只写了简单的字段校验和数据库插入却漏掉了邮箱格式验证、重复用户名处理、密码加密策略这些关键约束。SDD的思路是把这些约束前置到规范里用结构化的方式写清楚输入输出是什么、异常情况怎么处理、验证规则有哪些。AI在生成代码时其实是在“翻译”一份完整的规格说明书而不是在“猜测”需求。OpenSpec的价值在于它给了这份规格说明书一个标准格式让AI能稳定地定位到每一类约束。我实测下来规范写得越具体AI生成代码的一次通过率越高。以前可能要来回改五六轮prompt现在只需要在规范文件里把验收标准写清楚AI生成后跑测试通过率能到八成以上。这不是玄学而是因为大模型本身很擅长“按图索骥”问题是你要先画出一张足够精确的图。1.3 SDD与传统开发方式的对比传统开发流程里需求文档、架构设计、编码实现往往是三拨人在三个时间段里完成的信息丢失严重。SDD则尝试把三者压缩到一个统一的规范层而且这个规范层必须是机器可读、AI可理解的。相比TDD关注“测试先行”SDD更关注“全面约束先行”测试只是约束中的一类。拿我自己的项目举例以前我习惯先写接口代码再补测试最后写文档。代码跟文档经常对不上测试也覆盖不到全部边界。用SDD之后我要求自己先写OpenSpec规范把需求、设计、任务都定义清楚再让AI按规范生成代码。虽然前期写规范多花了一两个小时但后续省下的是几天的返工和沟通成本。2. OpenSpec规范文件的管理框架2.1 OpenSpec的设计理念OpenSpec并不是一个复杂的企业级平台它更像一个“规范和AI之间的翻译层”。它要求你把项目拆成一个个模块每个模块下都有独立的规范文档包含需求、设计、任务、验收标准等部分。这些文档都是纯Markdown方便人看也方便AI读取。它的核心理念是“变更驱动”每次功能开发或修复都对应一个变更集change set变更集里描述改动范围并且有清晰的验收条件。这种设计让AI在生成代码时有了明确的上下文边界不会把整个项目的代码都推翻重写。另外一个让OpenSpec加分的设计是它可以生成结构化的任务列表。你不需要自己在prompt里罗列“第一步做什么、第二步做什么”OpenSpec已经帮你拆好了AI只需要按顺序执行。这极大减少了AI生成代码时的“跳跃式”问题。2.2 规范文件结构解析一个典型的OpenSpec项目目录大概是这样的openspec/ ├── project.md ├── modules/ │ └── auth/ │ ├── requirements/ │ │ ├── 001_user_registration.md │ │ └── 002_login.md │ ├── design/ │ │ ├── 001_registration_api.md │ │ └── 002_session_management.md │ ├── tasks/ │ │ ├── 001_implement_registration_endpoint.md │ │ └── 002_add_psssword_hash_util.md │ └── changes/ │ └── 20240515_add_registration_api.mdproject.md描述整体项目背景和全局约束。modules/下面按功能模块组织每个模块有自己的requirements需求、design设计、tasks任务。changes/目录存放变更集每个变更集是一个独立的规范快照描述本次改动要解决什么问题、验收标准是什么。这种结构的好处是AI在生成代码时可以把注意力集中在一个变更集上而不是被整个项目的复杂性压垮。同时所有规范都纳入版本控制每次改动都有迹可循。2.3 安装与基础配置OpenSpec的安装方式很直接官方提供了CLI工具。以Node.js环境为例一般是这样npm install -g openspec/cli openspec initinit命令会在当前目录生成一个基础的openspec/结构。你需要做的是在project.md里填写项目背景然后创建模块和对应的规范文件。如果你用的是Cursor或者OpenCode这类AI编码工具通常不需要额外配置AI会自动扫描openspec/目录下的Markdown文件。如果你希望AI每次启动时都主动加载规范可以在项目根目录的AI指令文件里加一句话例如“开始任何任务前请先阅读openspec/project.md和相关的模块规范”。我在配置时踩过一个坑OpenSpec默认只会识别openspec/目录下的规范如果你把规范放在了别的位置AI很容易忽略。所以建议严格按照默认目录结构来不要自作聪明调整路径。2.4 从规范到任务清单OpenSpec最让我喜欢的一点是它能将规范自动解析成任务清单。比如你在tasks/001_implement_registration_endpoint.md里写清楚“实现注册接口包含邮箱、密码、用户名三个必填字段密码需要BCrypt加密”OpenSpec会把它标记为一个待办任务AI看到后会按顺序执行。这个能力看起来简单但在AI编程里非常关键。很多AI生成的代码质量差是因为它们试图一次性完成太多事情导致上下文窗口被填满中后段逻辑开始偷工减料。而任务清单强制AI“一次只做一件事”质量自然稳定。实际操作中我会在tasks/目录下给每个任务文件加上依赖关系例如“001必须在002之前完成”。OpenSpec支持简单的依赖描述AI在执行时会读到这里就不会乱序。3. SuperPowers为AI助手补齐执行技能3.1 SuperPowers到底是什么SuperPowers可以理解成一个“技能插件包”。它最初的设计目标是让AI助手具备一些“元能力”比如代码审查、重构、写文档、调试定位等。每一个能力都是一个Markdown文件里面详细描述了AI应该按照什么步骤执行这项任务以及有哪些最佳实践和禁忌。举个例子一个“code-review”技能可能会告诉AI先检查单测覆盖率再检查异常处理最后检查代码风格。如果AI没有加载这个技能它可能只会凭直觉审查。而加载了技能后AI的行为会更接近一个有经验的开发者在做code review。SuperPowers和OpenSpec的天然契合点在于OpenSpec告诉你“要做什么”SuperPowers告诉你“怎么把这件事做得专业”。如果只有OpenSpecAI可能生成能跑的代码但不够优雅。如果只有SuperPowersAI很专业却可能跑偏方向。两者结合才是完整的SDD工作流。3.2 与OpenSpec的搭配逻辑我实际使用时的流程是这样的先通过OpenSpec定义好变更集和任务然后在AI助手的系统提示词里指定“请加载SuperPowers中的xxx技能”最后才开始生成代码。技能文件里的指导会直接影响AI的代码风格和边界处理方式。比如在实现注册接口时我会要求AI加载“backend-api-design”技能这个技能通常包含接口版本管理、错误码规范、参数校验最佳实践等。加载后AI生成的代码就不会只是“能跑”而是从一开始就符合团队规范。这里有个小技巧SuperPowers的每个技能文件最好也放在版本控制里。因为技能本身会随着项目经验积累而优化你后来总结的“避坑指南”完全可以写进技能文件让AI每次都能享受你的最新经验。3.3 常用技能示例SuperPowers技能库里有不少现成的技能但也可以自己写。我常用的几个技能名称用途关键提示词error-handling规范异常处理逻辑避免吞异常“所有外部调用都必须捕获并包装为业务异常”logging统一日志格式方便排查“关键业务节点必须输出结构化日志”migration数据库迁移脚本生成与回滚“每个迁移脚本必须提供可回滚的down方法”security-check检查输入校验、权限控制“所有入口参数必须经过白名单校验”当然这些技能并不是死板的。你完全可以为你的项目定制一个“项目专属技能”把团队约定、代码风格、常用依赖版本都写进去。我把这些技能文件都放在项目根目录的powerups/文件夹下和openspec/并列AI能同时感知到规范和技能。4. 实操构建一条完整的SDD工作流4.1 场景设定为Python服务新增用户注册为了让你能直观看到这套工作流怎么落地我模拟一个常见的开发场景给一个FastAPI服务添加用户注册功能。假设技术栈是Python 3.11、FastAPI、SQLAlchemy、PostgreSQL。按照SDD的节奏我不会直接打开编辑器写代码而是先进入OpenSpec的规范流程。4.2 第一步定义项目规范和模块先检查openspec/project.md里面写清楚这个项目是做什么的有哪些全局约定。没有的话就先补上# 项目名称User Service ## 项目背景 提供用户注册、登录、个人信息管理功能。 ## 全局约束 - 代码风格遵循PEP8 - 所有接口返回格式统一为{code: 0, message: ok, data: ...} - 数据库表名使用snake_case - 密码必须使用bcrypt加密后存储接着为auth模块创建需求文件openspec/modules/auth/requirements/001_user_registration.md# 需求用户注册 ## 功能描述 允许用户通过邮箱和密码注册账号。 ## 验收标准 - 输入email, password, username - email格式必须合法 - username长度在2~32个字符之间 - password长度至少8位 - 重复注册同一邮箱时返回业务错误码1001 - 成功后返回用户ID和创建时间这步是整个工作流中最需要花心思的地方。验收标准一定要可测试、无歧义。比如“密码长度至少8位”就比“密码不能太短”好得多。AI在生成代码时会直接把这些标准转成条件判断。4.3 第二步将规范导入OpenSpec并生成任务需求写好后再补设计和任务文件。如果是比较简单的新增接口设计文件可以简短一点描述接口路径、请求体、响应体即可。任务文件则要更细。# 任务实现用户注册接口 ## 参考规范 - requirements/001_user_registration.md - design/001_registration_api.md ## 子任务 1. 创建User模型包含email、password_hash、username、created_at字段 2. 创建注册接口POST /api/v1/auth/register 3. 实现email格式校验和重复检查 4. 实现密码bcrypt加密存储 5. 返回统一格式响应OpenSpec会把这些子任务作为AI执行的蓝图。如果你用的是支持OpenSpec的AI编码工具它会自动读取这些任务并按顺序执行。如果你的AI工具没有直接集成也可以手动把任务内容粘贴到对话里作为上下文。4.4 第三步加载SuperPowers并生成代码在生成代码前我会在项目根目录的powerups/下放好两个技能文件api-boundary.md和database-access.md。前者告诉AI接口层应该如何校验参数、如何处理异常后者告诉AI数据库操作要用ORM、查询要加索引意识等。然后在AI助手的配置里增加全局指令在实现任何OpenSpec任务前请先读取powerups/api-boundary.md和powerups/database-access.md并严格遵循其中的规范。接下来就让AI从第一个子任务开始逐个实现。实际效果往往不错AI生成的User模型会包含唯一的email约束注册接口会先校验参数再查重复密码也会用bcrypt处理。相比没有技能时的“裸写”代码质量高一大截。4.5 第四步验证与迭代代码生成后我会立刻运行测试和静态检查。OpenSpec的验收标准本身就是很好的测试用例比如验证“重复邮箱返回错误码1001”是否成立。发现不符合规范的地方我会回到OpenSpec任务文件里补充说明然后让AI重新执行该子任务。这里有个重要心得不要直接在对话里让AI改“某一行代码”而是回到规范层面把缺失的约束补到验收标准里再让AI重新生成。这样做的目的是让规范成为最终的“唯一事实来源”。AI可能会忘记你曾经说过什么但它不会遗漏规范文件里的内容。我的迭代流程一般是这样的跑测试 → 发现问题 → 更新规范验收标准 → 让AI重新实现 → 再跑测试。通常两三轮之后接口就能稳定通过所有验收标准。5. 常见问题与避坑指南5.1 规范文件粒度怎么拿捏很多人在第一次写OpenSpec时会走极端要么只写一句话需求要么把代码逻辑也写进规范里。这两种都不好。规范文件应该描述“做什么”和“怎么验收”而不是“怎么实现”。实现细节交给AI根据技能和常识去发挥。我的经验是一个需求的验收标准控制在5~10条每条都是可观察的行为或约束。如果你发现需求文件快要超过一屏了大概率是粒度太细可以考虑拆分模块或者把设计细节移到design文件里。5.2 AI不按规范执行怎么办这是最让人头疼的问题。明明规范里写了密码要用bcryptAI还是用了MD5。我排查后发现绝大多数情况是因为AI的上下文窗口太大了它读取的规范文件被“淹没”在大量对话历史里。解决办法有几个一是每次新开会话时先让AI阅读规范而不是在长对话里反复使用二是把关键的、容易违反的约束在任务文件的子任务里再强调一次三是利用OpenSpec的“变更集”机制让AI只关注当前变更涉及的文件减少无关内容干扰。我还会在prompt里加一句类似“如果你发现当前任务与已有规范冲突先停下来问我”的话。虽然不能完全避免AI自作主张但至少能减少静默偏移。5.3 OpenSpec与IDE插件/CLI的协同如果你不用Cursor这类有OpenSpec集成的工具也可以直接用CLI手动操作。比如在终端里执行openspec task list查看当前所有待办任务用openspec change create description创建变更集。CLI的好处是纯文本、可脚本化可以和CI流程集成。我之前把OpenSpec命令接入了pre-commit钩子每次提交前检查是否存在未标记为“完成”的任务如果有就拦截提交。这能有效避免“规范还写着没做代码却进了仓库”的情况。另外如果你用的是OpenCode这类命令行AI助手可以直接在配置里指定OpenSpec路径让AI每次启动时自动加载相关文件。这比复制粘贴规范内容省事得多而且不会因为复制截断导致信息丢失。5.4 规范变更时的维护成本SDD有个常见质疑维护规范不是额外增加工作量吗我的经验是规范文件本身不需要频繁重写但每次需求变更时必须同步更新。如果你只改代码而不改规范逐渐地规范就会失效AI之后生成的代码也会偏离。为了降低维护成本我建议把规范当成代码的一部分来管理。每次变更都走同一个流程更新需求 → 更新设计 → 更新任务 → 生成代码 → 跑测试。虽然看起来步骤多了但每一步都很轻量。还有个实用技巧让AI反向生成规范。如果你已经有一份实现代码可以让AI总结它的行为生成一份初始规范。之后再基于这份规范修改和扩展比自己从零写规范省力太多。最后再分享一个小技巧我实践SDD一年多发现最容易被忽略的不是工具本身而是“把规范当成契约”的心态。很多开发者在写规范时潜意识里觉得“反正AI会读写得太粗糙也没关系”结果AI生成的代码自然也不可靠。如果你能像对待接口文档一样对待OpenSpec规范把每条验收标准都写得像测试断言那样精确整套工作流会顺畅很多。另外一个让我很受用的习惯是在SuperPowers技能文件里记录“失败经验”。比如我曾在日志规范上吃过亏后来就在日志技能里加了“禁止使用print调试必须使用结构化logger”。这样每次AI生成日志代码时都会自动避开这个坑。技能库会随着时间沉淀越来越像你的“个人首席工程师”。如果你正在尝试让AI更可靠地参与到项目里我建议你从今天开始选一个小功能用OpenSpec写一份最小规范挂上SuperPowers技能让AI完整走一遍流程。真正试过之后你就会理解为什么很多团队开始把“规范优先”当作AI协作的第一原则。