最近几个月我把团队里AI辅助编码的工作流做了一次大手术。从一个让Claude Code随便写写、我再花一小时review的状态切换成现在的固定动作brainstorm 澄清 - 写计划 - TDD 红绿循环 - 代码审查。这套流程的核心驱动不是某个IDE插件也不是再套一层Agent而是开源项目 Superpowers 提供的一套 skills 工作流。它原本是给 Claude Code 用的现在 Codex 和 OpenCode 也能接入等于把同一个方法论平移到不同的 AI 终端上。先说说背景。团队里有几条交付线都在用 Claude Code 写业务代码省是真省但坑也是真坑。最典型的三个场景第一需求一句话就开干写完发现和预期完全不是一个东西第二AI 从来不主动写测试你问它测了吗它答跑了没问题然后过两天线上冒出一个边界case第三为了修一个小bugAI顺手改了三处无关代码review的时候看着 diff 一脸懵。这类情况多了之后我逐渐意识到问题不在模型能力而在工作流的缺失。Superpowers 的价值就是把这个缺失补上。如果你也在用 Claude Code、Codex 或 OpenCode 写代码被写得快但不敢交付折磨过这篇文章就是给你准备的。下文会把 Superpowers 的原理、三端接入方式、从需求澄清到代码审查的完整链路以及我踩过的坑全部讲一遍。建议按顺序读第4章的实战复盘和第5章的问题速查表可以直接当手册用。1. 为什么需要SuperpowersVibe Coding的失控与Workflow的回归1.1 Vibe Coding最让人头疼的三个场景先说第一个场景需求只有一句话。之前有个需求给文件上传加个进度提示Claude Code 二话不说开始写前端、后端、数据库表都动了。review 的时候发现它把上传组件整个重写了接口路径也改了。项目里没人要求过这些改动纯粹是模型在自由发挥。这就是 vibe coding 最典型的失控——你把一个模糊意图丢给AI它敢在没人确认的情况下帮你做了所有决定。第二个场景测试缺失。有一次我让 Claude Code 写一个时间区间工具函数结果它写了 80 行实现测试一个没有。我追问测试呢它才补了两个 happy path。而我担心的是跨时区、夏令时、边界值这些角度的覆盖它压根没想过。不是说AI没有能力写测试而是默认流程里没有测试先行这个环节它就不会主动加。这事儿你靠 prompt 提醒一次管一次工作流不管下次照样忘。第三个场景回归破坏。有个内部服务某天 Claude Code 修了一个 NullPointerException顺带把缓存模块的默认过期时间从 300 秒改成了 60 秒。它在会话里说过这个改动但当时我在看别的任务没注意到。这事件让我意识到AI 会话中的每句话你都盯就是拿人肉审计去对抗工具效率成本不可持续。解决方向只有一个把工程实践固化到 AI 的执行流程里让约束而不是人肉来兜底。1.2 Superpowers到底是什么Superpowers 不是 IDE 插件也不是另一个跑在 Agent 上层的 Agent。它本质上是一个开源的AI 编码技能包仓库里面是一批 Markdown 格式的 skill 文件每个 skill 定义了一个工作流环节的规则、步骤、输出格式。AI 通过读取这些 skill 文件就知道在某个阶段应该怎么做、产出什么、禁止做什么。打个比方传统用法是你给一个聪明但没经验的新人下了一句指令把这个支付页面写了然后他自由发挥。Superpowers 的用法是你给这个新人一本《团队开发军规》要求他先读需求澄清章节在动键盘之前问你五个问题然后读计划章节把任务拆到 10 分钟一个颗粒度再读TDD章节必须先写失败的测试再写实现最后还要走代码审查章节叫一个同事来对拍。这套军规不是一个 10 万字的 prompt 塞进去的而是按需加载的。AI 在会话开始只读一个 AGENTS.md 入口文件里面写了遇到XX场景就调用XX skill。真正干活时模型再去读取对应的 skill 文件。这样做的好处有两个第一省 token上下文不会被一堆规则占满第二可维护你想改某个环节的规则只改一个文件就行不用重写整段系统提示词。1.3 为什么是TDD而不是先写代码再补测试Superpowers 把 TDD 作为默认开发路径这一点我有过犹豫。毕竟让 AI 写测试再写实现看起来多了一步时间成本更高。但实际跑下来这条路径反而更省。原因在于TDD 的红灯阶段给 AI 划定了一个明确的验收边界模型在写实现时不是猜你要什么而是朝着一个已经被测试定义好的行为去凑边界条件不会轻易漏。先写功能AI 大概率会把主流程写完边界 case 靠运气但你先让它写测试它为了测试通过必须考虑空输入、超时、异常类型、重复调用这些细节。这是写测试这个动作本身带来的强制思考。我的类比是先写测试相当于施工前先立承重墙的垂直度标准而不是楼盖完了再拿尺子量。后者不是不能测而是测出来的问题改起来代价大得多。2. 安装与三端配置Claude Code / Codex / OpenCode 一次配齐2.1 获取Superpowers安装方式不复杂。在自己电脑上建一个目录直接从 GitHub 把项目 clone 下来。Mac/Linux 都支持。拿到手后你看到的是一堆 Markdown 和脚本核心的东西有两个AGENTS.md和skills/目录。AGENTS.md 是入口skills 目录里按主题放着一批 skill。每个 skill 是一个文件夹里面有一个SKILL.md作为该技能的主文件。提示不要在系统的全局目录里直接改建议把 Superpowers 克隆成一个独立目录然后在项目里引用。这样升级项目时不会污染你自己的全局配置也方便团队多人共用同一份基线。2.2 Claude Code 配置Claude Code 原生支持 skills 机制。具体操作是把 skills 目录链接到 Claude Code 能扫描到的位置。我用的方式是在项目的.claude/skills/下面建软链接指向 Superpowers 克隆目录里的各 skill 文件夹。再把 Superpowers 根目录里的 AGENTS.md 内容合并到项目根目录的 AGENTS.md或者在项目 AGENTS.md 里写一句superpowers/AGENTS.md如果 Claude Code 支持 import 语法——不同版本支持程度不同最稳的办法是直接把内容复制进去。验证是否生效在 Claude Code 会话里输入list skills或者直接问你有哪些 skills。能看到 brainstorm、writing-plans、tdd、code-review 等条目就说明加载成功。如果看不到先检查目录结构再重启会话。Claude Code 对技能的扫描主要发生在会话启动时中途改了文件不重启大概率不生效。2.3 Codex 配置Codex 也读 AGENTS.md并且支持类似 skills 的目录。通常把 skills 放到~/.codex/skills/或者项目下的.codex/skills/然后在 AGENTS.md 里声明。和 Claude Code 的差异在于Codex 对自我反思式指令的响应方式略有不同。我在实测中感觉Codex 更吃显式步骤所以在 AGENTS.md 里建议把流程写得比 Claude Code 那边更死板一点明确要求每次开始任务前必须读取 skills/tdd/SKILL.md。另外Codex 可以配自定义模型当后端比如通过 API 配置接 DeepSeek 或其他兼容端点来跑。这类用法适合团队统一供应模型的场景切换时不用改代码只改 endpoint 和 key 就行。2.4 OpenCode 配置OpenCode 现在分老版本Ts 版和新版 Opencode V2Go 重写版。如果你用的是 V2配置放在opencode.json里再在项目目录下建.opencode/skills/放 skill 文件。配置逻辑类似在 AGENTS.md 或 opencode 的自定义指令中声明加载入口。另一个实用技巧cc-switch 这个开源工具可以统一管理多套 API 配置Claude Code、Codex、OpenCode 三者的 endpoint 和 key 都可以集中维护。遇到标题里那个cc switch local proxy failed的报错时优先检查 cc-switch 的配置项本地服务端口是否被占用、填写的 API base URL 是否以/v1结尾、key 是否有效。这类报错 90% 都是配置拼接不一致拆开排查很快能定位。2.5 三端能力对比工具skills 目录入口文件数据流特点适合场景Claude Code.claude/skills/AGENTS.md原生支持 skills加载稳定日常主力、长会话复杂开发Codex.codex/skills/AGENTS.md官方支持目录但部分版本解析较弱和 OpenAI 生态打通OpenCode V2.opencode/skills/opencode.json AGENTS.mdGo 重写后配置更灵活轻量、跨提供商切换这个表不是让你选一个用而是让你理解同一套 skill 在不同环境下怎么落地。我个人的建议如果只是个人写脚本选你装得最熟的那个如果是做交付项目把 Claude Code 和 Codex 都接上用同一套 skills方便以后在 A 家模型忙或挂的时候切到 B 家不中断流程。配置陷阱再多说一句。Claude Code 在某些地区会提示 might not be available in your country这个提示通常意味着你的账号或网络环境不在官方支持范围内。处理方式很简单自查没有灰色通道可走唯一正解是使用官方支持地区的账号或者把模型调用切换到你所在地区允许使用的提供商如通过 API 配置用 DeepSeek 等可用模型跑 Codex 命令行。OpenCode 的 free tier 也类似提示 only be used from within opencode意思是免费额度只能在 OpenCode 官方应用内部使用你想用 CLI 或外部工具调用就必须配置自己的 provider key。没配置就报错配置好就行。3. 核心工作流拆解从需求澄清到代码审查3.1 需求澄清把模糊想法变成可测试的行为Superpowers 的 brainstorm skill 并不是让你和 AI 聊人生它是一套结构化的质询流程。AI 接到需求后第一反应不是动手而是按 skill 里的规则向你提问。问题范围一般包括这个功能的真正目标是什么、用户是谁、边缘场景有哪些、现有系统里有没有相似逻辑、失败时怎么办、性能和量级要求如何。这一环节可能是整个流程里最反直觉的——看起来最耽误时间实际最能省时间。我举一个实际任务某天同事说给我们服务加个带超时的重试机制。如果按 vibe coding 走AI 会直接写一个retry装饰器出来参数就 timeout、retries 两个。但走 brainstorm 流程时AI 会追着问重试是针对网络超时还是所有异常TimeoutError和ConnectionError要不要区分线程安全要不要保证重试间隔是固定还是指数退避要不要带 jitter失败日志打到哪里这些问题的答案直接决定了函数签名、内部状态和测试用例比后面改 10 版代码便宜多了。这一环节的输出不是文档是一个被确认过的用户故事加一张已完成/未完成的定义清单。比如作为调用方我希望重试装饰器在网络抖动时自动重试最多 3 次并在退避间隔上做指数加抖动且过程中不吞掉非目标异常。完成标准目标异常重试 3 次、非目标异常立即抛出、等待时间符合退避公式、支持超时取消。3.2 写计划把需求拆成AI能独立执行的最小任务需求澄清之后进入 writing-plans。AI 会把上面的用户故事切成若干任务每个任务的粒度控制在一个10 到 15 分钟能实现的单元里。切分逻辑通常是先定义数据结构或接口再实现核心逻辑再补异常分支最后做文档和测试补充。每个任务包含三样东西目标、测试用例清单、实现要点。任务之间尽量不互相依赖这样即使 AI 在某个任务上跑了很久也不会把整个会话卡死。计划写完会生成一个 plan.md 文件AI 会把它贴出来让你确认。这个确认环节是审批闸门你必须看一遍觉得任务拆得不对就点一下让 AI 重拆直到你觉得这每一步我都能验收为止。很多人会在这儿偷懒跳过计划直接进代码结果就是后面 AI 经常写着写着忘了需求又要回头澄清。花 10 分钟读计划省 40 分钟 debug这笔账很划算。3.3 TDD红绿循环核心中的核心TDD skill 是 Superpowers 的重头戏。读了这个 skill 之后AI 的执行顺序会被强制改成这样红灯针对当前任务先写一个或多个测试运行看到失败。绿灯写最小实现代码让测试通过。重构在不改变行为的条件下优化实现保持测试全绿。重复直到完成当前任务。我观察到AI 一旦被 TDD skill 约束输出行为会发生两个明显变化。第一它写实现之前真的会先写测试不再跳过。第二它的实现会收敛不再自由发挥因为测试定义好了边界和输入输出它能扩展的空间变小了。这两个变化直接解决了前面说的没有测试意识、实现不可控的问题。这里有一个值得展开的点测试的质量。TDD 绝不是写两个断言能过就算绿。Superpowers 的 skill 里要求测试必须覆盖正常路径、边界路径、异常路径三条缺一不可。有种反面教材是 AI 写了一个只验证函数返回了东西的弱测试实现返回 None 也照样通过。这等于没有测试。所以我在用的时候会在 review 阶段专门检查测试断言强度后面第 4 章会给出实测案例。TDD 的时间配比我给个参考表这是我在团队里跑了两周之后定下来的。任务预计实现时长写测试红灯最小实现绿灯重构优化合计10 分钟3 分钟4 分钟3 分钟10 分钟30 分钟8 分钟14 分钟8 分钟30 分钟1 小时18 分钟27 分钟15 分钟60 分钟2 小时以上25% 时间40% 时间35% 时间按比例注意这个表不是算术题它是一个注意力分配提醒。经验是实现越复杂测试投入占比应该越高实现越简单重构占比反而可以拉高因为快速写出的代码往往有明显的可读性提升空间。3.4 代码审查让另一双眼睛盯着实现代码审查环节我刚开始没太在意后来发现这是整个流程里最能薅羊毛的部分。Superpowers 的 code-review skill 会让 AI 以另一个角色而不是代码作者的身份去读实现。怎么做到最简单的办法是让 AI 把当前会话的 diff 和测试文件作为输入然后按一套 checklist 去审。审查维度包括有没有隐藏的 bug、有没有安全问题、边界条件处理是否完整、命名是否表意、测试是否真的在测试行为而非实现细节、有没有死代码或多余的依赖。这里最微妙的一点是防止自己审自己的盲区。同一个 AI 写的代码同一个 AI 再审查很容易得出没问题的结论。我的破解办法是审查阶段用不同配置跑。比如 Claude Code 主写、Codex 做审查或者同一个 CLI 里用思考模式更强的长上下文跑一遍 review。两种方式我都试过都能比作者自审多发现 2 到 3 个真实问题。这些问题的典型类别是异常处理遗漏比如注册了KeyboardInterrupt却漏了SystemExit、边界条件悬空比如负数、空列表、并发环境下共享状态没保护。4. 实战复盘用Superpowers开发一个重试装饰器4.1 任务背景与需求澄清过程这个例子就是第 3 章提到的带超时的重试装饰器。任务背景是一个内部 Python 服务调用外部 HTTP API 时经常因为网络抖动失败需要加重试。我们直接走 Superpowers 流程。第一步需求澄清AI 没有直接写代码而是先抛了一串问题过来重试范围是对所有异常重试还是只针对网络层异常如ConnectionError、TimeoutError超时定义是单个调用超时取消还是整个重试过程中的总时长上限退避策略固定间隔、线性、指数、指数加随机抖动调用方签名装饰器是纯参数配置还是要支持传入自定义判断函数日志失败时要不要记录每条异常的类型和重试次数我们确认的结果是只重试网络类异常单个调用用timeout参数控制总时长用total_timeout控制退避用指数加 jitter装饰器签名上支持retry_exc自定义异常元组。这个确认过程大约花了 6 分钟但正是这 6 分钟避免了后面最昂贵的返工。4.2 计划文档任务拆解记录AI 随后生成了 plan.md任务拆成了 5 个定义RetryConfig数据类放 retries、timeout、total_timeout、退避参数。实现retry装饰器基础结构含参数解析。实现指数退避和 jitter 计算函数。接入日志模块记录重试原因和次数。补全文档注释和类型标注。每个任务下面还附了测试用例清单。比如任务 2 的测试清单包括目标异常达到次数上限后抛出原始异常非目标异常立即抛出成功时不再等待timeout 参数生效后尽快失败。这些用例如果放在一个 vibe coding 任务里几乎不可能出现因为它们是被计划环节逼出来的。4.3 TDD循环现场记录红灯 - 绿灯 - 重构实际跑 TDD 循环的时候第一轮的红灯环节我特意盯着看。AI 先写了测试文件运行 pytest 后报了一个ModuleNotFoundError——因为实现模块还没有建。这里有个细节AI 会在这个阶段主动报告测试失败符合红灯预期。这一步非常关键因为它是模型理解 TDD 的证明如果它假装红灯会说哦测试没过等我改一下再跑那就说明 skill 没加载成功。接着绿灯阶段AI 写了最简实现。为了通过成功时不再等待这条测试它用的是try-except里判断should_retry成功直接 return这对。为了过timeout 生效测试它引入了signal.setitimer后来发现这在多线程环境下有坑重构阶段换成了轻量级的超时包装。重构阶段把_exp_backoff_with_jitter从内联公式抽成独立函数并加了类型标注。整个循环跑了大约 40 分钟期间 AI 写出的测试从最初的 7 个变成 11 个中途它自己发现了两个边界问题一是retries0时的行为应与不重试一致二是total_timeout包含单次调用超时且两个参数同时设置时优先谁。这些问题如果用老的方式很可能交付之后才在线上暴露。4.4 审查结果发现了什么最后走 code-review。我用 Codex 对同一份 diff 做审查结论是整体通过但提出 3 个需要修正的问题问题一KeyboardInterrupt会被当成普通网络异常捕获并重试这会让用户在 CtrlC 退出时被卡住应把这类系统异常排除在重试范围外。问题二日志中记录了重试次数但没有记录单次重试等待时间排障时无法判断退避是否符合预期。问题三total_timeout的实现里时间检查点放在每次调用前但单次调用超时本身可能很长导致总时长超限后仍有一次长时间调用无法中断。需要重新设计时间边界。这三个问题都非常具体而且都不是语法错误是只有另一双眼睛才容易注意到的设计缺陷。修复完这些问题整个交付才真正敢说一次通过零报错——这里的一次通过不是玄学式蒙对而是测试、审查全链路绿灯。5. 常见问题速查表与工程化心法5.1 问题速查表我整理了这段时间实际踩过或帮朋友排查过的问题按现象 - 直接原因 - 处理方式记录下来现象直接原因处理方式Claude Code 加载不到 skillsskill 目录放在错误的位置或缺少 SKILL.md 入口确认目录结构是skills/skill名/SKILL.md重启会话AI 拿到需求后直接写代码没有走 brainstormAGENTS.md 里的流程声明写得不够强制AI 把它当建议改成显式措辞必须先调用 brainstorm skill否则不进入下一步写的测试都是弱断言实现怎么改都绿例如只断言返回值不是 None没有断言具体值、类型、边界review 阶段要求强断言逐条对照计划里的用例清单Codex 跑起来不按 TDD 走Codex 对软性流程遵守较差倾向效率优先在 AGENTS.md 里给 Codex 单独写明更死板的步骤序列OpenCode 提示免费层只能在应用内使用provider key 没有配置走了默认免费通道在 opencode.json 里配置自己的 provider 和 keycc-switch 报 local proxy failed本地服务的端口、配置路径或 endpoint 格式不一致检查 cc-switch 配置请求到目标 provider 的 base URL 是否吻合端口是否被占用修改了 AGENTS.md 但 AI 表现没变化会话使用了缓存或工具只在项目启动时读取该文件重启会话确认修改的文件确实在项目根目录TDD 循环里 AI 把多个任务合并实现计划拆得不够细模型觉得可以顺便一起做把计划任务再拆小每个任务只对应一个明确测试文件5.2 让Superpowers真正跑起来的三个心法第一别跳过审批闸门。brainstorm 和 plan 的输出都需要你读一遍并确认。前几次会觉得很啰嗦但它是在把需求和实现之间的信息差消掉。我在团队里观察到跳过计划确认的人通常会回头补两次需求。第二让测试先行成为不可争辩的事实。如果 AI 试图先写实现直接打断现在不是绿灯阶段先回去读 tdd skill写测试把红灯做出来。几次之后AI 在整个会话里都会很自觉。这一招比重写一万字 prompt 都管用因为打断本身就是在设定边界。第三审查阶段一定要换一个人。要么换工具Claude Code 写、Codex 审要么换模型便宜模型写、强模型审至少也要换会话。用同一个上下文做审查AI 很容易受到自己创造过程的隧道视角影响发现不了真正的问题。5.3 把Superpowers塞进现有工程规范Superpowers 不是要替代你现有的编码规范它更像团队流程的AI 侧版本。你在 AGENTS.md 里完全可以追加自己的规则比如禁止提交print调试代码、所有日志必须走统一 logger、函数必须带类型标注。这些规则和 Superpowers 的 skills 是并存的AGENTS.md 定义了总规则skills 则负责具体工作流。建议把 AGENTS.md 和 skills 目录放进团队的模板仓库。新人入职后 clone 模板就等于所有 AI 工具都按同一个流程运行。我实测这个做法对团队的收益非常大AI 写的代码风格统一了测试覆盖自动保证review 时大家看的是逻辑而不是在讨论风格。再进一步你还可以把 AI 生成的测试自动接到 CI 和 pre-commit hooks 里让AI 写的测试和人写的测试一样进入流水线从环境层面保证测试真正跑起来而不是只在会话里往返。我个人在实际操作中的体会是Superpowers 不会让你的 AI 从写不出代码变成写得出来但它会把 AI 的产出从像实习生的稿子变成像有老程序员把关过的交付。如果你也在为 AI 写得快但不敢交付发愁这一整套流程值得你花一个下午搭起来再用一周的项目去校准时间配比和计划粒度。最后再分享一个小技巧方案文档、计划文件、测试日志都放在项目的 docs/ai/ 目录下版本管理里能看到每一步决策出问题回溯时比聊天记录好用太多。
Superpowers工作流：用TDD让AI编码从失控到可控
最近几个月我把团队里AI辅助编码的工作流做了一次大手术。从一个让Claude Code随便写写、我再花一小时review的状态切换成现在的固定动作brainstorm 澄清 - 写计划 - TDD 红绿循环 - 代码审查。这套流程的核心驱动不是某个IDE插件也不是再套一层Agent而是开源项目 Superpowers 提供的一套 skills 工作流。它原本是给 Claude Code 用的现在 Codex 和 OpenCode 也能接入等于把同一个方法论平移到不同的 AI 终端上。先说说背景。团队里有几条交付线都在用 Claude Code 写业务代码省是真省但坑也是真坑。最典型的三个场景第一需求一句话就开干写完发现和预期完全不是一个东西第二AI 从来不主动写测试你问它测了吗它答跑了没问题然后过两天线上冒出一个边界case第三为了修一个小bugAI顺手改了三处无关代码review的时候看着 diff 一脸懵。这类情况多了之后我逐渐意识到问题不在模型能力而在工作流的缺失。Superpowers 的价值就是把这个缺失补上。如果你也在用 Claude Code、Codex 或 OpenCode 写代码被写得快但不敢交付折磨过这篇文章就是给你准备的。下文会把 Superpowers 的原理、三端接入方式、从需求澄清到代码审查的完整链路以及我踩过的坑全部讲一遍。建议按顺序读第4章的实战复盘和第5章的问题速查表可以直接当手册用。1. 为什么需要SuperpowersVibe Coding的失控与Workflow的回归1.1 Vibe Coding最让人头疼的三个场景先说第一个场景需求只有一句话。之前有个需求给文件上传加个进度提示Claude Code 二话不说开始写前端、后端、数据库表都动了。review 的时候发现它把上传组件整个重写了接口路径也改了。项目里没人要求过这些改动纯粹是模型在自由发挥。这就是 vibe coding 最典型的失控——你把一个模糊意图丢给AI它敢在没人确认的情况下帮你做了所有决定。第二个场景测试缺失。有一次我让 Claude Code 写一个时间区间工具函数结果它写了 80 行实现测试一个没有。我追问测试呢它才补了两个 happy path。而我担心的是跨时区、夏令时、边界值这些角度的覆盖它压根没想过。不是说AI没有能力写测试而是默认流程里没有测试先行这个环节它就不会主动加。这事儿你靠 prompt 提醒一次管一次工作流不管下次照样忘。第三个场景回归破坏。有个内部服务某天 Claude Code 修了一个 NullPointerException顺带把缓存模块的默认过期时间从 300 秒改成了 60 秒。它在会话里说过这个改动但当时我在看别的任务没注意到。这事件让我意识到AI 会话中的每句话你都盯就是拿人肉审计去对抗工具效率成本不可持续。解决方向只有一个把工程实践固化到 AI 的执行流程里让约束而不是人肉来兜底。1.2 Superpowers到底是什么Superpowers 不是 IDE 插件也不是另一个跑在 Agent 上层的 Agent。它本质上是一个开源的AI 编码技能包仓库里面是一批 Markdown 格式的 skill 文件每个 skill 定义了一个工作流环节的规则、步骤、输出格式。AI 通过读取这些 skill 文件就知道在某个阶段应该怎么做、产出什么、禁止做什么。打个比方传统用法是你给一个聪明但没经验的新人下了一句指令把这个支付页面写了然后他自由发挥。Superpowers 的用法是你给这个新人一本《团队开发军规》要求他先读需求澄清章节在动键盘之前问你五个问题然后读计划章节把任务拆到 10 分钟一个颗粒度再读TDD章节必须先写失败的测试再写实现最后还要走代码审查章节叫一个同事来对拍。这套军规不是一个 10 万字的 prompt 塞进去的而是按需加载的。AI 在会话开始只读一个 AGENTS.md 入口文件里面写了遇到XX场景就调用XX skill。真正干活时模型再去读取对应的 skill 文件。这样做的好处有两个第一省 token上下文不会被一堆规则占满第二可维护你想改某个环节的规则只改一个文件就行不用重写整段系统提示词。1.3 为什么是TDD而不是先写代码再补测试Superpowers 把 TDD 作为默认开发路径这一点我有过犹豫。毕竟让 AI 写测试再写实现看起来多了一步时间成本更高。但实际跑下来这条路径反而更省。原因在于TDD 的红灯阶段给 AI 划定了一个明确的验收边界模型在写实现时不是猜你要什么而是朝着一个已经被测试定义好的行为去凑边界条件不会轻易漏。先写功能AI 大概率会把主流程写完边界 case 靠运气但你先让它写测试它为了测试通过必须考虑空输入、超时、异常类型、重复调用这些细节。这是写测试这个动作本身带来的强制思考。我的类比是先写测试相当于施工前先立承重墙的垂直度标准而不是楼盖完了再拿尺子量。后者不是不能测而是测出来的问题改起来代价大得多。2. 安装与三端配置Claude Code / Codex / OpenCode 一次配齐2.1 获取Superpowers安装方式不复杂。在自己电脑上建一个目录直接从 GitHub 把项目 clone 下来。Mac/Linux 都支持。拿到手后你看到的是一堆 Markdown 和脚本核心的东西有两个AGENTS.md和skills/目录。AGENTS.md 是入口skills 目录里按主题放着一批 skill。每个 skill 是一个文件夹里面有一个SKILL.md作为该技能的主文件。提示不要在系统的全局目录里直接改建议把 Superpowers 克隆成一个独立目录然后在项目里引用。这样升级项目时不会污染你自己的全局配置也方便团队多人共用同一份基线。2.2 Claude Code 配置Claude Code 原生支持 skills 机制。具体操作是把 skills 目录链接到 Claude Code 能扫描到的位置。我用的方式是在项目的.claude/skills/下面建软链接指向 Superpowers 克隆目录里的各 skill 文件夹。再把 Superpowers 根目录里的 AGENTS.md 内容合并到项目根目录的 AGENTS.md或者在项目 AGENTS.md 里写一句superpowers/AGENTS.md如果 Claude Code 支持 import 语法——不同版本支持程度不同最稳的办法是直接把内容复制进去。验证是否生效在 Claude Code 会话里输入list skills或者直接问你有哪些 skills。能看到 brainstorm、writing-plans、tdd、code-review 等条目就说明加载成功。如果看不到先检查目录结构再重启会话。Claude Code 对技能的扫描主要发生在会话启动时中途改了文件不重启大概率不生效。2.3 Codex 配置Codex 也读 AGENTS.md并且支持类似 skills 的目录。通常把 skills 放到~/.codex/skills/或者项目下的.codex/skills/然后在 AGENTS.md 里声明。和 Claude Code 的差异在于Codex 对自我反思式指令的响应方式略有不同。我在实测中感觉Codex 更吃显式步骤所以在 AGENTS.md 里建议把流程写得比 Claude Code 那边更死板一点明确要求每次开始任务前必须读取 skills/tdd/SKILL.md。另外Codex 可以配自定义模型当后端比如通过 API 配置接 DeepSeek 或其他兼容端点来跑。这类用法适合团队统一供应模型的场景切换时不用改代码只改 endpoint 和 key 就行。2.4 OpenCode 配置OpenCode 现在分老版本Ts 版和新版 Opencode V2Go 重写版。如果你用的是 V2配置放在opencode.json里再在项目目录下建.opencode/skills/放 skill 文件。配置逻辑类似在 AGENTS.md 或 opencode 的自定义指令中声明加载入口。另一个实用技巧cc-switch 这个开源工具可以统一管理多套 API 配置Claude Code、Codex、OpenCode 三者的 endpoint 和 key 都可以集中维护。遇到标题里那个cc switch local proxy failed的报错时优先检查 cc-switch 的配置项本地服务端口是否被占用、填写的 API base URL 是否以/v1结尾、key 是否有效。这类报错 90% 都是配置拼接不一致拆开排查很快能定位。2.5 三端能力对比工具skills 目录入口文件数据流特点适合场景Claude Code.claude/skills/AGENTS.md原生支持 skills加载稳定日常主力、长会话复杂开发Codex.codex/skills/AGENTS.md官方支持目录但部分版本解析较弱和 OpenAI 生态打通OpenCode V2.opencode/skills/opencode.json AGENTS.mdGo 重写后配置更灵活轻量、跨提供商切换这个表不是让你选一个用而是让你理解同一套 skill 在不同环境下怎么落地。我个人的建议如果只是个人写脚本选你装得最熟的那个如果是做交付项目把 Claude Code 和 Codex 都接上用同一套 skills方便以后在 A 家模型忙或挂的时候切到 B 家不中断流程。配置陷阱再多说一句。Claude Code 在某些地区会提示 might not be available in your country这个提示通常意味着你的账号或网络环境不在官方支持范围内。处理方式很简单自查没有灰色通道可走唯一正解是使用官方支持地区的账号或者把模型调用切换到你所在地区允许使用的提供商如通过 API 配置用 DeepSeek 等可用模型跑 Codex 命令行。OpenCode 的 free tier 也类似提示 only be used from within opencode意思是免费额度只能在 OpenCode 官方应用内部使用你想用 CLI 或外部工具调用就必须配置自己的 provider key。没配置就报错配置好就行。3. 核心工作流拆解从需求澄清到代码审查3.1 需求澄清把模糊想法变成可测试的行为Superpowers 的 brainstorm skill 并不是让你和 AI 聊人生它是一套结构化的质询流程。AI 接到需求后第一反应不是动手而是按 skill 里的规则向你提问。问题范围一般包括这个功能的真正目标是什么、用户是谁、边缘场景有哪些、现有系统里有没有相似逻辑、失败时怎么办、性能和量级要求如何。这一环节可能是整个流程里最反直觉的——看起来最耽误时间实际最能省时间。我举一个实际任务某天同事说给我们服务加个带超时的重试机制。如果按 vibe coding 走AI 会直接写一个retry装饰器出来参数就 timeout、retries 两个。但走 brainstorm 流程时AI 会追着问重试是针对网络超时还是所有异常TimeoutError和ConnectionError要不要区分线程安全要不要保证重试间隔是固定还是指数退避要不要带 jitter失败日志打到哪里这些问题的答案直接决定了函数签名、内部状态和测试用例比后面改 10 版代码便宜多了。这一环节的输出不是文档是一个被确认过的用户故事加一张已完成/未完成的定义清单。比如作为调用方我希望重试装饰器在网络抖动时自动重试最多 3 次并在退避间隔上做指数加抖动且过程中不吞掉非目标异常。完成标准目标异常重试 3 次、非目标异常立即抛出、等待时间符合退避公式、支持超时取消。3.2 写计划把需求拆成AI能独立执行的最小任务需求澄清之后进入 writing-plans。AI 会把上面的用户故事切成若干任务每个任务的粒度控制在一个10 到 15 分钟能实现的单元里。切分逻辑通常是先定义数据结构或接口再实现核心逻辑再补异常分支最后做文档和测试补充。每个任务包含三样东西目标、测试用例清单、实现要点。任务之间尽量不互相依赖这样即使 AI 在某个任务上跑了很久也不会把整个会话卡死。计划写完会生成一个 plan.md 文件AI 会把它贴出来让你确认。这个确认环节是审批闸门你必须看一遍觉得任务拆得不对就点一下让 AI 重拆直到你觉得这每一步我都能验收为止。很多人会在这儿偷懒跳过计划直接进代码结果就是后面 AI 经常写着写着忘了需求又要回头澄清。花 10 分钟读计划省 40 分钟 debug这笔账很划算。3.3 TDD红绿循环核心中的核心TDD skill 是 Superpowers 的重头戏。读了这个 skill 之后AI 的执行顺序会被强制改成这样红灯针对当前任务先写一个或多个测试运行看到失败。绿灯写最小实现代码让测试通过。重构在不改变行为的条件下优化实现保持测试全绿。重复直到完成当前任务。我观察到AI 一旦被 TDD skill 约束输出行为会发生两个明显变化。第一它写实现之前真的会先写测试不再跳过。第二它的实现会收敛不再自由发挥因为测试定义好了边界和输入输出它能扩展的空间变小了。这两个变化直接解决了前面说的没有测试意识、实现不可控的问题。这里有一个值得展开的点测试的质量。TDD 绝不是写两个断言能过就算绿。Superpowers 的 skill 里要求测试必须覆盖正常路径、边界路径、异常路径三条缺一不可。有种反面教材是 AI 写了一个只验证函数返回了东西的弱测试实现返回 None 也照样通过。这等于没有测试。所以我在用的时候会在 review 阶段专门检查测试断言强度后面第 4 章会给出实测案例。TDD 的时间配比我给个参考表这是我在团队里跑了两周之后定下来的。任务预计实现时长写测试红灯最小实现绿灯重构优化合计10 分钟3 分钟4 分钟3 分钟10 分钟30 分钟8 分钟14 分钟8 分钟30 分钟1 小时18 分钟27 分钟15 分钟60 分钟2 小时以上25% 时间40% 时间35% 时间按比例注意这个表不是算术题它是一个注意力分配提醒。经验是实现越复杂测试投入占比应该越高实现越简单重构占比反而可以拉高因为快速写出的代码往往有明显的可读性提升空间。3.4 代码审查让另一双眼睛盯着实现代码审查环节我刚开始没太在意后来发现这是整个流程里最能薅羊毛的部分。Superpowers 的 code-review skill 会让 AI 以另一个角色而不是代码作者的身份去读实现。怎么做到最简单的办法是让 AI 把当前会话的 diff 和测试文件作为输入然后按一套 checklist 去审。审查维度包括有没有隐藏的 bug、有没有安全问题、边界条件处理是否完整、命名是否表意、测试是否真的在测试行为而非实现细节、有没有死代码或多余的依赖。这里最微妙的一点是防止自己审自己的盲区。同一个 AI 写的代码同一个 AI 再审查很容易得出没问题的结论。我的破解办法是审查阶段用不同配置跑。比如 Claude Code 主写、Codex 做审查或者同一个 CLI 里用思考模式更强的长上下文跑一遍 review。两种方式我都试过都能比作者自审多发现 2 到 3 个真实问题。这些问题的典型类别是异常处理遗漏比如注册了KeyboardInterrupt却漏了SystemExit、边界条件悬空比如负数、空列表、并发环境下共享状态没保护。4. 实战复盘用Superpowers开发一个重试装饰器4.1 任务背景与需求澄清过程这个例子就是第 3 章提到的带超时的重试装饰器。任务背景是一个内部 Python 服务调用外部 HTTP API 时经常因为网络抖动失败需要加重试。我们直接走 Superpowers 流程。第一步需求澄清AI 没有直接写代码而是先抛了一串问题过来重试范围是对所有异常重试还是只针对网络层异常如ConnectionError、TimeoutError超时定义是单个调用超时取消还是整个重试过程中的总时长上限退避策略固定间隔、线性、指数、指数加随机抖动调用方签名装饰器是纯参数配置还是要支持传入自定义判断函数日志失败时要不要记录每条异常的类型和重试次数我们确认的结果是只重试网络类异常单个调用用timeout参数控制总时长用total_timeout控制退避用指数加 jitter装饰器签名上支持retry_exc自定义异常元组。这个确认过程大约花了 6 分钟但正是这 6 分钟避免了后面最昂贵的返工。4.2 计划文档任务拆解记录AI 随后生成了 plan.md任务拆成了 5 个定义RetryConfig数据类放 retries、timeout、total_timeout、退避参数。实现retry装饰器基础结构含参数解析。实现指数退避和 jitter 计算函数。接入日志模块记录重试原因和次数。补全文档注释和类型标注。每个任务下面还附了测试用例清单。比如任务 2 的测试清单包括目标异常达到次数上限后抛出原始异常非目标异常立即抛出成功时不再等待timeout 参数生效后尽快失败。这些用例如果放在一个 vibe coding 任务里几乎不可能出现因为它们是被计划环节逼出来的。4.3 TDD循环现场记录红灯 - 绿灯 - 重构实际跑 TDD 循环的时候第一轮的红灯环节我特意盯着看。AI 先写了测试文件运行 pytest 后报了一个ModuleNotFoundError——因为实现模块还没有建。这里有个细节AI 会在这个阶段主动报告测试失败符合红灯预期。这一步非常关键因为它是模型理解 TDD 的证明如果它假装红灯会说哦测试没过等我改一下再跑那就说明 skill 没加载成功。接着绿灯阶段AI 写了最简实现。为了通过成功时不再等待这条测试它用的是try-except里判断should_retry成功直接 return这对。为了过timeout 生效测试它引入了signal.setitimer后来发现这在多线程环境下有坑重构阶段换成了轻量级的超时包装。重构阶段把_exp_backoff_with_jitter从内联公式抽成独立函数并加了类型标注。整个循环跑了大约 40 分钟期间 AI 写出的测试从最初的 7 个变成 11 个中途它自己发现了两个边界问题一是retries0时的行为应与不重试一致二是total_timeout包含单次调用超时且两个参数同时设置时优先谁。这些问题如果用老的方式很可能交付之后才在线上暴露。4.4 审查结果发现了什么最后走 code-review。我用 Codex 对同一份 diff 做审查结论是整体通过但提出 3 个需要修正的问题问题一KeyboardInterrupt会被当成普通网络异常捕获并重试这会让用户在 CtrlC 退出时被卡住应把这类系统异常排除在重试范围外。问题二日志中记录了重试次数但没有记录单次重试等待时间排障时无法判断退避是否符合预期。问题三total_timeout的实现里时间检查点放在每次调用前但单次调用超时本身可能很长导致总时长超限后仍有一次长时间调用无法中断。需要重新设计时间边界。这三个问题都非常具体而且都不是语法错误是只有另一双眼睛才容易注意到的设计缺陷。修复完这些问题整个交付才真正敢说一次通过零报错——这里的一次通过不是玄学式蒙对而是测试、审查全链路绿灯。5. 常见问题速查表与工程化心法5.1 问题速查表我整理了这段时间实际踩过或帮朋友排查过的问题按现象 - 直接原因 - 处理方式记录下来现象直接原因处理方式Claude Code 加载不到 skillsskill 目录放在错误的位置或缺少 SKILL.md 入口确认目录结构是skills/skill名/SKILL.md重启会话AI 拿到需求后直接写代码没有走 brainstormAGENTS.md 里的流程声明写得不够强制AI 把它当建议改成显式措辞必须先调用 brainstorm skill否则不进入下一步写的测试都是弱断言实现怎么改都绿例如只断言返回值不是 None没有断言具体值、类型、边界review 阶段要求强断言逐条对照计划里的用例清单Codex 跑起来不按 TDD 走Codex 对软性流程遵守较差倾向效率优先在 AGENTS.md 里给 Codex 单独写明更死板的步骤序列OpenCode 提示免费层只能在应用内使用provider key 没有配置走了默认免费通道在 opencode.json 里配置自己的 provider 和 keycc-switch 报 local proxy failed本地服务的端口、配置路径或 endpoint 格式不一致检查 cc-switch 配置请求到目标 provider 的 base URL 是否吻合端口是否被占用修改了 AGENTS.md 但 AI 表现没变化会话使用了缓存或工具只在项目启动时读取该文件重启会话确认修改的文件确实在项目根目录TDD 循环里 AI 把多个任务合并实现计划拆得不够细模型觉得可以顺便一起做把计划任务再拆小每个任务只对应一个明确测试文件5.2 让Superpowers真正跑起来的三个心法第一别跳过审批闸门。brainstorm 和 plan 的输出都需要你读一遍并确认。前几次会觉得很啰嗦但它是在把需求和实现之间的信息差消掉。我在团队里观察到跳过计划确认的人通常会回头补两次需求。第二让测试先行成为不可争辩的事实。如果 AI 试图先写实现直接打断现在不是绿灯阶段先回去读 tdd skill写测试把红灯做出来。几次之后AI 在整个会话里都会很自觉。这一招比重写一万字 prompt 都管用因为打断本身就是在设定边界。第三审查阶段一定要换一个人。要么换工具Claude Code 写、Codex 审要么换模型便宜模型写、强模型审至少也要换会话。用同一个上下文做审查AI 很容易受到自己创造过程的隧道视角影响发现不了真正的问题。5.3 把Superpowers塞进现有工程规范Superpowers 不是要替代你现有的编码规范它更像团队流程的AI 侧版本。你在 AGENTS.md 里完全可以追加自己的规则比如禁止提交print调试代码、所有日志必须走统一 logger、函数必须带类型标注。这些规则和 Superpowers 的 skills 是并存的AGENTS.md 定义了总规则skills 则负责具体工作流。建议把 AGENTS.md 和 skills 目录放进团队的模板仓库。新人入职后 clone 模板就等于所有 AI 工具都按同一个流程运行。我实测这个做法对团队的收益非常大AI 写的代码风格统一了测试覆盖自动保证review 时大家看的是逻辑而不是在讨论风格。再进一步你还可以把 AI 生成的测试自动接到 CI 和 pre-commit hooks 里让AI 写的测试和人写的测试一样进入流水线从环境层面保证测试真正跑起来而不是只在会话里往返。我个人在实际操作中的体会是Superpowers 不会让你的 AI 从写不出代码变成写得出来但它会把 AI 的产出从像实习生的稿子变成像有老程序员把关过的交付。如果你也在为 AI 写得快但不敢交付发愁这一整套流程值得你花一个下午搭起来再用一周的项目去校准时间配比和计划粒度。最后再分享一个小技巧方案文档、计划文件、测试日志都放在项目的 docs/ai/ 目录下版本管理里能看到每一步决策出问题回溯时比聊天记录好用太多。
