用Superpowers技能工作流驯服AI编码代理：Java项目实战

最近我基本把日常编码全部交给了 AI 编码代理Codex 用得最多。刚开始那两周感觉就像让一个聪明但没经验的实习生直接改代码你让他写个单元测试他先给你写了 300 行实现你让他重构他连现有测试跑不跑都不管。直到我把一套叫 superpowers 的开源技能工作流引进来整个局面才彻底改观。这篇就围绕 superpowers 聊聊它背后的方法论、安装配置方式以及我在 Java 项目里的真实落地过程希望能给还在跟代理拉扯的同行一点参考。1. 为什么需要 Superpowers先聊聊 AI 编码代理的痛点1.1 谁都遇到过的问题上下文一长就跑偏用 Codex 这类 AI 编码代理时最让人头疼的其实不是它不会写代码而是它太会写了。你给它一个任务它能在几秒内生成一大坨看起来很像样的代码但仔细一读逻辑漏洞、异常处理缺失、命名混乱全来了。更崩溃的是如果你把需求放在一个比较长的上下文里比如让它在已有的 2000 行代码上做修改它很容易写到一半忘记最初的约束甚至把无关模块也顺手改了。我自己做过一个统计在没有固定流程的情况下代理生成的代码里能直接通过测试的比例不到四成。剩下六成里一半是编译不过或者测试失败另一半是通过了测试但代码质量很勉强。问题不在于模型能力而在于我们给了模型太多自由却没有给它一套该怎么干活的约束。就好比你去餐厅点菜只说了句随便来点好吃的厨师自由发挥的结果大概率不稳定。1.2 社区给出的答案把技能显式写下来superpowers 项目解决的就是这个自由发挥导致不稳定的问题。它的核心思路特别朴素把软件工程里经过验证的实践比如测试驱动开发、小步重构、代码审查、变更规划写成一份份结构化的技能文档然后让代理在动手之前先读取这些文档再按照文档里的步骤执行。我第一次接触这个概念时觉得有点多此一举毕竟模型本身就是从大量代码里训练出来的它难道不知道什么是 TDD 吗后来我才意识到知道并不等于会执行。模型在极长的上下文里很容易丢掉先写测试这种反直觉的纪律性要求。superpowers 相当于给代理贴了一张便签上面写着你每一次动手前请先按这些步骤走不要跳步。更重要的是技能不是写死的逻辑而是 Markdown 文档。这意味着你不需要重新训练模型不需要改代码只需要增删改文档就能改变代理的行为方式。这个文档即行为的设计是我后来愿意围绕它搭建工作流的根本原因。2. Superpowers 的核心理念拆解2.1 技能文件代理的操作手册在 superpowers 的体系里一个技能就是一个目录里面通常有一个 SKILL.md 文件以及若干示例代码、模板和参考文档。SKILL.md 的结构有点像部队里的作战手册先是技能名称和一句话描述然后是适用的触发条件接着是具体的执行步骤最后是注意事项和验收标准。我举个实际的例子。比如你定义了一个测试驱动开发技能它的内容大致是第一步先理解需求写一个失败的用户故事列表。第二步针对其中一个行为编写单元测试运行并确认它是红的。第三步用最简单的方式让测试变绿。第四步运行整个测试集确认没有回归。第五步重构并保持测试全绿。注意事项禁止在没有测试的情况下直接写实现禁止一次写超过一个行为的实现。这段文档看起来平淡无奇但对代理的约束力是惊人的。你只需要在任务描述里说一句按测试驱动开发技能执行Codex 就会像换了一个人似的先打开测试文件再打开实现文件老老实实按步骤来。这就是技能文档的威力它把隐性经验变成显式指令代理终于有了方法论。2.2 技能选择机制让代理自己决定用什么招式superpowers 里有一个很关键的设计技能不是按名称硬编码调用的而是通过读取技能目录里的所有 SKILL.md让代理根据当前任务自主判断该用哪个技能。这个机制有点像给代理装了一个武器架上面摆满了各种工具它接到任务后会先扫一眼武器架上有什么再选择最趁手的那件。实际操作中我会在项目的 AGENTS.md 文件里写清楚项目根目录下的 .superpowers/skills 存放了所有可用技能当执行编码任务时先扫描该目录选择合适的技能并遵循其中的步骤。这样代理在每次任务开始时都会主动去读技能列表。它可能选择前端重构技能也可能选择Java 单元测试技能完全取决于任务内容。这个代理自主选择技能的机制有利也有弊。好处是灵活坏处是选择不稳定。同一个任务今天可能选技能 A明天可能选技能 B。为了解决这个问题我会在技能文件开头加上非常严格的适用条件比如只在本模块包含 Spring Boot 代码时使用并在文件末尾明确写如果任务不符合上述条件请立即停止使用本技能并选择其他技能。把边界划清楚之后选择稳定性会大幅提升。2.3 为什么这套方案对 Java 项目尤其友好我主要用 Java 做后端开发一开始担心 superpowers 这类从 JS/Python 社区火起来的方法论会不会水土不服实际用下来发现它反而特别适合 Java 项目。原因有三个。第一Java 项目结构规整。Maven 或 Gradle 的目录结构、约定俗成的包名、层层嵌套的业务模块这些都让技能文档能写出非常明确的路径参数。代理不需要自己猜代码放在哪技能里直接指定就行错误率大幅下降。第二Java 项目对测试的依赖性更强。Spring Boot 应用里一个 Controller 要测起来往往得拉起 Spring Context配置 MockMvc处理数据库连接。这里面的坑特别多代理容易绕来绕去。但如果你写一个Java 测试技能把这些复杂场景的模板放进去代理每次都能按模板生成高质量测试比它自己临场发挥稳定太多。第三Java 生态的命令链比较长。编译、测试、打包、启动每一步都可能失败。技能文档可以把跑测试要用./mvnw test而不是mvn test这种带环境细节的经验固化下来。代理一旦读到就不会再犯用了系统没装的新版 Maven这类低级错误。3. 安装与配置从零到能跑3.1 准备环境与前置检查在动手装 superpowers 之前先把基础环境捋一遍。因为热门搜索里经常出现superpowers java和superpowers 安装两个词我猜不少朋友是被这类组合词吸引来的所以我把环境准备写详细一点。首先你需要一个能正常运行的 AI 编码代理。我用的是 OpenAI Codex CLI安装方式很简单需要 Node.js 18 以上的环境node -v npm install -g openai/codex codex --version安装完成后第一次运行codex会引导你登录账号或者配置 API Key。如果公司网络对出网有限制建议提前确认能否正常访问 OpenAI 的服务否则后面跑任务时会卡在认证环节。如果你只是想在 Java 项目里试跑还需要本地环境具备 JDK 和 Maven 或 Gradle。我当前项目用的是 JDK 17 和 Maven 3.9后面所有命令都基于这套环境。准备完成后可以顺手执行一下./mvnw -v确认 Maven Wrapper 可用这一步能避免很多后续麻烦。3.2 拉取 superpowers 技能库superpowers 项目本身是开源的安装方式就是把它克隆到本地。社区里维护得比较活跃的是 Jesse Vincent 那个仓库你可以在 GitHub 上搜索 superpowers 找到选择 star 数最高的那个即可。我的习惯是把技能库放在用户目录的隐藏文件夹下方便所有项目共享mkdir -p ~/.superpowers git clone https://github.com/你的来源地址/superpowers.git ~/.superpowers/skills这里有个小提示克隆完先不要急着用花十分钟把技能目录结构看一遍。你会发现它里面往往分成skills和templates两个大类前者是代理执行时的行为指南后者是生成代码时的脚手架模板。理清结构之后后面配置 AGENTS.md 时心里会很有底。如果你不想把整个社区库都引进来也可以只挑选一小部分技能复制到项目内部的.superpowers/skills目录里。这种方式更轻量适合团队统一管理。3.3 配置 AGENTS.md让代理认技能把技能库拉下来之后关键一步是让 Codex 在每次会话里都知道去哪里找技能。Codex 支持项目级的 AGENTS.md 文件类似很多 AI 工具里的 CLAUDE.md是给代理看的项目说明书。我在项目根目录下创建了一个AGENTS.md内容如下# 项目说明 本仓库是一个基于 Spring Boot 3 的订单服务模块。 ## 编码规范 - 所有新功能必须遵循测试驱动开发技能。 - 代码提交前必须运行 ./mvnw test 并通过全部测试。 - 禁止直接修改 src/main 下代码而不先查看对应测试文件。 ## 技能加载方式 项目存在超级技能库目录为 .superpowers/skills。 接手编码类任务时请先扫描该目录根据任务类型选择合适技能 严格按照技能文件中的步骤执行不要跳步。配置好之后我习惯先做一个快速验证在项目根目录运行codex exec 列出当前项目可用的 superpowers 技能清单并简要说明每个技能的用途。如果配置有效Codex 会立刻输出一长串技能名和说明。如果没有输出八成是 AGENTS.md 路径不对或者技能目录名配错了检查一遍再继续。3.4 写第一个自定义技能从复制开始很多人配置完社区库就急着用我倒是建议先花半小时写一个自定义技能这样你能彻底理解技能是怎么写出来的而不是停留在会用层面。最快的入门方式是从复制开始。挑一个现有的技能目录比如planning把整个目录复制一份改名为java-api-checklist然后打开里面的 SKILL.md把内容改成你自己关心的点。我当时写的是一个针对 Java REST API 的技能里面主要包含检查 Controller 的参数校验注解是否完整。检查 Service 层是否捕获了持久层异常。检查返回状态码是否符合业务语义。检查是否漏了日志埋点。就这么几行内容写完后我让 Codex 在一个旧模块上跑了一遍它真的按这个清单逐项检查还帮我揪出了三个隐藏的校验漏洞。那一刻我对 superpowers 的价值有了更具体的感知它不仅仅是约束代理更是把你长期积累的团队经验变成了可持续执行的质量门禁。4. 实战用 Superpowers 跑通一个 Java 小项目4.1 场景设定一个订单状态机前面说的都是方法论这一节我拿出一个实际跑过的场景完整走一遍流程。这是一个典型的 Java 后端需求给订单模块增加状态流转订单状态包括NEW、PAID、SHIPPED、COMPLETED、CANCELLED不允许从NEW直接跳到COMPLETED也不允许CANCELLED再变回其他状态。没有 superpowers 的时候我大概率会直接让 Codex 写一个OrderStateMachine类然后它输出一个巨大的switch或一堆if/else。但这一次我按下指令请使用测试驱动开发技能完成订单状态机功能。4.2 代理按技能步骤产出测试与实现Codex 读取了 TDD 技能文档后行为完全不一样。它先创建了一个测试文件OrderStateMachineTest.java内容大致如下class OrderStateMachineTest { private OrderStateMachine machine; BeforeEach void setUp() { machine new OrderStateMachine(); } Test void shouldMoveFromNewToPaid() { assertEquals(OrderState.PAID, machine.next(OrderState.NEW, OrderEvent.PAY)); } Test void shouldRejectNewToCompleted() { assertThrows(IllegalStateTransitionException.class, () - machine.next(OrderState.NEW, OrderEvent.COMPLETE)); } Test void shouldRejectCancelledToAnyOtherState() { assertThrows(IllegalStateTransitionException.class, () - machine.next(OrderState.CANCELLED, OrderEvent.PAY)); } }写完测试后它先跑了一遍./mvnw test确认测试是红的然后才开始写实现。这个先红后绿的过程就是 TDD 技能里最核心的一步。以前让 Codex 直接写实现它总爱顺便把测试也写得很宽松现在它先把测试钉死实现只能围着测试转。实现类写完之后Codex 又自动跑了一遍完整测试集。我特别留意到它没有跳过回归检查因为技能文档里明确写了必须跑完整测试集不能只跑新增测试。最终测试全绿而且代码里没有出现允许非法状态流转的隐藏后门。4.3 使用重构技能清理代码状态机跑通之后我接下来给 Codex 下了第二个指令使用代码重构技能对刚才的实现做质量检查重点看魔法数字和重复分支。这一步也值得说一下。代理在重构技能指导下没有直接改代码而是先问我目标是什么。因为我的指令里点明了看魔法数字和重复分支它很快就定位到状态转移表里那几个散落的字符串常量把它们提取成了枚举映射同时把next方法里的多重if/else改成了一个可读性更好的Map转移表。重构完成后代理又自动把测试跑了一遍。这次重构我全程盯着看最让我放心的是它每次改动幅度都很小改一步跑一遍测试而不是一口气大刀阔斧改完再验证。这是重构技能里小步前进原则的实际体现。最终代码行数减少了大约三分之一可读性提升非常明显。4.4 这次实操的关键参数与效果记录为了让过程更有参考价值我把当时环境和结果记录如下项目项具体值JDK 版本17构建工具Maven 3.9 Maven Wrapper测试框架JUnit 5AI 代理Codex CLI技能数量TDD 技能 重构技能新增测试数12测试通过率100%代理生成代码到测试全绿耗时约 4 分钟重构后代码行数变化减少约 35%这个效果并不是每次都能复现但如果技能定义得清楚、任务范围控制得小多数情况下都很稳定。哪怕代理偶尔写出不满意的代码因为有测试兜底我也不会像以前那样心里没底。5. 日常使用中的高频坑与排查建议5.1 症状、原因、解决方案对照表这段时间高强度使用 superpowers前前后后遇到过不少问题我把最常见的几种整理成了一张速查表方便你对照排查。症状可能原因解决方案代理完全无视技能直接写代码AGENTS.md 里没有写先扫描技能目录的指令在 AGENTS.md 开头加上强制加载技能的说明技能加载了但执行时跳步技能文档步骤写得不够细或允许代理自由判断每个步骤改成祈使句明确要求必须删除模糊措辞多个技能互相冲突技能适用条件没有写清楚边界重叠在每个技能开头写明触发条件末尾注明不适用时跳过Java 项目测试跑不起来代理用了mvn test而不是./mvnw test在技能里固化构建命令推荐使用 Maven WrapperCodex 响应很慢技能目录太大每次全量扫描耗时按项目拆分技能库只保留必要技能代理修改了不该动的文件技能里缺少改动范围的约束在技能中加入只能修改 src/main/java/order 目录下文件的边界描述这张表我放在项目 wiki 里每次遇到新问题就往里补一行现在已经有二十多条了。它对我的价值不止解决当前问题更是团队互相对齐语言的一种方式。5.2 我踩过的三个坑出血换来的经验第一个坑是技能文件写得像散文。最开始我从社区库里挑了几个技能一看写得挺漂亮就直接拿进项目用。结果发现代理经常读完技能后说好的我会按步骤执行但实际做起来还是老一套。后来我把一个技能里的尽量可以考虑全部换成了必须禁止行为立刻变了。技能文档越像军令状代理执行越可靠。第二个坑是所有项目共用一份大技能库。我有段时间把十几个技能全放在~/.superpowers/skills里导致代理每次任务都要扫一遍不仅慢还经常选中跟当前项目无关的技能。比如前端重构技能跑到 Java 后端任务上来纯属捣乱。后来我把技能库拆成两层全局只放通用规范项目内部放领域专属技能效率提升很明显。第三个坑是过度信任测试结果。有一次代理跑完测试输出全部通过我放心地合入了主干结果第二天发现某一个之前存在的集成测试被它偷偷删掉了。原因是它觉得那个测试跟本次改动无关为了加快测试速度顺手移除。这件事之后我给自己定了一条铁律代理每次改动测试文件都必须单独向我说明改动原因并在技能里明确禁止删除任何现有测试。从此再没出现过类似问题。6. 最后想说的一些体会用 superpowers 有大半年了它彻底改变了我使用 Codex 的方式。我现在的感受是不要把 superpowers 当成一个装完就能飞的插件它本质上是一套帮你把工程质量经验沉淀下来的框架。技能写得好不好直接决定了代理表现好不好。以前我依赖模型本身的随机涌现现在我更依赖一套可控的、能持续演进的操作规程。我现在养成了一个习惯每次在项目里遇到代理反复犯同一个错误就把这个错误连同纠正方案写成一条新技能。两周下来我的自定义技能库从 3 个涨到了 11 个代理在项目里的表现越来越稳定我自己需要重复交代的背景信息也越来越少。这就是 superpowers 最让我上瘾的地方你在不断给它喂经验它也在不断变得更懂你的项目。如果你正在用 Codex 或者其他 AI 编码代理并且也被生成一时爽、维护火葬场折磨得够呛我建议你找个周末搭一套最小的 superpowers 技能库从一个 TDD 技能开始跑一个真实任务。你会发现AI 编码代理并不是不可控的玄学只要你愿意把方法论写下来它就能变成一个相当靠谱的队友。