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 -Dtest=UserControllerTest，并且要能看到红灯——此时 Controller 还不存在，测试会因为 404 或编译失败而红掉。看到红灯后，代理才开始补最小实现代码，包括 Controller、Service 和 DTO，然后再跑一次同一个测试，确认变绿。最后一步是重构，把可以复用的逻辑提取出来，再跑一遍全量相关测试确保没有回归。

整个过程里最值得称道的是，代理没有“顺手把 Controller 和 Service 一次写完再回头测”，而是严格卡在一个个小红灯之间推进。对于 Java 这种反馈慢的生态，这种做法能把每一段改动的风险控制在最小范围内。

4.3 实操中的关键参数与高效命令

用 Java 跑这套流程，有几个参数和命令在技能文件里值得固定下来，能显著节省时间。第一，尽量用./mvnw test -Dtest=某个测试类这种定向运行方式，而不是每次全量./mvnw test，Java 项目全量测试动辄几分钟，定向运行能瞬间缩小反馈回路。第二，编译检查可以用./mvnw -q compile，-q参数可以少打印大量无关 INFO 日志，让代理更专注于真正的报错信息。第三，如果你用了 Gradle，对应命令是./gradlew test --tests "UserControllerTest"，语义一致。

还有一个系统化调试的典型例子。假设接口返回了 400 而不是 200，代理按 systematic-debugging 流程，不会直接改代码，而是先看 MockMvc 打印的请求与响应日志，发现是路径变量的类型不匹配——{id}被传成了字符串，映射到 Long 参数时失败。于是它在测试里修正类型断言，确认假设，再跑测试回归。这个过程因为每一步都有依据，最终改动的代码量往往非常小，也不会牵扯到无关文件。

5. 常见问题与排查技巧实录

5.1 装了技能但代理完全不反应

这是我在实践中遇到最多的问题，表现是技能文件确实放在目录里了，可代理的对话行为毫无变化，问它有哪些技能也答不上来。按经验，排查顺序应该是：先确认技能目录名称是skills而不是skill，Codex 对目录名很敏感；再确认 SKILL.md 的 frontmatter 里有完整的name和description字段，描述缺失会让代理无法识别这个技能能干什么；最后确认代理版本是否支持技能读取，某些旧版本 CLI 根本不加载外部技能目录，这种情况只能升级或换安装方式。

这里提供一个快速排查表：

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 编程的团队认真试试。