最近我在折腾“规范驱动开发”Spec-Driven Development也就是 SDD的时候把 OpenSpec 和 SuperPowers 这两个东西搭在一起用效果确实有点超出预期。作为一个长期在需求漂移、代码腐化、文档失效里反复挣扎的开发者我原本对“AI 自动写代码”是持保留态度的但这两个工具组合起来之后最大的感受是不是 AI 不会写而是我们没给它一套清晰、可演进、可验收的“规矩”。这篇就聊一聊 SDD 的核心套路以及 OpenSpec 和 SuperPowers 到底该怎么配合使用适合那些正在用 Cursor、Codex CLI 或类似 AI 编程工具但总觉得“AI 写的代码不够听话”的人。1. 先搞清楚 SDD 到底在解决什么问题1.1 传统开发的痛点需求到代码的“翻译损耗”我以前做过不少传统项目最让人头疼的往往不是技术难点而是需求到实现之间的那种“翻译损耗”。产品经理在会议上口头描述一个功能开发理解的是另外一版写出来的代码又变形一次最后测试再按自己理解的验收标准去测等到上线的时候功能已经和最初的想法差了十万八千里。这个过程中间没有一个稳定的、机器可读的中间产物所有沟通都靠文档、聊天记录和人的记忆。在引入 AI 编程工具之后这个问题其实变得更严重了。因为你给 AI 一个大段自然语言的提示词它生成出来的代码只要表面上像那么回事你很难判断它是不是真的满足了业务约束。更麻烦的是下一轮对话时 AI 可能已经忘了之前的上下文或者换一个模型又有一版新理解整个开发过程就像是在开一辆没有方向盘的车能跑但方向完全不可控。SDD 的核心思路就是在这中间加一层“规范层”。它不是把需求简单写成人话而是把需求中那些必须满足的约束、验收条件、边界情况用结构化的方式记录下来。代码可以改但规范不能随意动如果规范变了代码必须跟着变。这等于给 AI 编程加了一个“合同”每次写代码、改代码都是围绕合同在执行而不是凭着模糊的印象在自由发挥。1.2 规范驱动开发的核心思路规范驱动开发并不是什么玄学它本质上就是“先定义可验证的行为再写实现”。传统的 TDD测试驱动开发是先写测试再写代码SDD 则更进一步先把业务规则、用户场景、验收标准都沉淀成规范文件这些规范文件可以被 AI 读取也可以被测试脚本校验还能在代码评审的时候作为依据。这里有一个关键点规范不是纯文本描述而是带有编号、约束词比如 MUST、SHOULD、验收条件的结构化文本。为什么要这么较真因为 AI 模型天然擅长理解模糊的自然语言但也天然容易把模糊变成“自由发挥”。当规范里明确写了 “用户密码连续输错 5 次后账号必须锁定 30 分钟”AI 在生成代码时就会优先去实现这个逻辑而不是自己发明一个“锁定 15 分钟”或者干脆忽略。我把 SDD 的落地过程总结成六步后文会一直用到这六步。1.3 SDD 六步实践指南可以直接抄第一步澄清目标。先搞清楚你要做的这件事为了谁、解决什么痛点、有哪些必须支持的主要场景。第二步编写规范。把目标拆成可验证的条目每一条都尽量写成“系统必须/应当/可以做到某件事”的形式并给出验收标准。第三步设计与风险分析。包括技术选型、模块划分、数据流走向以及可能出现的边界情况、兼容性风险。第四步实现。这阶段 AI 才能开始写代码而且它必须依据规范文件来生成实现而不是依据你随手敲的提示词。第五步验证。把规范中的验收条件转成测试用例跑一遍确定哪些通过了哪些还没满足。第六步记录与演进。把规范文件的变更记录纳入版本管理每次改动都走同样的流程。这套六步法听起来简单但实际执行的时候很容易被打回原形。原因很简单人都是有惰性的在没有工具支撑的时候“写规范”这件事特别容易被跳过或者写着写着就和代码脱节了。OpenSpec 这类工具就是来解决这个问题的。2. OpenSpec把规范变成可执行的“真文件”2.1 OpenSpec 是什么它管什么OpenSpec 是一个面向 SDD 的开源工具集核心目标是把规范文件从“别人看不看得懂”变成“机器能不能处理”。我第一次接触它的印象是它更像是一个规范文件的管理框架而不只是又一个文档模板。它提供了一套约定好的目录结构、一套规范文件的书写格式还提供了一些命令行工具用来创建、校验、跟踪规范的变化。用 OpenSpec 之后你就不是把规范散落在各个文档或者 Wiki 里了而是像管理代码一样管理规范。规范文件会进 Git 仓库会有版本会有变更历史甚至可以在 CI 里跑校验确保代码实现和规范之间没有明显的偏离。这里我特别想强调 OpenSpec 的“结构化”价值。它要求每条需求都有一个稳定 ID比如FR-1、NFR-3这种这样在后续的代码注释、测试用例、对话记录里都可以引用同一个 ID。AI 模型对这类稳定的标识符非常敏感它能够把一个写在代码注释里的FR-1和规范文件里的具体条目关联起来这比让它记住“刚才需求里说密码要加密存储”这种模糊信息靠谱得多。2.2 快速上手初始化一个 OpenSpec 项目因为 OpenSpec 还处在一个快速迭代的阶段安装方式会随版本变化最稳妥的办法是去它的官方 GitHub 仓库看 README。不过核心流程一般差不多如果是 Node 环境可以直接用 npm 全局安装npm install -g openspec openspec --version然后在一个 Git 仓库里初始化git init my-sdd-demo cd my-sdd-demo openspec init初始化之后OpenSpec 通常会生成一个specs/目录这个目录就是整个项目规范文件的大本营。如果你用的是 Cursor、Trae 这类 IDE建议在项目根目录的AGENTS.md或.cursor/rules里明确写上“所有新功能必须先在specs/中添加或修改规范再动代码”这一步看着多余实际上能有效避免 AI 一上来就闷头写实现。2.3 核心文件结构specs/ 目录应该怎么组织不同版本的 OpenSpec 在目录组织上会有些差异但大概的思想是一致的按功能领域或需求模块拆分成多个规范文件每个文件尽量克制不要什么都往里塞。常见的结构是这样specs/ ├── projects/ │ └── user-auth/ │ ├── README.md │ └── spec.md ├── capabilities/ │ ├── email-validation/ │ │ ├── README.md │ │ └── spec.md │ └── account-lock/ │ ├── README.md │ └── spec.md └── openspec.yamlprojects/user-auth/spec.md里面通常会写清楚这个功能模块的背景、目标、范围capabilities下面的每个子目录则对应一个更细的能力点比如邮箱格式校验、账号锁定策略。这样拆分的好处是AI 在生成实现时不需要读取一个大而全的文档而是按需去查对应能力点的规范文件。对于大模型来说上下文窗口再大也是有限的拆得越细检索越精确生成质量自然越高。在spec.md内部我习惯用下面这种结构# User Login Specification ## Context 用户需要输入邮箱和密码完成登录。 ## Requirements - FR-1: 系统必须校验邮箱格式是否合法。 - FR-2: 系统必须校验密码是否与已存储的哈希值匹配。 - FR-3: 连续登录失败 5 次后系统必须锁定账号 30 分钟。 - NFR-1: 登录接口的 P95 响应时间不得超过 500ms。 ## Acceptance Criteria - AC-1: 给定正确凭证系统返回登录成功。 - AC-2: 给定错误凭证系统返回可读错误提示。 - AC-3: 账号锁定期间系统拒绝登录并显示剩余解锁时间。你可能会说这跟我自己写需求文档有什么区别区别在于OpenSpec 会把“FR-1是否在代码里被实现”这件事工具化。也就是说这些编号不只是给人看的还可以通过脚本提取出来和测试用例、代码引用做关联。2.4 没有 OpenSpec 和有 OpenSpec 的时候有什么不同拿我自己的一次真实对比来说。之前我在一个模块里让 AI 写一个“用户资料编辑”功能在没有 OpenSpec 的时候我给它一句“实现用户修改昵称和头像”结果它发挥得非常奔放昵称校验逻辑写了一堆头像上传却做了本地文件存储而且没有做文件类型校验。改动起来非常麻烦因为我不知道它哪些设计是会后面传化成隐患的。同样一个功能我后来先用 OpenSpec 写了三条规范FR-1昵称长度 2-16 个字符FR-2头像只允许 JPG/PNG 格式且大小不超过 2MBFR-3头像上传后必须返回 CDN 地址。然后再让 AI 去实现。这次它生成的代码和规范的契合度明显高了很多测试时也只花了几分钟就发现它读错了FR-3的“返回 CDN 地址”这个要求因为代码里返回的是本地相对路径。如果没有规范文件作为对照我可能又要靠肉眼去 review 它的每一行代码。所以有没有 OpenSpec最大的区别不是“规范文件是否存在”而是有没有一套机制让 AI 在生成代码之前就先去读规范、在生成过程中引用规范、最后还能够被规范反查。这相当于把 AI 从一个“话痨实习生”变成了“按图纸施工的初级工程师”。3. SuperPowers给 AI 编码助手装上“技能包”3.1 SuperPowers 的本质一套可复用的 Skill 集合如果说 OpenSpec 解决的是“规范怎么写、怎么管理”那 SuperPowers 解决的是“AI 怎么按照规范去干活并且干活的过程有章法”。SuperPowers 是一个社区非常火的开源项目它本质上是为 AI 编码助手准备的一套 Skill技能集合。Skill 到底是什么你可以把它理解为 AI 的“操作手册”或者“工作流模板”。普通提示词是你一次性告诉 AI 要做什么而 Skill 则是把一组提示词、脚本、决策树打包成文件AI 在需要的时候可以加载这套技能按里面定义好的步骤去执行。比如一个“代码审查”技能会告诉 AI 先读 diff、再对照规范文件、再检查安全边界、最后输出审查意见每一步都有明确动作。SuperPowers 的厉害之处在于它把这些技能模块化而且有很多技能是针对“AI 写代码时的执行力”设计的。比如它会教 AI 怎么拆解任务、怎么把大任务切成小步、怎么在执行过程中自测甚至遇到编译错误时怎么自己修复。这些能力单看好像不稀奇但组合在一起之后AI 的表现会从“生成一段代码片段”升级成“可以独立完成一个小型功能模块”。3.2 安装 SuperPowers以 Codex CLI 为例具体的安装步骤还是得看官方 GitHub 仓库因为它的更新频率不低。以我上次在 Codex CLI 里安装为例大致流程是这样先把项目克隆到本地的技能目录git clone https://github.com/your-org/superpowers.git ~/.codex/skills/superpowers然后在 Codex 的配置文件里声明技能路径或者在项目根目录的AGENTS.md里写上类似“你可以使用~/.codex/skills/superpowers下的技能”的说明。这样当你输入指令时AI 会主动去查找是否匹配某个技能。如果你是第一次用千万别一次性把所有技能都塞给 AI会带来两个问题一个是上下文窗口被无关内容占满另一个是 AI 容易在多个技能之间来回横跳反而不知道先做哪个。我推荐优先开启和工作流直接相关的几个技能比如“规范驱动开发”、“任务拆分”、“测试验证”这三个等跑通了再加别的。3.3 与 OpenSpec 一起用的核心工作流OpenSpec 加 SuperPowers 的组合我用的最多的场景是“从规范到实现的自动闭环”。大致工作流是这样的第一步用 OpenSpec 写好或更新一个能力点的规范文件。这部分以人为主AI 可以辅助生成草稿但最终要有人确认。第二步在对话里明确告诉 AI“请先读取specs/projects/user-auth/spec.md然后按照 SuperPowers 中的规范开发技能把这个模块实现出来。”注意不要只说“帮我实现登录功能”一定要把规范文件路径作为重点信息给出来并且要求 AI 在实现前先复述一遍它理解的约束。第三步AI 在实现过程中会调用相关技能自动拆解任务先搭骨架再写认证逻辑再补测试。这个过程中它会自己检查代码是否符合规范和技能里的步骤。第四步实现完之后让 AI 输出“规范和实现的对照检查表”比如每个需求编号对应哪个文件哪段逻辑。这一步特别关键能让你快速发现哪些需求没有被覆盖。我用这个流程做一个小模块时整体效率至少提升了一倍而且返工少了。最明显的变化是以前 AI 写完代码我还要一条一条照着需求去验证现在它会主动把需求编号映射到代码里我可以直接跳着检查省去了大量人工对照的时间。3.4 在 Cursor / Trae 等 IDE 中接入的注意事项现在很多人用的是 Cursor、Trae 这类 AI IDE它们在原理上也是一个对话窗口加一个代码编辑器。SuperPowers 这类 Skill 能不能在这些工具里生效关键看它们是否支持加载类似AGENTS.md、.cursor/rules这样的项目级指令文件。我之前在 Cursor 里试过把 SuperPowers 的核心使用说明写进.cursor/rules/下面的一个 Markdown 文件里然后在对话中让 Cursor 读取它效果是可以的。不过要注意如果规则文件写得又长又杂Cursor 的上下文开销会很大反而影响后续代码生成的准确性。所以最好是只放关键摘要比如“必须优先参考specs/目录下的规范文件再使用特定技能完成工作”这一句话就比把整个技能库内容贴进去要有效得多。在 Trae 里接入也是类似的思路它的 Custom Instructions 或者项目描述文件都可以用来绑定规范和技能路径。但我个人建议不要纯依赖 IDE 图形界面最好还是在项目仓库里维护一份AGENTS.md这样无论是 Cursor、Trae 还是 Codex CLI都能看到同一份指导文件。工具可以换规范不能乱。4. 实操过程从零到一跑通 OpenSpec SuperPowers 完整链路4.1 环境准备与版本选型开始之前先把环境理清楚。我现在用的组合是Node 20Git 2.40OpenSpec 最新版Codex CLI 最新版然后 SuperPowers 是直接从 GitHub 拉的最新 main 分支。如果你用的 IDE 是 Cursor请确认版本支持自定义规则目录如果用 Trae就查一下 Custom Instructions 的加载方式。先建一个目录并初始化 Gitmkdir sdd-demo cd sdd-demo git init npm init -y然后安装 OpenSpec 并初始化npm install -g openspeclatest openspec init初始化后我们可以看一下生成的目录结构。如果和你的版本不一样也别慌核心不就是specs/吗只要保证规范文件有一个稳定的根目录就行。4.2 设计一个示例需求用户登录模块为了演示我挑一个大家都很熟悉的场景用户登录模块。需求描述是这样的用户输入邮箱和密码系统校验通过后返回一个 JWT Token如果密码错误累计失败达到 5 次账号锁定 30 分钟所有错误提示不能泄露用户是否存在。就这么一个看似简单的模块里面其实有好几个容易踩坑的边界条件。所以很适合用来做 SDD 的例子。4.3 用 OpenSpec 编写规范按照我们前面说的六步法先写规范。打开specs/capabilities/user-login/spec.md我建议写成这样# User Login Capability ## Context 系统需要为用户提供安全的登录认证能力基于邮箱和密码进行身份验证。 ## Requirements - FR-1: 系统必须校验邮箱格式合法。 - FR-2: 系统必须验证密码哈希。 - FR-3: 系统必须在连续登录失败 5 次后锁定账号 30 分钟。 - FR-4: 系统必须在登录成功后签发 JWT Token。 - SEC-1: 系统不得在错误信息中区分“邮箱不存在”和“密码错误”。 ## Acceptance Criteria - AC-1: 输入合法邮箱与正确密码返回 200 和 JWT。 - AC-2: 输入非法邮箱返回 400 且提示邮箱格式错误。 - AC-3: 连续失败 5 次后返回 423 且提示锁定剩余时间。 - AC-4: 密码错误时返回 401 且不暴露邮箱是否注册。写完这份规范后在对话里让 AI 快速“复述”一遍需求。如果它把SEC-1理解成了“提示用户邮箱不存在”那宁可不往下走先把规范解释清楚再继续。这一步是很多开发者会跳过的但恰恰是减少返工的关键。4.4 调用 SuperPowers 生成实现规范就位后我一般在 Codex CLI 里输入一段类似这样的指令请先读取 specs/capabilities/user-login/spec.md 中的全部需求然后使用 SuperPowers 的 task-breaking 技能和 test-first 技能基于 Node.js Express 实现该能力。实现完成后输出一份需求编号与代码位置的对照清单。这里我刻意把“技能名称”写在指令里而不是只说“用 SuperPowers”。原因是AI 在模糊指令下可能只加载最通用的技能未必会主动拆解任务。你把技能名说清楚等于给它指定了一条清晰的执行路径。AI 执行时通常会先输出一个任务清单初始化 Express 项目实现邮箱校验中间件实现密码哈希校验模块实现失败计数和账号锁定服务实现 JWT 签发编写对应的单元测试。这个任务清单出来之后你先别急着让它往下写而是检查一下清单是否覆盖了所有规范条目。比如SEC-1如果没出现在任务清单里那你就要补一句“别忘了 SEC-1 的安全约束必须让账号不存在和密码错误返回一致的提示”。4.5 验证、迭代、追踪规范变更代码生成完毕后先跑测试npm test如果测试没过先让 AI 看失败信息自己修。这里 SuperPowers 的好处就体现出来了它通常会引导 AI 先查日志、再改代码、再跑测试而不是表面修一下、测都不测就报“已完成”。测试过了之后我还建议让 AI 生成一份“规范覆盖矩阵”类似需求编号对应实现文件对应测试用例状态FR-1src/utils/email.jstest/email.test.js已实现FR-2src/services/auth.jstest/auth.test.js已实现FR-3src/services/accountLock.jstest/lock.test.js已实现SEC-1src/middlewares/errorHandler.jstest/security.test.js已实现这张表很有用后续如果规范变了比如“锁定 30 分钟”改成“锁定 15 分钟”你只需要定位到FR-3对应的代码和测试改起来非常快不用担心动了别的地方。5. 常见问题与排查技巧实录5.1 规范文件写好了AI 却不按规范写代码这是我被问得最多的问题。大多数人以为只要在系统提示词里写“请先读specs/目录下的规范”AI 就会照做但实际效果很多时候是AI 只是假装读了生成的代码还是自己发挥。解决办法有三层。第一层把规范路径明确写进对话不要用“项目中的所有规范”这种模糊说法而是指定到具体文件。第二层要求 AI 在动手前先输出“需求理解清单”把FR-1、FR-2等逐条列出并写出它将要如何实现。第三层最狠的一招在AGENTS.md里写强制要求“如果规范中定义了某个行为你必须严格按其实现如果你认为规范有问题不要擅自修改先停下来询问。”这看起来像一句废话但对 AI 的约束效果非常强。5.2 Skill 不生效或者找不到对应技能如果你发现 SuperPowers 已经克隆到本地了但 AI 在运行时报“找不到技能”大概率是路径问题。建议先确认你用的工具对技能目录的查找规则是什么。比如 Codex CLI 一般会读取某个固定的skills/路径如果你的仓库里也有同名目录可能会产生覆盖或冲突。还有一个容易忽略的点技能文件名和技能内部声明的名称要匹配。如果你创建一个task-breaking/SKILL.md但里面声明的技能名写成了task-splitting那 AI 可能按声明名找不到。遇到这种情况检查技能文件头部的前置元数据确保“名称”和“描述”写得准确且唯一。5.3 多个 Agent 协作时规范冲突怎么办我现在团队里会有几个 AI Agent 同时做不同模块最怕出现的情况就是一个 Agent 改了specs/capabilities/user-login/spec.md另一个 Agent 正在基于旧版本做代码实现两边就打架了。这个问题没有太高深的解法就是靠流程和版本管理。规范文件必须进 Git而且每个 Agent 在开始任务前都要git pull获取最新规范如果同一个规范文件被多个 Agent 同时修改一定要在合并时人工 review。我再建议一个小技巧每个功能模块的攻击范围尽量控制在单一的 capability 目录内不要把所有规范都塞进一个文件这样冲突概率会大幅降低。5.4 几个我自己踩过坑后的总结命名规范一定要稳定。我已经养成了一个习惯所有需求编号都存在 OpenSpec 的规范文件里代码注释、测试用例、提交信息里都复用这个编号。别在提交信息里写“fix login bug”而是写“fix FR-3: adjust account lock duration from 30min to 15min”。这样后续用git log就能直接追踪到规范变更。不要过度依赖 AI 自带的“记忆”。模型上下文再大也有窗口上限一次对话里如果既塞了规范、又塞了技能、又让 AI 实现一个完整模块它很可能做到后面开始丢前面内容。我的做法是一份规范文件对应一次任务任务开头和结尾都让 AI 重新确认需求编号宁多问几遍也不要让它自由飞。还有一个容易被忽略的点提示词里的“不要做某事”往往不如“必须做某事”有效。比如你与其说“不要跳过测试”不如说“在实现完成后必须运行npm test且确认通过你才能回复‘完成’”。把验收动作变成技能流程的一部分AI 执行的稳定率会高很多。最后再分享一点个人体会。SDD 加 OpenSpec 加 SuperPowers 这套组合不是拿来“炫技”的它最本质的价值是逼着人把“想清楚”这关过了。很多次我懒得写规范直接让 AI 开干结果都花了好几倍时间在改代码上。反而是多花十几分钟把规范写好、把验收条件列清楚整个开发过程会顺畅得让人上瘾。建议你可以先拿一个小功能试水跑通一遍六步流程慢慢形成肌肉记忆。等用顺手了你会发现 AI 编程这事真正的瓶颈不是模型能力而是你有没有给模型一套靠谱的“图纸”。