最早注意到 superpowers 这个词是我在一次 Code Review 被 Agent 改坏了数据之后。那天我让 Claude Code 去改一段支付回调的逻辑它一口气动了四个文件没有加一个测试还把异常处理悄悄删了。模型确实够聪明但它像极了一个刚入职的实习生——知识量很足却不知道什么时候该先查文档、什么时候该先写测试、什么时候该停下来问一句你确定要这么改吗。后来在社区里反复看到 superpowers第一反应是又一个吹得很神的 prompt 包。真正在项目里装完、跑完一圈才发现它解决的问题不是让模型更聪明而是让编码 Agent 像个有章法的工程师。这篇文章就是我近几周在 Claude Code 和 Codex 上的真实使用记录包含安装方式、核心技能拆解、Java 项目完整落地流程以及几个花了不少时间才想明白的坑。给那些已经接触过 AI 编程、但总觉得 Agent 干活方式不靠谱的开发者一个相对完整的参考。1. 在动手安装之前先搞懂它到底解决什么问题1.1 模型不傻但 Agent 缺的不是智力而是流程现在的大模型单看知识量已经足够吓人了你说 TDD、Code Review、依赖倒置它都能接上话。但问题恰恰出在这里——它知道一切却不代表它在具体任务里会主动使用。你丢给它一个 bug 描述时如果没有额外约束模型会默认把修改代码当成唯一目标因为它的行动逻辑是跟着概率走而不是跟着工程方法论走。我在裸环境下做过一个简单的观察让 Claude Code 修一个空指针异常它最常见的路径是定位到异常行 - 加一个 if null 判断 - 结束。听起来好像没问题如果这只是语法层面的修复确实没问题。可一旦涉及真实系统这个路径会漏掉三件关键的事根因是否在调用方、是否有其他调用点同样受影响、是否该为这个场景补一条回归测试。这三个问题恰恰是一个有经验的工程师在动手前就会问自己的。superpowers 的核心思路就是把这类优秀工程师的行为习惯固化成一套文字化的技能体系在正确的时机喂给 Agent。它没有教模型新的知识而是给 Agent 加了一套遇到什么情况就执行什么流程的约束。对很多团队来说这一层约束比换更大参数的模型更有性价比。1.2 它不是一段长 prompt而是一套可递归调用的技能链很多人的第一反应是这不就是给模型写一个超长 prompt 吗我自己一开始也这么想后来发现区别很大。一段长 prompt 是一次性的。你这次跟 Agent 说要先写计划、再写测试、再实现下次换一个会话它又回到原始行为。superpowers 的做法是把流程写成独立的技能文档存放在插件目录或项目目录里Agent 按需读取。你通过/superpowers菜单触发一个技能它就会加载对应的说明文档然后按照里面定义的步骤行动。这个过程不是固定的对话模板更像给 Agent 装了一套操作手册 查表机制。更有意思的是技能可以组合。比如一个修 bug的技能内部可能拆成复现问题 - 写失败测试 - 最小修复 - 回归验证四个子技能一个评审技能可能先调用检查变更范围再调用检查测试覆盖。子技能之间可以串联形成一条链路。有些复杂技能还支持将上一个技能的输出作为下一个技能的输入这就是社区常说的 skill chaining。换句话说superpowers 把方法论做成了可组合、可版本化、可分享的文件。对一个团队来说这意味着优秀工程师的做事方式可以沉淀进仓库而不是只存在于某次对话的 prompt 里。1.3 同样一句帮我修个 bug装前装后差距有多大我在一个内部测试工程里做过一次对比请求内容完全一样只是环境一个是裸 Claude Code一个装了 superpowers。对比维度裸 Agent 的典型行为接入 superpowers 后的典型行为接到问题后直接找代码改完就输出 diff先要求复现步骤或构造最小复现用例测试除非明确要求基本不跑先尝试写一条能暴露问题的失败测试修改范围趋向最小的局部修改会先列出受影响文件并说明影响面收尾解释改了什么跑回归验证并给出验证结果自审通常没有可触发 review 技能按清单自检这个表格不是说装了之后就一定每一步都完美执行但行为模式的改变是稳定的。我后来把所有项目都默认接入了这套流程因为哪怕只有一半任务能自动走完流程也能省掉我大量的 review 时间。2. 安装过程与第一次触发技能的真实体感2.1 在 Claude Code 里装它只需要三条命令如果你用的是 Claude Code安装流程非常短。打开终端在项目目录下先起一个会话claude然后在对话中输入/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace第一条命令是把插件的分发仓库地址加进 marketplace 列表第二条命令是从这个 marketplace 安装 superpowers 本体。装完以后在会话里输入/superpowers会看到一个技能菜单列出当前可用的全部技能清单。这里有个容易忽略的点安装命令需要在项目目录里执行装好之后技能会绑定到当前项目但插件本身是全局的新项目可以直接/superpowers调出菜单。我第一次装的时候以为每个项目都要重装一遍后来才发现不需要。如果你是公司网络环境先确认终端能正常访问 GitHub 仓库否则 marketplace add 那一步会卡住。2.2 别跳过 bootstrap它是 Agent 的入职培训装完插件只是第一步。我的建议是对现有项目先在项目根目录用一次bootstrap技能。这个技能做的事情非常像给 Agent 做入职培训它扫描项目结构、识别构建工具、找出测试框架、分析 README 里已有的约定然后把这些信息整理成一份CLAUDE.md文件。这份CLAUDE.md就是 Agent 长期记忆的核心。以后每次会话启动它都会先读这个文件于是它会知道这个项目用的是 Maven 而不是 Gradle测试命令是mvn test而不是./gradlew test核心代码在biz模块而不是web模块。没有这层信息Agent 每到一个新项目就像第一天上班的社招员工全靠猜猜错是常态。我在一个 Spring Boot 多模块项目上跑 bootstrap它生成的 CLAUDE.md 把模块目录、构建命令、测试框架、常用开发约定全部列了一遍。最让我意外的是它连Controller 包位于web/src/main/javaService 在biz模块这种依赖关系都梳理出来了省掉了我手动喂上下文的功夫。提示bootstrap 会写入或修改项目根目录的CLAUDE.md。运行前建议先保证工作区干净或者先看一眼它将要写入的内容再决定是否保留。我第一次跑的时候它在已有 CLAUDE.md 的基础上做了合并方向是对的但还是应该走一遍 diff 确认。2.3 第一次触发技能时发生了什么我第一次真正触发技能是让 Agent 给一个功能写实施计划。我在会话里输入/superpowers选择一个计划类技能接下来的行为跟裸环境完全不一样。Agent 没有直接去改代码而是先花几分钟输出了一份计划文档里面包含目标、非目标、涉及文件、测试策略和分步任务清单。然后它创建了一个 TODO 列表开始逐条执行每完成一项就在 TODO 上打勾并且会在推进到下一步之前先向我确认关键假设。从日志行为看它在触发技能时明显读取了对应的技能说明文档并把文档中的流程转化成了自己的执行路径。给我的体感就像是一个工程师翻出了一本《XX 系统故障处理手册》然后照着目录逐条执行。这种可复现性是单纯靠对话里临时说一句请你先做个计划很难稳定的。有一点要提醒技能链路执行到一半时尽量别打断它去问无关问题。Agent 需要维护当前技能的执行状态一旦你插入另一个高优先级的指令它可能忘记自己进行到哪一步。我踩过一次任务进行到第三步时我让它先帮我查个别的东西它回来后整个流程就断层了。合理的做法是等一个子技能结束再插入新请求或者重新触发一次技能。3. 一圈用下来我觉得最值得先掌握的是这四个技能superpowers 提供的技能清单很长但我在真实项目里反复使用的其实集中在四个方向想清楚、定计划、写测试、做评审。下面逐个说一下我的使用体验和判断标准。3.1 brainstorming把模糊诉求变成一张决策表很多时候团队给我的需求是这个页面有点慢优化一下或者是订单流程不太稳帮忙看看。这种模糊诉求直接丢给 Agent它大概率会按自己的理解动手而你很难判断它的理解对不对。brainstorming技能就是用来处理这种场景的。触发之后Agent 会围绕目标展开一轮结构化的发散先列出目标和非目标补出约束条件识别潜在风险再给出一个可执行的测试策略和验收标准。它不会马上写代码产出物是一段可以拿回去和团队对齐的决策内容。一个实际例子我说想优化订单列表慢查询brainstorm 输出的结果里明确写了非目标不调整现有表结构约束现有索引不允许新增大字段索引风险分页深翻页在大数据量下仍有性能波动验收P95 响应时间从 800ms 降到 300ms 以内。这些内容里有相当一部分是我没想到或者没想完整的。对团队讨论来说这几乎等于多了一个免费的需求分析师。3.2 writing-plans 和 executing-plans把计划与执行拆成两件事这两个技能通常搭配使用。writing-plans负责把想法写成正式计划文档内容包括背景、目标、涉及范围、风险、任务拆分、测试方案executing-plans负责把计划里的任务转成可执行的 TODO并逐条落实。为什么要把计划与执行分离开我的理解是一旦 Agent 开始写代码它的注意力会被细节遮蔽容易忘记最初的整体目标。先写计划、再执行能在动手前就把可能出问题的点暴露出来。尤其是跨模块、跨文件、涉及数据迁移或接口兼容的改动先有计划后动手返工率能降一截。我现在的习惯是改动涉及两个以上模块或者会改变对外接口行为就走一遍 writing-plans - executing-plans。单文件小改动就直接改不做完整仪式。计划文档建议保留在docs/plans/目录下它本身就是一份很好的变更设计记录后续 review 也有据可查。3.3 review让 Agent 先当自己的 Code Reviewer昨天让 Agent 写了一段新的权限校验逻辑写完我直接触发 review 技能。它没有立即输出代码写得不错之类的话而是按清单做了一遍自审先列出本次改动涉及的所有文件再逐项检查异常处理、边界条件、安全风险、资源释放、测试覆盖最后给出问题清单和建议修改。这次 review 发现了两个我在初看时完全没注意到的问题一是某个分支里把Optional.get()直接拿来用了却没有前置判空二是 catch 块把异常信息吞掉了只记录了日志头没有记录异常栈。这两个问题虽然不一定马上让程序出错但在生产环境的排查链路里都是隐患。让 Agent 在提交前自审一道等于多了个不知疲倦的代码门禁。有一点要诚实说review 技能不能替代同事的人工 review。它擅长发现局部代码里的逻辑漏洞和规范问题但判断不了产品语义是否正确、这个功能是不是用户真正需要的。所以我的用法是先用它做机器自审再交给人工 review效率和质量都有保证。3.4 debugging 和 test-driven-development用流程治上来就改的毛病debugging技能解决的是根因分析问题。它的流程是复现问题 - 构造最小复现用例 - 列出所有可能假设 - 逐个验证假设 - 做最小修复 - 回归测试。这套流程听起来很基础但对 Agent 来说意义重大因为裸环境下的 Agent 最常见的做法是看到异常栈直接搜代码然后猜一个原因就改。test-driven-development技能则是把红绿重构的循环变成显式步骤先写一个会失败的测试再写最少代码让它通过最后做安全重构。我在加入这个技能后Agent 产出的代码明显更稳因为它每写一个功能都要先面对一个失败测试这个约束把大量低级错误挡在了早期。指标裸 Agent使用 TDD 技能是否先写测试很少固定先写失败测试测试与实现的顺序实现完可能补一个测试测试先行再用实现去满足重构安全性重构后不跑测试每步重构后跑测试确认适合任务探索性脚本、临时修复核心业务逻辑、接口、工具类需要说明的是我并不是建议所有任务都上 TDD。对我而言探索性脚本、一次性数据修复用 debugging 流程就够了但凡是会长期维护、被多模块依赖的核心逻辑一律走 TDD 技能。这个判断标准可以在 CLAUDE.md 里写上让 Agent 自己根据任务类型选择。4. 在 Java 项目里落地一个 Spring Boot 接口改造的完整记录4.1 为什么 Java 项目更需要这套操作手册如果说 JavaScript 项目里 Agent 是半生不熟但能凑合干活那 Java 项目里就是经常性找不到北。根本原因在于 Java 项目的构建链比动态语言长得多有 Maven 或 Gradle 的生命周期有编译期的强约束有 Lombok 这种编译期生成代码的处理还有多模块之间的依赖顺序。我最初让 Claude Code 在一个多模块 Spring Boot 项目里加接口它直接在web模块里写了 Service 层代码可这个项目的 Service 层明明在biz模块导致编译过不去。它看到编译错误之后没有去查模块结构而是尝试给web模块加一个依赖结果把依赖关系搞得更乱。问题不在模型能力而在于它不知道这个项目的物理结构约定。superpowers 对这类问题的解法比较直接把项目的构建方式、模块结构、命令约定全部固化到技能档案里Agent 每次动手前先读这份档案。等于给 Agent 画了一张这个项目的地图而不是让它拿着通用知识到处碰运气。4.2 把 Java 生态信息写进技能档案在 CLAUDE.md 中我增加了下面这样一段 Java 约定### Java 项目约定 - 构建工具Maven所有 Maven 命令在项目根目录执行 - 编译命令mvn -q compile -DskipTests - 测试命令mvn -q test -DtestOrderQueryIntegrationTest - 模块结构common通用工具biz业务层webWeb 与控制层 - 多模块操作指定子模块时使用 -pl biz -am - 约定新增功能必须先编译再写测试最后实现 - 组件Spring Boot 3.2MyBatis-PlusLombok这里的先编译再测试不是废话。Lombok 会在编译期生成 getter/setter 和构造器Agent 只看源码时经常以为某个方法不存在然后瞎改。先跑一次mvn -q compile让编译期把符号表补齐后面遇到的cannot find symbol错误会少一个数量级。这是我踩过很多次之后总结出来的经验。如果项目用 Gradle就把对应命令换成./gradlew compileJava和./gradlew test --tests xxx并在档案里注明 wrapper 版本。同一份文档里写清楚就够了Agent 每次会话开始时都会读到。4.3 实战过程给旧的订单模块加一个查询接口背景是一个维护了两年多的 Spring Boot 订单服务需求是新增按用户查询订单摘要的接口要求按创建时间倒序并带分页。第一步我先让 Agent 用 writing-plans 技能生成计划。它输出的内容包含了三层结构Controller 路由、Service 层方法、Mapper SQL还单独列了个 DTO 定义和集成测试方案。计划里有非目标明确写了不调整现有订单表结构、不改变老接口行为。这个步骤大约花了几分钟但它极大降低了后面返工的概率。第二步我按照计划让 Agent 先写集成测试。它用 MockMvc 写了一组测试用例包括正常查询、空结果的边界情况、非法分页参数。这里遇到一个环境问题项目默认连本地数据库测试环境没有这个库。我让它把测试数据源切换成了 H2 内存库用一条 SQL 初始化用户和订单数据测试就跑起来了。这个取舍牺牲了一点与真实 MySQL 的语义一致性但对这个接口的集成测试来说够用。第三步按 TDD 流程实现。Agent 先看到测试失败然后依次补上 DTO、Service 实现、Mapper XML SQL。比较关键的是 MyBatis 的 SQL 文件没有像 Spring Data JPA 那样自动映射它把 XML 放在resources/mapper目录并让 Mapper 接口与 XML 的 namespace 正确对应。这一步如果不是先有测试约束Agent 很可能会漏掉 XML 的注册。第四步跑完整测试。mvn -q test通过后我又触发了一次 review 技能。它给我列出的问题里有一个确实值得改Controller 层把IllegalArgumentException和NoSuchElementException混在同一个 catch 块里处理导致客户端分不清是参数错误还是数据不存在。拆开处理之后重新跑测试全部通过。这次改动的整体节奏大概是计划 5 分钟测试先行 8 分钟实现 12 分钟review 修复 6 分钟全程不到半小时。对一个陌生老项目来说这个速度足够让人满意了。4.4 Java 场景下最容易翻车的三个坑第一个坑是 Maven 首次拉依赖超时。项目如果很久没更新mvn test会触发大量依赖下载Agent 默认不会等待太久可能在一半失败后就认为环境有问题。我的解法是在技能文档里写明运行测试前先执行mvn -q dependency:go-offline把依赖拉到本地仓库之后的操作会顺畅很多。第二个坑是多模块项目里跑错目录。Agent 如果在web模块目录下执行mvn test它只会编译和测试当前模块父模块的依赖和子模块的测试全部被跳过。更隐蔽的是它可能因为当前模块编译不报错就误以为整个项目没问题。我的处理是强调所有 Maven 命令必须在项目根目录执行跨模块时用-pl加-am参数。第三个坑是我前面提过的 Lombok 编译期符号问题。Agent 看到cannot find symbol: method getId()时会试图在源码里补一个方法而不是意识到这是编译期生成的 getter。规定编译错误先跑mvn compile之后这个问题基本消失了。这三个坑不是 superpowers 特有的而是 Java 生态下所有 Agent 工具都要面对的现实提前写进技能档案比每次都临时纠偏高效得多。5. 不是 Claude Code 专属把同款工作流搬进 Codex5.1 Codex 的定制入口为什么是 AGENTS.md很多人在问 superpowers 是不是只能用在 Claude Code 上我可以说不是。Codex 没有原生的 plugin/marketplace 机制但它支持通过项目里的AGENTS.md文件来注入项目级行为规范。这个文件的作用和 CLAUDE.md 很像每次会话开始时会自动读取并在任务执行中持续影响 Agent 的决策。所以把 superpowers 的方法论移植到 Codex 上本质上是把技能文档翻译成AGENTS.md里的一段流程规范。这并不是削足适履因为 superpowers 的核心资产就是那套文字化的流程而不是某个绑定特定运行时的功能。如果你使用的 Codex 版本支持自定义指令或 prompt pack也可以把技能文档作为一个目录挂进去按需引用。优先级是项目根目录的 AGENTS.md - 自定义指令 - 手工粘贴。先从小规模尝试开始不要一上来就搬整套。5.2 三种移植思路从轻到重第一种是直接翻译。把最核心的几段流程写进 AGENTS.md比如任务开始先列目标、动手前先写失败测试、完成后自审。这种做法的优点是改动极小一条命令都不用装缺点是它只能覆盖少量固定流程无法像原版那样动态跳转多个技能。第二种是技能包方式。如果你的 Codex 客户端支持类似 skills 的目录约定可以把 superpowers 的技能文档拷贝到项目的.codex/skills目录并调整格式和触发词。触发方式通常是在指令中引用技能名称比如请使用 review 技能检查你的变更。这种方式更接近原版体验但需要花时间适配目录格式和触发约定。第三种是手动触发。为最高频的三个流程分别写一个 short prompt需要用的时候复制粘贴。比如我自己的三个固定 prompt让 Agent 先列目标与验收标准、让 Agent 先写失败测试再实现、让 Agent 按评审清单自检。虽然原始但胜在可控、省 token。一段 AGENTS.md 的最小示例大概是这样## 任务工作流 1. 开始任务前先输出目标和验收标准。 2. 列出可能受影响的文件并说明风险。 3. 除非是一次性脚本先写一个会失败的测试。 4. 实现后运行相关测试全部通过才汇报完成。 5. 完成后用不超过 300 字总结改了什么、为什么改、如何验证。这套约束对 Codex 同样有效因为模型底层的知道 vs 主动执行问题并不分家只要把流程变成了显式指令行为就会明显改变。5.3 我在 Codex 上跑的对比结果我在一个 Python 脚本项目里试过同一个修复任务一个内存泄漏问题裸 Codex 会直接修改缓存清理逻辑然后说应该好了。加了 AGENTS.md 流程后它先给出了复现脚本写了一条能证明内存增长的测试再动手改改完跑测试确认。同样是修复差异有没有测试先行这一步最终结果的可信度完全不同。我并没有把原版技能全部搬过来只移植了 plan test-first review 三个流程大概覆盖了原版 80% 的收益。这个性价比是我比较满意的。5.4 要清醒插件级能力无法完全等价迁移如果你是重度 Claude Code 用户转到 Codex 后需要接受一个落差原版技能在运行时可以主动调用工具、读取 diff、执行测试并回填结果而移植到 AGENTS.md 后更多是行为约束没有完整的运行时支撑。比如 review 技能在 Claude Code 里能自己 diff 变更范围在 Codex 里更依赖你先把范围说清楚。所以我给团队的建议是不要追求 100% 还原把方法论和流程定义迁移过去工具能力上的差异在真实任务里慢慢补齐。重点是让 Agent 养成计划先行、测试随后、完成自审的习惯而不是纠结于某个命令或某个菜单选项是否与原来一模一样。6. 几周用下来真正需要记住的几条反直觉经验6.1 技能不是装得越多越好装了 superpowers 之后技能菜单一整屏。我一开始本着都要试试的心态把能用上的技能全开了结果 Agent 变得极度爱走仪式改一个变量名都要先给你写三页计划调一个参数都要先列风险清单。这种状态下效率反而下降。我的实际做法是默认只保留四个高频技能——计划、执行、review、TDD其他技能按需手动触发。也就是说不让技能全局自动运行而是我在需要时通过/superpowers菜单主动选择。这样既保留了流程约束又不会被仪式感拖垮。6.2 它救不了项目本身很乱的烂摊子这是我最想说的一点。如果项目本身没有一个稳定可跑的构建命令测试套件是红的模块边界一塌糊涂那再好的技能也只是给混乱增加流程开销。技能依赖的前提是项目存在清晰的上下文入口而这个入口需要项目本身基本是健康的。我接手一个遗留系统时直接让 Agent 走完整流程结果它花了大量时间在分辨是它的理解错了还是项目本身跑不起来。折腾一圈我才意识到应该先自己手动把mvn test跑绿把构建问题解决掉再把 superpowers 接进来。先让项目恢复基本秩序再谈 Agent 流程。6.3 Token 消耗不是免费的午餐走完整技能链路会显著增加 token 使用量。技能文档加载、计划生成、测试编写、review 自审每一步都在消耗上下文。我实测过一个中等规模改动走完整流程的 token 消耗大约是不走流程的 2 到 3 倍。这不代表流程不该走而是说明它适合用在重要任务上。五分钟能改完的单行修复就不要让它写计划了需要谨慎对待的核心模块改造才值得上完整流程。把技能当作因事启用的工具而不是常驻的默认模式既控制成本又保持效率。6.4 把技能沉淀进团队仓库比个人经验可靠得多我最后做的一件事是把自定义的技能文档和 CLAUDE.md 一起提交到了项目仓库。好处是团队里任何一个人 clone 项目后只要装了 superpowers就自动获得同样的 Agent 工作流。新成员不用重新摸索应该如何指挥 Agent老成员的踩坑经验也能以文件形式传递下去。配合 CI 再加一道Agent 变更必须带测试的检查比如对 PR 做测试文件的 diff 检测就能形成闭环。让 Agent 按照统一流程干活不再是某个人的操作习惯而是团队的工程规范。个人体会如果你让我只留一条经验那就是先让 Agent 学会计划先行、测试随后、完成自审。superpowers 的价值不在于多了多少魔法般的新功能而在于它把这一组工程师习以为常的做事方式变成了一套可以随时迁移到不同 AI 编码工具上的文本协议。现在我发起一个任务第一件事不是让它改代码而是让它先把计划和测试策略说清楚。这个习惯一旦养起来后面省下的是大量返工和 review 时间。