第一次在 GitHub 趋势榜上刷到“superpowers”这个名字，我以为是哪个中二程序员给项目起的网红名。直到我把它装进 Claude Code，让 AI 带着整套 TDD 流程、系统性调试步骤和代码审查清单去独立完成一个 Java 重构任务，才发现这个名字背后是实打实的野心——它不是在给编码助手加功能，而是在给 AI“上规矩”。

简单说，superpowers 是一套面向命令行编码智能体的“职业技能培训库”：把老师傅们写代码、排故障、做审查时的套路，整理成结构化技能文档，让 Claude Code、Codex 这类工具不再凭感觉回答，而是先定方案、再动手、最后验证。如果你已经受够了 AI“什么都会写、但写出来永远不牢靠”的状态，这篇实操记录应该能帮上忙。我会从安装、初始化、核心技能拆解、自定义技能，再到真实项目中的排查经验，把全流程完整写出来。

1. Superpowers 是什么：从“智能问答”到“职业素养”

1.1 为什么模型越来越聪明，项目里却越来越心累

现在的编程模型写单点功能真的很强：让它写一个排序函数、一个 REST 接口、一段正则表达式，基本秒出。可一旦让它完成一个“需要流程支撑”的任务，比如“给这个模块补上测试”“帮我排查线上偶发报错”“把这个历史代码安全重构”，它就开始飘——最常见的表现是跳过测试直接写实现、改一个 bug 顺手改了三处无关代码、或者重构到一半自己把接口改崩了。

问题的根源不是模型不够聪明，而是它缺少“工程章法”。人类程序员靠公司规范、Code Review、单元测试这些流程兜底，而裸奔的 AI 只有直觉，没有流程。一位三年经验的工程师不会在没写测试的情况下说“改完了”，但大模型会。superpowers 的思路，就是把“流程”本身做成可装载的资产。它不是提示词模板，也不是 IDE 插件，而是一套由若干“技能”组成的方法论库。每个技能都是一份结构化的操作手册，AI 按需加载后，严格按手册里的步骤执行，而不是自由发挥。

1.2 “技能”这套设计，到底解决什么问题

技能这个词听起来玄，实际落地很朴素。打开一个技能目录，核心文件 SKILL.md 用 Markdown 写成，开头一段 YAML 描述它的名称、适用场景、触发条件，正文就是分步骤的执行流程和守则。比如 TDD 技能会告诉 AI：先写失败测试，跑一遍确认红灯，再写最小实现，看到绿灯后重构，最后全量回归。调试技能则要求 AI：先复现、再缩小范围、读完整错误栈、找到根因后带着目的修、最后补回归测试。

这个过程和我们常见的“手写一大段 prompt 让它这么做”有什么本质区别？区别在于体系化与复用。手写 prompt 是一次性的，换个项目、换个会话就没了；而技能库是一次安装、全局生效，且技能之间能互相调用——AI 可以先加载“写计划”技能把需求拆成步骤，再加载 TDD 技能逐条实现，遇到问题自动切入“系统性调试”技能。这种组合出来的行为，已经接近一个受过训练的中级工程师的做事次序。我见过太多人把希望寄托在“换一个更强的模型”上，却忽略了：就算换了个聪明人进来，没有流程约束，他照样能把项目搞乱。

1.3 它在工具链里的位置：不是替代模型，而是替代提示词

很多人问：superpowers 是替代 Claude Code 还是替代 Codex？它哪个都不替代。它站在编码助手之上，把“怎么干活”这件事标准化。当前社区里最常见的是把它作为 Claude Code 的技能库来安装，但技能本身是纯文本 Markdown，只要你的工具能读入这些说明，它就能生效。Codex 同样可以用，后面第四章我会专门讲怎么把技能搬运给 Codex。

为了直观对比，我把三种用法的差异放在一张表里：

个人体感最明显的是“结果稳定性”这一列。裸聊模式下，同一个需求让 AI 写十次测试，它可能只有两三次真的走测试驱动；挂上技能库后，只要是它判断匹配的场景，基本每次都会走完整流程。这个“稳定”比单次惊艳重要得多——因为项目工程化的本质，就是让高质量的行为可以重复出现。

2. 安装与初始化：让编码助手真正“长本事”

2.1 前置环境：十几分钟能准备好的清单

别急着装，先确认基础环境，避免装到一半发现版本对不上。打开终端，逐个跑一遍：

node -v # 建议 18 以上，新版本要求 20 claude --version codex --version git --version

如果你的主要战场是 Java，额外确认 JDK 和构建工具：

java -version mvn -v # 或者 gradle -v

