从第一次接触到“Spec 驱动开发”这个概念到现在我前后折腾了好几版工作流。早期直接人肉写测试写着写着就发现需求变了连测试也跟着推倒重来后来尝试先写设计文档但文档和代码距离太远维护着维护着就没人看了。直到把 OpenSpec 和 Superpowers 组合起来搭了一套 SDDTDD 的闭环我才真正体会到“先定行为、再写测试、最后落实现”这条路是能走通的。这篇文档我把整个搭建过程、每一步的取舍、实际跑通的案例以及踩过的坑都记录下来适合想把手头开发流程往规范化和自动化方向推进一步的团队或个人也适合刚接触 SDD、TDD 概念但不知道怎么落地的新手参考。1. 整体设计与核心思路为什么把 Spec 放在测试前面1.1 SDD 是什么它解决了什么问题SDDSpec-Driven Development按照字面理解就是“由规格说明书驱动的开发”。它不是让开发变成写文档而是把需求行为用结构化的 spec 文件固定下来让 spec 成为开发、测试、评审的共同参照物。我个人的理解是传统开发的痛点在于需求存在人的脑子里。产品说“用户要能改头像”开发脑子里想的是“上传文件、裁剪、保存 URL”测试心里想的是“图片太大要报错格式不对要提示”。三方默认一致但一旦某个环节理解偏差返工成本就来了。SDD 做的事情就是把“用户能改头像”拆解成一组可验证的行为描述例如用户上传合法图片后系统中保存新的头像地址用户上传超过 5MB 的图片系统返回错误提示用户上传非图片格式的文件系统拒绝保存。这些描述一旦放进 spec 文件它就变成了开发的输入和测试的基准。OpenSpec 正是围绕这个需求设计的一套规格文件管理工具它定义了 spec 的目录结构、格式约定和变更流程让团队不再靠口头对齐。1.2 TDD 的循环是什么为什么单独做容易卡住TDD 的经典循环是红-绿-重构先写一个会失败的测试再写最小实现让测试通过最后优化代码结构。这个循环理论上非常清晰但实际落地时经常卡在第一步——测试到底该测什么。我刚学 TDD 的时候遇到复杂业务就懵。比如“积分规则按会员等级打折”这句话本身不精确测试没法写。是打折后向下取整还是四舍五入会员等级变化后历史订单算不算这些不定义清楚让测试先行的开发者硬写测试最后只会写出一个“测了但没意义”的测试。SDD 其实是在给 TDD 补充前置条件先通过 spec 把行为边界逼出来再动手写测试。所以 SDD 和 TDD 不是二选一而是上下游关系。spec 回答“要做什么”测试回答“怎么证明做对了”最后由实现代码回答“怎么做到的”。1.3 OpenSpec 与 Superpowers 在流程中的分工把两个工具放在一起之后它们的角色非常清晰工具角色核心价值OpenSpec规格管理把需求变成结构化的 spec 文件提供变更、审阅、版本管理机制Superpowers开发辅助技能集在 Codex 等 AI 编程助手中注入可执行的开发流程读取 spec、生成测试、生成实现我习惯把 OpenSpec 理解为“需求与代码之间的契约层”而 Superpowers 是“执行层”。OpenSpec 告诉你应该做什么Superpowers 则具体指导 AI 助手按照流程一步步实现。两者一起用效果是你的 AI 编码工具不再是一次性聊天框而是变成一个知道流程、知道规范、知道怎么自己验活的工程助手。提示如果你只用 OpenSpec 不用 Superpowers你得到的是一个规格管理工具如果你只用 Superpowers 不用 OpenSpec你得到的是一个能力很强但方向感不足的编码助手。两者的组合才是完整闭环。2. 环境准备把工具装进日常工作流2.1 OpenSpec 的安装与项目初始化OpenSpec 的实际安装方式在不同版本里会有些差异但大体路径是一致的把它作为命令行工具安装到项目或全局环境中。以常见的 npm 生态为例一条命令就能完成npm install -g openspec安装完成后在项目根目录执行初始化命令openspec init这个命令会生成一个规则约定目录通常包括 specs 目录、变更记录文件以及配置文件。初始化之后项目里会多出一个 specs 文件夹专门用来存放按模块拆分的规格说明。如果你是团队协作可以把 specs 目录一起提交到 git 仓库。这样每次需求变更都能走代码评审流程而不是依赖某个人脑子里的记忆。2.2 通过 Codex CLI 安装 SuperpowersSuperpowers 是按技能包skill方式运行的最常见的载体是 Codex CLI。安装思路非常简单从技能仓库将 Superpowers 克隆或下载到本地技能目录然后让 Codex 在运行时能识别到它。以我实测过的方式为例假设你的 Codex 配置中已经指定了项目级目录~/.codex/skills那么安装步骤就是git clone https://github.com/your-superpowers-repo/superpowers ~/.codex/skills/superpowers克隆完成后建议做一次目录检查确认技能包内包含 skills 子目录和对应的说明文件。如果目录结构不对Codex 是识别不到的这是新手最容易踩的坑。2.3 验证工具是否协同工作装完之后不要急着写业务代码先验证两个工具是否真的协同。我的验证办法有两个第一个在项目里跑一次 OpenSpec 的变更创建命令生成一个最小 spec确认目录结构正常。openspec change new 2025-01-test-change第二个在 Codex 里直接向 Superpowers 提问例如“请基于当前项目的 spec 工作流指导我完成第一个变更”。如果 Superpowers 生效AI 会按照 skill 文件里定义的流程逐步响应而不是给一段通用回答。注意打开 Codex 时可以通过命令行直接指定说明文件来激活 Superpowers。如果发现 AI 回答完全忽略 spec 目录的存在多半是技能包没有加载成功优先检查路径、文件名和权限。3. 核心实操从空 spec 到测试通过的完整闭环3.1 一个规范化的 spec 文件长什么样OpenSpec 的 spec 文件不是自由散文而是有结构约定的。以我之前做过的“用户头像上传”功能为例新建的 change 目录下会包含一个 proposal.md 文件核心段落一般是## 变更原因 用户目前无法更换个人头像影响社区互动体验。 ## 行为变化 - 用户在个人信息页可点击上传头像图片 - 系统对图片大小、格式进行校验 - 校验通过后保存头像 URL 并展示。 ## 影响范围 - 用户模块 / profile 服务 - 个人信息前端页面这段内容看起来像需求文档但它的价值在于为后续测试提供输入。每一条行为变化都应该能映射到一个或多个测试用例。写 spec 时不要用“优化”“增强”这类模糊词而是写“当 A 场景发生时系统会 B”这样测试才写得出来。3.2 从 spec 到测试先让测试失败按 SDDTDD 的顺序spec 定稿之后立刻进入测试编写阶段。还是头像上传的场景对应的测试可以拆成三条test(用户上传小于5MB的合法图片返回头像URL); test(用户上传大于5MB的图片返回大小超限错误); test(用户上传非图片文件返回格式错误);在实现还没有写的时候这些测试会全部失败或者因为依赖的接口根本不存在而报编译错误。这个阶段失败是对的它能证明测试真的在验证行为。很多团队忽略这一步直接用 AI 生成代码结果出现“测试全部通过但功能根本不完整”的情况就是缺少了红-绿-重构里的红。3.3 用 Superpowers 引导生成实现代码测试写好之后让 Superpowers 参与进来。Superpowers 的能力不是帮你写一大段代码而是按 skill 中所定义的流程指导 AI 助手读懂 spec、运行测试、修改实现、再次运行测试循环往复直到目标行为全部可验证。用 Codex CLI 时我会先输出一条指令例如codex 请加载 superpowers 技能依据 specs/2025-01-test-change/proposal.md 中描述的行为变化在 tests 目录中补齐失败测试的对应实现并运行测试直到通过这时候 Superpowers 会引导 Codex 进入“先看测试失败再改代码”的循环而不是直接甩出一整段实现。它能减少一种很常见的失控现象AI 一次性生成大段代码结果把不相关的模块也改了。从实操效果来说网络上的相关热词里有很多人搜“superpowers 如何使用”说明很多人卡在这一步。我的建议是不要指望 Superpowers 替你做设计决策它的价值在于让 AI 帮手的行为更规范、更有章法。3.4 把 SDDTDD 跑成一个固定循环当单个变更跑通之后要把它固化成团队日常流程。运行循环的节奏我在团队里落地成了四步产品需求产生后先写 change 的 spec 文件并提交评审spec 评审通过根据行为变化编写测试用例跑红使用 Superpowers 在 Codex 中实现代码直到测试全绿并完成 code review测试全绿后回到 OpenSpec 执行变更完成指令让这次 spec 变更归档。这四步跑顺之后开发节奏从“需求会议-开发-吵架”变成了“写规格-写测试-补实现-归档”每次需求变更都有据可查。4. 完整案例为用户配置模块落地 SDDTDD 工作流4.1 需求拆解与 spec 编写下面用一个更完整的例子过一遍全流程。假设我们有一个 Web 应用需要增加一个用户配置模块核心功能是允许用户修改自己的昵称并校验昵称是否合法。我先用 OpenSpec 创建变更openspec change new user-profile-nickname然后编写 proposal.md把行为写细## 变更原因 用户希望修改个人昵称目前系统不支持。 ## 行为变化 - 用户可在设置页输入新昵称并提交 - 昵称长度为 2 到 20 个字符超过或不足时提交失败 - 昵称不可包含特殊符号仅允许中英文、数字、下划线 - 修改成功后页面展示新昵称并同步到用户信息接口。 ## 影响范围 - user profile 领域模型 - 用户设置接口 - 前端设置页不要小看这种逐条列举它直接决定后面的测试数量。如果这一阶段不写清楚“长度 2 到 20”后面的测试就是拍脑袋。4.2 测试先行与实现生成根据上面的行为变化我设计了四组测试用例测试场景输入预期结果合法昵称“新的昵称”修改成功返回 true昵称过短“a”返回长度错误昵称过长长度为 21 的字符串返回长度错误非法字符“你好”返回格式错误测试写好之后第一次运行全部失败。原因很简单接口还不存在。此时请 Superpowers 介入我在 Codex 里会让 AI 实现updateNickname函数并且明确要求它“在实现过程中运行测试直到所有测试通过”。Superpowers 的 skill 在这中间起到的作用是节点控制。没有它Codex 可能把校验逻辑写在接口层之外的另一处或者尝试重构整个项目有了它AI 会按 skill 描述的步骤一步步走先读 spec再读测试再定位实现位置。4.3 回归验证与变更归档所有测试通过之后不要急着开始下一个需求回到 OpenSpec 完成变更openspec change complete user-profile-nickname这一步会把当前变更合并进项目的规格基线。以后如果有人问“昵称长度到底是多少”直接查 specs 基线文件就行不用翻聊天记录。实测下来一次干净的变更大概在 20 分钟到 1 小时之间具体取决于复杂程度。和之前没有规范时相比最大的差别是任何时候中断都能恢复打开 specs 目录就知道做到哪一步了。5. 常见问题与排查技巧实录5.1 Superpowers 技能包没有被加载怎么办这是出现频率最高的问题症状是你在 Codex 里怎么喊 Superpowers 都没反应AI 的回复和平时完全一样。排查顺序按下面三条来检查技能包目录是否在 Codex 配置的加载路径下检查 skill 描述文件是否存在且格式正确尝试在 Codex 中直接询问“可用的技能列表”看它是否列出 Superpowers。有几次我以为是技能没装好结果只是目录层级套深了一层。技能仓库解压出来通常会有一层 GitHub 风格的文件夹用户要找到superpowers根目录把它整个放到 skill 目录里而不是再包一层。5.2 spec 写得太粗导致生成代码跑偏AI 生成代码跑偏几乎都是 spec 没有约束到位。举一个实际例子我让 AI 实现一个“搜索”按钮但 spec 里没写清搜索是前端过滤还是后端查询结果 AI 在两个方案之间来回摇摆最后生成了一版刷新页面的伪实现。解决的办法只有一条把粒度细化到“行为可观察”。你写“当用户点击搜索按钮后列表区域展示与关键词匹配的结果”比写“支持搜索功能”要可靠得多。这条技巧同样适用于人有团队协作——spec 越细评审越容易发现问题。5.3 测试全绿但对需求理解错了怎么办这是一个隐蔽问题。测试全绿不代表需求做对了。比如需求是“用户上传头像后裁剪为正方形”你写成“保存原图并压缩比例”测试当然能动但结果和产品预期完全不同。我的做法是在 spec 评审时加上验收场景的复核对每一条行为变化问一句“用户能从界面上观察到什么变化”。如果这句话说不出来说明 spec 本身有问题。有几次我宁可推迟编码时间也要先把这条拧清楚否则后续返工成本更高。5.4 团队协作时 spec 与代码的同步节奏多人协作时容易出现的乱象是 spec 已经更新到第三版代码还在按第一版实现。如果项目使用 git我建议把 spec 目录纳入 code review 范围不允许绕过 code review 直接改规格。规格变更相当于需求变更线上偷偷改版本一定会出事故。另外可以借助 Codex 和 Superpowers 的能力在实现代码时让它输出一份与原始 spec 的映射说明。哪个测试对应哪个行为变化实现改动了哪些文件都可以作为 review 时的对照材料。我们团队这么跑了几周之后评审效率明显提升因为不用每个人从头读一次代码了。6. 把工作流扩展到自己项目里的几个建议如果你之前完全没有接触过 SDD不要一上来就把所有模块都要求写 spec那样团队会直接反抗。我建议先选一个边界清晰、改动频繁的小模块做试点比如用户配置、偏好设置或导出功能跑通一轮完整闭环让大家看到收益后再逐步铺开。Superpowers 不是银弹它是一个流程增强工具。关键是背后的流程本身要合理。我在实际使用中最大的体会是这一套工作流最大的价值不是自动化而是它逼着你在写代码之前先想清楚行为边界。很多代码写不下去根本原因是需求没有描述到行为粒度和工具没关系。最后分享一个小技巧。在 OpenSpec 的 change 目录里保存一些成功的 spec 作为模板。下次写新 spec 时直接参考已经通过评审的写法比从空白文档开始要快得多也能保持团队风格一致。我在连续写了十几个 change 之后已经能在一杯咖啡的时间内完成一个中大型功能的规格初稿。这种手感光看工具文档是练不出来的。