Superpowers使用指南：用技能让AI编程遵循工程工作流

最近聊AI编程的人，越来越多地提到 Superpowers 这个词。一开始我以为是某个新出的大模型名，或者又是营销号在炒作“AI超能力”概念，直到我把这套东西真正装起来跑了一周，才发现它值得单独写一篇使用指南。如果你正在用 Claude Code、Codex CLI 这类终端AI编程工具，并且受够了“AI很能聊，但一放代码就乱来”的现状，那这篇文章应该能帮到你。我会从实际踩坑的角度讲，尽量少说空话。

过去我拿终端AI工具做重构，最怕它一口气给我输出五百行代码。看起来逻辑完整、注释齐全，跑起来却全是低级错误：类型对不上、函数引用不存在、该改的地方没改、不该动的地方反而被顺手“优化”了。更麻烦的是，它不会主动跑测试，也不会在动手之前问清楚项目结构，结果项目越改越乱，最后只能整体回滚。我一度怀疑是自己的用法不对，直到接触了 Superpowers——一种给终端AI编程工具注入“技能（Skills）”的增强方案——才意识到问题出在缺少工作流约束。

所以这篇文章不会只贴一张命令列表了事。我会从“它到底解决了什么问题”讲起，然后拆解技能机制、安装接入路径、几个真正好用的技能，最后单独分享我在Java项目里折腾出的经验和踩过的坑。无论你是第一次听说，还是已经装了一半卡住，应该都能找到对应的章节。

1. 为什么我会关注Superpowers这个AI编程“外挂”

1.1 从一次“AI爽文式编程”现场说起

大约两个月前，我在一个内部小项目上想偷个懒：让终端AI给现有列表页加一个分页功能。我原本的预期是它改一个查询方法、调一下前端参数就完事。结果它很“积极”：先自己创建了一个新的service类，又把原来的DAO重命名，顺手把列表页的组件结构也重构了。功能确实加上了，但代码审查的时候我对着三百行diff完全不敢合并。这件事让我意识到：现阶段的AI编程工具不是不够聪明，而是太容易顺着“把任务完成”的思路跑，缺少一个资深工程师进场时自带的那套“做事方式”。

这个场景你大概率也遇到过。大模型被训练得特别擅长续写，你给它一个目标，它就往下补剧情。在纯聊天场景里这没问题，但在代码库里，这种“补剧情”式的编程就是灾难。它补出来的代码往往语法漂亮、变量名考究，可是没有经过编译验证、没有测试覆盖、没有和项目现有模块做依赖分析，充其量是一段“看起来对的幻觉代码”。Superpowers 这类工具之所以能火，就是因为它把“老工程师怎么做事的步骤”固化下来，让AI照着执行，而不是凭着语感往下编。

1.2 “会聊天”不等于“会干活”：终端AI工具的现状

先说说这类工具的背景。Claude Code、Codex CLI 这些终端AI编程工具，和聊天网页版最大的区别是有“行动力”：能读文件、能执行命令、能改动整个目录。这个能力是双刃剑。一方面，它真的可以帮你改完一整个功能；另一方面，如果它绕过了验证环节，副作用也会被放大。你知道一个改了接口签名但没跑编译的AI，能在十分钟内制造出多少个编译错误吗？答案是：你项目里每一处用这个接口的地方，都会“精准爆炸”。

我见过好几种典型翻车方式。一种是不跑测试就宣布完成；一种是改完一个文件但不知道谁在引用它；还有一种是AI为了“让代码更优雅”，自作主张重构了和需求完全无关的部分。这些问题本质上都是同一个原因：模型按照概率生成代码，而不是按照工程流程推进代码。要解决它，光靠你在对话里反复吼“先写测试、不要乱改”效果很有限，因为人不会每次敲指令都保持同样的语气和维度。这时候，把规则写进一套可复用的“技能”里，就成了更可靠的方案。

1.3 Superpowers 的第一印象和适用人群

我第一次跑通 Superpowers 的时候，最大的感受是：AI 好像换了个“性格”。同样一个任务，它不再第一时间甩代码，而是先输出一个简短计划，然后问我“这个函数的边界条件你希望怎么处理”。这种变化不是模型的功劳，而是技能在起作用——它的工作流里明确写了“动手前先确认需求、先写失败测试、在小步提交后再进入下一步”。