注意：技能库本身不挑语言，但如果你主要在 Java 项目上使用，JDK 17 + Maven 3.8 以上是比较省心的组合。JDK 太老会导致 JUnit 5 跑不起来，到时候你会分不清是技能的锅还是环境的锅。

这里有个容易忽略的点：技能库不是独立运行的程序，它依附于编码助手。所以前置环境的核心不是 Node 版本多新，而是 Claude Code 或 Codex 本身已经能正常干活。我的习惯是先让助手在项目里完成一次最简单的“读取文件并总结”，确认链路通了再装技能，省得后面排查问题时分不清是装坏了还是本来就没配好。

2.2 安装方式：选一种，别混着来

社区里主流的装法有两种，我都试过。第一种是直接在 Claude Code 里装插件：

/plugin install superpowers@latest

装完它会新增一组斜杠命令，用来初始化技能、查看技能列表、管理项目级配置。第二种是走 npm 全局安装，再在项目目录里执行初始化：

npm install -g superpowers superpowers install

两种方式本质都是把技能文件释放到项目里的.claude/skills目录，区别只是入口不同。按你平时习惯选一种就行，千万不要混用——混用容易出现双份技能，白白占用宝贵的上下文。初始化时插件通常会问几个问题：主要编程语言、常用测试框架、完成一个需求的默认流程。这个环节别跳过，你的回答会被写进项目级配置，之后 AI 会拿着这份“工地守则”开工。我见过有人一路回车跳过，结果 AI 默认用 Python 的 pytest 给他测一个 Java 项目，闹出不少笑话。

2.3 初始化完成后的快速验证

装完别急着开工，先做一个 5 分钟的冒烟测试。随便建一个空目录，初始化 git，然后让 AI 做一件事：“帮我在这个目录里规划一个带测试的计算器模块，先写计划，不要直接码代码。”

没有技能库时，AI 大概率立刻开始创建文件；技能库生效时，你会看到它先加载 writing-plans 技能，输出一份计划文档，再按计划一步步来。更直接的验证是查技能文件是否落地：

ls -la .claude/skills/

正常情况下你会看到一堆以技能名命名的目录，比如 tdd、systematic-debugging、writing-plans、code-review 等。看到这些目录，说明安装这步成功了；如果目录是空的，多半是插件与 CLI 版本不匹配，去核对一下版本再重装。

2.4 一个容易忽略的权限细节

技能里的很多步骤需要 AI 实际执行命令，比如跑测试、查文件、提交代码。因此要让技能库存完整发挥作用，需要给助手放行相应的工具权限。如果你习惯全程自动确认，那没问题；如果用逐条确认模式，建议至少把当前项目目录和常用命令（mvn、npm、git）加入白名单，否则每次跑技能都要手动点好几下确认，体验很割裂，也会打断技能的连续性。

权限这块还有一个隐蔽的坑：有些项目里 AI 根本没有 bash 权限，它就会尝试用伪代码“假装”跑测试。你看到的结果是它汇报“测试通过”，实际上什么都没执行。所以冒烟测试时我要求 AI 必须粘贴真实的测试日志，而不是让它口头总结。

3. 核心技能包拆解与实战

3.1 TDD 技能：红灯、绿灯、重构，一步都不能跳

TDD 技能是整套技能库里含金量最高的一个，对 AI 行为方式的改观也最明显。加载之后，AI 面对一个功能需求不再是“开始写实现代码”，而是先做三件事：读需求、列出验收条件、把验收条件转成测试用例。然后按红灯—绿灯—重构的节奏推进：先写一个注定失败的测试，运行并确认它是红的，再写最小实现让它变绿，最后在绿灯保护下重构。

为什么红灯确认对 AI 尤其重要？因为模型有“一步到位”的倾向，总觉得实现写完顺便补两个测试就叫测试驱动。结果不但测试质量差，而且一旦实现有问题，你根本说不清是代码错还是测试错。红灯验证这个动作，相当于给 AI 上了一道保险：测试在写实现之前已经证明了它的“杀伤力”，之后的修改都在安全网里进行，它敢放手重构。

实操里我会专门要求 AI 把每次mvn test或npm test的输出原样粘贴回来，而不是让它一句“测试全部通过”带过。看到真实的测试日志，你才能确认它真的执行了，而不是靠脑补。这一步劳烦一点，但长期省下的返工时间远超这点成本。

3.2 系统性调试：先证明病因，再动手修

调试技能解决的是 AI 最让人头疼的毛病：瞎猜。你丢给它一个报错，它经常不看堆栈、不看上下文，直接基于“我见过类似的问题”给一个看似合理的修复。运气好一次中，运气不好改完引入新问题，来回折腾一整天。

