如果你手头有一个能跑Codex的环境大概率也遇到过类似的场景一条简单的bug修复它能轻松搞定但一旦任务变成“这个模块有两个编译错误、那个模块的测试还挂了一个用例”它就明显力不从心——不是不会写代码而是不会安排工作。我最近一直在折腾基于Codex的自主编码流程最后把注意力放在了一个叫superpowers的开源工作流项目上。这个东西不是什么神秘框架也不是新语言而是一整套用来“重新教育”AI编码agent的工作规则和工具链。它能解决的核心问题就是让Codex从“你问一步它答一步”的工具人变成接了任务会自己规划、自己执行、自己验证、自己修复的编外员工。这篇内容我会从它产生的背景、底层机制、安装配置讲起再用一个Java项目实战来验证它的真实效果最后把我在使用过程中踩过的坑和排查链路完整复盘。适合已经会用Codex CLI、但觉得它“不够聪明”的人阅读如果你刚接触Codex建议先把基础操作过一遍再来。1. 在认识superpowers之前先说说Codex让人头疼的几个时刻Codex本身的能力不弱尤其在做单点修改、补测试、写文档这类任务时表现相当好。但一旦任务稍微复杂几个老问题就会反复出现。1.1 没有任务拆解容易“抓着哪算哪”默认状态下你给Codex一个包含多个子任务的描述它会倾向于直接开始动手改代码而不是先做任务拆解。比如你说“这个模块编译不过而且相关测试挂了”它很可能直接去改它认为相关的文件改完就跑一边测试如果没过再继续猜。这在小项目上勉强能跑通但Java这种动辄几个模块、上千个文件的工程里没有计划地乱撞就是一场灾难。我之前的经历是让Codex处理一个Maven多模块项目的编译错误它改了A模块里的一个类结果因为依赖关系导致B模块也跟着报错它又去改B模块改完发现C模块的测试开始失败……一个下午就耗在里面了。问题不在Codex不会写代码而在它不会安排代码任务的优先级。1.2 验证反馈弱修完了不知道算不算成功Codex默认也会运行测试、看结果但它对“反馈循环”的利用很浅。它不会主动建立一个“当前我改了什么、验证到了哪一步、还有哪些没验证”的清单。它就像一个没有checklist的实习生做完一件说一件你不追问它就不继续往下推进。尤其是在修复过程中出现新的编译错误或测试失败时默认Codex往往会把报错信息重新读一遍然后陷入“再猜一次”的循环。好消息是它每次都猜得比上一次准一点坏消息是这个过程不可追溯你不知道它为什么这么改也不知道它下一步想干什么。1.3 没有长期记忆换一个会话就要重新解释上下文这个问题在复杂项目里最致命。Codex的上下文窗口再大也有上限一旦任务跨越多个会话或者中间需要压缩上下文它就会把前面几轮的关键决策忘掉。你不得不反复补充背景信息“上次我们已经确认了根因在配置类不要动业务代码”这类话说多了真的心累。所以我当时想要的东西很明确不是更强的代码生成能力而是一套能让Codex养成“工作习惯”的外置大脑。superpowers就是冲着这个需求来的。2. superpowers的核心机制把“工具人”变成“编外员工”的关键设计先说结论superpowers不是一个IDE插件也不是独立运行的Agent框架。它本质上是一套高度结构化的“工作流程规则集”通过一组Markdown文件、技能库和启动约定把Agent的行为从“对话式应答”切换成“任务式执行”。2.1 自主循环与TODO驱动superpowers最核心的机制是“自主循环”。它要求Agent在接到任务后先不要急着写代码而是先创建或刷新一个TODO清单把任务拆解成可验证的步骤然后按顺序执行。一个典型的执行循环长这样读取任务描述拆解出具体的子任务项。写入TODO文件标注每个子任务的状态待做、进行中、已完成、阻塞。每完成一个子任务立即运行对应的验证命令编译、测试、静态检查。如果验证失败读取错误输出定位到具体文件创建修复计划。修复后再跑验证直到这一步变绿。处理下一个子任务。我不止一次感叹这套循环如果把主语从“Agent”换成“人类开发者”完全就是一个资深工程师在大型项目里工作的标准流程。它避免了两个极端不规划就直接动手、做完了不验证就宣布成功。2.2 技能库把“经验”固化成人人可复用的SOPsuperpowers里有个很妙的机制叫“技能”。简单说就是把一类高频任务的标准操作步骤写成一个独立的Markdown文件让Agent在执行任务时自动加载对应的技能。比如“Java编译失败排查”技能内容大致是这样的结构# 技能Java编译失败排查 ## 适用场景 Maven/Gradle项目编译失败错误信息包含多个错误点。 ## 执行步骤 1. 先定位第一个编译错误只处理这一个。 2. 找到对应的源文件和行号阅读上下文代码理解错误原因。 3. 修改代码后重新执行编译命令。 4. 如果出现新的错误继续处理下一个绝不要一次性改动多个文件。 5. 全部编译通过后再运行相关测试模块。 ## 注意事项 - 不要依赖IDE的自动修复Agent环境里没有IDE。 - 遇到依赖缺失先检查pom.xml或build.gradle确认依赖坐标是否正确。这种技能的价值在于它把“经验”从人脑中搬到了文件系统里。遇到同类问题Agent不需要重新试错直接按SOP走。而且技能文件是纯文本任何人都可以往里面补充自己的实践经验攒成团队的私有知识库。2.3 记忆持久化与上下文交接superpowers另一个关键设计是记忆持久化。它会引导Agent在任务过程中把阶段性结论写入本地文件比如learnings目录下的Markdown文件。这些内容不是给人看的流水账而是给未来会话读的“交接文档”。实际操作中它的效果非常明显。有一次我让Codex修一个关于时区处理的bug任务做到一半上下文被压缩了如果是默认模式它大概率会忘掉已经确认的根因。但superpowers模式下Agent在前面几轮已经把“问题根因是日志组件默认UTC时间”写进了learnings文件上下文压缩后它自己会去读这些文件然后无缝衔接继续干。我觉得可以把这三块机制简单类比一下自主循环是工作纪律技能库是工作经验记忆持久化是纸质笔记。纪律保证不跑偏经验提高一次成功率笔记确保长时间作战不遗忘。三者合在一起才勉强算得上一个“合格的远程开发者”。3. 安装与配置把superpowers接进Codex的完整步骤下面这部分是实操重点。我会按正常接入流程一步步说明并标注每一步背后的意图方便你出了问题能自己排查。3.1 环境准备需要什么前提条件要跑通这套流程你需要准备以下环境一台Linux/macOS的机器Windows也行但后面会有额外坑我会在第5节讲。Node.js 18以上版本Codex CLI本身是Node生态。已经安装并登录好的Codex CLI能正常执行codex exec命令。Git用来拉取superpowers仓库。一个真实的项目目录建议先拿一个小型Java工程试水。这里多说一句不要直接在项目仓库里跑codex然后手动粘贴规则那样很容易漏东西。正确做法是把superpowers作为一套独立的工作流文件放到一个固定目录再让Codex在启动时去加载它。3.2 拉取工作流文件并放置到固定目录第一步把superpowers工作流文件克隆下来。具体命令不需要死记它和普通Git Clone没区别git clone superpowers仓库地址 ~/.superpowers克隆完成后检查一下目录结构。通常情况下你会看到类似这样的内容AGENTS.md工作流总规则Agent每轮都要参考的核心行为守则。skills/各类技能的Markdown文件集合。runbook/针对不同类型项目的启动手册。templates/TODO、进度报告等过程文件的模板。把仓库放到~/.superpowers这个独立目录的原因是你的项目仓库是经常变的但工作流规则应该稳定。两者分离项目怎么清理都不会影响工作流文件。3.3 在项目根目录创建AGENTS.md入口文件下一步在你要处理的Java项目根目录下创建一个AGENTS.md文件内容是告诉Codex请加载superpowers工作流并按它的规则执行任务。一份简化但可用的AGENTS.md大概长这样# 项目工作守则 执行任务时必须遵守以下规则 1. 在开始修改代码前先扫描项目结构理解模块划分。 2. 将所有待办项写入TODOs.md每完成一步就更新状态。 3. 每项修改完成后必须运行对应的验证命令编译/测试。 4. 验证失败时读取完整错误日志并基于日志创建修复计划。 5. 关键结论和根因分析写入learnings目录供后续会话参考。 更多详细规则见 ~/.superpowers/AGENTS.md请不要小看这短短几行。它相当于“员工手册”的开篇——告诉Agent现在开始按新规矩干活。它不需要写完所有细节但必须让Agent知道去哪里找完整版规则。3.4 调整Codex的权限策略让Agent能自主执行命令这是整个配置过程中最容易被忽略、却最关键的一步。superpowers的自主循环要求Agent在执行命令时不被打断。如果你的Codex还停留在“每次执行命令都要用户批准”的模式那么循环会在第一条命令后卡死。Codex CLI的权限策略一般通过配置文件设置把approval策略调整为自动接受即可。不同版本的配置项名称略有差异但大方向是一致的允许Agent在没有人类干预的情况下执行无副作用的命令或者指定一批可信命令白名单。我个人的建议是如果你只是在自己机器上跑直接放开自动接受理由很简单——就算改坏了也是Git仓库随时能回滚。等到你要把它接进CI/CD流程或共享机器时再考虑用命令白名单来收紧权限比如只允许git、mvn、npm test这类命令自动通过。3.5 启动Codex并验证工作流是否生效配置完成后启动Codex的方式也需要调整。不要直接问“帮我解决这个问题”而是要让Agent先进入superpowers工作模式。启动时可以这样下达指令请加载superpowers工作流切换到自主执行模式。当前任务是修复项目中的所有编译错误并在结束时运行完整的测试套件。启动后观察它的行为。如果配置正常你应该在几秒钟内看到它开始扫描项目、创建TODO列表而不会立刻去改代码。为了确认工作流真的被加载了有一个很实用的验证方法故意问它“请复述你的核心工作守则前三条”。如果它能准确答出TODOs、验证循环、learnings写入这些内容说明AGENTS.md已经被正确读取了。如果它答不上来那说明规则文件没有被加载后面所有行为都会变回默认模式。4. Java项目实测从“每次只改一个小点”到“自动跑完修复闭环”光说不练不行我找了个多模块Java项目实际跑了一轮。这个项目的结构不算复杂三个Maven模块核心库、业务服务、Web入口外加一层集成测试。我在里面故意埋了几个问题一个编译错误、一个过期API导致的测试失败、一个模块间的依赖漏配。4.1 启动阶段Agent自己产出了任务清单启动superpowers模式后Agent先花了大约一分钟读取项目结构然后自动创建了一个TODOs.md文件。我没给它任何提示它自己把任务拆成了下面几个条目扫描POM文件确认模块间依赖关系。修复core模块的编译错误。修复services模块中因API变更导致的编译错误。修复Web模块的测试失败。运行全模块测试确认所有用例通过。这里最让我满意的是它把“扫描POM”放在第一位。很多默认模式的Codex会在不了解模块依赖的情况下直接改代码这在一个多模块项目里是致命的。superpowers的AGENTS.md里写了一条“先扫描项目结构”它就老老实实照做了。4.2 执行阶段一个真实的修复循环接下来它开始按清单逐项执行。我记录了一段它处理第一个编译错误的执行轨迹运行了mvn -pl core -am compile拿到编译错误输出。错误定位到core/src/main/java/.../DateUtils.java第37行一个方法签名变了调用处没同步更新。它没有直接改DateUtils而是先读了调用处的上下文确认语义没变化后补全了新的参数。再次运行编译命令错误消失。到这里还只是常规操作。真正体现出差异的是后面处理集成测试失败时。测试抛出的是一个Mockito相关的异常大致内容是“当调用某个方法时没有找到对应的Mock配置”。默认模式下的Agent通常会去补Mock配置然后祈祷测试能过。但superpowers模式下的Agent做了一件很骚的事它先读了测试类的完整代码又检查了被测类的实现发现被测类的内部实现已经在前面某次编译修复时改变了调用路径所以原来的Mock配置根本不会命中。它最终的动作是改Mock配置使其匹配新的调用方式并顺手更新了一个断言里的期望值。整个过程没有额外打扰我直到跑完所有测试后才汇报结果。4.3 效果对比人肉模式、默认Codex、superpowers模式跑完这一轮我顺手整理了一个对比表覆盖的是同样一次多问题修复任务维度默认Codexsuperpowers模式任务拆解基本不做直接改先写TODOs按优先级推进处理编译错误逐个试错可能反复只改第一个错误验证后再继续测试失败先猜原因碰运气先读测试和实现定位根因上下文管理压缩后就失忆靠learnings文件恢复上下文执行中断次数频繁请求确认基本全程自主我个人的体感是代码生成的单点能力并没有提升多少但整个任务完成的质量和可追溯性提升了一个档次。就像同样两个人写代码一个想到什么写什么一个先列大纲再动笔后者的产出不只在质量上更稳更重要的是每一步都有迹可循review起来舒服得多。5. 实测中遇到的问题与排查链路完整的踩坑记录这部分的价值不亚于前面的安装配置。我前前后后踩了四个坑每一个都花了不少时间才理清根因。下面按完整的排查过程来写不给灵机一动的答案。5.1 坑一循环卡死在“等待命令批准”现象Agent跑了几步日志停在那里一行行显示“等待用户批准执行命令”然后任务就没了下文。这个坑我一开始没想明白因为前面几步它明明能自己执行命令。排查链路我先是翻看了Codex的会话日志发现前几条命令都是自动执行的到了某一条特定命令比如mvn test后开始请求批准。我意识到这不是网络问题、也不是工作流文件问题而是权限策略在某类命令上被拦住了。进一步检查配置文件发现默认的approval策略只放行了一小部分“无副作用”命令而mvn test这类会修改本地构建产物的命令被归类为“有条件允许”。所以问题根源不是superpowers本身而是它和我本地的Codex权限配置不匹配。解决办法把权限策略全局改成自动接受或者把mvn、git、cp这类我信任的命令加入白名单。改完后重新启动循环立即恢复了顺畅。5.2 坑二Agent开始“自作主张”改得范围越来越远现象本来让它修A模块的编译问题结果它一路改到了B模块还顺手重命名了一个公共方法。一开始我觉得是它理解任务出了问题可能是提示词里没说清楚。但后来我发现每次会话它都这样那就不是提示词的事了。排查链路我先检查项目根目录的AGENTS.md是否存在结果文件在。然后我让Agent“读出AGENTS.md的第一行”它能正确读出。但我继续追查发现它读取的是另一个地方的AGENTS.md——原来我用的是Codex的全局配置全局里有一个旧版AGENTS.md把它“召回”到了一个错误的工作目录。问题根源很清楚Codex加载规则文件时会优先加载最近目录里的AGENTS.md而我的全局配置指向了一个不相关项目。Agent按照那套过时规则里的“可以重构公共接口”执行自然就越改越远。解决方案清理掉全局配置中指向错误路径的规则引用确保项目根目录的AGENTS.md是唯一生效的入口。修复之后Agent的任务边界立刻收敛了。5.3 坑三Maven多模块下Agent在错误目录跑了命令现象Agent在根目录执行mvn test结果所有模块都编译失败但它报错指向的是某个子模块的编译错误导致修复方向整个错了。排查链路看Agent的执行日志它在根目录跑了mvn testMaven尝试把整个reactor都构建一遍。问题是它没有先编译依赖模块而子模块之间还有未发布的SNAPSHOT依赖于是编译失败。我一开始以为是Maven命令选得不对但我注意到Agent完全可以读取POM文件它没这么做的原因大概率是技能库里没有“Java多模块项目处理”的SOP。解决方法是两个一是手动在项目里补充一个“Java多模块构建”技能文件明确写下“碰到多模块优先执行mvn -pl 模块 -am test并用-DskipTests先安装依赖模块”二是检查它是否加载了项目根目录的POM。我把技能文件补充进去后同样的场景它一次就选对了命令。5.4 坑四上下文压缩后“忘了自己在干嘛”现象一个比较大的Java项目跑了一个多小时后Agent的上下文被压缩它开始重复读取已经修过的文件甚至尝试再次修改已经改对的代码。排查链路我观察到一个规律——它每次上下文压缩后会重新扫描项目结构但不会再主动去读learnings目录。我最初怀疑是记忆文件命名不规范导致它没有识别到。检查后发现learnings文件确实生成了但放在了一个隐藏目录里而AGENTS.md里写的是“写入learnings目录”没有明确给出绝对路径。Agent在压缩上下文后因为路径不明确就选择了放弃读取直接重新扫描。这个问题修复很简单在AGENTS.md里把记忆目录的绝对路径写清楚同时约定“上下文压缩后第一步必须读取该目录下的最新文件”。改完后再测上下文压缩后它就能无缝接上了。这个经历也让我意识到记忆系统不能只靠“写了就行”还得让Agent在关键时刻有地方去查老话说得好好记性不如烂笔头但烂笔头也要放在固定的位置。给同样在折腾这套流程的人几句经验之谈如果你打算跟进superpowers工作流我的建议是分三步走先拿一个小型项目跑通安装和基础循环感受TODO驱动的节奏再把它应用到一个中等规模的Java项目上重点观察多模块场景下的命令选择最后才是把它拉到真实业务项目里配合Git分支和code review使用。我实际的习惯是每轮任务结束后会让Agent花五分钟写一段“本轮经验”到项目的learnings目录把那些非显而易见的结论沉淀下来。比如“这个模块不能直接改DateTimeFormatter的pattern因为序列化层有缓存”——这种经验单独看毫无意义但在未来的某一次修复里它可能帮你省下两个小时。说句实在话superpowers并没有改变AI写代码的本质它改变的是AI工作的方式。方式这东西恰恰是最容易被低估的地方。工具还是那个工具模型还是那个模型但装上工作流之后Codex确实从“实习生”变成了“熟手”。你要是手头正好有复杂的Java项目要整值得花一个下午把这套东西装上试试。