我不是说要吹它有多神奇，但它的定位很清楚：给那些已经具备读写文件能力的终端AI工具，补上一层“工程流程约束”。如果你习惯先写测试再写实现，喜欢小步提交、随时能回退，希望AI改动代码的时候带上理由而不是直接动手，那这套东西会很对你的胃口。反过来，如果你只是想快速生成一个demo，或者让AI临时写段脚本跑一下，那大可不必上这套体系，普通的AI对话反而更省事。

2. Superpowers的核心机制：为什么它比普通提示词更管用

2.1 技能的本质是什么

Superpowers 里最核心的概念就是“技能（Skill）”。我理解它的方式很简单：技能是一套“结构化说明书”，告诉AI在遇到某一类任务时，应该按什么顺序做哪些事、每一步做到什么程度算完、哪些行为绝对不能做。

打个比方。普通提示词相当于你跟AI说“去把晚饭做了”；而一个技能相当于一份菜谱加厨房守则：先检查冰箱里有什么、洗菜切菜按什么顺序、热锅冷油还是热锅热油、出锅之前怎么试味、做完之后怎么收拾台面。AI原本就会“做饭”，但有了这套说明书，它做出的饭才稳定。代码场景里也是一样：TDD技能规定它必须先写测试、运行后看到失败、再写实现；Git技能规定它在关键节点做小步提交，并且每条提交信息符合项目规范。

2.2 与普通提示词的本质差异

区别不只是“更详细”。普通提示词你写多长都是“一次性”的东西，下一次对话它可能又忘光了。技能则是体系化的：有描述、有触发条件、有步骤、有验收标准，还能反复复用。更关键的是，很多技能体系采用了渐进式加载——AI不会把几十个技能的全文一口气吞进上下文，而是先读一个技能清单文件，看到每个技能的名字和一句话说明，遇到匹配的任务再去加载对应的详细文件。

这种设计非常聪明，因为上下文窗口始终是稀缺资源。如果每次对话都把全部技能的详细步骤塞进去，token消耗会把成本直接拉爆，对话也会因为上下文过长而变得迟钝。渐进式加载相当于给AI配了一本目录和索引，用到哪章翻哪章，这和我自己查文档的习惯其实一模一样。

2.3 一个技能文件通常包含什么

从实用角度说，一个好的技能文件至少会包含这几块内容：触发场景、前置条件、主流程步骤、每步的执行要求、完成标准、以及禁止事项。触发场景用来判断“什么情况下该干活”，前置条件和项目约束挂钩，主流程步骤是核心，禁止事项则是用来拦住AI各种“自由发挥”的冲动。

我特别喜欢技能里“完成标准”和“禁止事项”这两块。完成标准能防止AI做到一半就说“做完了”，禁止事项能拦住类似“顺手重构无关代码”“跳过测试直接提交”这类行为。例如在Bug定位技能里，常会出现一条很硬的规定：在没有复现问题之前，不允许提出修改方案。就这一条，就能挡住大部分“看代码靠猜修bug”的低级操作。

3. 安装与接入：让Superpowers跑起来的完整路径

3.1 先确认前置条件

动手之前先确认你自己的环境。Superpowers 不是独立软件，而是寄生在终端AI编程工具之上的增强层，所以你必须先有一个能跑命令的终端AI工具。目前我试过的环境里，Claude Code 的适配度最高，Codex CLI 也有社区适配方案，其他带有“技能/插件目录”的终端工具理论上也能用，只是文档成熟度不同。

另外建议把AI工具升级到较新版本，因为技能加载依赖一些版本较新的配置项。操作系统层面，macOS 或主流Linux发行版最省心；Windows下我见过有人用WSL跑通，但没亲自试过，暂不评价。安装前注意备份一下AI工具的配置文件，因为安装脚本有可能会往里写默认路径，万一后悔了还能还原。网络方面，只要你的机器能正常访问代码托管平台和官方仓库就行。

3.2 通用安装路径：三步走

因为项目本身的安装说明会持续更新，我在这里只给通用思路，具体命令请以官方仓库为准。

第一步，克隆或者下载 Superpowers 仓库，把项目目录放到你觉得顺手的本地位置。第二步，查看仓库里的安装文档，通常会提供一个安装脚本，或者要求你把技能目录软链到AI工具约定读取的目录里。第三步，重启AI工具，让它重新加载配置。