挂了调试技能后，AI 会被要求按固定动作来：第一步，复现问题，通常是用一个失败的测试把 bug 钉死在测试台上；第二步，完整读错误信息和堆栈，而不是只看第一行；第三步，定位根因而不是表面现象，区分“是空指针本身”还是“是数据流上游传了 null”；第四步，带着理解去修，修完跑测试确认；第五步，扫一遍是否有同类问题；最后一步，提交时写下根因，而不是只写“修复 bug”。

一个很典型的 Java 例子：Service 层报 NullPointerException，没有技能的 AI 可能直接在方法入口加一个if (xxx == null) return;。加了调试技能之后，它会先去看这个 null 是从哪一层传来的，很可能发现是 Controller 层把前端空值透传进来，最终修复点落在参数校验上。差别就在这：前者把症状盖住，后者把病灶挖掉。这两者在一个真实项目里的结局天差地别，前者会在下一个接口里再次爆炸。

3.3 Java 实例：一次完整的技能驱动开发回合

我拿一个真实的练习项目演示完整流程。需求很简单：订单金额 = 商品单价 × 数量 × 折扣，折扣按档位给，满 100 打 9 折，满 500 打 8 折，其余不打折。

先让 AI 用 writing-plans 技能出计划，它会列出：定义 Order 类、写参数化测试、实现折扣计算、跑 Maven 回归。然后进入 TDD 流程，第一批测试长这样：

