最近在折腾AI编程工作流的时候codex superpowers这个词反复出现在我眼前。它不是新的模型也不是某个IDE插件而是给OpenAI Codex这个命令行AI编程助手配上一整套工作制度的开源方案。你可能已经试过让AI帮忙写代码——它能聊得头头是道但一放进真实项目里常常不是漏了依赖就是改坏了别的地方或者干脆给你原地画饼。superpowers就是冲着这些痛点来的它把AI从什么都懂一点的问答机器人改造成会先读文档、再列计划、然后小步提交、最后自己跑测试的工程协作伙伴。如果你在用Codex或者想用命令行AI编程工具处理中大型项目这篇文章就是为你准备的。1. 先说清楚superpowers到底解决了什么问题1.1 它不是魔法是一套流程纪律先说结论superpowers并不是给Codex额外装了个大模型也不是什么黑客技巧。它本质上是一组精心设计的提示词策略、项目文档规范和技能包存放在本地通过Codex的配置文件加载进来。它的作者是Jesse Vincent一个在开源社区很有名的程序员。他把这套方案命名为superpowers意思是给本来就聪明的Codex补上稳定发挥的能力。为什么需要稳定发挥因为大模型天然有方差。同一句话问十次十次可能给你十种写法今天它知道先看测试再改代码明天可能一上来就改配置文件。在纯聊天的场景里这种随机性问题不大可一旦放到真实项目的代码库中随机性就是事故的源头。superpowers的核心做法是把AI的工作流程压缩成一套固定纪律开工前先读什么、动手前先列什么计划、每完成一步要做什么校验、做完之后要交什么记录。它不改变模型本身的智商但把如何干活的路径牢牢钉死。这就像给一个天赋很高的实习生发了本员工手册作用不是教他写代码而是让他别乱来。1.2 三个让我印象深刻的痛点我在自己的项目里试跑过一段时间后发现它主要在解决三个实际痛点。第一个是上下文缺失问题。你让AI改一个订单模块它只看得到当前对话里的那几段代码不知道项目里还有别的模块在依赖这个类的接口。结果一改编译过了但另一个服务运行时报错。superpowers强制AI在动手前先读AGENTS.md和项目结构文件把全局视角补上这非常关键。第二个是任务漂移问题。如果你直接对Codex说帮我加一个取消订单接口它经常会顺手把数据库模型也改了、把中间件也加了、把路由表也动了一次改十几个文件。出问题以后排查起来极其痛苦。superpowers要求AI先输出计划改哪些文件、每个文件改什么、是否需要数据库变更等你确认之后才动手。等于是在任务开始前加了一道人工审核闸门。第三个问题是承诺与能力不匹配。AI特别爱说好的我会确保所有测试通过我会注意代码风格说完就忘。superpowers把自我校验变成了强制步骤要求AI在完成实现之后自己编译、自己跑测试、自己列举已经验证过哪些内容。这比靠模型自觉要可靠得多。1.3 和普通提示词、插件方案的区别市面上很多AI编程增强方案本质是给你一段更长的prompt告诉你你是一个资深工程师请仔细思考逐步回答。这类方案有效但很依赖模型当时的发挥而且没法沉淀成项目级的知识。superpowers不太一样。它把方法和知识分开了。方法是提示词、技能包和工作流知识是你项目里的AGENTS.md、文档、代码约定。它把AI变成了一个带着文件夹干活的人开工前先看文件而不是光凭脑袋里的记忆。这种设计方案让它的效果不依赖某个特定模型——GPT也好、其他模型也好只要遵循同一套流程输出质量的方差都会被压下来。这一点我认为是它和普通提示词方案最本质的区别。2. 核心设计拆解为什么这套方案能稳住AI2.1 工作流从一问一答变成项目协作superpowers最让我喜欢的一点是它的工作流设计得像一个真正的开发协作流程。它不追求AI一次生成完所有代码而是强制走一段类似入职—分析—计划—实现—验证—总结的路径。每次你给它一个任务它会先读取项目里的AGENTS.md文件弄清楚项目是什么、命令怎么跑、代码风格怎么样、有哪些不能碰的区域。然后它会打开和任务相关的源码文件形成对现状的理解。接着输出一份执行计划列清楚要动哪些文件。你对计划点头之后它才开始写代码。每完成一个步骤它会停下来验证最后再汇总结果。这套流程看起来慢但实际省下的时间非常可观。我试过让Codex直接写一个功能它在三分钟内改完八个文件我花了一个小时修回归问题。而用superpowers的流程它五分钟列完计划我确认后它花十分钟实现并测试全程没有返工。这个对比让我彻底接受了慢就是快的理念。2.2 AGENTS.md给AI的入职培训手册AGENTS.md是superpowers工作流里最核心的文件可以理解为给AI看的新员工手册。Codex CLI本身就支持读取项目里的AGENTS.md但superpowers把它的地位提到了最高——要求AI在每次会话开始、每个新任务开始前都必须先读它。这份文件里写什么决定了AI在项目里是懂规矩的协作工程师还是瞎猜的临时工。我的经验是AGENTS.md越具体越好。不要只写这是一个电商系统而要写清楚技术栈是什么、构建命令是什么、测试命令是什么、代码分层的约定是什么、哪些目录不能改、数据库变更流程是什么、完成一个任务需要满足什么标准。它本质上是一份验收标准行为边界项目地图三合一的文件。你花三十分钟把它写好换来的是AI几百次任务都走在正道上。2.3 技能包让AI知道自己有多少种干法superpowers的另一个重要设计是技能包。所谓技能就是一组组结构化的markdown文件每个文件描述一种能力的适用场景和执行方法。比如分析既有代码该怎么做、规划任务拆解该怎么做、实现功能时该遵循什么步骤、调试问题时要按什么顺序排查。系统提示词会告诉AI你拥有以下技能并引导它在遇到对应任务时主动调用。这就像给实习生发了一张岗位技能清单。他不用靠猜来决定怎么处理任务而是翻开手册找到对应章节按里面的SOP执行。实际效果就是AI面对不同任务时输出质量更稳定而且使用者能预测它下一步做什么。这一点在团队协作和多任务切换时特别有价值。我自己在用它处理代码审查、安全排查、性能调优这类不那么常规的任务时明显感觉到它比裸Codex更知道轻重缓急。2.4 节奏控制慢就是快superpowers里有个很重要的理念叫节奏控制。它要求AI在动手之前停下来想一想在改完一个文件之后停下来验证一下。这种节奏在人类工程师看来太自然了但对AI来说是反直觉的——因为模型的最大倾向就是一口气把话说完、把代码写完。没有一个外部机制强制它分段它就会一直输出到上下文尽头。我拿这个理念去类比日常开发你写一段复杂逻辑大概率不会不编译就一次性写二十个函数而是写几个就跑一下测试确认没跑偏再继续。superpowers把这个习惯移植给了AI。它通过各种提示词让AI养成每走一步就检查一下当前状态的反射避免在错误的方向上跑太远。这个设计虽然朴实但我认为是整个方案里最提效的部分。因为AI在编程上的错误越早发现修复成本越低跟人是一样的。3. 实操落地从安装到Java项目配置3.1 准备工作与安装在开始之前你本机需要准备好Node.js 18以上、Git、OpenAI Codex CLI。Codex本身的安装方式不在本文展开但有一个前提——你先得确认在终端里能正常跑codex命令并且已经完成模型访问的配置。装完Codex之后接下来就是获取superpowers的源码。按住键盘不放在终端里执行克隆仓库的命令从GitHub上把superpowers仓库clone到本地。仓库里会有一个安装脚本常见的情况是直接运行./install.sh它会把配置、提示词、技能包等文件链接到你本机的~/.codex配置目录下。如果在安装脚本不可用或者你想手动控制也可以直接参考仓库里的目录结构把config.toml和skills、prompts等目录复制到~/.codex下。安装完成后执行codex进入交互界面如果对话中能看到类似superpowers已加载或者模型主动列出可用技能就说明安装成功。这里有一个我用下来的心得安装之前务必备份你已有的~/.codex/config.toml。superpowers的安装过程会改变或者覆盖你现有的Codex配置如果之前配过其他模型参数或者自定义过提示词不备份就装很容易丢配置。我头一回就是没备份直接把之前调好的温度参数弄丢了后来花了点时间重新调。3.2 初始化Codex配置安装完成后最关键的是理解config.toml里发生了什么。superpowers会在里面注册一个专门的profile把所有提示词和技能目录关联到这个profile上。也就是说它不是简单修改你全局的Codex行为而是给你一套独立的带规则的工作环境。这样你既可以用普通模式跟Codex闲聊、问问题也可以在处理正经开发任务时切到superpowers模式。配置里通常还会指定模型名称和相关参数。不同时期、不同版本的superpowers对模型的要求可能有变化建议直接以仓库README里写的配置为准。如果你之前对Codex做过定制化配置可以用profile嵌套的方式把superpowers作为一个子profile加载避免覆盖你原有的设置。我的建议是第一次先保持默认配置跑通一个简单任务确认整个链路没毛病之后再按自己的习惯调整。# 安装完成后可以用一条命令确认当前生效的配置 codex --config ~/.codex/config.toml --info3.3 在项目根目录写AGENTS.mdJava版接下来是实战里最重要的一步写项目级的AGENTS.md。网上很多教程会简单翻译仓库自带的模板但真正要发挥作用你必须针对自己的项目改。这里我拿Java项目举一个我最常用的实例。下面是我给一个Spring Boot订单服务项目写的AGENTS.md你可以直接参考使用。# AGENTS.md ## 项目简介 这是一个基于 Spring Boot 3.x 的订单服务使用 Maven 构建最低要求 JDK 17。 业务领域商品订单的创建、支付状态流转、取消与退款。 ## 常用命令 - 编译mvn -q compile - 运行全部测试mvn -q test - 运行单个测试类mvn -q -DtestOrderServiceTest test - 打包mvn -q package -DskipTests ## 代码约定 - Controller 层只做路由和参数校验不写业务逻辑。 - Service 层必须通过构造器注入依赖不要用字段注入。 - Entity 只做持久化映射禁止在 Entity 中写业务方法。 - 所有对外接口统一返回 ResultT 包装类型。 - 涉及金额、状态字段一律使用 BigDecimal 和枚举禁止使用浮点型。 ## 任务边界 - 不允许修改 database/migration 目录下已有的迁移脚本。 - 改动公共接口签名之前必须向用户说明影响范围并等待确认。 - 不要擅自引入新的第三方依赖如果确有必要先解释原因。 ## 完成标准 - 新增或修改代码后必须执行 mvn test并确保通过。 - 涉及数据库字段变更时必须同时提供新的 Flyway 迁移脚本。 - 禁止在未执行测试的情况下声明已完成。写这份文件的过程等于把项目里人看起来理所应当、AI完全不知道的上下文全部显式化。有了它AI就能在开工前搞清楚边界和验收条件。我实测下来同样一个Java任务有AGENTS.md和没有AGENTS.mdAI第一次生成代码的质量差距非常明显。有这份文件的场景里基本不会出现AI偷偷改了pom.xml这种事故。3.4 本地会话记录与技能目录说明superpowers的安装目录里除了配置和提示词还有一块容易被忽略的内容——本地会话记录机制。它会在工作目录下维护类似笔记文件的结构让AI在每次会话开始时先读取之前留下的记录了解上一次做到了哪里、踩过什么坑、下一步计划是什么。这个设计特别适合中断后继续干活的情况。比如你昨天让AI搭一个订单导入功能写到一半就关终端了。今天重新打开Codex继续聊它先读笔记自动接上已经完成了文件解析部分下一步是写数据校验逻辑而不是像之前那样从头问起。这个体验对真实开发来说太重要了因为没有人能保证一次会话就把任务干完。技能目录则位于~/.codex下的技能文件夹中。里面有几十个markdown文件每个文件都描述一类任务的标准做法。你可以随时打开看也可以自己添加新的技能文件。比如你经常处理某个内部框架的兼容问题可以自己写一个处理XXX框架兼容性的技能让AI按你写的步骤去排查。这种私有技能包的能力让superpowers非常适合团队沉淀集体经验。3.5 跑通一个真实Java任务理论说了一大堆我实际演示一个典型任务的完整流程。假设项目是一个订单服务我现在要求Codex给订单模块新增一个取消订单的接口。在superpowers模式下它的行为大致是这样的。第一步它先读AGENTS.md再打开pom.xml、订单实体类、现有Controller和Service甚至看一眼已有的测试。然后它输出一份简明计划新建一个CancelOrderRequestDTO、在OrderService中新增cancelOrder方法、在OrderController中新增POST /orders/{id}/cancel路由、补充两个单元测试、不需要数据库变更。我确认无误后它才开始动工。先写DTO再写Service再写Controller每写完一个文件会停一下检查类型和依赖关系。最后它会主动执行mvn -q test把测试结果贴出来然后总结改动了哪些文件、测试是否全部通过、有没有遗留风险。整个过程不用我反复纠正方向它自己就在计划—实现—验证的闭环里走完了。这个体验用一句话形容就是之前在指挥一个什么都不懂的实习生现在像在跟一个懂行但需要审批的同事协作。3.6 使用turbo mode加速简单任务superpowers并不要求所有任务都走全套流程。它内部包含一个turbo mode的概念适合那些目标明确、风险极低的小改动比如把日志输出格式改成JSON把某个工具类的常量提取到配置里。在这些任务上你可以在Prompt里明确告诉AI使用turbo mode它就会跳过冗长的分析和计划阶段直接动手实现并跑测试。这个设计很务实。如果每次改一行日志都要走读AGENTS.md—分析—计划—确认—实现—验证—总结的流程效率反而被拖垮。真正合理的用法是根据任务风险来动态选择模式涉及跨模块改动、数据库变更、公共接口调整的时候老老实实走完整流程单纯改常量、调格式、删无用代码的时候直接用turbo mode快速过。这一快一慢之间才是superpowers真正提效的地方。4. 常见问题与定位思路4.1 速查表我自己使用过程中遇到过不少问题也看过社区里别人踩坑的经历。把典型的几个整理成速查表方便你快速对照。问题现象可能原因定位思路AI不读AGENTS.md上来就写代码superpowers的profile没有正确加载检查~/.codex/config.toml里是否注册了skills和prompt确认安装时软链是否有效任务拆得太细进展非常慢简单任务也走了完整分析流程在Prompt里明确要求进入turbo mode跳过分析和计划阶段一改就是十几个文件拦不住任务边界定义不清楚在AGENTS.md的任务边界里写明涉及公共接口变更需确认多模块项目里不知道从哪下手AGENTS.md缺少模块地图在AGENTS.md开头加一页模块目录树标注各模块职责和入口编译报错后反复试错AI没有先看pom.xml的依赖关系在AGENTS.md中指定动手前先读pom.xml确认依赖版本测试跑不过AI自己修不好缺少最小复现意识要求AI先定位失败用例用-DtestXXTest单独跑再逐步扩大范围4.2 案例复盘AI不读AGENTS.md我自己在刚装完superpowers时遇到过最头疼的问题明明安装成功了但AI仿佛没看见AGENTS.md一样跳过分析和规划直接开始输出代码。后来排查发现问题出在配置加载的顺序上。Codex在启动时会读取配置文件如果当前工作目录不在项目根目录或者配置里指定的某个路径不对AI就会退回默认行为。解决方式很简单把项目目录切到cd /path/to/project确认当前目录下有AGENTS.md然后在配置里指定好superpowers的profile以后重启Codex会话。还有一个隐蔽的坑很多终端工具启动Codex时不在项目目录里导致它根本找不到AGENTS.md看起来就像没读文档。碰到这种情况先在终端里手动进入项目目录再启动问题立刻就消失了。4.3 案例复盘中途改动文件太多另一个常见现象是AI在执行任务过程中临时起意顺手改了并不需要的文件。比如我在一个遗留Java项目里让它加一个字段它居然连带着改了另一个模块的接口定义还动了数据库迁移脚本。这个问题的本质是任务边界没写清楚AI不知道哪些区域是禁区。我在AGENTS.md里加了任务边界一节明确写不允许修改database/migration目录下已有迁移脚本改动公共接口签名前必须向用户说明影响范围。之后AI在生成计划时会先检查有没有触及这些红线甚至会在计划阶段主动提醒我这个改动会影响到公共接口需要您确认。这种方式比我人工盯着它改代码要省心太多。4.4 案例复盘复杂模块迷失入口还有一个值得一提的坑是多模块的Java项目。AI面对一个包含十几个子模块的工程时经常不知道业务入口在哪。你让它改订单查询它可能在common模块里翻了半天找不到实际的业务代码。这其实不是superpowers不行而是AGENTS.md里没给够线索。我把项目的模块结构树、各模块的职责说明和几个关键入口类的位置写进了AGENTS.md同时标注了订单模块的代码在XXX子模块下的YYYY包里。从那以后AI找入口的速度快了很多定位代码也不会跑偏。这也印证了我前面说的AGENTS.md不是仪式感它是实打实的上下文补给线。5. 哪些场合别硬上superpowers5.1 适合用的地方superpowers最适合的场景是中大型项目、多人协作代码库、以及对代码质量和可维护性有明确要求的日常工作。在这些场景里AI的发挥不稳定会直接转化为返工成本和线上风险superpowers用流程纪律把这些风险压到了可控范围。同时它有沉淀知识的能力AGENTS.md和技能包会随项目一起演进。今天花半小时写好的规范明天、下个月、甚至换了个AI工具都还能复用这是我觉得它最划算的地方。5.2 不适合用的地方它也不是万能药。如果你只是写一次性脚本、做个Demo验证想法、或者在一个不打算长期维护的练习项目里随便试试那这套流程反而会拖后腿。为了一个一次性脚本去写AGENTS.md、走计划确认流程纯粹是浪费生命。这种场景里直接让AI火力全开、快速输出反而更合适。我自己的做法是小任务、临时任务用裸Codex直接跑正经项目才切到superpowers模式。工具是为人服务的不是反过来。5.3 使用中的几条私人建议最后分享几个切切实实的建议。第一AGENTS.md一定要当成给AI的入职培训文档来写而不是简单的项目介绍。它越具体AI越不会跑偏。第二不要一上来就追求把所有流程跑完先拿一个小功能试水观察AI的行为是否稳定、计划是否符合预期再逐步扩大使用范围。第三技能包这个机制值得好好利用。遇到一次性的、复杂的排查过程可以把当时的排查步骤记成一个技能文件下次AI遇到类似问题照着文件做就行等于把个人经验沉淀进了工具里。我踩过最深的坑是第一次装完就拿着一个遗留Spring项目直接跑AI上来就提议改pom.xml的依赖版本吓得我立刻回滚。后来把AGENTS.md写清楚把不允许擅自改pom.xml依赖写进任务边界AI才老实下来。这个经历让我彻底明白了superpowers真正管理的不只是模型输出更是人对AI的预期。投入二十分钟写好项目规范省下的是后面几十个小时的返工时间。如果你也在用Codex处理正经项目这套方案值得一试。
Codex Superpowers：用AGENTS.md和技能包打造稳定AI编程工作流
最近在折腾AI编程工作流的时候codex superpowers这个词反复出现在我眼前。它不是新的模型也不是某个IDE插件而是给OpenAI Codex这个命令行AI编程助手配上一整套工作制度的开源方案。你可能已经试过让AI帮忙写代码——它能聊得头头是道但一放进真实项目里常常不是漏了依赖就是改坏了别的地方或者干脆给你原地画饼。superpowers就是冲着这些痛点来的它把AI从什么都懂一点的问答机器人改造成会先读文档、再列计划、然后小步提交、最后自己跑测试的工程协作伙伴。如果你在用Codex或者想用命令行AI编程工具处理中大型项目这篇文章就是为你准备的。1. 先说清楚superpowers到底解决了什么问题1.1 它不是魔法是一套流程纪律先说结论superpowers并不是给Codex额外装了个大模型也不是什么黑客技巧。它本质上是一组精心设计的提示词策略、项目文档规范和技能包存放在本地通过Codex的配置文件加载进来。它的作者是Jesse Vincent一个在开源社区很有名的程序员。他把这套方案命名为superpowers意思是给本来就聪明的Codex补上稳定发挥的能力。为什么需要稳定发挥因为大模型天然有方差。同一句话问十次十次可能给你十种写法今天它知道先看测试再改代码明天可能一上来就改配置文件。在纯聊天的场景里这种随机性问题不大可一旦放到真实项目的代码库中随机性就是事故的源头。superpowers的核心做法是把AI的工作流程压缩成一套固定纪律开工前先读什么、动手前先列什么计划、每完成一步要做什么校验、做完之后要交什么记录。它不改变模型本身的智商但把如何干活的路径牢牢钉死。这就像给一个天赋很高的实习生发了本员工手册作用不是教他写代码而是让他别乱来。1.2 三个让我印象深刻的痛点我在自己的项目里试跑过一段时间后发现它主要在解决三个实际痛点。第一个是上下文缺失问题。你让AI改一个订单模块它只看得到当前对话里的那几段代码不知道项目里还有别的模块在依赖这个类的接口。结果一改编译过了但另一个服务运行时报错。superpowers强制AI在动手前先读AGENTS.md和项目结构文件把全局视角补上这非常关键。第二个是任务漂移问题。如果你直接对Codex说帮我加一个取消订单接口它经常会顺手把数据库模型也改了、把中间件也加了、把路由表也动了一次改十几个文件。出问题以后排查起来极其痛苦。superpowers要求AI先输出计划改哪些文件、每个文件改什么、是否需要数据库变更等你确认之后才动手。等于是在任务开始前加了一道人工审核闸门。第三个问题是承诺与能力不匹配。AI特别爱说好的我会确保所有测试通过我会注意代码风格说完就忘。superpowers把自我校验变成了强制步骤要求AI在完成实现之后自己编译、自己跑测试、自己列举已经验证过哪些内容。这比靠模型自觉要可靠得多。1.3 和普通提示词、插件方案的区别市面上很多AI编程增强方案本质是给你一段更长的prompt告诉你你是一个资深工程师请仔细思考逐步回答。这类方案有效但很依赖模型当时的发挥而且没法沉淀成项目级的知识。superpowers不太一样。它把方法和知识分开了。方法是提示词、技能包和工作流知识是你项目里的AGENTS.md、文档、代码约定。它把AI变成了一个带着文件夹干活的人开工前先看文件而不是光凭脑袋里的记忆。这种设计方案让它的效果不依赖某个特定模型——GPT也好、其他模型也好只要遵循同一套流程输出质量的方差都会被压下来。这一点我认为是它和普通提示词方案最本质的区别。2. 核心设计拆解为什么这套方案能稳住AI2.1 工作流从一问一答变成项目协作superpowers最让我喜欢的一点是它的工作流设计得像一个真正的开发协作流程。它不追求AI一次生成完所有代码而是强制走一段类似入职—分析—计划—实现—验证—总结的路径。每次你给它一个任务它会先读取项目里的AGENTS.md文件弄清楚项目是什么、命令怎么跑、代码风格怎么样、有哪些不能碰的区域。然后它会打开和任务相关的源码文件形成对现状的理解。接着输出一份执行计划列清楚要动哪些文件。你对计划点头之后它才开始写代码。每完成一个步骤它会停下来验证最后再汇总结果。这套流程看起来慢但实际省下的时间非常可观。我试过让Codex直接写一个功能它在三分钟内改完八个文件我花了一个小时修回归问题。而用superpowers的流程它五分钟列完计划我确认后它花十分钟实现并测试全程没有返工。这个对比让我彻底接受了慢就是快的理念。2.2 AGENTS.md给AI的入职培训手册AGENTS.md是superpowers工作流里最核心的文件可以理解为给AI看的新员工手册。Codex CLI本身就支持读取项目里的AGENTS.md但superpowers把它的地位提到了最高——要求AI在每次会话开始、每个新任务开始前都必须先读它。这份文件里写什么决定了AI在项目里是懂规矩的协作工程师还是瞎猜的临时工。我的经验是AGENTS.md越具体越好。不要只写这是一个电商系统而要写清楚技术栈是什么、构建命令是什么、测试命令是什么、代码分层的约定是什么、哪些目录不能改、数据库变更流程是什么、完成一个任务需要满足什么标准。它本质上是一份验收标准行为边界项目地图三合一的文件。你花三十分钟把它写好换来的是AI几百次任务都走在正道上。2.3 技能包让AI知道自己有多少种干法superpowers的另一个重要设计是技能包。所谓技能就是一组组结构化的markdown文件每个文件描述一种能力的适用场景和执行方法。比如分析既有代码该怎么做、规划任务拆解该怎么做、实现功能时该遵循什么步骤、调试问题时要按什么顺序排查。系统提示词会告诉AI你拥有以下技能并引导它在遇到对应任务时主动调用。这就像给实习生发了一张岗位技能清单。他不用靠猜来决定怎么处理任务而是翻开手册找到对应章节按里面的SOP执行。实际效果就是AI面对不同任务时输出质量更稳定而且使用者能预测它下一步做什么。这一点在团队协作和多任务切换时特别有价值。我自己在用它处理代码审查、安全排查、性能调优这类不那么常规的任务时明显感觉到它比裸Codex更知道轻重缓急。2.4 节奏控制慢就是快superpowers里有个很重要的理念叫节奏控制。它要求AI在动手之前停下来想一想在改完一个文件之后停下来验证一下。这种节奏在人类工程师看来太自然了但对AI来说是反直觉的——因为模型的最大倾向就是一口气把话说完、把代码写完。没有一个外部机制强制它分段它就会一直输出到上下文尽头。我拿这个理念去类比日常开发你写一段复杂逻辑大概率不会不编译就一次性写二十个函数而是写几个就跑一下测试确认没跑偏再继续。superpowers把这个习惯移植给了AI。它通过各种提示词让AI养成每走一步就检查一下当前状态的反射避免在错误的方向上跑太远。这个设计虽然朴实但我认为是整个方案里最提效的部分。因为AI在编程上的错误越早发现修复成本越低跟人是一样的。3. 实操落地从安装到Java项目配置3.1 准备工作与安装在开始之前你本机需要准备好Node.js 18以上、Git、OpenAI Codex CLI。Codex本身的安装方式不在本文展开但有一个前提——你先得确认在终端里能正常跑codex命令并且已经完成模型访问的配置。装完Codex之后接下来就是获取superpowers的源码。按住键盘不放在终端里执行克隆仓库的命令从GitHub上把superpowers仓库clone到本地。仓库里会有一个安装脚本常见的情况是直接运行./install.sh它会把配置、提示词、技能包等文件链接到你本机的~/.codex配置目录下。如果在安装脚本不可用或者你想手动控制也可以直接参考仓库里的目录结构把config.toml和skills、prompts等目录复制到~/.codex下。安装完成后执行codex进入交互界面如果对话中能看到类似superpowers已加载或者模型主动列出可用技能就说明安装成功。这里有一个我用下来的心得安装之前务必备份你已有的~/.codex/config.toml。superpowers的安装过程会改变或者覆盖你现有的Codex配置如果之前配过其他模型参数或者自定义过提示词不备份就装很容易丢配置。我头一回就是没备份直接把之前调好的温度参数弄丢了后来花了点时间重新调。3.2 初始化Codex配置安装完成后最关键的是理解config.toml里发生了什么。superpowers会在里面注册一个专门的profile把所有提示词和技能目录关联到这个profile上。也就是说它不是简单修改你全局的Codex行为而是给你一套独立的带规则的工作环境。这样你既可以用普通模式跟Codex闲聊、问问题也可以在处理正经开发任务时切到superpowers模式。配置里通常还会指定模型名称和相关参数。不同时期、不同版本的superpowers对模型的要求可能有变化建议直接以仓库README里写的配置为准。如果你之前对Codex做过定制化配置可以用profile嵌套的方式把superpowers作为一个子profile加载避免覆盖你原有的设置。我的建议是第一次先保持默认配置跑通一个简单任务确认整个链路没毛病之后再按自己的习惯调整。# 安装完成后可以用一条命令确认当前生效的配置 codex --config ~/.codex/config.toml --info3.3 在项目根目录写AGENTS.mdJava版接下来是实战里最重要的一步写项目级的AGENTS.md。网上很多教程会简单翻译仓库自带的模板但真正要发挥作用你必须针对自己的项目改。这里我拿Java项目举一个我最常用的实例。下面是我给一个Spring Boot订单服务项目写的AGENTS.md你可以直接参考使用。# AGENTS.md ## 项目简介 这是一个基于 Spring Boot 3.x 的订单服务使用 Maven 构建最低要求 JDK 17。 业务领域商品订单的创建、支付状态流转、取消与退款。 ## 常用命令 - 编译mvn -q compile - 运行全部测试mvn -q test - 运行单个测试类mvn -q -DtestOrderServiceTest test - 打包mvn -q package -DskipTests ## 代码约定 - Controller 层只做路由和参数校验不写业务逻辑。 - Service 层必须通过构造器注入依赖不要用字段注入。 - Entity 只做持久化映射禁止在 Entity 中写业务方法。 - 所有对外接口统一返回 ResultT 包装类型。 - 涉及金额、状态字段一律使用 BigDecimal 和枚举禁止使用浮点型。 ## 任务边界 - 不允许修改 database/migration 目录下已有的迁移脚本。 - 改动公共接口签名之前必须向用户说明影响范围并等待确认。 - 不要擅自引入新的第三方依赖如果确有必要先解释原因。 ## 完成标准 - 新增或修改代码后必须执行 mvn test并确保通过。 - 涉及数据库字段变更时必须同时提供新的 Flyway 迁移脚本。 - 禁止在未执行测试的情况下声明已完成。写这份文件的过程等于把项目里人看起来理所应当、AI完全不知道的上下文全部显式化。有了它AI就能在开工前搞清楚边界和验收条件。我实测下来同样一个Java任务有AGENTS.md和没有AGENTS.mdAI第一次生成代码的质量差距非常明显。有这份文件的场景里基本不会出现AI偷偷改了pom.xml这种事故。3.4 本地会话记录与技能目录说明superpowers的安装目录里除了配置和提示词还有一块容易被忽略的内容——本地会话记录机制。它会在工作目录下维护类似笔记文件的结构让AI在每次会话开始时先读取之前留下的记录了解上一次做到了哪里、踩过什么坑、下一步计划是什么。这个设计特别适合中断后继续干活的情况。比如你昨天让AI搭一个订单导入功能写到一半就关终端了。今天重新打开Codex继续聊它先读笔记自动接上已经完成了文件解析部分下一步是写数据校验逻辑而不是像之前那样从头问起。这个体验对真实开发来说太重要了因为没有人能保证一次会话就把任务干完。技能目录则位于~/.codex下的技能文件夹中。里面有几十个markdown文件每个文件都描述一类任务的标准做法。你可以随时打开看也可以自己添加新的技能文件。比如你经常处理某个内部框架的兼容问题可以自己写一个处理XXX框架兼容性的技能让AI按你写的步骤去排查。这种私有技能包的能力让superpowers非常适合团队沉淀集体经验。3.5 跑通一个真实Java任务理论说了一大堆我实际演示一个典型任务的完整流程。假设项目是一个订单服务我现在要求Codex给订单模块新增一个取消订单的接口。在superpowers模式下它的行为大致是这样的。第一步它先读AGENTS.md再打开pom.xml、订单实体类、现有Controller和Service甚至看一眼已有的测试。然后它输出一份简明计划新建一个CancelOrderRequestDTO、在OrderService中新增cancelOrder方法、在OrderController中新增POST /orders/{id}/cancel路由、补充两个单元测试、不需要数据库变更。我确认无误后它才开始动工。先写DTO再写Service再写Controller每写完一个文件会停一下检查类型和依赖关系。最后它会主动执行mvn -q test把测试结果贴出来然后总结改动了哪些文件、测试是否全部通过、有没有遗留风险。整个过程不用我反复纠正方向它自己就在计划—实现—验证的闭环里走完了。这个体验用一句话形容就是之前在指挥一个什么都不懂的实习生现在像在跟一个懂行但需要审批的同事协作。3.6 使用turbo mode加速简单任务superpowers并不要求所有任务都走全套流程。它内部包含一个turbo mode的概念适合那些目标明确、风险极低的小改动比如把日志输出格式改成JSON把某个工具类的常量提取到配置里。在这些任务上你可以在Prompt里明确告诉AI使用turbo mode它就会跳过冗长的分析和计划阶段直接动手实现并跑测试。这个设计很务实。如果每次改一行日志都要走读AGENTS.md—分析—计划—确认—实现—验证—总结的流程效率反而被拖垮。真正合理的用法是根据任务风险来动态选择模式涉及跨模块改动、数据库变更、公共接口调整的时候老老实实走完整流程单纯改常量、调格式、删无用代码的时候直接用turbo mode快速过。这一快一慢之间才是superpowers真正提效的地方。4. 常见问题与定位思路4.1 速查表我自己使用过程中遇到过不少问题也看过社区里别人踩坑的经历。把典型的几个整理成速查表方便你快速对照。问题现象可能原因定位思路AI不读AGENTS.md上来就写代码superpowers的profile没有正确加载检查~/.codex/config.toml里是否注册了skills和prompt确认安装时软链是否有效任务拆得太细进展非常慢简单任务也走了完整分析流程在Prompt里明确要求进入turbo mode跳过分析和计划阶段一改就是十几个文件拦不住任务边界定义不清楚在AGENTS.md的任务边界里写明涉及公共接口变更需确认多模块项目里不知道从哪下手AGENTS.md缺少模块地图在AGENTS.md开头加一页模块目录树标注各模块职责和入口编译报错后反复试错AI没有先看pom.xml的依赖关系在AGENTS.md中指定动手前先读pom.xml确认依赖版本测试跑不过AI自己修不好缺少最小复现意识要求AI先定位失败用例用-DtestXXTest单独跑再逐步扩大范围4.2 案例复盘AI不读AGENTS.md我自己在刚装完superpowers时遇到过最头疼的问题明明安装成功了但AI仿佛没看见AGENTS.md一样跳过分析和规划直接开始输出代码。后来排查发现问题出在配置加载的顺序上。Codex在启动时会读取配置文件如果当前工作目录不在项目根目录或者配置里指定的某个路径不对AI就会退回默认行为。解决方式很简单把项目目录切到cd /path/to/project确认当前目录下有AGENTS.md然后在配置里指定好superpowers的profile以后重启Codex会话。还有一个隐蔽的坑很多终端工具启动Codex时不在项目目录里导致它根本找不到AGENTS.md看起来就像没读文档。碰到这种情况先在终端里手动进入项目目录再启动问题立刻就消失了。4.3 案例复盘中途改动文件太多另一个常见现象是AI在执行任务过程中临时起意顺手改了并不需要的文件。比如我在一个遗留Java项目里让它加一个字段它居然连带着改了另一个模块的接口定义还动了数据库迁移脚本。这个问题的本质是任务边界没写清楚AI不知道哪些区域是禁区。我在AGENTS.md里加了任务边界一节明确写不允许修改database/migration目录下已有迁移脚本改动公共接口签名前必须向用户说明影响范围。之后AI在生成计划时会先检查有没有触及这些红线甚至会在计划阶段主动提醒我这个改动会影响到公共接口需要您确认。这种方式比我人工盯着它改代码要省心太多。4.4 案例复盘复杂模块迷失入口还有一个值得一提的坑是多模块的Java项目。AI面对一个包含十几个子模块的工程时经常不知道业务入口在哪。你让它改订单查询它可能在common模块里翻了半天找不到实际的业务代码。这其实不是superpowers不行而是AGENTS.md里没给够线索。我把项目的模块结构树、各模块的职责说明和几个关键入口类的位置写进了AGENTS.md同时标注了订单模块的代码在XXX子模块下的YYYY包里。从那以后AI找入口的速度快了很多定位代码也不会跑偏。这也印证了我前面说的AGENTS.md不是仪式感它是实打实的上下文补给线。5. 哪些场合别硬上superpowers5.1 适合用的地方superpowers最适合的场景是中大型项目、多人协作代码库、以及对代码质量和可维护性有明确要求的日常工作。在这些场景里AI的发挥不稳定会直接转化为返工成本和线上风险superpowers用流程纪律把这些风险压到了可控范围。同时它有沉淀知识的能力AGENTS.md和技能包会随项目一起演进。今天花半小时写好的规范明天、下个月、甚至换了个AI工具都还能复用这是我觉得它最划算的地方。5.2 不适合用的地方它也不是万能药。如果你只是写一次性脚本、做个Demo验证想法、或者在一个不打算长期维护的练习项目里随便试试那这套流程反而会拖后腿。为了一个一次性脚本去写AGENTS.md、走计划确认流程纯粹是浪费生命。这种场景里直接让AI火力全开、快速输出反而更合适。我自己的做法是小任务、临时任务用裸Codex直接跑正经项目才切到superpowers模式。工具是为人服务的不是反过来。5.3 使用中的几条私人建议最后分享几个切切实实的建议。第一AGENTS.md一定要当成给AI的入职培训文档来写而不是简单的项目介绍。它越具体AI越不会跑偏。第二不要一上来就追求把所有流程跑完先拿一个小功能试水观察AI的行为是否稳定、计划是否符合预期再逐步扩大使用范围。第三技能包这个机制值得好好利用。遇到一次性的、复杂的排查过程可以把当时的排查步骤记成一个技能文件下次AI遇到类似问题照着文件做就行等于把个人经验沉淀进了工具里。我踩过最深的坑是第一次装完就拿着一个遗留Spring项目直接跑AI上来就提议改pom.xml的依赖版本吓得我立刻回滚。后来把AGENTS.md写清楚把不允许擅自改pom.xml依赖写进任务边界AI才老实下来。这个经历让我彻底明白了superpowers真正管理的不只是模型输出更是人对AI的预期。投入二十分钟写好项目规范省下的是后面几十个小时的返工时间。如果你也在用Codex处理正经项目这套方案值得一试。