这套三步走看起来简单，但每一步都有值得注意的地方。比如脚本安装省事，但你要能接受它可能修改你的全局配置；手动软链自由度更高，适合你已经有一套自己的技能体系、需要把两者合并的场景。我自己的习惯是：先看脚本到底动了哪些文件，再决定用脚本还是手动，绝对不闭眼执行网上来路不明的命令。

3.3 Codex CLI 的接入思路

很多人搜“codex superpowers”其实就是想回答一个问题：这套技能到底能不能给 Codex CLI 用？从社区现状看，答案是“能，但要手动桥接一下”。Superpowers 早年主要是面向 Claude Code 的技能体系，Codex CLI 本身没有完全相同的“技能目录”概念，但我们可以用一个通用的办法：把技能文件放在项目目录中，然后在 Codex 会自动读取的项目说明文件里写清楚规则，告诉它“当遇到XX类任务时，去读哪个技能文件，并按照里面的步骤执行”。

这本质上就是给 Codex 当“翻译官”。我在这样做之后，Codex 也确实能表现出类似 Claude Code 的工作流程。需要提醒的是，不同版本的 Codex 对项目说明文件的读取策略有差异，如果你发现它完全没按技能走，优先去项目文档看看当前版本支持的协议有没有变化，不要急着怪技能本身。

3.4 怎么验证安装成功

安装完别急着部署大活，先做两个验证。最直接的验证方法是问AI“你现在掌握了哪些技能”，如果它列出了一串技能名字和用途说明，说明技能清单已经被加载。第二个验证是触发一个具体技能试运行：让它实现一个带测试的简单函数，观察它有没有先创建测试文件、执行测试、看到失败（红灯），再开始写实现。只要出现这个“先测试后实现”的行为顺序，基本可以断定核心链路已经通了。

提示：确认技能是否生效，看的不只是AI回答变长，而是行为顺序有没有改变。如果它还是直接甩实现代码、测试后补，说明技能根本没被触发。

我见过不少新手装完就问AI“能不能帮我写个快速排序”，AI正常输出代码就以为成功了，其实那只是普通对话能力在起作用，技能根本没触发。记住，技能触发的标志是“行为顺序改变”，而不是回答变复杂。

4. 核心技能逐个拆解：哪些技能真正改变了我的使用习惯

4.1 TDD技能：从“先写代码”到“先写测试”的强制纠正

我先把话放这：如果只允许我保留一个技能，我选TDD技能。它带来的最大变化，是让AI从“写完代码再看结果”变成“先写测试再写实现”。具体工作流是：先理解需求，把用户故事拆成可验证的行为；然后编写测试用例，运行测试并确认红灯；接着写最小实现代码，直到测试通过；最后在绿灯状态下做重构，确保重构后依然通过。

这个流程最反直觉的地方在于“确认红灯”。很多人写代码习惯直接写实现，连测试都不写；而习惯写测试的同学，又常常忽略先跑一次看它失败。红灯确认其实很关键，它证明测试真的在检测缺失的行为，而不是一个永远通过的摆设。AI一旦有了这一步约束，产出的代码质量完全不是同一个档次。我在实际使用时，甚至会让AI把“红灯输出结果”贴进对话里作为证据，强制它不糊弄。

4.2 Bug定位技能：没有复现就不允许动手

另一个我很常用的技能是Bug定位。它规定AI拿到问题报告后，必须先复现问题、收集完整的报错堆栈、划出“问题出现前的最后一次改动”，然后再提出“可能是根因”的假设，最后才谈修改。这个顺序对Java项目尤其重要，因为Java的错误多半跨了好几个类甚至好几个模块，凭眼睛看代码猜根因，十次有八次是蒙错。

我个人的体会是，这项技能治好了AI的“手痒病”。没有这个约束时，AI看到NPE就会自动在那一行前后加空指针判断，看起来是在“修”，实际上只是在掩盖症状。有了复现要求后，它老老实实先跑一遍，通常会发现NPE的源头是某个上游模块返回了空集合，问题根本不是那个局部变量。

4.3 Git技能：小步提交，让AI的每一步都可审查

第三个值得重点说的是Git工作流技能。它会在关键节点自动创建提交，并且要求每次提交只包含一个逻辑改动。比如“实现分页”“修复参数校验”“补充单元测试”各是一个提交，而不是把所有东西混在一个大提交里。

