做开发这么多年我越来越相信一件事工具本身不产生价值用工具的习惯才产生价值。superpowers 这个名字听起来像游戏外挂实际上是一套围绕 AI 编程助手设计的技能增强方案。它不是要替代 Codex 这类智能体而是给它们装上角色意识、任务拆解能力和自检机制让一问一答变成说清楚需求、看着它规划、一步步实现、最后自己检查结果的完整闭环。这篇文章我把自己的实践过程完整写出来怎么装、怎么配、跑 Java 重构时踩过哪些坑以及排查思路给想折腾又不想走弯路的朋友一条可复现的路径。全程没有晦涩的理论只有我实测过的命令和配置。1. 项目定位与整体设计思路1.1 原生 AI 编程助手到底缺什么先说痛点。我过去直接用 Codex 干活遇到最简单的需求还不错比如给这个类加一个方法它能答得八九不离十。但一旦需求稍微复杂比如重构这个模块保持接口不变把 I/O 和业务逻辑拆开补上单元测试问题立刻出现。第一是没有全局观。默认会话里助手只知道你贴给它的那几段代码和对话历史对项目结构、现有约定、构建方式一概不知。于是它可能往一个明显不该改的地方加逻辑甚至把 package 结构搞乱。第二是没有步骤感。复杂的改动不是一个动作能完成的它却往往试图一次性产出所有代码。一次交互里改十几个文件中间任何一个环节出错后面全部白搭而且很难定位。第三是没有自查意识。模型生成代码后不会自动跑测试、不会对照 lint 规则检查更不会主动说这里我改了私有方法调用方需要同步调整。导致的结果就是输出完之后错误还是要靠人肉去查。这四个字叫上下文缺失加缺乏元认知本质上就一句话默认助手是个很聪明的实习生但没有工作方法。superpowers 想解决的问题恰恰是这个。1.2 设计理念给 AI 装一套工作方法论我当时看到这个方案的时候最认同的并不是它有多少炫酷功能而是它的三个设计原则技能化、可编排、可追踪。技能化是指所有高阶能力都被拆成独立的技能包Skill每个技能包就是一段结构化的提示词加执行脚本。比如写单元测试是一个技能做代码审查是一个技能技能之间互相独立按需加载。这样既不会在无关场景下浪费 token也让行为边界可控。可编排是指 superpowers 定义了一套标准工作流状态机——Plan、Implement、Test、Review。它不会让 AI 自己乱发挥而是强制按阶段推进先读懂需求和约束再产出方案确认后动手写代码写完跑测试最后自查改动范围。每个阶段有明确的产出物也有明确的终止条件。可追踪是指所有关键决策都落成文件或日志。方案写到临时文档里改动列表记录到会话摘要里测试结果与审查清单一并留存。出了任何问题可以回看是哪个阶段、哪一步出了偏差而不是面对一团黑盒输出。这套设计解决的不只是代码写得对不对更深一层是工作方式稳不稳。对个人开发者来说它让 AI 结对变成真正可依赖的流程对团队来说它让 AI 生成的代码风格和提交记录可控也方便人来做 review。2. 安装与快速起步2.1 准备这些前置环境我实测下来的推荐环境是这样这也是项目文档里要求的基线操作系统macOS 14 或 Ubuntu 22.04Windows 建议用 WSL2否则后面有些脚本会有路径问题Node.js18 以上最好用 20 LTS。它底层很多工具链要跑 esbuildNode 16 会有兼容坑包管理器npm 或者 pnpm 都行Git2.30 以上一个已经能用的 AI 编程助手 CLI我这边用 Codex CLI原理上只要是支持读取本地文件的命令行助手都适用先更新一下 Node。比如在 mac 上brew install node20 node -v在 Ubuntu 上curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs这里有一个容易踩的坑如果你之前装过旧版 Node环境变量可能还是指向旧的二进制。装完务必新开一个终端执行which node确认路径确实切过来了不然后面npm install成功后一运行就报语法错误。2.2 三步完成安装第一步拉代码。superpowers 本身是一个用 Node 写的命令行工具安装方式不复杂git clone 你的仓库地址或者官方仓库地址 cd superpowers npm install第二步装全局命令npm link superpowers --version如果能看到版本号说明安装成功。第三步进入项目目录做初始化cd /path/to/your-proj superpowers init这个 init 命令会做几件事在当前项目里建一个.superpowers/目录、一个AGENTS.md约定文件、一个skills/空目录并向你询问项目的构建命令和测试命令。它生成的内容大概长这样superpowers init ? 项目类型: java-maven ? 构建命令: mvn -q package -DskipTests ? 测试命令: mvn -q test ? 代码规范文件: checkstyle.xml我不建议一路回车跳过这一步因为后面所有工作流都依赖这些元数据。我自己的习惯是先手动把构建和测试命令敲准尤其是跳过测试的构建和完整测试要分开写因为 Plan 阶段和 Test 阶段用的命令并不一样。2.3 首次连通性验证装完之后先别急着做真实任务跑一个冒烟测试确认助手能被正确唤起superpowers run 给 AGENTS.md 里的构建命令加一行注释这个指令会触发一次最小工作流读取项目元数据、加载技能、调用后端模型、执行修改。如果顺利你会看到类似下面的输出[plan] 解析需求 [plan] 读取 AGENTS.md [plan] 定位文件 [implement] 修改 src/AGENTS.md [test] 无测试需要执行 [review] 变更内容确认这里我特别提醒一句第一次跑的时候如果输出卡在连接模型那一步绝大多数情况是 API Key 没有设置。superpowers 本身不负责管理密钥它读取的是你原 AI 助手 CLI 的环境变量一般是OPENAI_API_KEY或ANTHROPIC_API_KEY。检查方式echo $OPENAI_API_KEY如果没有直接到 shell 配置里导出这个跟日常使用 AI 助手是一样的。3. 核心功能拆解技能包、项目记忆与四阶段工作流3.1 技能包Skills让助手学会分步做事技能包是 superpowers 最核心的扩展单位。init之后你的项目里会生成这样一个目录.superpowers/ skills/ unit-test/ # 每个技能一个文件夹 SKILL.md # 技能描述与默认提示词 templates/ # 可选模板 scripts/ # 可选脚本 code-review/ SKILL.mdSKILL.md的格式我见过两种一种是 YAML 头加正文一种是纯 Markdown 约定。核心字段都差不多name是技能名description是一两句话说清楚这个技能是干嘛的以及什么样的需求会触发它keywords是触发词列表比如单测、unit test、coverageprompt是真正注入给模型的提示词正文。用一个我一直在用的写单测技能举例它的 description 是这么写的当用户要求为某个类或方法补充单元测试时自动加载。 适用新增测试、修复失败测试、提高覆盖率。 不适用生产代码开发、性能优化。这个描述至关重要。因为 superpowers 是拿这个描述去跟用户需求做匹配的写得太泛它会在不恰当的时机被触发写得太窄又永远匹配不上。我的经验是在 description 里同时写清什么情况适用和什么情况不适用匹配准确率会明显提高。技能里还可以带脚本。比如我写过一个生成 JUnit 5 测试骨架的技能里面放了一个 Node 脚本用来扫描指定类的方法签名自动生成测试方法的空壳。这样模型就不需要靠记忆去猜方法列表直接读脚本输出即可。这个设计很妙——它把模型不擅长的精确枚举交给代码把理解意图和写合理断言留给模型各司其职。3.2 项目上下文注入写好 AGENTS.md助手不再问废话在没有 superpowers 的时候我每次打开新会话都要手动贴一段项目说明这是 Maven 项目JDK 17测试用 JUnit 5类路径在 src/main/java…… 烦不胜烦而且经常贴不全。superpowers 解决这个问题的方式非常优雅它会在每次会话初始化时自动读取项目根目录的AGENTS.md把它注入到系统提示里。这个文件就是这个项目的使用说明书建议包含四块内容项目结构核心目录和模块职责最好是树状图构建与测试命令精确到可直接执行代码约定包命名、异常处理风格、是否允许 Lombok、日志规范约束与红线哪些文件不能改、哪些目录是生成代码、外部依赖来源限制我自己的AGENTS.md开头是这样的# 项目约定 这是一个 Java 17 Maven 工程业务代码在 src/main/java。 包名以 com.example 开头禁止使用 Lombok。 构建命令mvn -q package -DskipTests 测试命令mvn -q test 生成的文件放 target/ 目录不要手工修改 target/ 下的任何内容。写完AGENTS.md之后最直观的感受是助手不再问你们项目的测试命令是什么这种问题了也不再往 target/ 里改代码了。它脑子里始终有这个文件的存在等于给模型接入了项目级记忆。提示AGENTS.md不是越长越好。模型上下文长度有限我建议把内容控制在 60 行以内把信息压成短句。排序上把最重要的红线放最前面因为上下文是前置注入的越靠前越不容易被后续对话冲淡。3.3 自动化工作流计划、编码、测试、评审superpowers 的默认工作流是四阶段Plan → Implement → Test → Review。我实际跑下来的感受是它带来的最大价值不是自动干活而是强制节奏。Plan助手会先解析需求结合AGENTS.md写一个简短方案里面包含涉及文件、改动思路、风险点。这个方案默认会打印出来等用户确认后才会进入下一阶段。如果不加干预它有时候会直接往下走所以我习惯在命令后面加--pause-after plan这类的参数强制它在方案阶段停一下。Plan 阶段的输出大概长这样[plan] 需求解析完成 影响文件OrderService.java修改、PricingService.java新增 改动思路 1. 将价格计算私有方法迁移至 PricingService 2. OrderService 通过构造函数注入 PricingService 3. 保持对外方法签名不变 风险点MQ 事件发送逻辑必须保留在 OrderService 确认方案后进入实施阶段 (y/N)Implement方案确认后助手开始按文件列表逐个修改。这里的细节是它要求一次只改动一个逻辑单元并随时输出进度摘要。用完几次之后我明显发现它的中途错误变少了因为每步都在校验上下文。Test代码写完只是第一步Test 阶段会直接执行你在 init 时填写的测试命令。如果失败它会读取失败日志决定是修复代码还是补充测试然后重跑最多重试三次。Review全部通过后进入复审。它会比对自己改了什么、哪些行为发生了变化输出一份变更清单。我在 Review 阶段最常用到的就是让助手生成diff 摘要方便直接贴到 commit message 里。这套流程让我最受益的一点是当任务失败时我知道该去看哪个阶段。如果 Plan 阶段方案就错了重心是拉齐需求如果 Test 阶段才失败问题多半出在实现细节定位成本大幅下降。4. Java 重构实测12 分钟拆掉一个 1200 行的上帝类4.1 任务准备一个 1200 行的上帝类光讲概念不够我记录一次完整的实测。我之前遇到一个老旧的 Java 服务OrderService一个类里塞了 1200 行既连数据库、又发 MQ、还算价格三个职责搅在一起。需求是把价格计算逻辑拆到独立的PricingService保证对外行为不变并且给新旧逻辑各补两个单测。准备工作很关键。传统做法是我自己写任务拆分文档再一段段喂给助手。用 superpowers 之后我先在项目根目录写好AGENTS.md然后在命令里精确描述需求superpowers run 重构 OrderService将价格计算逻辑提取到 PricingService 保持对外方法签名不变补充 JUnit 5 单元测试原有行为不得改变这里我特意写清楚了三个约束位置提取到新类、接口签名不变、质量要求补测试。越明确Plan 阶段的方案就越贴近现实。4.2 执行过程中值得记录的三个细节第一次执行Plan 阶段给了很漂亮的方案列出PricingService建议的接口、需要从OrderService迁移的私有方法清单、以及测试的断言思路。但进入 Implement 阶段后问题来了——它把OrderService里一个原本 package-private 的静态方法直接复制过去却忘了在PricingService里显式声明它原本所在的包。编译直接失败。这里有个很有意思的细节Test 阶段立刻抓住了错误。mvn test在编译期就报了找不到符号助手读取失败日志之后自己做了修正把新类的包路径补齐重跑通过。换作以前我手工拿助手一次一次改可能来回三轮才发现是包名问题这套流程一次就抓住了。第二个细节是测试设计。助手生成的第一个测试里有个断言写得太宽松只校验了返回值大于 0这在重构场景下意义不大。我在 Review 阶段看到变更清单后追加了一条指令测试属于回归保护断言要能区分重构前后的错误行为。 它随即把断言改成精确的比较并补了边界用例。所以Review 阶段不要直接点通过要带着质疑去看。第三个细节关于副作用。OrderService里原来算完价格之后会直接发送一个价格变更的 MQ 事件重构后这个事件仍然由OrderService自己发PricingService只负责纯计算。这个边界在 Plan 阶段其实写过但助手 Implement 时一度把 MQ 发送也搬去了新类。我是在审查计划时发现的反馈后它立刻撤回。这里的重要教训是涉及副作用的边界必须在 Plan 阶段反复确认不能只在提示词里带一句。4.3 复盘结果、耗时与方法论沉淀重构完成之后我跑了全量测试45 个用例全部通过mvn package无告警。改动文件只有 4 个新增PricingService.java和它的测试修改OrderService.java和它的测试。整体耗时约 12 分钟其中大部分时间花在 Test 阶段的三次重跑上。对比我过去手动操作的流程最大的省心点在于以前让助手干这种活我得在旁边盯着每生成一段代码就自己编译一次出问题再针对性提问整体至少半小时起步。现在相当于把编译-报错-修复的闭环交给了工作流本身我只在开头定义任务、在中间检查方案、在最后审查 diff。时间上的对比如下维度过去手动喂代码superpowers 流程我的介入全程盯、反复编译三次介入确认方案、补断言、审 diff耗时约 30-45 分钟约 12 分钟中间错误容易遗漏、人肉发现Test 阶段自动抓结果记录散落在聊天记录里方案、变更清单自动落盘对于经常做重构的人来说这种可追溯性其实比速度更重要。因为重构的核心风险不是改得慢而是改完之后不知道动了哪些地方、影响哪些调用方。superpowers 在 Review 阶段输出的变更清单恰好就是重构评审里最需要的那份材料。5. 踩坑实录安装、运行与上下文问题的排查方法5.1 安装与依赖问题速查我总结了这张表基本覆盖了我在 Mac 和 Linux 上遇到过的安装问题现象原因解决办法npm install 报esbuild二进制下载失败本地网络或 Node 版本过低升级到 Node 20 LTS删除 node_modules 重装运行superpowers提示命令不存在npm 全局路径不在 PATH 里执行npm config get prefix并把对应 bin 目录追加到 PATHEACCES: permission denied权限不足不要用 sudo 硬装改用 nvm 管理 Node 版本init 时找不到 Java 项目类型目录里缺少pom.xml或build.gradle先确认项目文件结构完整再执行 initWindows 下脚本路径报错原生 shell 与 POSIX 脚本不兼容换 WSL2在 Ubuntu 环境里跑第二个问题我特别说一下。Node 用官方安装包装的时候npm link出来的全局命令默认在/usr/local/bin这通常没问题。但如果你的 shell 配置里自定义了PATH而且把某个目录放到前面就可能出现命令找不到。排查命令是which node which npm which superpowers三个命令的结果必须在同一套安装目录下只要发现某个指向了别的路径就沿着那个路径去清理。5.2 运行期异常模板不触发、助手犯迷糊怎么办比起安装问题运行期的问题更隐蔽也更耗时间。我把最常见三类整理一下。模板匹配失灵。我遇到过技能包一直不触发排查半天才发现是 description 里用了中文单测但项目里大家口头都叫unit test用户自然语言里根本不会出现单测。关键词覆盖面要宽且要看你项目里实际怎么说不要只写自己习惯的说法。上下文越长越健忘。大项目里会话进行到 Implement 中段时助手开始忘记AGENTS.md里最开始的约束。这不是 superpowers 的 bug是上下文窗口的物理规律。缓解办法有两个一是把最重要的红线写在AGENTS.md最前面二是把任务拆小一次superpowers run只干一件事不把十个修改点塞进一个任务里。计划阶段被跳过。我前面提过一旦任务描述里出现直接改某些模型会跳过 Plan 直接实现。我的做法是命令里显式要求分阶段例如加上先输出修改方案等待确认后再实施。或者直接用--pause-after plan等参数把节奏锁死。5.3 上下文溢出与大任务拆解技巧最后聊一个所有 AI 辅助编程工具都会碰到的天花板上下文窗口。superpowers 对上下文的消耗其实比裸聊天更省因为它按需加载技能但有几种场景还是会快速撑爆超大文件单个文件超过 800 行、大范围重构一次改几十个文件、日志测试输出过多。我的实操经验是三个动作。第一改需求描述而不是改代码。把重构 OrderService 并优化所有相关调用方改成先只在 OrderService 内部做提取调用方不动把一个大任务拆成几个有先后依赖的小任务。这是成本最低、见效最快的办法。第二在技能里启用摘要。比如 Test 阶段让助手只读取测试日志里的 ERROR 级别内容而不是整段 stdout。很多集成工具里有专门的日志过滤配置花 5 分钟配好能省下大量 token。第三隔离超大文件。如果某个类 1200 行别让助手一口气全读进去先用 grep 或脚本把关键方法签名提取出来做成中间摘要文件再让助手基于摘要操作。这个思路跟人类看代码一样先了解接口再决定要不要看实现。另外如果你是在某些图形化的应用里调用这套工作流原理也是一样的本质上就是项目上下文文件 技能目录 按阶段执行的命令。只要宿主应用允许你指定项目根目录和读取本地文件就能把 superpowers 的工作方式平移到任何环境里并不局限于命令行。最后再分享一个小技巧。我每次跑完一个任务都会去改一下对应技能的 description把这次遇到的边界情况补进去。比如跑完那次 Java 重构后我在单测技能的 description 里加了一句注意断言必须能区分行为差异不要只判断返回值为正。这样下次再触发时模型默认就会沿用这条经验。superpowers 用久了之后这套技能文件会越来越像你自己的编码手册——这才是它真正值钱的地方。