class OrderTest { @Test void should_apply_no_discount_below_100() { Order order = new Order(3, 30.0); // 数量3，单价30 assertEquals(90.0, order.total(), 0.001); } @Test void should_apply_10_percent_discount_above_100() { Order order = new Order(10, 15.0); // 150元 assertEquals(135.0, order.total(), 0.001); } }

先跑一次，让它确认红灯——此时 Order 类可能还没建，编译错误也算一次有效的红灯。然后 AI 实现 Order 类，再跑测试确认绿灯：

mvn test

输出里出现Tests run: 2, Failures: 0的时候，这个回合才算结束。整个过程我没有手动写一行代码，AI 按技能流程把需求拆解、测试先行、实现、回归全部走完。你会明显感觉到它从“给一段代码”变成了“交付一个被验证过的结果”。如果一开始没有技能库，同样需求它大概率直接甩给你一个 Order 类加一个 main 方法让你自己去验证。两种结果的工程价值差距，不需要我多说。

3.4 代码审查与重构：让 AI 在交付前当一次守门员

写完功能不算完，superpowers 里还有两个高频技能：code-review 和 refactoring。code-review 技能会让 AI 在自己的 diff 上做一次正式审查，重点盯错误处理、边界条件、命名、安全问题——比如拼接 SQL、日志里打敏感字段、重复代码。我在项目里经常把它当“合并前最后一道闸门”，实测能拦住不少低级问题，尤其是异常被静默吞掉和边界值漏判这两类。

refactoring 技能则强调“行为不变”：任何重构都必须有测试兜底，并且分小步进行，每步保持绿灯。这个技能和 TDD 技能配合极好，适合对大方法、坏味道代码做整理。别指望它能像人一样做出大规模架构级重构，但清理一个 200 行的 God Method 绰绰有余。我建议每个迭代结束前，专门抽出一个会话把这两个技能串起来跑一遍，成本很低，收益却很实在。

4. 自定义技能：把团队的最佳实践喂给 AI

4.1 技能到底长什么样：一次 SKILL.md 的解剖

如果你来自建技能，会发现流程其实很轻。技能就是一个目录，目录名就是技能名，里面必须有且只有一个 SKILL.md。文件头部是 YAML frontmatter，至少要写 name 和 description，description 里最好带上触发关键词，方便 AI 判断什么时候加载这个技能；正文则是给 AI 看的操作守则，通常用“必须/禁止”句型加编号步骤来写。

我见过很多自定义技能写得不好的例子，通病是 description 写得太泛，比如“帮我写好代码”。AI 拿到这种描述根本不知道什么时候该触发。正确的写法要具体：“当项目需要执行发布流程时使用，涵盖构建、测试、打包、生成 changelog 四步。”越具体，AI 越容易在恰当的时机把它调出来。

4.2 手写一个发布检查技能

举一个真实可抄的例子。我给前端团队写过 release-checklist 技能，目录结构是这样：

.claude/skills/release-checklist/SKILL.md

文件内容如下：

--- name: release-checklist description: 在 npm 包发布前执行。触发词：发布、publish、release、npm version。 --- # 发布检查清单 1. 运行 `npm test` 并确认全部通过。 2. 运行 `npm run build`，确认产物无错误。 3. 检查 package.json 的 version 字段符合语义化版本规则。 4. 检查 CHANGELOG.md 是否有本次变更记录。 5. 以上任一步失败，禁止继续下一步。

把这个文件放到项目里之后，对 AI 说“准备发布”，它就会把这几条当硬性规定执行。团队成员有新的发布要求，直接改这一个文件就行——技能库本质上已经变成了团队的“流程仓库”。比起在群里发一份没人看的规范文档，这样一个能被 AI 强制执行的文件，管用得多。

4.3 给 Codex 用户的特别通道：技能转 AGENTS.md

Codex CLI 读的是 AGENTS.md，而不是 Claude 的 skills 目录。但技能本质是 Markdown，完全可以手动合并。我通常用一个简单的 shell 命令，把项目里所有技能文件合成一份 AGENTS.md：

for f in .claude/skills/*/SKILL.md; do echo "===== $(basename $(dirname $f)) =====" cat "$f" echo done > AGENTS.md

生成之后，Codex 读取仓库上下文时就会看到全部技能。这个方案的缺点是所有技能常驻上下文，token 占用偏高；优点是零依赖、直接生效。项目小，完全够用；项目大，建议只挑两三个核心技能合并进去，其余临时按需写。用这个方案把 TDD 技能转给 Codex 之后，我实测它在 Java 项目上行为改善很明显，至少会先想着跑测试了。

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

5.1 技能装了，AI 却“假装没看见”

多数情况不是 bug，而是触发条件没匹配上。技能库的加载依赖 description 与当前任务的语义匹配，如果 AI 没主动加载，最直接的办法是显式点名：“用 systematic-debugging 技能处理这个报错。”另外检查一下项目根目录的 SUPER.md 或等效配置是否还生效——我有一次改了技能目录的路径，配置还指在旧位置，AI 每次都想加载但找不到文件，表现就是“技能不生效”。

还有一种隐蔽情况：旧会话里还残留着未加载技能的上下文缓存，新装的技能需要新开一个会话才生效。所以装完技能第一件事是重开会话，别在旧会话里干等。

5.2 多技能打架：上下文里全是方法论

技能之间偶尔会抢话说，一个任务同时触发 TDD 和 code-review，AI 会把两份流程叠在一起，显得非常啰嗦。缓解办法有两个：一个是给 description 增加更严格的触发词；另一个是在提问时就限定“只用 TDD 技能，其他技能不要加载”。更根本的调整是养成“一个会话只做一件事”的习惯，任务混杂时，技能加载策略会变得不可预测。你想让 AI 又写功能又做审查又重构，最后往往什么事情都做得不彻底。

5.3 Java 项目特有的几个坑

Java 用户多，踩的坑也多。我整理成一张速查表：

这里我要强调一下第一行。Maven 的测试发现规则是*Test.java结尾的类，并且放在src/test/java下。AI 有时会把测试写在src/main/java里，编译能过，但mvn test一个都不跑，整轮 TDD 等于白做。所以技能流程里一定要有“跑一次测试，确认用例数大于零”的检查点。

5.4 token 焦虑：技能太多会挤爆上下文

技能文件本身占 token，全部常驻的话，大项目里很容易触发上下文超限，AI 开始“忘记”早前内容。我的经验是：默认只保留三到五个核心技能，其余技能按需放进临时目录，任务结束就清理，别让.claude/skills变成垃圾场。自定义技能也要定期合并重复项，一个团队有十来个技能已经很多了，超过这个数，AI 的选择成本会急剧上升。

另外一个减轻压力的技巧是尽量精简每个 SKILL.md 的正文。一个技能的核心价值在于“关键步骤”和“强制要求”，只要把这两块写清楚就行，不要长篇大论解释原理。原理是给人看的，AI 只需要知道做什么和禁止做什么。

6. 两个月用下来，我最想说的几点

6.1 上限靠模型，下限靠流程

踩过几次坑之后，我现在的用法很简单：保留 writing-plans、tdd、systematic-debugging、code-review 四个核心技能，Java 项目再加一个测试习惯配置。最大的体会是，这套东西的上限由模型决定，下限由流程兜住。模型不够强的时候，技能流程照样会出错，但它至少错得可追溯——你能清楚看到它是在哪一步开始跑偏的，而不是面对一团神秘代码无从下手。这种可追溯性，在写正式项目时比什么都重要。

6.2 给新用户的最低配置建议

最后分享一个小技巧：不要一上来就把官方技能全装上。技能越多选择越乱，也越耗 token。先装两三个，用一周，让 AI 的新行为方式适应你的项目，再逐步扩展。你不需要让 AI 学会一百种技能，先让它把三件事做扎实——写计划、先测试、再验证。这三件事做好了，它给你带来的效率提升，绝对超过你多装几十个花哨技能的实际收益。技能库这种东西，少而精，才能变成真正的 superpowers。