为什么这个能力这么重要？因为它把AI的执行过程从“黑盒”变成了“可审计”。每一次提交我都可以单独用 diff 去查看，一旦发现它改了不该改的地方，直接单独回退那个文件。这个流程让我敢把更难的任务交出去，因为任何一步出问题都能精准定位，而不是面对一堆扯不清的改动文件干瞪眼。

4.4 计划与自查技能：有些AI的“自觉”是需要被流程逼出来的

最后说说计划和自查这组技能。它们的核心是两点：动手前先输出计划，完成后对照计划逐条自查。听起来像形式主义，但在AI场景里价值很大。计划能提前暴露AI理解偏差，比如它准备改的模块根本不是需求涉及的那一个；自查则能拦住“开口就说完成了”的老毛病，因为流程会要求它对变更文件、测试结果、是否遗留调试代码做逐项确认。

我还喜欢在计划技能里加一句“列出你明确不在本次任务范围内做的事”。这句话特别管用。AI一旦把自己的边界写下来，后续它去乱动无关文件的概率会明显降低，因为它等于给自己立了一个书面承诺。

4.5 哪些技能我建议先别碰

也不是所有技能都适合一上来就全套上。我看到有些增强包里带了“自主探索大型代码库并独立完成功能”这类高自由度技能，描述看起来很爽，实际用起来很容易失控：AI在没搞懂业务规则的情况下大规模改代码，最后变成给我留了一堆需要人工复核的“惊喜”。建议新手先避开这类高自由度的技能，从TDD、计划、Git这种行为约束型技能起步，等对“AI如何按技能工作”有了体感之后，再尝试更激进的玩法。

5. Java场景下的Superpowers实践：从Maven多模块到测试策略

5.1 Java项目为什么更需要工作流约束

Java项目大概是当前终端AI编程最容易翻车的类别之一。原因很现实：类型系统严格、编译链路长、框架习惯重，而且绝大多数业务项目都是Maven或Gradle管理的多模块工程。AI在脚本语言环境里改错一两个函数，可能过了半天才暴露；在Java里改错一个接口签名，全项目的编译错误立刻就糊你一脸。

也正因为如此，Java项目其实比 Python 或 Node 项目更依赖工作流约束。比如“先编译再继续”“改公共接口前必须搜索调用方”“测试命令要精确到模块”这些规矩如果没人强制，AI就只会按统计惯例继续写“看着像Java”的代码，而不是“真正能在你的项目里编译通过的代码”。把 Superpowers 装起来后，我第一条自定义技能就是“Java编译检查前置”。这条技能生效后，AI每次改完代码都会先运行一次模块级编译，确认没有引入错误再继续下一步，项目稳定性提升立竿见影。

5.2 Maven/Gradle多模块环境下的实操注意

多模块项目里，最坑的一件事是AI分不清模块边界。我遇到过一次：想让AI在支付模块加一个回调接口，结果它顺便把基础模块的公共异常类签名给改了，理由是“为了统一错误处理”。它汇报的时候还很得意，我一编译才发现所有模块都在报错。从那以后我给自己立了规矩：在技能或项目说明文件里明确写“一次只允许改动一个业务模块；修改公共模块前必须列出所有受影响模块并逐一确认”。

另外一个实操点是测试命令不能让它猜。Maven项目里，模块级测试可能是mvn -pl payment -am test，Gradle项目里则是gradle :payment:test，命令完全不同。我建议在项目根目录的说明文件里，把这三类命令写死：快速单测命令、模块级测试命令、全量编译命令。AI就不用每次推理该用什么命令了，直接照做，省时间也少出错。

5.3 测试策略与Superpowers的适配

Java项目的测试体系往往比脚本项目更重：有单元测试、有集成测试、有需要外部中间件的容器测试。如果让TDD技能默认跑“所有测试”，一次构建能磨蹭十几分钟，AI的上下文窗口分分钟被撑爆。所以我在技能定义里做了分层配置：开发阶段只跑快速单元测试；涉及数据库、消息队列的功能，跑指定的集成测试类；全量回归单独作为收尾指令。

这一步配置好之后，TDD技能才能真正在Java项目里跑得动。否则它会因为测试时间过长而“卡住”，或者因为超时被迫跳过验证——一旦跳过验证，整个技能体系的约束力就崩了。所以在Java场景里，与其说是 Superpowers 适不适用于Java，不如说你要先把项目的测试分层这件事做扎实。

