1. 不是“超能力”是一套工程化的工作流我见过不少团队引入 AI 编程工具之后第一周兴奋得不行第二周开始嫌弃——“问它改个 Bug它给我把整个模块重写了”“让它写个单元测试它翻来覆去就那几个同名用例”“明明上下文里说了别动数据库脚本它转头就改了迁移文件”。问题不在于模型能力而在于我们把它用成了“聊天框”。你把光标一放把需求一贴剩下的全靠模型当场发挥。结果发挥好的时候像超能力发挥差的时候像抽卡。如果你也受够了这种状态Superpowers 这套工作流值得认真研究一下。Superpowers 不是某个大厂发布的商业产品也不是某个语言特有的语法糖它本质上是给 AI 编程代理尤其是 Codex CLI 这类命令行编码代理设计的一套“能力扩展框架”。它的核心思路很朴素把零散的提示词、项目上下文、任务拆解规则、代码检查标准组织成一个个可以被重复调用的“技能包”。你在项目里引入这些技能包之后代理就不再是一个只会接话的模型而是一个按你设定的规则行动的工具。我第一次见到这个项目时第一反应是“这不就是个模板库吗”。后来在真实的大型 Java 项目里用了两个月才发现它卷得比我想象中深。它不是简单地把几个 Markdown 文件塞给模型而是提供了一整套任务编排方式什么时候该先搜索定位什么时候该只读不改什么时候可以动手写代码写完代码之后要怎么验证收敛每一步都有对应的约束和触发机制。这东西用对了才是真正的“超能力”——不是让 AI 替你拍脑袋而是让 AI 严格按照项目规范干活。换句话说Superpowers 的核心价值不在于模型回答得多聪明而在于“确定性”。它让 AI 的输出从随机波动变成可预期的工程交付。拿我做 Java 后端迁移那段时间举例过去让 AI 重构一个老模块我得花大量篇幅跟它解释Maven 还是 Gradle、Java 版本卡在多少、可不可以引入新依赖、日志规范是什么、异常要不要包装成自定义 RuntimeException。这些话每开一个新任务就得重说一遍。用 Superpowers 之后这些信息全部固化成了项目级技能文件代理每次开工前自动加载我再也不用复制粘贴那几百字的“开场白”。所以这篇内容我不打算写成翻译文档而是想聊清楚三件事Superpowers 怎么装、怎么在 Java 项目里落地、怎么跟 Codex CLI 打配合。顺便把我踩过的一些坑也一并交代清楚。2. 安装 superpowers给 CLI 补上“能力仓库”2.1 先搞清楚你装的是什么东西刚开始我看文档也懵一会儿“skills”一会儿“workflows”一会儿“AGENTS.md”感觉名词满天飞。后来在本地跑通了一个最小实验才把概念理顺。Superpowers 的安装目标不是你当前打开的 IDE而是你本机全局的编码代理配置目录。装上之后它会建立一个“能力仓库”里面按目录组织各种技能。每个技能通常包含三个东西说明文件描述这个技能解决什么问题、模板文件给代理参考的标准做法、脚本文件如果需要执行命令比如编译、测试、搜索。代理启动时Superpowers 会把这些技能注册到自己的工具列表里并在你输入任务关键词时自动匹配。按我自己的理解它相当于给代理装了一堆“预设工具”而不是只喂一段话。区别在哪里只喂话模型记住了是记住了忘了就是忘了经常在前面表现为“哦好的我会记住”转头就翻脸不认账。注册成技能之后代理每次出发前会自动检查这个能力列表中哪些适用按固定流程执行执行顺序和判断标准都有文件可查不确定性被大大压缩。2.2 最小安装路径不同平台、不同分支的安装方式会有差异我建议你安装前先看一眼官方仓库的 README。我自己在 macOS 上走的完整路径大概是这样第一步准备一个全局目录。我习惯放到~/.superpowers这里存放所有的技能和配置。第二步通过包管理器拉取主程序。现在社区主流的安装方式是 npm 或者直接从源码构建依赖 Node.js 环境。先确认本地 node 版本在 18 以上再执行npm install -g superpowers-cli装完之后可以用一条命令校验superpowers --version如果环境干净这里会直接输出版本号。如果你跟我一样机器上同时有多个 Node 版本管理工具建议先切到 LTS 版本再装避免因为全局权限问题卡在EACCES这类错误上。第三步初始化能力仓库superpowers init这条命令会在你当前用户目录下创建~/.superpowers目录结构并在你的 shell 配置文件里注入一个代理启动辅助脚本。它的作用是让 Codex CLI 这类工具下次启动时能自动找到技能目录。2.3 目录结构到底长什么样初始化完成后结构大概是这样.superpowers ├── skills │ ├── java-refactoring │ │ ├── SKILL.md │ │ ├── template.md │ │ └── validate.sh │ ├── dependency-analysis │ │ ├── SKILL.md │ │ ├── template.md │ │ └── rules.json │ └── ... ├── workflows │ ├── bug-fix.md │ └── feature-dev.md ├── AGENTS.md └── config.jsonSKILL.md是技能的主描述文件代理会用它判断“这个任务能不能用这个技能处理”。template.md是输出模板告诉代理最终交付物要长成什么样。validate.sh是自动校验脚本用来检查这次改动有没有通过测试、有没有违反静态检查规则。AGENTS.md是全局行为准则类似于整个代理的“员工手册”优先于大多数临时提示词。这套结构最舒服的一点是它把“人告诉 AI 该怎么做”这件事变成了“AI 自己查手册后再做”。你只要把判断规则写清楚代理会自己去匹配不需要每次对话都手动强调。3. Java 项目里的正确用法别让超级能力变成过度设计3.1 Java 项目接入时我最关注的三件事我日常工作主要是 Java 后端Maven 和 Gradle 项目都接触代码库动辄几十个模块。接入 Superpowers 之前我先明确了三个目标构建流程不能被破坏、代码风格必须统一、依赖变更必须走审查。这三件事是我对 AI 编码工具最低的容忍线。拿代码风格来说。过去用 AI 辅助开发最烦的就是它生成的代码“看起来没问题但不像是这个项目里写的”。有人喜欢var满天飞有人习惯写完整类型有人用Optional做空值兜底有人坚持Objects.requireNonNull。这些东西靠临时提示词约束效果很差因为模型在聊到一半的时候容易丢失上下文。Superpowers 的解决方式是把风格规则写进技能模板。我在java-refactoring技能里写了一段约束- 使用 Java 17 语法但不要使用 var 声明公有 API 参数和返回值。 - 所有对外方法参数使用 final 修饰。 - 禁止在既有代码中混入新的 Lombok 用法除非项目内其他模块已经使用。 - 日志统一使用 slf4j私有静态常量 logger 命名为 log。这段描述每次代理执行重构任务时都会被读取相当于把团队编码规范做成了自动执行的检查项。实际效果很直观以前每轮让 AI 改代码我都要花一轮对话来纠正“变量命名”“日志写法”这些细节现在很少需要了。3.2 把 Maven 构建校验接入技能第二步是让代理在“改完代码”之后能自动验证而不是交差了事。我给 Java 项目配置了一套子技能命名为maven-verify它不是让代理自己去猜而是固定执行三条命令。第一条是编译mvn -q compile第二条是跳过集成测试的运行单元测试mvn -q test -DskipITs第三条是静态检查mvn -q verify -DskipTests -Dspotbugs.skipfalse如果这三条命令有任何一个非零返回技能模板里要求代理停下来阅读报错修正之后重新执行直到全部通过才能进入交付环节。这里有个细节值得注意不要让代理在任何情况下都跑全量测试。大项目通常包含大量集成测试跑一次可能二十分钟而且对环境有依赖比如要连数据库、要拉取某个测试容器。正确的做法是让技能文件里带上触发条件只有改动到基础设施相关代码时才执行完整测试链路。这个判断逻辑不需要写太多行关键是明确“什么时候可以跳过”“什么时候必须全跑”把它固化成一串 if-else 规则。3.3 依赖变更必须“报备”Java 项目里最危险的操作就是让 AI 给pom.xml加依赖。它可能为了修一个顺手的小问题给你从 Maven 中央仓库拉进来一个新版本的 JSON 库然后整个项目的依赖冲突问题就像多米诺骨牌一样倒下来。我在这里定的规则很硬任何pom.xml的变更代理都不得直接修改只允许生成变更建议文件由人工去合并。我是通过工作流文件实现的。在dependency-change技能里写清楚先分析现有依赖树再评估引入新库的必要性最后输出dependency-proposal.md里面要包含版本号、依赖坐标、引入原因、潜在冲突点。代理可以在建议文件里写“我建议引入 XX 版本”但没有权限直接往pom.xml里写代码。这套约束帮我拦住了至少三次事故。有一次它为了处理一个 JSON 字段反序列化问题想要引入一个轻量级 JSON 工具库。我看了建议文件才意识到项目里已经有 Jackson只是用法不对正确方案是配置一个自定义反序列化器而不是新增依赖。如果让它直接改pom.xml代码可能能跑但维护成本和依赖膨胀就埋下了。4. 与 Codex 联动从“问题”到“改动”的完整链路4.1 为什么是 Codex CLI我日常测试过几种主流 AI 编程代理Codex CLI 给我的感觉是最适合跑 Superpowers 这种工作流的。原因很简单它天然以命令行工具的形式存在系统提示词可以由用户自定义并且可以中途调用外部脚本。Superpowers 本质上就是通过响应能力把 Codex 变成一个有自主工作流意识的开发者助手。如果你还没装 Codex CLI装完后先在项目根目录确认一下环境codex --version目前它需要登录 OpenAI 账号部分版本还需要配置 API Key。这一步不同版本差异很大建议直接按官方最新的认证方式来。启用 Superpowers 的能力仓库需要在 Codex 的配置文件里把~/.superpowers/AGENTS.md作为附加系统提示词并开放技能目录的读取权限。我自己的配置大致思路是这样的{ model: gpt-5, extraContextFiles: [~/.superpowers/AGENTS.md], allowedDirectories: [~/.superpowers, ./] }配置完成后启动 Codex CLI它会自动读取全局行为准则。这个时候你再下任务代理就不只是会聊天而是会先从技能库里匹配可用的能力再按工作流文件拆解任务步骤。4.2 一个典型的“Bug 修复”闭环演示我拿一个真实案例来演示一下工作流是怎样的。某次项目里有个接口偶发超时线上日志指向一个老旧的同步调用但没人愿意手动去查这条链路。我向 Codex 发的指令很简单调查 payment-service 中订单状态轮询超时问题按照 bug-fix 工作流处理。代理收到指令之后的动作分了几步第一步读取workflows/bug-fix.md。这个文件会告诉它流程是定位问题、复现问题、分析根因、提出方案、实现修复、自动测试、输出总结。第二步它从技能库里匹配了java-debugging技能。技能里规定要先用搜索工具在代码库中找到相关类和配置而不是凭记忆猜。第三步它沿着调用链找到了订单状态查询走的是一个同步 HTTP 调用并且该调用设置了 10 秒超时而支付网关平均响应时间是 8 秒。高峰期一拥堵频繁触发超时。第四步它按模板提出了候选方案改异步轮询、调大超时时间、引入熔断降级。并且在方案末尾标出推荐项是异步化但风险和改动范围都大建议先做超时时间调优缓解。第五步在得到我确认后它进入实现阶段。按照maven-verify技能先后执行编译和单元测试全部通过后生成了变更摘要。整个过程我没有去纠正它的任何步骤它也没有跑偏重写其他模块。核心原因就在于bug-fix.md工作流文件把行动的边界画好了技能模板又规定了每一步应该怎么做。这不是某一次大模型发挥好而是这套机制的稳定性体现。4.3 自定义一条新技能的最小写法Superpowers 的一个特点是技能可以自己扩展。你不需要等官方更新的技能包自己写一个也就十几行。以“生成 Controller 层代码”为例。我写了一个generate-controller技能结构非常简单--- name: generate-controller description: 根据 service 接口生成 Spring MVC Controller 层代码 triggers: - 生成controller - 新建controller - controller层代码 --- ## 要求 1. 根据已有 service 接口方法生成 RESTful Controller。 2. 统一使用 RestController不额外引入旧的 Controller。 3. 返回类型统一封装到 ResultT。 4. 参数校验使用 Validated 分组校验。 5. 不要生成无用的 swagger 注解。这个文件放在skills/generate-controller/SKILL.md里就可以了。之后在 Codex 里只要提到“生成 controller”代理就会自动去读这个技能的约束。你会发现它的命中率比临时提示词高很多因为临时提示词需要你在对话里完整复述需求而技能文件可以让代理在一开始就自查“输出是否满足约束”。5. 我踩过的坑和现在的固定操作流程5.1 坑一技能文件写成了“建议”而不是“规则”刚开始用 Superpowers 的时候我把 SKILL.md 写得像一篇散文。比如“尽量保持代码简洁”“注意异常处理”“规避明显的设计问题”。这种表述看着没问题但对代理来说太模糊了它的输出和没写这些几乎没有区别。后来我把规则改成了带否定条件和明确指令的表达方式比如“禁止 catch Exception 后吞掉异常”“所有 throw 出的业务异常必须是 BizException 类型”“不得在 Controller 中打印堆栈日志”。规则越具体代理的执行越可预测。如果你发现自己写完了技能之后跑任务代理还是我行我素先检查一下技能文件里面有没有出现“尽量”“可能”“建议”这类软性词汇。有的话把它们改成“必须”“禁止”“只能”。它们语义的确定性完全不同。5.2 坑二给了代理过大的文件写入权限Superpowers 最诱人的一点是它可以调用本地脚本甚至可以自己做文件操作。但这同时也意味着风险。如果你给代理开放的目录是整个家目录它可能在你不知情的情况下改动无关配置文件。我现在的做法是权限最小化。在 Codex 配置里只开放项目根目录、临时目录和.superpowers/skills目录。除此之外像~/.ssh、~/.aws这类敏感目录一律封死。代理如果需要读取环境信息应该通过明确的安全接口而不是直接翻文件系统。这里再补一个非常关键的细节我从来不在任务指令里写“你随便看下有没有问题就改一下”。“随便”这个词对代理来说太危险了。我所有任务都要求它先给出改动计划和范围等确认后再动手。这不是为了流程僵化而是为了在出问题的时候有据可查。5.3 坑三Java 项目与技能仓库版本管理脱节Superpowers 的技能文件是跟着你本地环境走的默认不在项目仓库里。这就导致了一个问题项目里换了新同事他本地没有这些技能AI 编码的行为表现就完全两样。我的解决方法是把技能仓库纳入到 dotfiles 管理并且按项目维度单独抽出项目级技能。项目根目录下放一个superpowers/目录里面是针对当前项目的技能和工作流然后把这个目录提交到 git。全局放通用技能项目里放专项约束两者叠加使用。这样做还有一个额外的好处技能变更可以跟随代码评审走。你在 code review 的时候如果发现某个 AI 生成的代码风格不符合要求可以直接在项目技能里加一条规则下次它就不会再犯。这些规则会跟着仓库走而不是只存在你个人电脑里。5.4 我目前的固定操作流程经过这几个月的折腾我现在接手一个 Java 项目时流程已经基本固定下来第一步克隆代码仓库确认 Java 版本和构建工具。第二步在项目根目录执行superpowers init的局部初始化模式为项目生成一个初始技能目录。第三步根据项目实际情况补充三条规则代码风格约束、构建校验命令、禁止涉及的安全边界比如密钥、生产数据库配置、支付相关逻辑。第四步启动 Codex CLI加载全局和项目两个技能源。第五步跑一个最小的任务验证链路比如让代理找一个老接口的单元测试缺失情况。如果它输出的结果符合预期说明整个链路通了。日常使用中我的角色更像一个项目经理分配任务、验收输出、补充规则。具体的代码搜索、修改实现、单元测试跑批都交给代理来完成。工作流稳定之后手里能并行推进的事情明显变多了。6. 真正花时间的地方持续维护技能而不是追新很多人在接触 Superpowers 这类工具之后会陷入一个误区到处收集新技能技能包越装越多最后反而不知道该怎么用。我自己也经历过这个阶段。后来我砍掉了绝大部分花哨技能保留了六七个真正与日常工作强相关的能力代码搜索、Java 重构、Maven 校验、依赖变更分析、接口生成、Bug 排查。原因很简单Superpowers 的价值密度来自你对技能库的理解和维护而不是从仓库里复制粘贴的数量。比如你给它准备了一个“重构技能”技能文件里写着如果项目里有pmd.xml就要读取它的规则集并且把编译期要用到的参数都写明白。代理只有真正理解了这些规则才能在你预期它配合的地方发力。维护技能的最佳时机是刚踩完坑之后的那十分钟。趁着你记忆最清楚、问题的上下文还热着把这次的教训写成一条规则加进技能文件。比如那次我遇到“代理为了修一个方法把同一个类里三个不相关方法也重构了”我就在 maven-verify 技能里加了一条“改动范围不得超过任务说明中指定的类和方法若确需改动相邻代码必须先输出说明并等待确认”。从那之后类似的越界行为基本没有再发生过。换句话说Superpowers 给你的不是一句“包治百病”的 AI 咒语而是一套可以被持续打磨的 AI 协作体系。你今天写下的每一条规则都会成为接下来每一次编码任务中代理自动遵守的纪律。学会把规则固化下来比催着模型“聪明一点”要可靠得多。
Superpowers工作流：让AI编程代理在Java项目中高效落地
1. 不是“超能力”是一套工程化的工作流我见过不少团队引入 AI 编程工具之后第一周兴奋得不行第二周开始嫌弃——“问它改个 Bug它给我把整个模块重写了”“让它写个单元测试它翻来覆去就那几个同名用例”“明明上下文里说了别动数据库脚本它转头就改了迁移文件”。问题不在于模型能力而在于我们把它用成了“聊天框”。你把光标一放把需求一贴剩下的全靠模型当场发挥。结果发挥好的时候像超能力发挥差的时候像抽卡。如果你也受够了这种状态Superpowers 这套工作流值得认真研究一下。Superpowers 不是某个大厂发布的商业产品也不是某个语言特有的语法糖它本质上是给 AI 编程代理尤其是 Codex CLI 这类命令行编码代理设计的一套“能力扩展框架”。它的核心思路很朴素把零散的提示词、项目上下文、任务拆解规则、代码检查标准组织成一个个可以被重复调用的“技能包”。你在项目里引入这些技能包之后代理就不再是一个只会接话的模型而是一个按你设定的规则行动的工具。我第一次见到这个项目时第一反应是“这不就是个模板库吗”。后来在真实的大型 Java 项目里用了两个月才发现它卷得比我想象中深。它不是简单地把几个 Markdown 文件塞给模型而是提供了一整套任务编排方式什么时候该先搜索定位什么时候该只读不改什么时候可以动手写代码写完代码之后要怎么验证收敛每一步都有对应的约束和触发机制。这东西用对了才是真正的“超能力”——不是让 AI 替你拍脑袋而是让 AI 严格按照项目规范干活。换句话说Superpowers 的核心价值不在于模型回答得多聪明而在于“确定性”。它让 AI 的输出从随机波动变成可预期的工程交付。拿我做 Java 后端迁移那段时间举例过去让 AI 重构一个老模块我得花大量篇幅跟它解释Maven 还是 Gradle、Java 版本卡在多少、可不可以引入新依赖、日志规范是什么、异常要不要包装成自定义 RuntimeException。这些话每开一个新任务就得重说一遍。用 Superpowers 之后这些信息全部固化成了项目级技能文件代理每次开工前自动加载我再也不用复制粘贴那几百字的“开场白”。所以这篇内容我不打算写成翻译文档而是想聊清楚三件事Superpowers 怎么装、怎么在 Java 项目里落地、怎么跟 Codex CLI 打配合。顺便把我踩过的一些坑也一并交代清楚。2. 安装 superpowers给 CLI 补上“能力仓库”2.1 先搞清楚你装的是什么东西刚开始我看文档也懵一会儿“skills”一会儿“workflows”一会儿“AGENTS.md”感觉名词满天飞。后来在本地跑通了一个最小实验才把概念理顺。Superpowers 的安装目标不是你当前打开的 IDE而是你本机全局的编码代理配置目录。装上之后它会建立一个“能力仓库”里面按目录组织各种技能。每个技能通常包含三个东西说明文件描述这个技能解决什么问题、模板文件给代理参考的标准做法、脚本文件如果需要执行命令比如编译、测试、搜索。代理启动时Superpowers 会把这些技能注册到自己的工具列表里并在你输入任务关键词时自动匹配。按我自己的理解它相当于给代理装了一堆“预设工具”而不是只喂一段话。区别在哪里只喂话模型记住了是记住了忘了就是忘了经常在前面表现为“哦好的我会记住”转头就翻脸不认账。注册成技能之后代理每次出发前会自动检查这个能力列表中哪些适用按固定流程执行执行顺序和判断标准都有文件可查不确定性被大大压缩。2.2 最小安装路径不同平台、不同分支的安装方式会有差异我建议你安装前先看一眼官方仓库的 README。我自己在 macOS 上走的完整路径大概是这样第一步准备一个全局目录。我习惯放到~/.superpowers这里存放所有的技能和配置。第二步通过包管理器拉取主程序。现在社区主流的安装方式是 npm 或者直接从源码构建依赖 Node.js 环境。先确认本地 node 版本在 18 以上再执行npm install -g superpowers-cli装完之后可以用一条命令校验superpowers --version如果环境干净这里会直接输出版本号。如果你跟我一样机器上同时有多个 Node 版本管理工具建议先切到 LTS 版本再装避免因为全局权限问题卡在EACCES这类错误上。第三步初始化能力仓库superpowers init这条命令会在你当前用户目录下创建~/.superpowers目录结构并在你的 shell 配置文件里注入一个代理启动辅助脚本。它的作用是让 Codex CLI 这类工具下次启动时能自动找到技能目录。2.3 目录结构到底长什么样初始化完成后结构大概是这样.superpowers ├── skills │ ├── java-refactoring │ │ ├── SKILL.md │ │ ├── template.md │ │ └── validate.sh │ ├── dependency-analysis │ │ ├── SKILL.md │ │ ├── template.md │ │ └── rules.json │ └── ... ├── workflows │ ├── bug-fix.md │ └── feature-dev.md ├── AGENTS.md └── config.jsonSKILL.md是技能的主描述文件代理会用它判断“这个任务能不能用这个技能处理”。template.md是输出模板告诉代理最终交付物要长成什么样。validate.sh是自动校验脚本用来检查这次改动有没有通过测试、有没有违反静态检查规则。AGENTS.md是全局行为准则类似于整个代理的“员工手册”优先于大多数临时提示词。这套结构最舒服的一点是它把“人告诉 AI 该怎么做”这件事变成了“AI 自己查手册后再做”。你只要把判断规则写清楚代理会自己去匹配不需要每次对话都手动强调。3. Java 项目里的正确用法别让超级能力变成过度设计3.1 Java 项目接入时我最关注的三件事我日常工作主要是 Java 后端Maven 和 Gradle 项目都接触代码库动辄几十个模块。接入 Superpowers 之前我先明确了三个目标构建流程不能被破坏、代码风格必须统一、依赖变更必须走审查。这三件事是我对 AI 编码工具最低的容忍线。拿代码风格来说。过去用 AI 辅助开发最烦的就是它生成的代码“看起来没问题但不像是这个项目里写的”。有人喜欢var满天飞有人习惯写完整类型有人用Optional做空值兜底有人坚持Objects.requireNonNull。这些东西靠临时提示词约束效果很差因为模型在聊到一半的时候容易丢失上下文。Superpowers 的解决方式是把风格规则写进技能模板。我在java-refactoring技能里写了一段约束- 使用 Java 17 语法但不要使用 var 声明公有 API 参数和返回值。 - 所有对外方法参数使用 final 修饰。 - 禁止在既有代码中混入新的 Lombok 用法除非项目内其他模块已经使用。 - 日志统一使用 slf4j私有静态常量 logger 命名为 log。这段描述每次代理执行重构任务时都会被读取相当于把团队编码规范做成了自动执行的检查项。实际效果很直观以前每轮让 AI 改代码我都要花一轮对话来纠正“变量命名”“日志写法”这些细节现在很少需要了。3.2 把 Maven 构建校验接入技能第二步是让代理在“改完代码”之后能自动验证而不是交差了事。我给 Java 项目配置了一套子技能命名为maven-verify它不是让代理自己去猜而是固定执行三条命令。第一条是编译mvn -q compile第二条是跳过集成测试的运行单元测试mvn -q test -DskipITs第三条是静态检查mvn -q verify -DskipTests -Dspotbugs.skipfalse如果这三条命令有任何一个非零返回技能模板里要求代理停下来阅读报错修正之后重新执行直到全部通过才能进入交付环节。这里有个细节值得注意不要让代理在任何情况下都跑全量测试。大项目通常包含大量集成测试跑一次可能二十分钟而且对环境有依赖比如要连数据库、要拉取某个测试容器。正确的做法是让技能文件里带上触发条件只有改动到基础设施相关代码时才执行完整测试链路。这个判断逻辑不需要写太多行关键是明确“什么时候可以跳过”“什么时候必须全跑”把它固化成一串 if-else 规则。3.3 依赖变更必须“报备”Java 项目里最危险的操作就是让 AI 给pom.xml加依赖。它可能为了修一个顺手的小问题给你从 Maven 中央仓库拉进来一个新版本的 JSON 库然后整个项目的依赖冲突问题就像多米诺骨牌一样倒下来。我在这里定的规则很硬任何pom.xml的变更代理都不得直接修改只允许生成变更建议文件由人工去合并。我是通过工作流文件实现的。在dependency-change技能里写清楚先分析现有依赖树再评估引入新库的必要性最后输出dependency-proposal.md里面要包含版本号、依赖坐标、引入原因、潜在冲突点。代理可以在建议文件里写“我建议引入 XX 版本”但没有权限直接往pom.xml里写代码。这套约束帮我拦住了至少三次事故。有一次它为了处理一个 JSON 字段反序列化问题想要引入一个轻量级 JSON 工具库。我看了建议文件才意识到项目里已经有 Jackson只是用法不对正确方案是配置一个自定义反序列化器而不是新增依赖。如果让它直接改pom.xml代码可能能跑但维护成本和依赖膨胀就埋下了。4. 与 Codex 联动从“问题”到“改动”的完整链路4.1 为什么是 Codex CLI我日常测试过几种主流 AI 编程代理Codex CLI 给我的感觉是最适合跑 Superpowers 这种工作流的。原因很简单它天然以命令行工具的形式存在系统提示词可以由用户自定义并且可以中途调用外部脚本。Superpowers 本质上就是通过响应能力把 Codex 变成一个有自主工作流意识的开发者助手。如果你还没装 Codex CLI装完后先在项目根目录确认一下环境codex --version目前它需要登录 OpenAI 账号部分版本还需要配置 API Key。这一步不同版本差异很大建议直接按官方最新的认证方式来。启用 Superpowers 的能力仓库需要在 Codex 的配置文件里把~/.superpowers/AGENTS.md作为附加系统提示词并开放技能目录的读取权限。我自己的配置大致思路是这样的{ model: gpt-5, extraContextFiles: [~/.superpowers/AGENTS.md], allowedDirectories: [~/.superpowers, ./] }配置完成后启动 Codex CLI它会自动读取全局行为准则。这个时候你再下任务代理就不只是会聊天而是会先从技能库里匹配可用的能力再按工作流文件拆解任务步骤。4.2 一个典型的“Bug 修复”闭环演示我拿一个真实案例来演示一下工作流是怎样的。某次项目里有个接口偶发超时线上日志指向一个老旧的同步调用但没人愿意手动去查这条链路。我向 Codex 发的指令很简单调查 payment-service 中订单状态轮询超时问题按照 bug-fix 工作流处理。代理收到指令之后的动作分了几步第一步读取workflows/bug-fix.md。这个文件会告诉它流程是定位问题、复现问题、分析根因、提出方案、实现修复、自动测试、输出总结。第二步它从技能库里匹配了java-debugging技能。技能里规定要先用搜索工具在代码库中找到相关类和配置而不是凭记忆猜。第三步它沿着调用链找到了订单状态查询走的是一个同步 HTTP 调用并且该调用设置了 10 秒超时而支付网关平均响应时间是 8 秒。高峰期一拥堵频繁触发超时。第四步它按模板提出了候选方案改异步轮询、调大超时时间、引入熔断降级。并且在方案末尾标出推荐项是异步化但风险和改动范围都大建议先做超时时间调优缓解。第五步在得到我确认后它进入实现阶段。按照maven-verify技能先后执行编译和单元测试全部通过后生成了变更摘要。整个过程我没有去纠正它的任何步骤它也没有跑偏重写其他模块。核心原因就在于bug-fix.md工作流文件把行动的边界画好了技能模板又规定了每一步应该怎么做。这不是某一次大模型发挥好而是这套机制的稳定性体现。4.3 自定义一条新技能的最小写法Superpowers 的一个特点是技能可以自己扩展。你不需要等官方更新的技能包自己写一个也就十几行。以“生成 Controller 层代码”为例。我写了一个generate-controller技能结构非常简单--- name: generate-controller description: 根据 service 接口生成 Spring MVC Controller 层代码 triggers: - 生成controller - 新建controller - controller层代码 --- ## 要求 1. 根据已有 service 接口方法生成 RESTful Controller。 2. 统一使用 RestController不额外引入旧的 Controller。 3. 返回类型统一封装到 ResultT。 4. 参数校验使用 Validated 分组校验。 5. 不要生成无用的 swagger 注解。这个文件放在skills/generate-controller/SKILL.md里就可以了。之后在 Codex 里只要提到“生成 controller”代理就会自动去读这个技能的约束。你会发现它的命中率比临时提示词高很多因为临时提示词需要你在对话里完整复述需求而技能文件可以让代理在一开始就自查“输出是否满足约束”。5. 我踩过的坑和现在的固定操作流程5.1 坑一技能文件写成了“建议”而不是“规则”刚开始用 Superpowers 的时候我把 SKILL.md 写得像一篇散文。比如“尽量保持代码简洁”“注意异常处理”“规避明显的设计问题”。这种表述看着没问题但对代理来说太模糊了它的输出和没写这些几乎没有区别。后来我把规则改成了带否定条件和明确指令的表达方式比如“禁止 catch Exception 后吞掉异常”“所有 throw 出的业务异常必须是 BizException 类型”“不得在 Controller 中打印堆栈日志”。规则越具体代理的执行越可预测。如果你发现自己写完了技能之后跑任务代理还是我行我素先检查一下技能文件里面有没有出现“尽量”“可能”“建议”这类软性词汇。有的话把它们改成“必须”“禁止”“只能”。它们语义的确定性完全不同。5.2 坑二给了代理过大的文件写入权限Superpowers 最诱人的一点是它可以调用本地脚本甚至可以自己做文件操作。但这同时也意味着风险。如果你给代理开放的目录是整个家目录它可能在你不知情的情况下改动无关配置文件。我现在的做法是权限最小化。在 Codex 配置里只开放项目根目录、临时目录和.superpowers/skills目录。除此之外像~/.ssh、~/.aws这类敏感目录一律封死。代理如果需要读取环境信息应该通过明确的安全接口而不是直接翻文件系统。这里再补一个非常关键的细节我从来不在任务指令里写“你随便看下有没有问题就改一下”。“随便”这个词对代理来说太危险了。我所有任务都要求它先给出改动计划和范围等确认后再动手。这不是为了流程僵化而是为了在出问题的时候有据可查。5.3 坑三Java 项目与技能仓库版本管理脱节Superpowers 的技能文件是跟着你本地环境走的默认不在项目仓库里。这就导致了一个问题项目里换了新同事他本地没有这些技能AI 编码的行为表现就完全两样。我的解决方法是把技能仓库纳入到 dotfiles 管理并且按项目维度单独抽出项目级技能。项目根目录下放一个superpowers/目录里面是针对当前项目的技能和工作流然后把这个目录提交到 git。全局放通用技能项目里放专项约束两者叠加使用。这样做还有一个额外的好处技能变更可以跟随代码评审走。你在 code review 的时候如果发现某个 AI 生成的代码风格不符合要求可以直接在项目技能里加一条规则下次它就不会再犯。这些规则会跟着仓库走而不是只存在你个人电脑里。5.4 我目前的固定操作流程经过这几个月的折腾我现在接手一个 Java 项目时流程已经基本固定下来第一步克隆代码仓库确认 Java 版本和构建工具。第二步在项目根目录执行superpowers init的局部初始化模式为项目生成一个初始技能目录。第三步根据项目实际情况补充三条规则代码风格约束、构建校验命令、禁止涉及的安全边界比如密钥、生产数据库配置、支付相关逻辑。第四步启动 Codex CLI加载全局和项目两个技能源。第五步跑一个最小的任务验证链路比如让代理找一个老接口的单元测试缺失情况。如果它输出的结果符合预期说明整个链路通了。日常使用中我的角色更像一个项目经理分配任务、验收输出、补充规则。具体的代码搜索、修改实现、单元测试跑批都交给代理来完成。工作流稳定之后手里能并行推进的事情明显变多了。6. 真正花时间的地方持续维护技能而不是追新很多人在接触 Superpowers 这类工具之后会陷入一个误区到处收集新技能技能包越装越多最后反而不知道该怎么用。我自己也经历过这个阶段。后来我砍掉了绝大部分花哨技能保留了六七个真正与日常工作强相关的能力代码搜索、Java 重构、Maven 校验、依赖变更分析、接口生成、Bug 排查。原因很简单Superpowers 的价值密度来自你对技能库的理解和维护而不是从仓库里复制粘贴的数量。比如你给它准备了一个“重构技能”技能文件里写着如果项目里有pmd.xml就要读取它的规则集并且把编译期要用到的参数都写明白。代理只有真正理解了这些规则才能在你预期它配合的地方发力。维护技能的最佳时机是刚踩完坑之后的那十分钟。趁着你记忆最清楚、问题的上下文还热着把这次的教训写成一条规则加进技能文件。比如那次我遇到“代理为了修一个方法把同一个类里三个不相关方法也重构了”我就在 maven-verify 技能里加了一条“改动范围不得超过任务说明中指定的类和方法若确需改动相邻代码必须先输出说明并等待确认”。从那之后类似的越界行为基本没有再发生过。换句话说Superpowers 给你的不是一句“包治百病”的 AI 咒语而是一套可以被持续打磨的 AI 协作体系。你今天写下的每一条规则都会成为接下来每一次编码任务中代理自动遵守的纪律。学会把规则固化下来比催着模型“聪明一点”要可靠得多。
