最近不少同事问我明明 Codex CLI 这工具本身很聪明可为什么让它改个跨模块的功能改着改着就跑偏了我一开始也困惑直到我认真用上了一个叫 Superpowers 的开源增强方案才算把这些毛病治得七七八八。这篇就把我实际安装、配置以及用它驱动 Java 功能开发的完整过程写出来希望能帮你少走一点我踩过的弯路。Superpowers 的作用一句话就能说清它给 Codex CLI 装上了一套可复用的“工程方法”——任务拆解、计划制定、子代理分工、测试驱动开发、上下文持续管理这些从“提示词技巧”变成了项目里的实体文件。适合的人群很明确日常用 Codex 写业务代码、但觉得结果不够稳定的开发者以及想在团队里把 AI 编程规范固化下来的技术负责人。下面直接进入正题。1. 为什么原生 Codex CLI 干活“飘”先看看 Superpowers 要解决的问题1.1 裸 Codex 的典型翻车场景我最早用 Codex CLI 时最挫败的不是它不理解需求而是它太“就事论事”。比如我让它给一个已有 Spring Boot 项目加一个 REST 接口它确实能写出 Controller但它不会主动去看这个项目的分层结构、不会去翻已有 Service 的命名风格、更不会意识到我应该先写测试再写实现。等你追问一句“你怎么没加 Service 层”它才会补一个出来然后你又发现 Mapper 那块也没对。这种体验总结起来就三个字不省心。明明每一次对话里它都听懂了但把几次对话串起来看它缺乏一个完整的、贯穿始终的“任务观”。它不知道当前改动属于哪个大目标不知道项目里有哪些约定必须遵守也不会在动手之前给自己列一个检查清单。1.2 Superpowers 给出的补强思路Superpowers 的处理方式很有意思它不尝试让模型本身变得更聪明也不靠一段神奇的提示词去“唤醒”推理能力而是把工程经验拆成一堆能被模型反复读取的文件——技能文件、命令脚本、子代理角色、项目级指引文件。以前你每次开新对话都要手动跟 AI 交代“我们项目是 Maven 管理的”“Service 层要写接口和实现”“代码要遵守项目已有的风格”现在这些内容都变成了文件AI 在开始干活前会自动去读。以前 AI 做完一个步骤就等着你下一条指令现在它跟着技能文件里的步骤清单走先分析、再规划、后实现、最后验证。这个思路本质上是把 AI 编程从“对话式问答”改造成“流程式协作”。就像你带一个能力很强但没什么经验的新人与其每次都口述要点不如给他一本操作手册和一张检查卡让他按着跑。Superpowers 在我看来就是给 Codex 准备的那本手册。1.3 一句话读懂这个项目的架构如果你去看 Superpowers 的仓库会发现它的核心其实是三个部分命令、脚本、技能。命令是你在 Codex 里直接斜杠调用的入口比如/code、/superpowers脚本负责完成一些自动化操作比如提取变更摘要、更新规范文件技能则是一组带描述和步骤说明的 Markdown 文件每个技能都对应一类常见开发任务。它们之间的关系可以这么理解命令负责把任务领进门技能负责告诉 AI 具体怎么做脚本负责顺手把收尾工作做掉。我用的版本里最常用的就是/code这个入口它会自动加载规划技能让 AI 先把任务拆成待办清单再逐个去执行。下面我会把这套运行机制展开讲但先别急先把环境装起来再谈原理会更直观。2. 环境准备与安装按我的步骤走二十多分钟能跑起来2.1 前置依赖清单安装之前先把底下的环境确认好避免装到一半才发现版本不对。检查项我的建议说明Codex CLI已安装且能正常运行Superpowers 是增强层依赖 Codex 本体Node.js18 及以上仓库里的脚本和安装器依赖 Node 运行时Git已安装拉取仓库和后续更新都需要终端Bash 或兼容环境Windows 用户建议用 Git Bash 或 WSL我自己用的是 macOS 环境Codex 是 npm 全局装的Node 版本是 20。如果你还没装 Codex CLI先去把它装好、确认codex命令能在终端里跑起来再继续下面的步骤。2.2 安装流程与关键路径Superpowers 的安装方式很简单把仓库克隆到本地然后执行仓库里的安装脚本。脚本做的事情说白了就是复制文件——把命令文件复制到~/.codex/commands把脚本复制到~/.codex/scripts把技能目录复制到~/.codex/skills。不同版本的目录命名可能有细微差异一切以官方仓库的 README 为准。我当时操作的流程大致是这样的找一个你常用的工作目录把仓库克隆下来进入仓库目录执行安装脚本一般是./install.sh有的版本也支持 npm 方式脚本结束后检查~/.codex/commands下是否多了一堆.md文件重启终端里正在运行的 Codex 会话输入/help确认新的斜杠命令已经出现。这里有一个细节需要特别注意安装脚本只会把文件复制到位不会自动帮你重启 Codex 会话。如果你安装完发现/code命令不存在先别怀疑装错了大概率是会话没重启。2.3 装完怎么验证装好之后我建议你不要急着上真实项目先做一个快速验证。启动 Codex输入/code然后随便给一个很小的任务比如“帮我在当前目录生成一个 README.md内容概述这个目录里的文件”。观察 AI 的行为正常情况下它不会马上动手写文件而是会先创建或更新一个待办清单通常是todo.md然后逐步打勾执行。你还会看到它尝试读取或生成AGENTS.md这个文件里面是它对这个项目协作约定的理解。这个现象出现基本就说明 Superpowers 生效了。2.4 安装阶段最容易踩的三个坑路径问题~/.codex/commands里的文件需要有读权限如果之前你以 root 身份装过 Codex目录属主可能是 root会导致当前用户读不到命令。解决办法很简单sudo chown -R 你的用户名 ~/.codex一下。版本兼容Codex CLI 升级到新版本后Superpowers 的旧命令文件不一定兼容。我遇到过升级 Codex 后/code命令报错的情况最后是把 Superpowers 仓库更新到最新版、重新执行安装脚本才恢复。建议你用一段时间后就git pull一下仓库再装一遍。Windows 路径差异如果你在 Windows 上用 Git Bash 安装脚本里写的很多路径是 macOS/Linux 风格的可能会碰到路径转换问题。折中的办法是直接改用 WSL 环境我在 Windows 机器上试下来 WSL 比 Git Bash 稳得多。3. 技能文件、子代理与工作流Superpowers 的底层运转逻辑3.1 SKILL.md 与技能目录把“经验”变成 AI 能读的文件Superpowers 里最核心的概念是“技能”。什么叫技能你可以把它理解成一个带有身份说明、使用场景和操作步骤的 Markdown 文件包。每个技能占一个目录里面最重要的文件是SKILL.md它规定了这个技能在什么情况下启用、按什么顺序执行哪些步骤、有哪些禁用事项。举个我在 Java 项目里用到的例子仓库里有一个专门负责“按项目规范编写单元测试”的技能。它的SKILL.md会写明“前置条件是新写的业务代码已完成”“步骤包括——确认测试框架是 JUnit 5 还是 4、检查已有测试的命名风格、为新类生成对应测试类、运行测试命令验证”还会写“禁止直接跳过测试运行步骤”。AI 在接到相关子任务时会去读取这份文件而不是凭它自己的经验瞎猜。这套设计的精妙之处在于技能文件是团队经验和工程规范的可执行化载体。你不需要每次对话都重复“测试要跑到全绿”只要技能文件里写了AI 就会当成硬性约束去执行。3.2 子代理与命令系统谁负责想谁负责做Superpowers 还引入了一组“子代理”的概念。/code命令会先调用规划类子代理让 AI 先做任务分解和方案设计接着进入执行阶段时又会调用执行类子代理去写具体代码在验证阶段还有专门的审查类子代理去检查结果。这种分工的价值在于减少角色混乱。如果你让同一个智能体既当“架构师”又当“搬砖工”还当“质检员”它的行为会有倾向——很容易急着写代码而跳过思考和验证。拆成不同角色后规划阶段只输出计划和待办项不写代码执行阶段才写代码审查阶段才挑毛病。整个流程更像一个真实团队的分工。我用一个生活类比来解释这就像你写了一台自动售货机消费者投币之后机器内部先判断商品在哪个货道、再联动传送带出货、最后亮灯提示取货。每一步有专门的模块负责而不是让一枚硬币同时干所有事。3.3 上下文保持与 AGENTS.md 的自动更新Superpowers 另一个让我觉得靠谱的地方是它把“项目记忆”固化了。Codex 的对话窗口是有限的每条消息都会消耗上下文。如果你做了二十步修改AI 很可能会忘记第十步之前的约定。Superpowers 的做法是维护AGENTS.md——一个项目根目录下的协作说明文件里面记录着项目结构、命名规范、构建命令、测试方式等关键信息。AI 每次开始任务前会先读这个文件每次完成一个重要阶段后又会主动更新它。等于把“短期记忆”不断转存成“长期记忆”。我一开始还担心这个文件会被 AI 写得乱七八糟实战跑过几次后发现只要初始模板给得清楚它维护出来的内容基本准确偶尔有冗余但整体可靠。3.4 一次完整技能调用的生命周期把上面这些串起来一次/code驱动的完整开发流程大致是这样的读取项目根目录的AGENTS.md和已有技能文件理解项目约定创建或更新todo.md把需求拆成可执行的小步骤按优先级规划执行路径确定哪些子任务需要调用哪些技能对每个子任务按对应技能的SKILL.md步骤执行完成一项就更新一次待办清单并同步刷新AGENTS.md全部完成后做一次全局检查确认没有遗漏或风格不一致的地方。这个过程和裸 Codex 的最大区别是它不再是一个“问一句答一句”的对话而是一个有始有终、有清单、有验证的项目执行流程。这也是为什么它对复杂任务的效果提升远大于简单任务——简单任务你不需要这套流程复杂任务没有这套流程就容易翻车。4. Java 项目实战一次完整的驱动式开发过程4.1 任务设计与初始状态说了这么多原理拿真实项目跑一遍最直观。我挑了一个不算简单的任务在一个 Maven 管理的 Spring Boot 项目里新增一个“根据用户 ID 查询详情”的 REST 接口。项目的初始状态是有User实体类、UserRepository但还没有 Service 层也没有 Controller。我启动 Codex输入/code然后写下需求新增GET /api/users/{id}接口要求包含 Service 层使用已有的UserRepository响应格式遵循项目里已有的统一返回结构并补上单元测试。这个需求本身就包含了不少隐含约束要不要建 Service 接口、异常怎么处理、测试用 Mockito 还是直接用内存数据库。换作裸 Codex我可能得追加好几条指令才能让它把细节对齐而这次我全程没有干预。4.2 技能串联的执行路径任务提交后我观察到的执行路径非常清晰。第一步AI 读取项目结构更新todo.md列出类似这样的小项检查现有实体和 Repository 的方法、设计 Service 接口与实现、创建 Controller、补充 Service 层单元测试、运行 Maven 测试命令验证。第二步AI 并没有立刻写代码而是先找到了我提到过的“按项目规范编写单元测试”技能先写了UserServiceTest的骨架。这一步我当时愣了一下——正常直觉是先写实现再补测试但技能文件里的流程是先确认测试目标、写失败测试、再写实现让它通过。这就是典型的 TDD 节奏而这一整套节奏都被固化在了技能文件里。第三步实现阶段。AI 按AGENTS.md里记录的命名规范完成了接口和实现类Controller的返回类型也自动套用了项目已有的ApiResponseT结构没有出现“跑偏”的情况。整体代码风格和项目原有代码保持一致我审查起来省了很多力。第四步运行mvn test验证。这一步让我很满意的是AI 没有在测试还红着的时候就说“完成了”而是真的把测试跑绿了才更新待办清单。整个过程我零介入任务完成后它还在AGENTS.md里追加了一条关于 Service 层结构约定的记录。4.3 实测表现与原生模式的对比我把这次表现和以前裸 Codex 的结果做了个对比差异非常明显维度裸 Codex 的典型表现使用 Superpowers 后任务拆解一次性生成全部代码先列待办逐项执行测试行为容易跳过或只写“看起来对”的测试先写失败测试再跑绿项目风格大概率忽略已有约定自动读AGENTS.md遵循规范文档维护不主动更新主动刷新项目协作说明多步骤一致性长任务容易前后矛盾通过待办和文件固定上下文我特别想强调的是“多步骤一致性”。裸 Codex 在长任务里经常出现前后矛盾比如前面用了某个工具类后面又重新定义了一遍Superpowers 模式下这类情况明显减少核心原因是每一步都有文件可以参考AI 不需要靠上下文记忆硬撑。当然它不是万能药。遇到业务逻辑特别模糊、需要大量领域判断的任务它依然会卡壳。这时候我不会怪 Superpowers因为流程和方法只能保证“做得对”不能替我做“该做哪个”的决策。5. 调优建议与真实使用边界5.1 哪些场景收益最大用了一阵子之后我明显感觉到 Superpowers 的收益是分场景的。收益最大的是三类任务第一跨多文件的新功能开发比如上面这种新增接口、新增模块的任务流程化带来的收益非常明显 第二需要严格遵守团队规范的任务比如必须遵循特定分层、特定命名、特定测试风格的项目技能文件比口头交代靠谱得多 第三需要反复迭代修改的任务比如你让 AI 改完这轮还要改下轮待办清单和AGENTS.md能帮它记住上一轮是怎么处理的。收益相对有限的场景包括单文件小改动、纯研究性或探索性任务、对实时性要求极高的对话式问答。这种场景里 Superpowers 反而显得有点“重”因为它再怎么也得先读文件、建待办这些动作会拖慢响应速度。5.2 自定义 Java 技能的正确姿势如果你想把 Superpowers 真正用成自己的工具光靠内置技能是不够的自定义技能是绕不开的一步。我调试了无数次之后总结出的经验是不要一上来就写大而全的技能而是从一个你反复做过、经常嫌 AI 做得不好的真实任务开始。比如我团队里有个项目要求“新增数据库表时必须同时生成对应的 Flyway 迁移脚本和实体映射”。以前每次都要手工提醒 AI 两三次后来我写了一个专门的技能把步骤拆成检查迁移脚本目录命名规则、按照版本号生成新的 SQL 文件、编写实体映射、运行迁移验证命令。技能文件写好后这个任务我基本可以放手了。写技能文件有几个关键点描述要写清楚使用条件让 AI 能判断“什么时候该激活这个技能”步骤要足够细每个步骤之间逻辑连贯AI 不容易中间卡住一定要写禁止事项比如“禁止在未运行迁移验证的情况下标记任务完成”。这几个要点比你在提示词里苦口婆心说十遍都管用。5.3 需要绕开的限制与替代方案使用 Superpowers 到现在我遇到的最大的限制是“它或多或少会改变你的使用习惯”。你不能再随手一问就指望它给个出色方案你得接受先建待办、再分步执行这个相对慢的节奏。如果你日常主要用 Codex 做快速问答刚开始可能会觉得“怎么变笨了”。但只要切换到真实开发任务就能明显感觉到后半程的省力。另外一点是技能文件的质量决定了 AI 的表现。如果你仓库里的技能写得很烂AI 执行起来会一板一眼地错甚至比没有技能更糟。我的建议是先小范围试点确认流程跑通后再铺开。如果你试了之后觉得 Superpowers 不适合自己的项目结构也可以参考它的思路自己写一套轻量方案核心就是“项目规范文件 命令入口 技能目录”这三件套完全可以手动搭建不用依赖任何第三方仓库。我在另外一个小型开源项目里就这么干过效果依然不错。最后再分享一个小技巧每次更新 Superpowers 之后别直接上生产项目测试先在临时目录里用一个空仓库跑一遍/code确认命令加载正常、技能目录没被覆盖丢再回到真实项目里继续用。这个习惯帮我躲过好几次因为版本更新导致的配置丢失问题。