5.4 Java项目里的踩坑记录

最后分享几个真实的坑，希望能帮后来人少走弯路。

坑一：Lombok。AI经常把 @Data 生成的 getter/setter 当成手写方法去修改或补全，结果编译直接失败。解决方法是技能的前置条件里写清楚“如果实体类上有Lombok注解，不允许修改类中那些看起来像是样板代码的方法”。

坑二：AI引用了项目里根本不存在的测试框架。比如项目用的是JUnit 5，它凭空写出 JUnit 4 的注解和断言。这个很难靠技能完全拦住，因为模型对“常用框架”统计上很熟练。我能给的建议是，在项目说明文件里显式写明当前用的测试框架、版本和典型测试写法，并把一个标准测试类作为示例贴上去。

坑三：多模块编译顺序。AI在一个模块里改了依赖另一个模块的接口，自己没有去跑调用方的编译。对此单纯靠它自觉是很不靠谱的，最有效的还是我在前面提到的：把“模块级编译命令”写进项目说明文件，并让技能规定“修改公共接口后必须运行依赖方模块的编译测试”。

坑四：全量测试跑太久导致上下文超限。前面说过的测试分层就是为这个准备的。如果你发现AI开始反复重看测试输出直到把上下文塞满，不妨先检查一下是不是没有给它配置“只跑模块级测试”的硬性规则。

6. 使用Superpowers一段时间后的真实感受与避坑清单

6.1 什么时候该用，什么时候别用

用了一段时间后，我开始对它的边界有清晰的认识。我的建议是：凡是需要“可审查、可回退、高质量”的代码工作，比如主线功能开发、老代码重构、高测试覆盖模块的维护，都适合把Superpowers的技能流打开。尤其当你需要把任务交给AI然后还要对它负责时，工作流带来的审查便利比生成速度重要得多。

反过来，探索原型、一次性的数据迁移脚本、临时调试代码这些场景，就别上技能了。这些任务重在快速和灵活，上流程反而容易让简单事情变复杂。我自己现在会先估一下任务性质：如果这个代码未来三个月还要维护，我会让AI带上技能干；如果它只是今晚临时验证个想法，我直接用普通对话。

6.2 三个高频坑和应对方案

技能升级漂移这个坑我踩得最多。因为技能本质也是代码和文本，维护者一调整，行为就会变。我现在会锁住技能的版本，除非有明确的新特性想要，否则不轻易跟着最新版走。每次升级前用 diff 看它到底改了哪些步骤描述，再决定要不要升。

6.3 我建议的起步配置

如果你刚准备入坑，我建议控制住自己的手，别一次性把所有技能都装齐。起步阶段装三个就好：TDD技能、Git小步提交技能、计划优先技能。先找一个你熟悉的小模块，让AI按这套流程实现一个带测试的小功能，跑通一个完整的“计划→测试→实现→提交”闭环。这个正向体验比任何教程都管用。

跑通之后，再把你团队的代码规范里最要紧的一条写成一个极简技能，格式先照葫芦画瓢，不用追求全面。比如我们团队强制“禁止直接使用裸的 System.out”，我就写了一个对应技能，AI每次提交前会自查输出语句。这种自定义技能体积不大，但非常贴合实际。

6.4 后续扩展方向

我目前还在尝试的方向有三个。一个是把代码审查checklist写成技能，让AI在提交后先按checklist自查再交给我review。另一个是把技能和本地CI脚本结合，让AI在执行完测试后顺手解析CI日志，提前发现那些“编译过了但明显不对劲”的警告。还有一个是多工具复用，同一套技能文件在 Claude Code、Codex CLI 之间迁移，争取把维护成本降下来。这几个方向还在试验中，等跑稳定了，我会再写一篇专门分享。

6.5 最后的个人建议

我个人的体会是，Superpowers 这类把工作流写进AI的工具，真正改变的不是代码生成速度，而是审查成本。AI编程工具已经足够聪明，缺的往往不是智力，而是流程。一套好的技能机制，等于给AI装上了“先想后做、边做边验、小步可回退”的行为约束。最后再分享一个小技巧：别一口气把所有技能都装上，先挑一个最匹配你团队痛点的技能，用一周做顺手，再叠加下一个。技能这东西，不是为了“显得专业”才装，而是为了每一次AI动手之前，你都能更放心地把活交给它。