1. Superpowers 到底是什么先搞懂它在解决什么问题1.1 它不是又一个 AI 助手而是一套“技能包”协议先说结论Superpowers 不是 IDE 插件也不是又一个对话机器人它是一组以 Markdown 文件形式存在的“技能包”专门服务 Codex CLI、Claude Code 这类终端里的 AI 编码代理。只要你把仓库里的 skills 目录接进代理的配置代理就等于多了一整套“资深工程师操作手册”每个技能是一个子目录目录里放一个 SKILL.md职责是告诉代理“这个技能在什么场景下启用、启用了以后按什么顺序做什么事、哪些事绝对不能做”。我用一个生活化的类比解释模型本身像是一个极其聪明、知识量很大但没什么工作经验的实习生。你直接说“帮我改个 bug”它确实会动手但很可能上来就猜、改完不跑测试、遇到报错又重新试一次。Superpowers 做的不是教它更多编程知识而是交给它一套工作纪律——碰到问题先复现、先读日志、先写失败测试、先出计划。这套纪律全部落在 SKILL.md 的明文规则里不藏在黑盒 prompt 里所以你能一条一条地 review代理有没有按规矩办事一看便知。这也就是为什么“Superpowers 是什么”这个问题特别值得先讲清楚。很多第一次搜到的人会误以为它是一个可执行程序结果克隆下来发现一堆 md 文件心里犯嘀咕。实际上它越“轻”反而越好——技能文件是纯文本不参与编译不增加运行时依赖只影响代理在对话中如何思考和组织动作。1.2 它解决的核心痛点代理有知识但没流程用多了 Codex、Claude Code 这类工具的人迟早会遇到几个同样的现象让它修一个 bug它修完 A 却把 B 弄坏了让它加一个接口它跳过测试直接写实现遇到编译报错它不读完整日志就开始“换一种写法再试”。问题不是模型不够聪明而是缺少流程约束。Superpowers 的出发点恰恰是把高质量工程师的工作习惯沉淀成可复用、可版本化的技能文件让代理照着走。仓库里的技能大致分成两大类。一类是工程流程技能包括 TDD测试驱动开发、systematic-debugging系统化调试、writing-plans动手前写计划、using-git-worktrees用 git worktree 隔离任务、speed-coding快速原型等另一类是思维辅助技能例如 brainstorming、thinking以及一些笔记、写作相关的技能。工程流程技能是核心也是大多数人真正需要的部分。细看网上“codex superpowers”这个热词的火爆你会发现一个很有意思的现象很多人原本用的是手写式的 Codex CLI让它“听话”的方式是每次手动掰开揉碎地写指令。装完 Superpowers 后代理从“拨一下动一下”变成“自己会安排节奏”——先出方案、再写测试、再实现、最后回归。这就是“代码代理获得超能力”这句话的真实含义。换句话说Superpowers 卖的不是功能是工作方式。2. 安装与接入Codex 和 Claude Code 的完整使用教程2.1 安装前需要准备的环境想跑通 Superpowers前提是你本地已经有一个能正常对话的 Codex CLI 或 Claude Code 环境。这两类终端工具通常依赖 Node.js 运行时所以新手首先确认系统里有 Node 18 以上的版本用node -v看一眼即可。其次确认 git 已安装因为技能包需要克隆仓库也方便后续拉更新。最后确保你的代理已经完成登录、能正常发起任务这一步没打通后面装技能多半也是白装。环境这块我不展开太多实际操作中 90% 的问题都出在“代理本身还没配好”而不是 Superpowers 上。你可以先用一句最简单的“你好”测试代理能回复再进入下一步。这样后面出现任何异常排错范围会更小。2.2 Claude Code 接入方式插件市场一条龙如果你用的是 Claude Code接入 Superpowers 是最省事的一条路因为项目已经把技能打包成插件走官方插件市场即可。启动claude后输入/plugin进入插件管理界面选择添加插件市场填入obra/superpowers这个仓库地址确认后系统会拉取插件元数据。再回到/plugin菜单找到 Superpowers 并安装启用整个过程不需要手动改配置文件。装完之后如何验证直接在对话里问一句“你现在有哪些技能”如果代理能看到并列出 tdd、systematic-debugging、writing-plans 等名字说明技能已经载入。这里有个小坑部分版本插件安装后需要重启一次会话才生效所以如果一开始代理“一问三不知”先退出来重新进入对话再去检查技能列表比反复重新安装要高效得多。2.3 Codex CLI 接入方式手动拷贝或软链Codex 这边稍微费点手工活因为不同版本对技能目录的读取位置不一样这也是“superpowers 安装”会成为一个独立热搜词的原因——网上教程互相有出入很多人照做却发现没生效。通用做法是先克隆仓库再把仓库根目录下的 skills 目录接到 Codex 的全局技能目录里。一个典型操作序列如下git clone https://github.com/obra/superpowers.git ~/superpowers mkdir -p ~/.codex/skills ln -s ~/superpowers/skills/* ~/.codex/skills/这里用软链而不是复制的好处是以后想更新 Superpowers只需要git pull一次所有技能自动同步新版本。如果你的 Codex 版本读取的是项目级技能目录那就在项目根目录下建.codex/skills把需要的技能项目单独软链进去避免把全量技能带到每一个仓库。验证方法和 Claude Code 类似启动codex问一句“你加载了哪些技能”或者直接说“使用 tdd 技能的任务流程是什么”看它能否准确描述出红绿重构的步骤。如果答不上来大概率是技能目录位置或命名没对上。由于 Codex 迭代速度很快目录约定可能随版本变化建议以仓库 README 和当前 Codex 官方文档为准不要盲目照搬旧教程。2.4 目录结构与 SKILL.md 的写作规范看清楚技能目录的结构对接入和自定义都很有帮助。仓库里的 skills 目录通常长这样skills/ ├── tdd/ │ └── SKILL.md ├── systematic-debugging/ │ └── SKILL.md ├── writing-plans/ │ └── SKILL.md └── using-git-worktrees/ └── SKILL.md每个技能根目录下的 SKILL.md 是核心文件由两部分组成顶部是 YAML frontmatter里面至少包含name和description两个字段下面是正文用于详细描述启用时机、执行步骤、注意事项、示例场景。description字段地位很关键代理就是靠它来判断“当前任务是不是该调用这个技能”写得太笼统会导致技能频繁被误触发写得太窄又会漏触发。这一点在你改造或新增团队自定义技能时尤其要留意后文我会再展开。3. 核心技能逐个拆解哪些技能最值得开箱即用3.1 TDD强制代理“先看红灯再写代码”TDD 技能可以说是 Superpowers 里价值最高、也最容易立竿见影的一个。它把代理的默认工作流从“直接改代码、最后补测试”硬生生掰成经典的红绿重构循环先写一个会失败的测试运行测试确认它确实失败用最小改动实现功能让测试通过运行测试确认变绿最后在测试保护下安全重构。为什么一定要强调“先看到失败”因为这一步才是 TDD 的灵魂。如果测试一开始就绿说明它根本没测到新逻辑后面全是在自欺欺人。代理天生有“尽快让任务看起来完成”的倾向所以技能文件里会明确要求它把红绿灯结果如实报告出来。我实测下来配上这个技能后代理写出不可测代码、绕过测试交差的概率明显下降。特别是 Java 这种编译期长、反馈链慢的语言提前用测试锁定行为比什么都实惠。3.2 systematic-debugging遇到报错先别急着改排查 bug 是最容易暴露代理短板的任务。没有规则约束时代理最常见的做法是“看到报错→猜一个原因→改掉→再跑”循环往复运气好几分钟解决问题运气差能把无关代码也改一遍。systematic-debugging 技能给出的流程则要严格得多复现问题、完整读取错误信息与堆栈、检查最近一次改动、形成假设、用最小实验验证假设、修复后运行相关测试确认回归。这套流程看起来笨实际上非常省 token。以 Java 的 Maven 构建失败为例代理经常只盯着终端最后一行“BUILD FAILURE”就开始改 pom而真正的异常往往藏在更靠前的堆栈里。技能会要求它把 ERROR 开头的日志行和关键异常类型完整摘录出来再下判断。把“先看完整证据”变成硬性步骤之后代理犯低级错误的次数会肉眼可见地减少。3.3 writing-plans动手前先交一份路线图writing-plans 解决的是“代理太急着写代码”的反面——任务一复杂就乱了阵脚。这个技能要求代理在改动代码之前先产出书面计划需求拆成哪些任务、每个任务改动哪些文件、测试策略是什么、完成标准怎么判断。计划通常以独立文档或对话中的结构化清单呈现人可以在动手前 review 并修正方向避免代理闷头写完一大坨才发现理解偏了。实际用起来我会把 writing-plans 和 TDD 组合触发先让代理出计划确认无误后再让它按计划以红绿重构的方式逐项落地。两个技能搭配时代理的行为模式非常接近一个有条理的工程师先想清楚、再小步快跑、每一步都有测试反馈。对于新功能开发和较大规模重构这个组合我几乎必用。3.4 using-git-worktrees并发开发不互相踩脚using-git-worktrees 是一个偏“工程卫生”的技能适合那些喜欢让代理一口气开多个任务的人。它的思路很简单每次新任务都从主分支开一个独立的 worktree而不是在当前工作目录里直接切来切去。命令大致是git worktree add ../feature-login -b feature/login任务完成后跑完测试、合并回主分支、再清理 worktree。好处很明显多个任务可以并行进行互不污染代理改一半不想改了直接丢弃整个 worktree 即可不需要小心翼翼地把工作区恢复原状。Java 项目尤其适合这个做法——代码库大、可能有多个服务模块用独立 worktree 开发时构建目录和本地缓存不会互相打架。不过这个技能对不熟悉 worktree 概念的代理需要额外解释所以技能文件里通常会带上完整的命令示例和清理步骤。3.5 speed-coding 与思维类技能怎么选怎么用speed-coding 则是和 TDD 风格相反的另一极它适合快速搭建原型、探索性编码追求“赶紧跑起来看效果”暂时不把测试放在首位。这两个技能看起来冲突实际可以搭配使用新功能先用 speed-coding 快速验证方案可行性确定方向后再用 TDD 重写或补测试锁定行为。我会在任务描述里明确指出本次使用哪个技能避免代理自己拿不定主意。至于 brainstorming、thinking 这类思维辅助技能属于锦上添花。它们让代理在回答前先组织思路、列出候选方案、评估取舍。对于已经比较有条理的模型帮助不算巨大但如果你的目标是培养代理“想清楚再回答”的习惯这类技能可以作为团队文化的一部分保留。我的建议是新手阶段只装 TDD、systematic-debugging、writing-plans 三个跑顺了再逐步加一次装太多反而会让代理在技能触发上犹豫不决。4. Java 场景实战把 Superpowers 用在 Spring Boot 工程里4.1 为什么 Java 项目尤其需要这套流程“superpowers java”这个热词背后是一批 Java 开发者在 AI 编码工具上踩过坑之后的真实诉求。Java 项目的编译和测试周期比 Python、JavaScript 这类脚本语言长得多一次全量构建可能要几十秒甚至几分钟。如果代理不先写测试就闷头改代码你很难确认行为是否被破坏等到集成阶段再发现问题定位成本已经很高。反过来因为 Java 有足够成熟的 JUnit、MockMvc、Maven/Gradle 生态只要代理被约束着“先测试、后实现”质量就能得到很扎实的保障。Superpowers 在这里扮演的角色就很清晰了它并不给 Java 带来任何新的测试框架或工具而是负责让代理老老实实去调用 mvnw、去等待测试结果、去读懂 JUnit 的失败输出。说白了技能管流程工具链还是你原有的那一套。4.2 实战场景给用户服务加一个 GET 接口我拿一个具体场景演示这套技能的用法假设你有一个 Spring Boot 项目现在要新增GET /api/users/{id}接口返回用户基本信息。任务开始时我在对话里明确说“这次请使用 writing-plans 和 tdd 技能”代理随后进入计划模式列出预期改动新增一个UserController、一个UserService、一个 DTO以及一个UserControllerTest测试类验收标准是“请求存在的用户返回 200 和正确 JSON请求不存在的用户返回 404”。计划确认后进入 TDD 的第一步写失败测试。典型的 MockMvc 测试代码大致长这个样子mockMvc.perform(get(/api/users/{id}, 1L)) .andExpect(status().isOk()) .andExpect(jsonPath($.name).value(Alice));关键操作是写完测试后代理必须运行./mvnw test -DtestUserControllerTest并且要能看到红灯——此时 Controller 还不存在测试会因为 404 或编译失败而红掉。看到红灯后代理才开始补最小实现代码包括 Controller、Service 和 DTO然后再跑一次同一个测试确认变绿。最后一步是重构把可以复用的逻辑提取出来再跑一遍全量相关测试确保没有回归。整个过程里最值得称道的是代理没有“顺手把 Controller 和 Service 一次写完再回头测”而是严格卡在一个个小红灯之间推进。对于 Java 这种反馈慢的生态这种做法能把每一段改动的风险控制在最小范围内。4.3 实操中的关键参数与高效命令用 Java 跑这套流程有几个参数和命令在技能文件里值得固定下来能显著节省时间。第一尽量用./mvnw test -Dtest某个测试类这种定向运行方式而不是每次全量./mvnw testJava 项目全量测试动辄几分钟定向运行能瞬间缩小反馈回路。第二编译检查可以用./mvnw -q compile-q参数可以少打印大量无关 INFO 日志让代理更专注于真正的报错信息。第三如果你用了 Gradle对应命令是./gradlew test --tests UserControllerTest语义一致。还有一个系统化调试的典型例子。假设接口返回了 400 而不是 200代理按 systematic-debugging 流程不会直接改代码而是先看 MockMvc 打印的请求与响应日志发现是路径变量的类型不匹配——{id}被传成了字符串映射到 Long 参数时失败。于是它在测试里修正类型断言确认假设再跑测试回归。这个过程因为每一步都有依据最终改动的代码量往往非常小也不会牵扯到无关文件。5. 常见问题与排查技巧实录5.1 装了技能但代理完全不反应这是我在实践中遇到最多的问题表现是技能文件确实放在目录里了可代理的对话行为毫无变化问它有哪些技能也答不上来。按经验排查顺序应该是先确认技能目录名称是skills而不是skillCodex 对目录名很敏感再确认 SKILL.md 的 frontmatter 里有完整的name和description字段描述缺失会让代理无法识别这个技能能干什么最后确认代理版本是否支持技能读取某些旧版本 CLI 根本不加载外部技能目录这种情况只能升级或换安装方式。这里提供一个快速排查表现象可能原因处理方式技能列表为空目录名错误或放错位置改成skills并放在全局配置目录技能可见但从不触发description 写得模糊补充具体触发场景与关键词代理答非所问版本不支持技能加载升级 CLI 或改用插件安装更新后行为异常软链过期或仓库被改重新git pull并重启会话5.2 技能之间互相打架技能多了以后代理可能同时触发两个流程典型如 TDD 和 speed-coding 一起启动结果一个让它赶紧出原型一个让它先写失败测试代理就开始左右横跳。我的解决方式是在任务描述里直接指名“这次用 tdd不要用 speed-coding”或者反过来。如果某个技能经常在错误场景被触发问题多半出在它的description写得过于宽泛把它限制到更精确的场景就好。技能为你所用不是反过来让你适应它。5.3 担心技能文件把上下文撑爆有人会担心装了几十个技能后每次对话都得把所有 SKILL.md 读进上下文token 消耗会很大。实际体验并不是这样Codex 和 Claude Code 对技能文件大多采用按需读取的机制代理先根据当前任务和技能描述做出初步匹配再决定要不要加载某个技能正文。换句话说装 30 个技能不等于一次对话里真的读入 30 个文件。不过也要注意纪律SKILL.md 本身应保持精简步骤写到“可执行”粒度就好不要塞大段教程需要详细背景时可以放到子目录里的附加文档中由代理按需加载。5.4 团队如何统一 Superpowers 版本与自定义技能如果团队里有好几个都在用 Superpowers最大的坑是各人克隆的版本不一样技能行为出现差异。最简单的做法是把 skills 目录固定到一个团队仓库里用 git submodule 或直接 vendoring 锁住某个 commit升级时由一人发起、大家同步。团队也可以在默认技能之外维护自己的技能目录比如“安全审计”“Code Review 清单”“分支清理”等放在同一个技能体系里。这样代理在各种项目里的行为就变得可预期也给后续做工程规范落地提供了载体与其把规范写在没人看的文档里不如把它写成代理必须执行的技能。6. 我的实操心得与建议实际用了 Superpowers 几周之后我最明显的感觉是代理还是那个代理但它做事的“姿态”变了。以前它像个急于表现的新人现在它更像一个肯先想清楚再动手的同事。TDD 技能对我的帮助最大它不但让 AI 生成的代码拥有测试保护也顺带纠正了我自己“偷懒不写测试”的习惯——当代理每次都在红灯前停下来等你确认你也会重新理解测试的价值。有几个经验值得分享。第一技能文件不要只装不改遇到代理行为不符合预期第一时间检查对应技能的 SKILL.md调整措辞和步骤顺序往往比分叉重装更有效。第二别追求技能数量我见过有人一下装了几十个结果代理在触发哪个技能上浪费大量时间。挑三四个解决当前痛点跑顺了再加才是稳定节奏。最后分享一个小技巧在 Codex 会话里发起任务时直接在开头写明“请使用 tdd 和 writing-plans 技能推进”这会显著提高代理按流程执行的概率。虽然技能设计上允许代理自主判断但显式指定依然是最稳妥的指挥方式。对我来说Superpowers 最大的贡献不是某个具体的技能而是它让我意识到AI 编码代理的产出质量很大程度上取决于你愿意花多少功夫约束它的工作习惯这套用 Markdown 管理“代理素养”的思路值得每个深度使用 AI 编程的团队认真试试。