最近在改一个 Java 老项目的遗留代码我被一个问题反复折磨Codex 生成的“修复”在局部看很聪明但放到整条调用链上一看就是错的。它不知道这个异常最早是从哪个过滤器抛出来的也不关心事务边界在哪里更不会主动跑一遍测试验证——改完直接告诉我“应该没问题”。我当时的困惑是AI 编程助手的语言能力明明很强为什么一遇到复杂的跨文件任务就露怯后来我在技术社区里翻到一个叫 Superpowers 的工具包它要解决的问题恰好就是这个把资深工程师的“解题招式”结构化成技能Skills让 Codex、Claude Code 这类以 Agent 方式工作的 AI 编码助手在动手前先加载一套完整的工程方法论——TDD 怎么走、代码审查按什么标准、定位 bug 需要先做哪四件事。它不是让你多写几句提示词而是给 Agent 一套可以复用的“工作肌肉记忆”这也是最近社区里 “superpowers 使用指南”、“superpowers 安装” 这类话题突然热起来的原因。这篇文章不打算讲什么高深理论就结合我的实际落地过程把 Superpowers 是什么、为什么值得用、怎么安装、在 Java 项目里怎么真正跑起来讲清楚最后把踩过的坑整理成一份排查速查表。适合正在用 Codex 或 Copilot 但总觉得“不够靠谱”的开发者也适合想给团队 AI 工作流建立统一规范的技术负责人。1. 为什么是 Superpowers从“聪明”到“靠谱”的差距1.1 默认 AI 助手的四个老毛病先说一个我自己的观察。把 Codex 这类工具用到第三个星期后你会慢慢摸清它的套路它不是一个“水平稳定”的工程师更像一个记忆力超强但没受过正规训练、没读过《临床路径》的实习生。它的毛病集中在这四点上。第一上下文盲区。它确实能读多个文件但当问题牵扯到一条完整的请求链路、一套涉及五个模块的状态变更时它往往只盯着你当前打开的或它最近读过的文件忽略上下游。这一点在 Java 这种强调类型和调用关系的语言里尤其致命——接口、抽象类、Spring Bean 之间的间接调用很多AI 一旦忽略中间层很容易把修复点放错位置。第二没有流程纪律。默认情况下Codex 接到“修复一个 bug”或“实现一个功能”的指令时默认路径是“直接开写”。它先写实现代码写完后补一个“我改了 xxx”就算交差。它不会先写一个失败的测试来复现问题不会在重构之前先确认现有行为也不会主动跑构建。对我来说这就像请了个很积极但完全没受过训练的新人交上去的东西你总得返工。第三过度自信。遇到不确定的 API 或类名时它会凭概率“编”一个看似合理的名字。JUnit 的断言顺序写错、Mockito 的 when/thenReturn 用反、Spring 注解位置放错这类问题我碰到过不止一次。如果在 Java 项目里你让它引用一个它没读过的第三方库它甚至可能直接给你造一个不存在的类然后说“请检查依赖”。第四行为不稳定。同一个问题换个说法问它能给你两套完全不同的方案甚至第二次和第一次互相推翻。你很难在没有统一流程约束的情况下要求它“按上次那个思路继续”因为它的记忆其实是一次性的。我把这些问题统称为“聪明但不靠谱”。语言模型的天花板其实很高但它缺少的是职业工程师身上的那套“默认动作”——先理解再动手、先测试后实现、先复现后修复、先看影响面再改调用链。1.2 Superpowers 的解决思路把工程能力变成可加载的招式Superpowers 的核心思路是把上面这些“默认动作”固化成一份份结构化的技能文档然后在 Agent 启动时按照任务类型自动加载。它不是提示词集合也不是一个插件库它更像一本“作战手册”工程化之后放在你的项目目录里。你可以这样理解普通提示词和技能包的区别提示词是一张便利贴写“你要注意代码质量哦”贴在哪里都行但内容模糊、没有行为约束力而 Superpowers 里的一个技能是一份完整的行为模板有适用场景、前置条件、执行步骤、产出格式甚至还有少样本示例。比如 TDD 技能里会明确规定先写一个失败测试运行它确认失败再写最小实现运行确认通过最后做重构每一步缺一不可。所以 Superpowers 想解决的不是“AI 不会写代码”的问题而是“AI 像个全能但没有方法的人”的问题。它给 Agent 的不是更多的智商而是更可靠的工作套路。这也是为什么它叫 superpowers——它不是直接替你做决定而是给你的 AI 编码助手装上职业工程师的方法论。这里多说一句网上有些人把它理解成“让 AI 自动写全套项目的银弹”这个预期是错误的。实测下来它更像一个“行为护栏”保证 AI 在复杂任务里不至于跑偏但前提是你自己得知道项目要什么、验收标准是什么。2. 核心概念与安装实操2.1 Skills技能机制解析要真正用起来得先搞清楚 Superpowers 里几个基础概念技能Skill、技能元信息Frontmatter、触发条件和技能执行体Body。技能元信息是技能文件开头一段结构化的描述通常用 YAML 写里面记录了技能的名字、用途、适用场景、禁止事项、依赖关系和作者信息。Agent 在扫描技能包时就是靠这段元信息来判断“当前任务该不该用这个技能”。你写自定义技能时这段元信息直接决定技能能不能被正确触发务必多花时间打磨。技能执行体是技能的主体一般用 Markdown 写因为 Agent 阅读文本的效率远高于解析结构化代码。执行体里描述的是具体的操作流程例如前置条件检查确认现有代码能编译确认当前分支状态干净。第一步动作为当前需求编写一个最小失败测试。第二步动作运行测试观察失败信息确认失败原因是需求本身而不是测试写错。第三步动作写最简实现让测试通过。第四步动作运行完整测试套件确认无回归。收尾动作提炼重构点做小步重构并重新跑测试。这类流程如果只用一句“你要做 TDD”来提示AI 大概率会滑过去但当你把每一步都写成明确的动作序列并放在技能包里随任务加载AI 的执行稳定度会高很多。这有点像给实习生一份 SOP 和只是一句话叮嘱的区别。2.2 安装步骤以 Codex 为例下面说安装。以 Codex 为例常见的做法是把技能包直接放到项目根目录下的.superpowers文件夹里然后在项目的AGENTS.md文件里告诉 Agent 去这里加载技能。这个过程其实不复杂大致分四步。第一步获取技能包。最稳妥的方式是从官方仓库或你信任的镜像仓库克隆技能包到本地。这一步的要点是把技能包放在项目根目录下面而不是放在用户全局目录里。全局目录的问题是跨项目共享会导致技能污染A 项目的约定跑到 B 项目里去反而引发混乱。第二步在AGENTS.md中显式声明技能路径。Codex 这类 Agent 在工作时会优先读取项目根目录下的AGENTS.md你可以在文件里写清楚技能目录的位置以及最常用的几个技能名称。这样 Agent 每次启动时都会知道“这个项目配了作战手册”而不是靠运气发现。第三步配置权限。Superpowers 里的多数技能需要 Agent 有执行命令的能力比如运行测试、跑构建、查看 Git 状态。如果你是第一次用建议先把执行权限放开到项目目录内并把命令白名单限定在mvn、gradle、git、java这些常规命令上等熟了你再按技能粒度收紧。第四步验证装载。装完后不要急着写业务需求先让 Agent 做一次现状收集让它列出项目根目录下的技能清单告知当前分支、最近一次的测试结果并说明它打算用哪个技能来处理一个模拟任务。这一步能快速确认装载是否生效也能让你发现权限配置有没有挡住必要的操作。提示AGENTS.md不是所有 AI 编码工具都会自动识别。如果你用的是其他工具请先确认它的上下文加载约定。比如 Claude Code 更习惯读CLAUDE.mdCodex 则偏向AGENTS.md。我自己的习惯是两种文件里都放一段指向.superpowers的说明成本很低兼容性更好。2.3 Java 项目中的目录组织与版本控制装完之后目录结构大概长这样my-java-service/ ├── AGENTS.md ├── CLAUDE.md ├── .superpowers/ │ ├── README.md │ ├── skills/ │ │ ├── tdd/ │ │ │ ├── SKILL.md │ │ │ └── examples/ │ │ ├── code-review/ │ │ │ └── SKILL.md │ │ ├── debugging/ │ │ │ └── SKILL.md │ │ ├── planning/ │ │ │ └── SKILL.md │ │ └── ... │ └── templates/ └── pom.xml在 Java 项目里我会特别建议把.superpowers目录纳入 Git 版本控制。原因很简单技能包本质上是团队的工程规范如果只躺在某个开发者本地那它就不能为团队协作产生价值。提交到仓库后新同事一 clone 项目就拥有整套 AI 工作规范不用再去口头同步“你让 AI 先写测试再写实现”这些事。另一个 Java 项目特有的建议是在技能包里额外放一个java-spec.md或者直接在技能元信息里标注适用的语言版本和构建工具。比如你的项目用 Maven 和 Java 17就在AGENTS.md里写清楚是mvn而不是gradle避免 AI 自作主张生成 Gradle 文件也别让它生成 Java 8 时代的代码风格。3. 实战拆解在 Java 项目里把 Superpowers 用起来3.1 场景一TDD 技能驱动的订单状态机光讲概念容易飘下面用一个我实际做过的例子说明。假设现在有一个需求给订单模块加一个状态机订单从CREATED可以流转到PAID从PAID可以流转到SHIPPED非法状态转移需要抛出业务异常。如果没有 Superpowers我让 Codex 直接实现它的典型输出是一个大而全的OrderStateMachine类附带一堆枚举和 if/else看起来完整但未必符合项目的现有结构。而且它不会先给你写测试你要么事后补测试要么干脆先把自己项目里现成的模式贴给它。用上 Superpowers 里的 TDD 技能之后整个交互序列就变了。Agent 会先问自己一个问题这个需求的最小测试是什么然后它开始写一个失败测试例如package com.example.order.domain; import org.junit.jupiter.api.Test; import static org.junit.jupiter.api.Assertions.*; class OrderStateMachineTest { Test void orderShouldMoveFromCreatedToPaidWhenPaymentSucceeded() { Order order new Order(OrderState.CREATED); order.handle(new PaymentSucceeded(txn-001)); assertEquals(OrderState.PAID, order.state()); } Test void orderShouldRejectTransitionFromCreatedToShipped() { Order order new Order(OrderState.CREATED); assertThrows(IllegalOrderTransitionException.class, () - order.handle(new ShipmentRequested(box-01))); } }写完测试后技能要求它立即运行测试确认红色。这一步不是走过场而是让 AI 真正看到“失败信息长什么样”避免它把“测试写得不对”误判成“实现还没写”。等失败信息确认无误后它才开始写最小实现package com.example.order.domain; import java.util.EnumMap; import java.util.Map; import java.util.Set; public class Order { private OrderState state; public Order(OrderState state) { this.state state; } private static final MapOrderState, SetOrderState ALLOWED_TRANSITIONS new EnumMap(OrderState.class); static { ALLOWED_TRANSITIONS.put(OrderState.CREATED, Set.of(OrderState.PAID)); ALLOWED_TRANSITIONS.put(OrderState.PAID, Set.of(OrderState.SHIPPED)); } public void handle(OrderEvent event) { OrderState next event.desiredState(); if (!ALLOWED_TRANSITIONS.getOrDefault(state, Set.of()).contains(next)) { throw new IllegalOrderTransitionException(state, next); } this.state next; } public OrderState state() { return state; } }然后技能要求再次运行测试确认绿色通过之后再检查有没有明显的重复代码或坏味道做小步重构。这一整套动作走完不需要你一直在旁边指点“先写测试啊”技能本身就把顺序和节奏卡死了。我自己的体会是TDD 技能在 Java 项目里的价值不只是“有测试”而是逼着 AI 先把测试意图表达清楚。很多时候AI 在设计阶段就想歪了但在写测试时它会先暴露出对业务规则的理解你看到这几行测试就能提前发现它把状态流转关系理解错了而不用等它写完一整套实现后再逐行 review。3.2 场景二代码审查与调试技能第二个高频场景是代码审查和 bug 定位。默认情况下如果我丢给 Codex 一个 pull request 的改动它会泛泛地说“代码挺清晰逻辑没问题”。这显然不是合格的审查。Superpowers 里的代码审查技能会强制 Agent 按一套固定结构输出先列变更影响面再按严重程度分级列出问题致命问题、逻辑缺陷、风格问题、遗漏场景最后给出每一个问题的具体修改建议。这套结构能让 AI 的输出从“泛泛而谈”变成“可以直接贴在 review 评论里用”。调试技能就更实用。之前我遇到一个诡异的线上问题订单状态偶发没有持久化日志里明明打印了PAID数据库里却是CREATED。这种问题让我自己查可能要折腾很久。用 Superpowers 的调试技能后Codex 的推理顺序完全变了它不是直接去改保存逻辑而是先列出一个需要验证的假设清单比如事务是否提交、实体类是否有Transactional传播问题、状态字段是不是在快照之后被修改、持久化上下文是否在状态变更后丢了修改。顺着这个清单它迅速把目光聚焦到OrderService里的一个细节状态变更发生在事务提交之前的最后一行但order.handle()返回之后方法里又调用了某个外部缓存组件这个组件通过反射修改了实体字段并触发了实体状态清理。于是“日志里打印了新状态但 Hibernate 的持久化上下文里已经把这个实体标记为 detached”的根因浮出来了。这个案例让我印象很深的地方不是 AI 多聪明而是技能给了它一套“先复现、再假设、再验证、最后修复”的路径。没有这套路径它会直接猜一个最像答案的原因然后改一行代码告诉你解决了。有了这套路径它会先花两轮对话把问题收敛再动手改。3.3 实测效果与 Token 成本当然Superpowers 是有代价的主要就是 Token 消耗。技能包每次随着会话加载会占用一部分上下文窗口。我用下来在没裁剪的情况下一个会话里技能占用的 Token 可能在 2000 到 4000 之间具体取决于技能数量和你写的详细程度。这在小项目里还能接受但如果你的任务本来就很小比如“帮我给这个工具类加一个日志”那是真的没必要加载全套技能。我建议对技能做“分级裁剪”日常维护类任务只加载轻量技能比如代码风格涉及新功能开发和复杂重构的任务才显式要求 Agent 加载 TDD、设计和调试技能。也可以把技能拆成更细的粒度只让当前任务需要的几个文件被读取而不是一次性把整个技能目录注入进去。注意很多技能框架支持“按需触发”即在AGENTS.md里只声明关键技能名而不把技能全量塞进初始上下文。让 Agent 在看到特定任务类型时再去读对应技能的完整 Markdown。这种按需加载的方式能把 Token 开销降到一个更合理的水平。4. 常见问题与排查实录4.1 安装后不生效除了路径还要检查这四个点很多人在安装 Superpowers 之后发现 Codex 的行为完全没变依然是“上来就写代码”。我排查过几次常见原因有四类这里整理成一张速查表。问题现象可能原因排查方法技能目录存在但 Agent 看不到没有在AGENTS.md中显式声明路径打开AGENTS.md检查是否写清.superpowers/skillsAgent 能看到技能但不使用技能元信息里的触发关键词和任务描述不匹配检查 SKILL 文件里的when_to_use字段是否覆盖当前任务类型前几步正常但执行不了权限配置限制了命令执行查看 Agent 输出里的权限拒绝日志放开对应命令换个分支或新 clone 后不生效.superpowers没纳入版本控制确认目录已提交到 Git并在 README 中写明启动步骤4.2 Token 消耗明显增大先做减法再做缓存如果你发现一个会话的 Token 消耗比装 Superpowers 之前高出不少先别急着卸载。多数时候不是技能包本身的问题而是它被塞进了不该塞的场景。给你几个降本的思路。第一按任务选择技能不要把技能包当默认配置全局加载。第二精简技能文档把“背景说明”和“原理”删掉只留操作步骤、检查清单和失败标准因为 Agent 是来执行的不是来理解哲学。第三如果一个技能你反复使用可以考虑把其中最固定的流程直接固化在AGENTS.md里这样 Agent 不需要每次重新读取整个技能文件上下文占用会更小。4.3 技能与项目已有规范冲突以项目为主缝合适配Java 项目里最容易碰到的冲突是Superpowers 的 TDD 技能要求先写测试但你们项目里有一段历史代码根本没有测试基础设施连 JUnit 依赖都没加。这时候如果让 AI 裸上 TDD它会先去加一堆依赖反而引发新的风险。我的做法是写一个项目定制的技能副本把 TDD 步骤里的“先写测试”调整为“先确认当前模块是否有可运行的测试基础设施如果没有先建立最小测试结构再写实现”。这样既能保留技能的核心优点又能和项目现状对齐。记住技能包是你团队工作方式的延伸不是必须原样照搬的教条。4.4 AI 完全不按技能走拆开检查触发链最后一种情况比较挫败技能装了、路径对了、权限也开了但 Agent 还是我行我素。这时候需要拆开触发链逐段排查。先看AGENTS.md里是不是同时写了一大堆注意事项导致技能指令被稀释了。我看过一个例子AGENTS.md 里写了六条规范技能文件有三千字结果 Agent 在最应该触发 TDD 的时候选择了忽略技能因为它觉得“规范太多不知道怎么权衡”。解决办法是把最高优先级的技能放到最前面并在任务描述里显式写“请先阅读并遵守 TDD 技能”。再看技能文件是不是太长了。如果 Agent 在上下文压力下主动截断了技能内容那它就只看到了前半部分流程后半部分的收尾要求全被丢掉了。我的经验是单个技能文件的正文尽量控制在 200 行以内把不重要的背景全部移出只留步骤和判定标准。如果确实需要详细说明拆成两个技能一个主流程一个补充说明。5. 一些实操心得与后续扩展5.1 用了几周后的真实感受连续用了几周之后我对 Superpowers 的态度是值得装但别神化。它最大的价值不是让 AI 写出更多代码而是让 AI 的产出具备可预期性。以前我 review Codex 的改动像是在“摸彩票”现在更像是“走流程”——我知道它会先给测试还是先给实现知道它的输出结构是什么也知道哪些节点需要我去确认。它的局限性也很明显技能本身不会提升模型的理解力。如果项目业务逻辑真的很复杂领域知识很隐晦光靠一套 TDD 技能不可能替代真正的分析与沟通。该你画的上下文边界、该你澄清的业务规则一样都少不了。技能是放大器不是替代品。5.2 自定义自己的技能包从最小模板开始如果你决定把团队自己的方法论沉淀进技能包我建议从最小的模板开始别一上来就规划一个大而全的技能框架。最简结构只要一个文件--- name: our-api-checklist description: 在修改 API 层代码时使用检查请求校验、错误码和兼容性。 when_to_use: 任务涉及 Controller、DTO 或开放接口变更时 --- ## 步骤 1. 列出当前变更涉及的 API 路径和已有兼容性约定。 2. 检查新增或修改的 DTO 是否补充了参数校验注解。 3. 确认业务异常是否都映射到了约定的错误码和 HTTP 状态。 4. 对比上一次发布的接口定义标记所有破坏性变更。 ## 判定标准 - 所有新增字段都有校验约束。 - 错误响应符合团队规范模板。 - 破坏性变更在 PR 描述中显式标注。写自定义技能的几个原则描述里写清楚“什么时候用”比写清楚“怎么做”更重要每一步都要能被执行或检查不写模糊形容词最后一定要有判定标准这样 AI 才能自我检查是否完成。5.3 给团队推广时的建议如果你想在团队里推广 Superpowers我的建议是不要一步到位。挑一个正在用 AI 编码助手的同事先在一个中等复杂度的需求里试点跑通 TDD 技能和调试技能然后让团队 review 一次 AI 产出的 PR。看到效果之后再把技能包纳入仓库并在团队文档里写一页使用说明。推广过程中最容易忽略的是技能版本的维护。技能包进入仓库后它就是代码的一部分应该同样走 review、同样有更新记录。我见过一个团队因为技能包改了一行触发条件结果 AI 在某个场景下不再执行强制测试步骤差点把回归漏掉。所以技能变更也一样要认真对待。另外不要把技能包当作考核工具别拿“你是否按技能步骤执行”来评判 AI 助手。它只是提高成功率的工具项目质量最后还是由人来兜底。你自己心里要始终有这根弦。最后再分享一个我自己的小习惯每次让 AI 动手之前我会先让它把“本次任务适用的技能和关键步骤”复述一遍。这不是为了训 AI而是为了让我自己确认它理解的作战计划和我心里想的是一致的。就这一步帮我避免了很多后半程才发现方向跑偏的尴尬。