最近我把 OpenSpec 和 Superpowers 拼在一起搭了一套从需求到测试闭环的 AI 辅助开发工作流。跑了几个实际迭代之后最大的感受是以前让 AI 写代码像碰运气现在至少每一步都有依据——先有规格再有测试最后才有实现。这篇文章就把整套流程拆开讲清楚包括怎么做、怎么搭、有哪些坎。如果你正在用 Claude Code、Codex 或 Cursor 这类 AI 编程工具写代码并且已经受够了 AI 随手改需求、测试写不完整、代码改完没反馈这些问题这套 OpenSpec Superpowers 的组合应该能帮你省下不少力气。1. 这套工作流到底解决了什么问题1.1 OpenSpec 和 Superpowers 各管哪一段先说 OpenSpec。它是一套面向 AI 辅助开发的轻量级规格管理约定核心思路是把模糊的需求拆成两套 Markdown 文件一类是“能力规格”描述系统应该具备的稳定能力另一类是“变更提案”描述一次迭代里要改什么、验收标准是什么。这些文件直接放在代码仓库里和代码一起走版本管理。这样做的价值在于AI 编程助手在动手之前能看到一份结构化的“做什么”的说明而不是靠上下文里的几句零散对话猜测需求。OpenSpec 解决的是“需求漂移”问题让产研说话有了一个共同参考基线。Superpowers 这边是一组可以被 AI 编程助手直接调用的技能包里面封装了 TDD测试驱动开发、代码审查、任务拆解等标准工作流。它解决的是“怎么写才对”的问题。比如你启动一个 TDD 技能它就会按“先写失败测试 → 跑出红色 → 写最小实现 → 跑绿 → 重构”的节奏推进而不是一上来就甩出一大坨代码。所以两者其实是上下楼的关系OpenSpec 管需求层Superpowers 管编码层。OpenSpec 回答“我们要做什么、怎么验收”Superpowers 回答“代码怎么写才能持续满足验收条件”。两个一接上就形成了 SDDSpec-Driven Development规格驱动开发与 TDDTest-Driven Development测试驱动开发的完整闭环。1.2 为什么 SDD 和 TDD 一定要绑在一起过去我单独用 TDD 时最常见的困境是测试能跑绿但测试本身可能测错了方向。比如产品要的是一个“登录失败后锁定账号”的功能开发按自己的理解写了一个“连续输错三次就锁定”的测试代码也通过了测试但产品其实想要的是“连续输错五次且当天晚上十二点重置”。这种偏差靠 TDD 自己是发现不了的。单独用 SDD 也有问题。规格写得很漂亮但落到代码时AI 可能忽略了入口边界、异常分支或者把验收标准当成参考而不是硬性条件。文档是人写的代码是机器跑的二者之间缺一道强制校验的桥梁。把 OpenSpec 和 Superpowers 连起来之后这道桥梁就出现了。OpenSpec 里的验收标准会被翻译成可执行的测试用例Superpowers 再把“先写测试再写实现”的纪律注入给 AI。这样需求到代码的每一步都有迹可循。AI 不会因为上下文遗漏而跳过反例也不会凭空脑补一个不存在的需求。这套工作流尤其适合需求频繁变动、但又希望每一步都稳住的质量敏感型项目。不管是个人维护的开源库、创业公司的 MVP还是企业内部的中后台系统都能直接套用。如果你的项目本身就还在疯狂探索阶段需求天天推翻重来那建议先别急着上整套流程否则维护规格文件的成本可能会让你怀疑人生。1.3 整套流程的工作模式我把这套工作流跑顺之后日常开发节奏基本是这样的从 OpenSpec 新建一份变更提案描述清楚要做什么和怎么验收。让 Superpowers 里的 planning 技能把这个提案拆成行动步骤。启动 TDD 技能按红绿循环逐步实现。每完成一个步骤回到 OpenSpec 更新状态标记哪些验收标准已经满足。全部跑完后用代码审查技能做一次最终检查。这样一个闭环走下来AI 不会在中途“跑偏”因为每一步都有当前阶段的上下文和检查点。遇到需求变更也只需要改 OpenSpec 的变更提案再重新驱动 TDD 循环而不是人肉去翻代码找逻辑散落点。2. 环境准备把两个工具装进开发环境2.1 基础环境检查在装 OpenSpec 和 Superpowers 之前我先确认了本地环境里这几样东西是齐全的一个支持 skill 机制的 AI 编程助手我用的是 Claude CodeCodex CLI 和 Cursor 也能跑这套流程后面会专门说差异。Git因为 OpenSpec 文件需要在 Git 仓库里管理。Node.js 和 Python。OpenSpec 本身的命令不强制要求但后续跑测试或者写脚本时会用到。如果你已经装了 AI CLI 工具可以先执行--version确认版本足够新。skill 机制是最近几个版本才稳的老版本可能识别不了目录结构。2.2 安装 OpenSpec 并初始化规格库OpenSpec 的安装方式因发布渠道而异。我用的版本是一个命令行工具Mac 上可以直接通过 Homebrew 安装其他平台可以从 GitHub Releases 下载二进制文件后放到 PATH 目录里。你在终端里输入openspec --help如果能看到命令列表说明安装成功。不同版本的命令名会有一点差异有的版本是openspec有的可能需要加一个子命令前缀但这都不重要关键是先把可执行文件跑起来。初始化工具有两种玩法。一种是在空仓库里执行初始化生成标准的规格目录另一种是在已有项目里手动创建规格目录。我建议用初始化命令它会帮你生成目录骨架和示例文件省得自己记忆结构。初始化完成后的目录一般长这样spec/ capabilities/ auth/ spec.md changes/ 2025-01-15-add-login-lock.mdcapabilities下放的是稳定能力规格changes下放的是当前迭代的变更提案。这套结构的好处是历史记录和当前需求分离方便回溯。2.3 安装 Superpowers 技能包Superpowers 的安装相对简单因为它本质是一个 skills 目录。从 GitHub 上把仓库克隆下来然后放到对应 AI 工具的 skills 路径下即可。以 Claude Code 为例git clone https://github.com/your-superpowers-repo.git mkdir -p ~/.claude/skills cp -r superpowers ~/.claude/skills/如果你是 Codex CLI路径一般是~/.codex/skills/。如果在 Cursor 里用通常放在当前项目的.cursor/skills/目录下这样只对当前仓库生效。注意不同工具的 skill 加载方式不完全一样。部分工具需要在配置文件里显式声明允许哪个目录的 skill而不是放进去就能直接用。我遇到过几次“明明放好了但 AI 不认”的情况基本都是配置文件没更新。装好后重启 AI 会话然后在对话里问一句“你有没有 superpowers 相关的 skill 可以调用”如果 AI 回答得上来就说明加载成功了。2.4 两个工具如何配合工作环境装好之后还要想清楚两者的协作方式。我的做法是在 AI 的工作记忆里把 OpenSpec 的规格目录作为“需求事实源”把 Superpowers 作为“操作规范”。具体落地时我会在项目根目录放一个CLAUDE.md或AGENTS.md里面写明需求变更前必须先从 OpenSpec 新建变更提案。代码必须遵循 TDD 循环由 Superpowers 的 TDD 技能驱动。提交代码前必须对照 OpenSpec 验收标准自查。这样 AI 在每次对话开始都会自动加载这些规则不需要我在每次对话里重复叮嘱。3. 实操案例做一个带过期时间的本地缓存理论讲了这么多还是用一个具体需求把整条链路走一遍。我选的例子是一个带过期时间的本地缓存写入一个 key-value可以指定存活时间读的时候如果已过期自动返回空并删除。3.1 用 OpenSpec 定义需求规格首先在终端里新建一个变更提案openspec new change add-ttl-cache这个命令会生成一个 Markdown 文件里面预置了“背景、变更内容、验收标准”几个小节。我按实际需求填了进去。背景是“当前项目中多个模块都要缓存临时数据但没有统一封装导致内存不断增长”。变更内容是“新增一个TtlCache类支持 set/get/delete 操作每个 key 可设置过期时间”。验收标准我写了五条每一条都是可以机械判断的写入一个 key设置过期时间为 1 秒1 秒后读取应返回 null。未过期的 key 读取应返回原值。过期 key 被读取后应从存储中删除。构造时如果传入默认过期时间set 时不传过期时间则使用默认值。所有操作都是线程安全的。写验收标准时我的原则是能写“应返回 null”就不写“应该能正常判断过期”。越机械后面转测试用例越省事。3.2 让 Superpowers 进入 TDD 循环提案写完后我回到 AI 助手对话里让它激活 Superpowers 的 planning skill 拆解任务。AI 很快把工作分成了三步定义接口、实现过期判断、封装线程安全。接下来切换到 TDD skill。第一次运行 TDD 循环AI 先问我“你希望先写哪个验收标准对应的测试”我选了第一条。于是 AI 先写出了这样一个测试用例def test_expired_key_returns_none(): cache TtlCache(default_ttl1) cache.set(name, tom) time.sleep(1.2) assert cache.get(name) is None然后运行测试结果当然是红色——因为TtlCache类还不存在。这一步是整个 TDD 流程里最容易忽略的一定要先看到失败。我看到不少人在这种情况下直接让 AI “顺便”把类和测试一起写出来这等于把 TDD 变成了“写测试写实现”丢失了“让失败驱动最小实现”的意义。看到红色之后AI 才开始写最小实现目标仅仅是通过这个失败测试。于是它创建了一个简单的类内部用一个字典存数据set 时记录写入时间get 时判断是否过期。测试再跑绿色。接着进入下一轮循环。3.3 逐步实现所有验收标准同一套流程继续跑剩下四条验收标准。每跑完一条测试文件就会多一个或多个用例实现文件也越来越完整。到第四条的时候遇到了一个边界问题默认过期时间怎么处理如果 set 时不传过期时间应该回退到构造时的默认值如果构造时也没有默认值那这个 key 永不过期。这个边界在 OpenSpec 提案里没有写明确。AI 在 TDD 循环里停下来问我“要不要把这条规则写进规格”这正是这套工作流比较舒服的地方。我改了一下提案把验收标准补充为“构造时未提供默认过期时间则 set 时不传过期时间视为永不过期”然后 AI 继续推进。最后的线程安全我用threading.Lock实现锁的粒度控制在最小范围只在读写字典的时候加锁过期判断也放在锁内避免竞态条件。实现完成后整份测试文件从 1 个用例增长到了 7 个用例覆盖了正常读写、过期读取、默认过期、删除、并发安全五个维度。3.4 把需求变化同步回 OpenSpec写完实现后我再回到 OpenSpec 提案文件里把每个验收标准后面的状态从pending改成done。如果后续想撤销某个行为直接看 history 就能找出当时为什么这么设计。这个过程不需要修改代码里的注释因为规格文件就在代码仓库里评审的人能直接对照。这也是我认为 OpenSpec 最有价值的地方它让需求和代码之间的“空间距离”消失了。以前需求文档在 Confluence 里代码在 GitLab 里现在两者在同一个仓库提交 PR 时可以直接引用规格文件的链接。4. 实操中遇到的坑与排查实录4.1 常见问题速查表我把这套工作流推给团队里几个同事之后大家踩过的问题我整理成了一张速查表。现象可能原因处理办法openspec命令找不到二进制没加到 PATH检查安装目录重新添加 PATH 并重启终端AI 不调用 Superpowers 技能skills 目录没放对位置确认当前工具的 skill 路径并查看配置文件是否允许TDD 循环没有先写测试上下文里没有明确规则在项目根目录的AGENTS.md里写明必须使用 TDD skill测试污染导致随机失败测试之间共享了全局状态每个测试前都创建独立的TtlCache实例OpenSpec 文件变更后 AI 不知道没有在对话里重新加载文件用spec/xxx.md显式引用或先让 AI 读一遍变更提案规格验收标准太口语化无法转换成可运行测试改成“给定...当...则...”的句式让动词可执行4.2 我的三个调优建议第一OpenSpec 的变更提案尽量做到原子化。有一次我图省事把一个“加缓存”和一个“改日志格式”的需求写在同一个提案里结果 TDD 循环做了一半才发现这两个需求完全无关测试也要分开写。后面我强制规定一个变更提案只解决一个痛点即使提交流程繁琐一点也比后期拆代码轻松得多。第二Superpowers 的 TDD 技能不是银弹。它本质上是一套外部 prompt 驱动的行为准则如果 AI 的上下文窗口太满了部分规则可能会被遗忘。我通常会在做完两个循环之后主动说一句“继续按 TDD 技能推进”相当于手动提醒一次。第三不要把 OpenSpec 文件写成一篇文章要写成一张检查表。我见过有人把背景写了一大段验收标准只有一句“系统应能正常工作”那这套流程等于没搭。好的验收标准是执行测试时能直接复制粘贴校验条件的语言。就像我给缓存案例写的每个标准都有明确输入、行为、预期输出。4.3 遇到的最隐蔽的问题测试先红还是先绿这篇值得单独拿出来说。在 TDD 流程里第一步写出的测试必须运行并失败这个失败最好是因为“功能缺失”或“断言不通过”而不是因为测试代码本身有语法错误。如果你看到红色是因为ImportError或者NameError说明测试还没进入真正的行为验证阶段直接进入实现会让这个循环质量打折扣。我最初让 AI 跑第一轮循环时它就犯过这个错误测试文件里from ttl_cache import TtlCache但实现文件还没建自然导入失败。AI 把红色结果视为“测试通过前的准备阶段”直接补了一个空模块然后测试还是因为断言失败变红。这样虽然也红了但红色来自断言而不是导入错误才算有效。后来我要求 AI 必须把失败原因解释清楚确认是断言失败后才开始写实现整个流程就规范多了。5. 扩展这套工作流还能往哪走现在已经把 OpenSpec Superpowers 跑成日常开发标配我还在尝试几个扩展方向。一个是把 OpenSpec 变更提案和 CI 流程打通在合并 PR 前自动检查规格文件里的验收标准是否都有对应的测试用例覆盖。目前是人工对照检查后续想写成一个小脚本从changes/里解析验收标准再从测试目录里匹配关键词。另一个是让 Superpowers 的 planning skill 在任务拆解阶段更贴近 OpenSpec 的“能力规格”也就是先识别这个改动会不会影响已有的稳定能力。比如本地缓存案例如果放在一个大项目里新增能力时可能要同时考虑是否修改capabilities/cache/spec.md的通用描述。这样能力规格不会随着迭代腐烂。如果你已经在用 AI 编程工具但还没试过这套组合我的建议是从一个小功能开始不要一上来就重构整个项目。先建一份 OpenSpec 变更提案再加载一个 TDD skill走通一次完整的“规格 → 测试 → 实现”闭环。等你习惯了这种节奏再回头看以前那种直接让 AI “帮我写个 XX”的开发方式大概率会觉得太没底了。这套流程真正改变的不是速度而是每一步都有的安全感。