1. 从装库到装能力superpowers到底在解决什么问题先说一个很多开发者容易忽视的事实AI编程助手装好之后大部分人的用法只是在对话框里丢一段报错、复制一段代码、让它解释一下。这当然能用但你很快就发现它更像一个高级搜索框不是一个能帮你干活的队友。我最早用Codex的时候也是这个体验直到我把助手的能力从单轮对话扩展成带上下文的项目级执行才真正有种多了个结对工程师的感觉。我当时给自己配的这一整套东西就是后来在圈子里被称作superpowers的能力增强方案。它不是一个单一工具也不是某个插件而是一组可复用的**技能包skills加命令封装commands**的组合。它做的事情可以用一句话概括把AI编程助手从你问一句、它答一句的被动问答模式变成你给目标、它拆任务、自己查工程、自己改代码、自己跑测试的多步执行模式。你可能会问这不就是Agent吗对方向上是但superpowers这类方案更落地的地方在于它把Agent需要的能力拆分成了一个个独立的技能文件每个技能文件就是一段写好的提示词加执行脚本专门解决某一类任务。比如修改接口是一个技能写单元测试是一个技能跑代码审查又是一个技能。你可以单独启用、自由组合甚至按自己团队的工作流去扩展。适合看这篇文章的人我猜大概是这么几类已经在用Codex、Claude或其他AI编程助手但觉得它不够懂项目结构的开发者刚听说superpowers想装但不想对着README一步步踩坑的新手在Java、Python这类工程化程度较高的语言上做开发想让AI真正参与到编译、测试、重构流程中的人。下面我会按我的实际使用路径来写先讲为什么需要这套能力包再讲怎么装、怎么调、怎么在Java项目里落地最后把我踩过的坑和优化经验一并放出来。全程不会给你灌AI改变世界之类的大词只讲能直接抄作业的操作。2. 先把基础架起来安装环节的四个步骤与三条红线2.1 安装前先想清楚你的执行链安装superpowers之前我先建议你花十分钟理清自己的工具链。因为这套技能包本质上是在指挥你的本地开发环境你本地的CLI能力越完整它的发挥空间就越大。最基本的搭配是AI助手命令行工具如Codex CLI 一套成熟的shell环境 Git仓库结构规范的项目。我第一次装的时候犯过一个典型错误直接把它当成一键安装的软件装完就以为能用。实际上你需要的是让它能看到你的项目结构、能读你的代码、能调用你的构建工具。以我的环境为例环节我使用的工具作用AI执行入口Codex CLI接收任务、拆解步骤、调用技能Shell环境zsh oh-my-zsh提供命令执行的底层能力终端复用tmux让AI能在独立会话里跑长任务项目构建MavenJava场景编译、测试、打包的出口版本控制Git让AI的改动可回溯、可审查这些工具你应该大部分都有但要注意版本问题尤其是Codex CLI这类更新比较快的工具尽量用最新稳定版。我的建议是装之前先升级一遍npm install -g openai/codex具体包名按你自己安装方式为准把它升到能支持命令封装和技能加载的版本否则后面配好的技能可能根本不生效。2.2 安装与初始化的完整流程不同人的安装路径不同但核心流程是一致的。以我记录下来的步骤为参考确认Node.js版本在18以上然后安装Codex CLInpm install -g openai/codex codex --version命令行输出版本号就说明装成功了。进入你的项目根目录初始化superpowers的配置目录。注意它不是往全局塞一堆配置而是更推荐每个项目一份配置这样不同团队的代码风格、构建命令、技能集可以隔离。我的做法是在项目根目录建一个.superpowers/目录mkdir .superpowers cd .superpowers把技能文件skills装进去。这个目录通常分两块skills/技能定义和commands/快捷命令结构大致是这样.superpowers/ ├── skills/ │ ├── implement-change.md │ ├── review-code.md │ └── write-tests.md └── commands/ ├── implement.md ├── test.md └── debug.md在项目的agpt-plan.md或同等全局指令文件里写入加载入口让AI助手每次启动时读取你的技能索引。这一步很关键它相当于给AI一份我会什么能力的清单。验证安装成功。最简单的验证方式是给AI下一个完整任务比如用implement技能把src/main/java下第一个类的代码做一次接口抽取。如果AI先读取项目结构、列出改动计划、再动手改代码说明整个链路已经通了如果它只是给了一段修改建议并让你手动复制那就说明配置还缺东西。2.3 三条红线我踩过之后才明白的硬性要求安装环节有几条红线是文档里不会写但实践中几乎必踩的红线一技能文件不是越全越好。我第一次从别人仓库里复制了二十几个技能文件结果AI每次加载都要读一遍不仅慢还经常把相关技能搞混。后来我只留了六个最核心的技能剪掉之后准确率明显提升。技能包讲究的是按需装配不是全家桶。红线二构建命令必须写清楚尤其是Java项目的Maven/Gradle命令。如果技能文件里只写运行测试AI会默认用mvn test那还行但如果你的项目是./mvnw test这种wrapper方式AI用错命令就会白跑。我在这上面浪费的时间至少有半天后来学乖了把构建命令写进项目的全局指令里让AI每次直接用wrapper。红线三历史对话要定期清理不能让它一直戴着旧任务的上下文帽子进新任务。这个后面展开讲但安装阶段你就要有这个意识。3. 核心能力包拆解为什么编辑→执行→回顾循环是superpowers的发动机装好之后最关键的是理解superpowers里面的技能文件到底在干什么。很多人以为技能文件是给AI喂更多的上下文其实它的设计逻辑更像把一个大目标拆成一个个有验收标准的小流程。我自己把核心技能归纳成三类编辑类、执行类、回顾类。每个类别的技能对应不同的任务类型使用场景完全不同。我强烈建议你先框架上理解这个分类再逐一配置。3.1 编辑类技能从给建议到动手改编辑类是superpowers的立足之本。默认的AI助手给你提修改建议你得自己去找文件、改代码有了编辑技能之后它会先解析与任务相关的代码范围读入相关文件内容然后一次性生成完整的差异补丁甚至直接改好文件。我的implement-change.md技能文件核心指令是## implement-change 技能 适用场景需求明确到可以动手改代码时。 执行流程 1. 读取项目根目录的AGENTS.md/全局指令文件 2. 定位相关源文件生成将要修改的文件清单改动动机 3. 修改代码保持与现有代码风格一致 4. 运行相关测试确认没有破坏现有功能 5. 输出改动摘要说明每个文件改了什么、为什么这么改。 禁止行为 - 禁止只贴代码不给操作 - 禁止大段重写没有修改必要的文件 - 禁止跳过测试直接交工。我实际用下来的体会是禁止行为这部分比执行流程还重要。AI助手有很强的过度优化倾向你让它改一个方法重命名它能把整个类的注释格式都给你改了然后在diff里塞大量无关内容。把禁止行为写清楚能很大程度上抑制这种冲动。3.2 执行类技能AI要学会自己跑命令并看结果执行类技能解决的是AI改完代码不知道自己改坏了没有的问题。具体做法是让AI主动调用构建和测试命令而不是等你把报错丢给它。以Java项目为例run-tests技能的核心指令是这样的## run-tests 技能 1. 根据项目类型识别构建工具Maven、Gradle或wrapper 2. 执行 ./mvnw test如果存在wrapper否则 mvn test 3. 读取测试输出区分编译失败断言失败测试跳过三类情况 4. 若失败定位到具体测试类与用例修复后重跑 5. 如果重跑后依然失败立即停止输出失败上下文不要反复盲试。我之所以强调跑命令是因为很多人配置superpowers时只给了编辑能力没给执行能力结果AI改完代码像盲人开车你也不知道它到底改对没有。真正把执行类技能配置好之后AI的反馈回路就闭环了改代码 → 跑测试 → 看结果 → 发现问题 → 再改。这是它从聊天工具变工程师的关键一步。3.3 回顾类技能让AI学会检查自己回顾类技能容易被人忽略但我认为它是整个superpowers体系里最能提升交付质量的模块。常见场景是AI完成了一个较大的改动你让它基于diff做自查检查点包括是否遗漏了文件末尾的导入是否有重复代码或无用变量接口改动是否同步更新了调用方是否引入了不相关的格式化差异我用的是review-my-diff技能一句话让它做Checklist执行 review-my-diff 技能目标检查当前未提交改动给出准确性评分与风险项。它会执行git diff逐条对照检查清单最后输出一份风险提示列表。我用了这个技能之后AI生成代码的合并审查通过率高了不少因为很多低级的逻辑问题在进入PR之前就被它自己拦住了。4. Java项目实战把superpowers真正用起来的三条经验4.1 项目中让AI遵循Maven的生命周期管理我手上的主力项目是Java 17 Spring Boot Maven搭建的后端服务。接入superpowers后遇到的最有价值的变化是AI能在合理的Maven生命周期节点做该做的事。以前我自己手写任务给AI助手加一个分页查询接口它会直接给我改Controller、Service、Repository三层代码然后让你自己测试。配置好superpowers之后它的行为就变成先读取pom.xml确认项目依赖了spring-boot-starter-web、mybatis-plus等检查现有代码结构在对应包路径下新增类写完代码后自动执行./mvnw -DskipTests compile确认能编译通过编译通过后再执行./mvnw test确认现有测试不受影响最后给出改动清单和运行访问路径。其中最关键的是第3步。让AI编译通过后再交工这个习惯是superpowers的执行类技能带来的。它避免了最大的坑AI改完代码你本地一编译直接满屏红。4.2 Java项目的技能文件要按包职责组织Java项目有个特点包结构清晰类的职责相对固定。所以给这类项目配superpowers技能文件不能是通用的修改代码而要细分到业务场景。我实际在项目中放了这几个技能文件效果很好技能文件名功能典型触发语add-api.md新增一个REST接口新增查询用户的接口fix-compile.md修复编译错误解决编译不过的问题add-test.md给指定类补单元测试给UserService补测试refactor.md抽取公共方法或类抽取一个通用分页工具类这一举动的最大好处是AI不用从你的只言片语里猜你到底想让我干什么而是直接匹配到对应技能的精确定义。比如说add-api.md里我会写明Controller层入参要用DTO而非Entity返回统一Result包装类事务注解放在Service层实现类上这些团队规范AI就不会写出不符合架构的代码。4.3 用superpowers做长工时任务代码审查的另一种用法Java项目里最让我省时间的其实是PR审查环节。代码审查需要审阅者快速理解改动意图、检查边界条件这恰好是superpowers中回顾类技能的主场。我现在的流程是开发分支提交后在Codex里执行一条命令codex执行 review-code 技能审查 origin/develop...当前分支 的差异AI会输出以下内容每个改动文件的变更摘要潜在的空指针、并发、事务边界风险是否符合团队现有命名和分层规范建议修改的优先级排序。实测下来AI在风格类问题和明显逻辑遗漏上的表现最好基本能拦下80%左右的低级问题但在业务语义是否正确这种高层问题上还是需要人来判断。所以我的定位是AI做初筛人做终审效率提升非常明显。5. 实测中的坑与优化这些调试经验文档里不会写5.1 上下文污染最大的隐性杀手用superpowers最典型的问题不是装不上而是AI突然变笨了。我遇到过好几次上午跑得好好的任务下午同样的指令AI突然开始答非所问或者频繁用错技能。排查到最后绝大多数是上下文污染。因为AI助手会把整个对话历史都当作上下文你在前面任务里让它改过一个订单模块到了下一个新任务中它仍带着当前正在改订单模块的假设。尤其在做Java这种大工程时前面的依赖分析、日志输出、调试过程占用的上下文越滚越大后续任务就会被稀释。解决方式很粗暴但有效每个独立任务尽量开新会话或者用/new先把上下文清空。团队可以约定一个任务包的粒度一个需求、一个Bug、一次重构都算独立任务完成后立刻结束会话。5.2 命令封装之后AI还是自作主张怎么办我自己写Custom Command时踩过的一个坑是命令写得越复杂AI越容易在执行过程中偏离。比如我想做一个新增MyBatis查询方法的封装写了八个步骤结果AI跑到第四步就开始自由发挥自己加了一堆过滤条件。后来我总结出一个原则封装命令里判定条件要多于操作步骤。与其写清楚你要怎么怎么做不如写清楚满足什么才算做对了。前者是流程后者是验收标准。AI只要拿到清晰的验收标准反而能自己优化路径如果只给流程它就变成死板地走步骤而且中间一步出错就全会乱。改完之后的命令结构大概是任务新增MyBatis查询方法。 验收标准 - Mapper接口有对应方法 - XML中有对应SQL语句且id匹配 - Service层调用处已注入 - 编译通过且相关测试全绿。这样AI就知道目标在哪中间的路径它自己选自由度更高也更容易交付正确结果。5.3 一个倒霉的Maven本地依赖锁死问题最后分享一个让我印象最深的排查过程因为在Java项目里几乎一定会遇到类似问题。现象AI执行./mvnw clean package时本地仓库里某个SNAPSHOT依赖一直使用旧版本怎么编译都拉不到新代码。最开始我怀疑是superpowers的构建命令写错了检查之后发现命令没问题问题出在本地Maven仓库的缓存机制上。根因是SNAPSHOT版本的依赖默认更新策略是一天一次如果那天依赖还是一样的版本号Maven根本不会去远程仓库拉最新快照。于是AI每次执行打包都是在用旧版本任务表现当然不稳定。排查链路是这样走的用ls -l ~/.m2/repository/.../xxx-snapshot/看本地仓库的jar文件时间戳发现是前一天确认不是构建命令问题因为单独跑mvn clean package也一样检查远程仓库配置发现没有开启snapshot的更新策略最终在pom.xml里对那个依赖单独配置snapshotupdatePolicyalways/updatePolicy/snapshot重跑任务AI行为立刻恢复正常。这个坑给我的启发是当你觉得AI突然变傻了的时候先别急着改superpowers配置很大概率是它背后的构建环境出了问题。它只是按流程执行但环境坏了它再清醒也没办法。5.4 我的日常优化清单现在我的项目里保持着一个固定的优化节奏分享给你作为参考每两周检查一次技能文件里禁止行为的覆盖范围把新踩的坑追加进去。每次AI完成一次较大改动后让它执行一次自查diff意外改动的回顾技能。定期清理~/.m2/repository里长期不用的SNAPSHOT版本避免本地仓库越滚越大。新建分支后第一件事就是让AI重新读取最新的项目结构防止它拿旧上下文开新任务。这几条看着都很小叠加起来的效果非常明显。尤其最后一条基本能消除一半的AI答非所问现象。6. 从零手写一个技能文件的示范模板如果你打算在团队里推广superpowers迟早会需要自己定制技能。我建议别直接改别人的因为团队规范不同照搬很容易出现命令格式化很好但格式和你们项目风格冲突的情况。我最常用的模板有两种覆盖大部分自定义需求。任务型技能模板## [技能名] ### 适用场景 什么时候触发这个技能举一个具体命令示例。 ### 禁止行为 - 禁止xxx写出团队最容易犯的错 - 禁止yyy写出AI最容易越界的动作 ### 执行清单 1. 操作前先读取哪个文件 2. 改动涉及哪些路径 3. 改完如何验证 4. 交付时输出什么。自查型技能模板## [技能名]-review 触发方式接到 review 指令时。 校验项 - [ ] 代码分层是否符合项目约定 - [ ] 是否包含了无关文件的格式化改动 - [ ] 异常路径是否覆盖 - [ ] 测试是否通过。 输出格式 - 风险项列出问题列表 - 修复建议需要改动的地方我在实际项目里用这个模板写过新增定时任务技能和异常日志排查技能基本都是一次跑通微调一两次就能稳定复用。写技能文件时一个比较实用的习惯是先让AI跑一两轮把跑偏的地方写成禁止行为加进去。两三轮之后这个技能基本就稳定了——因为AI踩过的坑和数据是累积的技能文件本身也变成了团队经验的载体。最后再分享一个小技巧刚开始配置superpowers时别贪多求全。先把改代码、跑测试、自查、编译这四个最基本的能力装好稳定用一周再逐步扩大技能覆盖范围。我见过太多人一开始就配置了十几个技能结果自己和AI都乱套。从最小闭环开始比一次性配齐全家桶要靠谱得多。