一开始我在本地把 superpowers 装进 Codex CLI纯粹是因为受不了默认对话模式反复返工。你让 Codex 改一个 Java 方法它改了实现却忘了按约定跑测试你提醒一次它才补上补完之后又把无关的格式动了一堆。与其说这是在协作不如说是在盯人。后来我把 superpowers 作为一套技能目录挂到 Codex 的技能加载路径里情况才真正好转它开始自己拆任务、先写测试、再实现、再重构像一个有基本职业素养的同事而不是一个只会接话的聊天窗口。这篇算是一份个人实测记录不是官方文档。我会把安装方式、目录规划、Java 项目实战和踩坑排查都写清楚适合那些已经在用 Codex CLI、想进一步规范 AI 工作流的开发者。如果你主要写 Java第 4 和第 5 节可以直接当作业指导来用。1. 先搞清楚Superpowers 到底给 Codex 加的是什么能力1.1 一个反直觉的结论它不是插件而是“技能包”很多人一听“给 Codex 装 superpowers”会下意识以为是个 VSCode 插件、MCP 服务或者 npm 包。我最初也这么想结果 clone 下来一看项目里最多的东西是.md文件。Superpowers 本质上是一套“工作流指令集”。它通过 Markdown 文件定义各种技能每个技能文件里写清楚了这个技能在什么场景下触发、执行时先做什么后做什么、中间要输出什么中间产物、最后用什么样的验收标准来判断完成。Codex 作为 Agent 读取这套技能之后相当于拿到了一本非常细的作业手册。你可以把它理解成给实习生写的 S.O.P。实习生聪明反应快但不知道你公司的代码规范是先写测试再写实现不知道重构前后要跑完整套用例不知道改完接口还要顺手更新调用方。S.O.P 把这些流程固化成文本Agent 每次开工前先读一遍行为就从“自由发挥”变成了“按流程执行”。这也是为什么它叫 superpowersCodex 本身的能力天花板没有变但使用方式被重新组织之后产出质量明显提升。注意它不是黑魔法它改变的是工作流不是模型智商。1.2 为什么 Codex 原生对话做不到这些直接和 Codex 对话时它会根据上下文即兴决定下一步。如果用户不提测试它就默认你不需要测试如果用户说“帮我重构一下”它可能只改了一个文件剩下的地方靠猜。原生对话模式的问题不是模型能力不足而是缺少“强制步骤”。Superpowers 解决的是这个“缺少强制步骤”的问题。它的技能文件里会明确要求开始写业务代码前必须先写一个失败测试测试跑红之后才允许进入实现阶段实现通过后再进入重构阶段。每一步都有明确的输入输出Codex 不能跳过“跑测试”这个动作直接给你交代码。我试过在同样一台机器上用同一个 Codex 模型处理同一个 Java 需求。不开 Superpowers 时它给出的代码能编译但单元测试覆盖率只有 30%而且没有按项目里既有的异常处理风格来写。开了 Superpowers 并加载 TDD 技能后它先自己建了src/test/java目录写了完整的边界测试再实现主类最后跑mvn test还主动把 Integer 运算改成了 BigDecimal。差距就在流程。1.3 Superpowers 替你跑起来的三条核心工作流我实际用得最多的是三条工作流。第一条是 TDD测试驱动开发。这个技能会要求 AI 严格按“红灯-绿灯-重构”来走。红灯阶段只写测试不写实现绿灯阶段用最简代码让测试通过重构阶段清理重复代码和命名问题。第二条是任务拆解。面对一个比较大的需求比如“给现有模块加一个消息队列消费者”Superpowers 会先把这个需求拆成若干子任务每个子任务有明确的交付物和验收条件然后逐个执行。这个能力在长任务里特别重要因为 Codex 一旦上下文被拉长很容易忘记最初目标。第三条是自动代码审查。完成实现后技能会要求 Codex 自己扮演 reviewer检查潜在 bug、并发问题、异常处理漏洞和测试盲区。它会输出问题清单再根据清单逐条修复。这三条工作流可以单独用也可以串起来。我通常把三条串在一起使用先拆任务再对每个子任务执行 TDD最后做一轮 review。效果比单独开任何一条都要稳。2. 安装前必须想明白的目录规划与版本选择2.1 先检查你的本地环境在动手装之前我建议你先跑一遍环境检查。以下三个命令分别确认 Codex CLI、Git 和构建工具的状态codex --version git --version mvn --version如果你用的是 Gradle 项目就把最后一个换成gradle --version。这里有个容易忽略的点Codex CLI 本身是通过 npm 安装的所以 Node.js 环境也需要是正常的但只在安装阶段用到运行时不一定依赖 Node。我遇到过一个情况Codex 版本太老技能加载路径还不稳定导致软链接过去了也读不到。后来升级到新版本才恢复正常。所以如果你之后遇到“明明配置了却不起作用”的怪问题先怀疑版本再怀疑配置。2.2 用户级、项目级、全局三种安装位置的取舍安装 Superpowers 之前要决定放哪里。这个决定影响范围很大我见过不少人直接散装到一堆项目里最后每个项目都要维护一份很痛苦。用户级安装是把技能目录放到~/.codex/skills/下面所有项目都能用。单个开发者自己用我推荐这种方式。项目级安装则是放到某个仓库的.codex/skills/或.agents/skills/目录下会随仓库走团队提交代码时能一起同步。全局安装是把它当作系统级指令放到 PATH 或公共配置目录里适合公司内部统一推行的场景但维护成本最高。你可以先按一张表来判断安装位置生效范围适合场景维护成本用户级当前用户所有项目个人日常开发、试验新技能低项目级单个仓库团队项目、需要统一规范的仓库中全局系统级机器上所有用户公司开发机标准化高从我自己的经验看绝大多数开发者从用户级开始就够了。等你在团队里验证了某条工作流确实有用再把它下沉到项目级让每一个克隆仓库的同事都能自动拿到。2.3 我推荐的目录布局目录布局不复杂但有个结构问题值得提前想好Superpowers 自带的技能是公用的你自己后加的技能是私有的。如果混在一个目录里升级 Superpowers 时可能会把自定义内容覆盖掉。我是这么组织的~/.codex/ ├── config.toml ├── AGENTS.md └── skills/ ├── superpowers/ # 官方技能 ├── team/ # 团队私有技能 └── personal/ # 个人私有技能这样升级 Superpowers 时只需要替换superpowers这一个子目录team和personal完全不受影响。Codex 加载技能是读取整个skills目录的所以不同来源之间不会冲突只要技能命名唯一就行。3. 挂载 Superpowers 到 Codex CLI两条实测可行的路线3.1 路线一软链接到 Codex 全局技能目录我先说我自己最常用的方式。它基于用户级安装好处是升级方便、回滚方便而且不会把第三方代码散落到项目仓库里。第一步把 Superpowers 仓库克隆到一个固定位置git clone https://github.com/obra/superpowers.git ~/superpowers第二步在 Codex 的技能目录里创建一个软链接mkdir -p ~/.codex/skills ln -s ~/superpowers/skills ~/.codex/skills/superpowers这里有一个细节链接目标不是~/superpowers本身而是它内部的skills目录。因为 Codex 期望的是“技能目录下面直接放技能文件”而不是“技能目录下面再套一层仓库结构”。我第一次犯过这个错误链接到仓库根目录结果加载时一个技能都识别不到。第三步如果你是新版本 Codex通常还需要在配置里确认启用了 Agent Skills。在~/.codex/config.toml里加入[skills] enabled true不同版本的配置字段名可能不一样。最稳妥的办法是运行codex --help查看当前版本是否包含 skills 相关参数。如果没找到也不用慌很多版本会在检测到技能目录后自动加载。3.2 路线二放进项目级 .agents 目录如果你的团队成员都会 clone 同一个仓库项目级安装更合适。Codex 在项目目录下会读取.agents/skills/或者.codex/skills/具体看版本。你可以直接复制也可以用子模块引入。用 git submodule 的方式是cd your-project mkdir -p .agents/skills git submodule add https://github.com/obra/superpowers.git .agents/skills/superpowers然后用一条软链接再处理一层让技能文件位于.agents/skills/superpowers下面一层。如果直接 clone 到.agents/skills/superpowers你需要确认这里面直接是 Markdown 技能文件而不是又包含一个skills子目录。项目级安装最大的好处是“开箱即用”。新人 clone 仓库之后Codex 自动就带上了全部技能不用每个人手动去配。它的代价就是仓库里多了第三方代码如果你不喜欢 submodule也可以用脚本在初始化时自动 clone 和软链。3.3 修改配置与验证加载配置除了开关 skills还有一个容易被忽略的文件AGENTS.md。Codex 在开始任务前会自动读取当前目录和用户目录下的AGENTS.md你可以用它来声明技能加载规则。我习惯在用户级~/.codex/AGENTS.md里写这么一段# Agent Instructions - 开始任务前检查 ~/.codex/skills/ 下是否有与任务匹配的技能。 - 如果存在匹配技能必须按技能文件中的步骤执行不能跳过任何步骤。 - 涉及测试代码时优先遵循 TDD 技能的“红灯-绿灯-重构”流程。这段文本的作用是让 Codex 别偷懒。技能文件是“储备”AGENTS.md是“启动器”。两者配合Codex 才会真的去翻技能而不是你每次手动在对话里要求它读文件。验证是否加载成功我提供一个最简单的办法直接在 Codex 里问他“你当前有哪些可用的技能请列出技能名称和用途”。如果它正确说出了 Superpowers 里的几项技能说明加载链路已经通了。如果它一脸茫然就去查~/.codex/skills/目录结构和配置文件八成是路径套多了一层。4. 真刀真枪在 Java 项目里让 Superpowers 驱动 TDD4.1 先准备一个不会干扰 AI 的最小 Java 工程很多人在这一步就栽跟头工程里有一堆历史遗留代码、多模块依赖、自定义 parent POMCodex 一启动就被上下文塞满后面根本跑不起来。我建议你用一个“最小可复现工程”来验证 Superpowers而不是直接扔一个大仓库。最小工程要满足三个条件只有一个模块构建工具用 Maven 或 Gradle依赖尽量少src/main/java和src/test/java目录结构明确测试框架用 JUnit 5不要引入 Mockito、MockMvc 这类容易分散注意力的东西我用一个金额计算器来做实验。需求很简单支持金额的加法、减法、乘法且不能出现浮点精度问题。这类需求足够触发一次完整的 TDD 循环又不会让 AI 花太多时间在业务背景上。工程目录结构大概是money-calc/ ├── pom.xml └── src/ ├── main/java/com/example/money/ │ └── Money.java └── test/java/com/example/money/ └── MoneyTest.java注意初始状态只保留 Maven 配置和一个空模块两个 Java 类都不用写交给 Codex 来生成。4.2 用一句话需求触发完整工作流在 Codex 里输入一句话“在这个 Maven 工程里新增一个 Money 类金额用分存储支持加、减、乘要求所有运算不丢精度。请按照 TDD 技能执行。”如果你已经正确加载了 SuperpowersCodex 的第一步不会是直接创建Money.java而是先检查测试目录里有没有测试文件。发现没有后它会先创建MoneyTest.java。这个测试文件会覆盖至少五种情况金额加法正常进位金额减法出现负数乘法结果四舍五入到分大数相加不溢出字符串转金额时处理非法输入然后它才创建Money.java的实现类用long类型的字段保存“分”而不是用double。实现完成后再跑一次mvn test确认全部测试通过。这是不是看着很简单是的。但注意在没挂 Superpowers 之前同一句话进 Codex它大概率会先给你一个Money类里面用BigDecimal然后告诉你“用 BigDecimal 就不会丢精度”。它不会先写测试也不会验证边界。两种输出的差别就是技能流程带来的。4.3 我对输出产物的验收标准让 Codex 干完活之后我不会只看“测试通过”就收工。我有一套自己的验收清单针对 Java 项目重点检查以下项目领域类的核心状态是不是用了原始类型或不可变对象避免自动拆箱问题金额输入是否在构造函数里做了校验负数、null、非数字字符串有没有被拦截测试是否覆盖了“边界值”比如等于 0、正好进位、超过 Long 最大值是否遵循了项目既有的异常设计比如统一抛出IllegalArgumentException是否在实现阶段引入了不必要的外部库比如为了一个加法把整个 Guava 拉进来Superpowers 的 TDD 技能会让 AI 在“红灯”阶段先写失败测试这本身就保证了大多数边界会被覆盖。但 AI 不会替你决定业务规则比如“金额是否允许为负数”这事必须由你在需求里讲清楚。你在对话里说“金额不能为负”它就会把校验逻辑放进实现里你不说它可能就漏掉。4.4 如果第一步没跑通先查这四件事如果你像我一样满怀期待地输入需求结果 Codex 还是直接生成实现类完全没走 TDD先别急着怀疑工具炸了。按顺序排查第一技能是否真的被加载。回到第 3 章最后说的验证方法问一次“当前可用的技能”。第二AGENTS.md是否生效。如果你只配置了技能文件但没在AGENTS.md里声明“必须按技能执行”Codex 很可能会忽略它因为对它来说技能只是“可用参考”不是“必须流程”。第三当前工作目录对不对。如果你从~目录启动 Codex而不是从项目目录启动它可能读不到项目级配置也不会认为这是 Maven 工程。第四模型上下文窗口是否被塞满。如果刚才的对话已经很长了技能文件的加载会被截断工作流自然就走不完整。新开一个会话再试一次。我遇到的绝大多数问题都能靠“新开会话 明确让 AI 使用 TDD 技能”解决。5. Codex Superpowers 跑 Java 时我踩过的四个坑5.1 坑一Maven 还是 Gradle——AI 自己换了构建工具有一次我在一个 Maven 工程里让 Codex 完成一个模块开发结果它生成了一堆build.gradle文件还自作聪明地把目录结构调整成了 Gradle 布局。原因是我在自然语言里提了一句“用你熟悉的构建方式”它就直接选择了 Gradle。这很麻烦。因为 CI、IDE、同事的本地环境全是以 Maven 为准AI 擅自切换构建工具会导致整个分支不可用。根因是技能文件里只定义了 TDD 流程并没有限定“当前项目必须识别既有构建配置”。解决办法是在项目内AGENTS.md里写死# 构建规范 - 本项目使用 Maven禁止生成或新增 Gradle 相关文件。 - 所有新代码必须位于 src/main/java 和 src/test/java。 - 构建命令一律使用 mvn不使用 gradle。这条规则加进去之后Codex 不会再自由发挥。类似地如果你项目里用的是 Kotlin最好也把语言版本和构建命令写清楚。5.2 坑二误删手写测试的问题挂上 Superpowers 之后AI 的任务拆解能力变强但它对“哪些是它生成的、哪些是手写的”并没有可靠判断。某次重构时它把一批手写测试删掉了理由是“这些测试覆盖场景与生成的测试重复”。我回过神之后发现它其实不是真的想删而是技能的 review 环节要求它清理“冗余测试”它把“覆盖逻辑重复”和“直接删除”划了等号。这是 Agent 常见的过度总结。解决思路有两个。第一在手写的测试文件顶部加注释说明该文件是人工维护AI 只能追加不能删除例如// IMPORTANT: Manually maintained test. Do not delete or rewrite. Only append.第二在AGENTS.md里增加一条硬性规则“任何删除测试文件的操作必须经过用户明确批准不能自行判断。”这两条加进去之后我再没遇到过误删。5.3 坑三技能文件被带进 git 提交项目级安装 Superpowers 后如果你把它放进了.agents/skills/很容易在提交代码时不小心把整个技能仓库一并提交。我自己有一回发现提交记录里多了几百个 Markdown 文件全是第三方技能内容把仓库搞得又臭又大。这并不是说不能放项目级而是要在.gitignore里明确排除或者用 submodule 而不是直接复制文件。如果你想让技能随项目走我建议用 submodule并在仓库文档里写清楚如何初始化和更新如果你不想让技能进仓库就把它放进用户级目录项目内只通过AGENTS.md引用。我最终的选择是官方 Superpowers 放用户级团队私有技能放独立私有仓库项目只保留一份AGENTS.md引用指南。这样仓库干净升级也灵活。5.4 坑四上下文太长导致工作流中断Superpowers 的工作流步骤不少每一步都会产生大量输出。Codex 的上下文窗口虽然不小但在一个超过千行的 Java 工程里再叠加多轮对话很容易出现“后半段工作流被截断”的情况。表现是红灯测试还在绿灯实现已经结束了重构步骤直接消失。我的处理方式很简单一个任务只做一件事。不要让 Codex 在一个会话里同时完成需求分析、代码生成、测试、重构、文档更新。把任务拆小之后再用 Superpowers 的技能逐个执行。你可以手动拆也可以让它先执行“任务拆解”技能给你一份子任务清单然后你在新会话里逐个发起。这个习惯我非常推荐。不只解决上下文问题也让 Codex 每一步的变更都更可控代码 review 更容易。6. 从“能用”到“好用”把 Superpowers 变成团队规范6.1 把团队规范写进自定义 skillSuperpowers 自带的技能面向通用开发场景但每个团队都有自己的规矩数据库访问必须走某个封装类日志必须带 traceId接口返回必须包一层 Result。这些规矩如果只靠口头交代Codex 永远学不会。你应该做的是写自己的技能文件。放在~/.codex/skills/team/目录下命名如java-project-standards.md里面用步骤条形式写清团队规范。比如# Java Project Standards 当处理 Java 代码时必须遵循以下规范 1. 所有对外接口的返回类型必须是 ResultT禁止直接返回裸对象。 2. 日志必须包含 traceId禁止使用 logger 输出敏感字段。 3. 新增依赖前先检查 pom.xml 中是否已有相同功能依赖。 4. 异常处理统一使用 BizException禁止在业务代码里吞异常。 5. 单元测试类命名为 XxxTest所有公开方法必须有覆盖。写完之后Codex 每次在这个目录下启动都会自动读取相当于团队规范被标准化成了 Agent 可以直接执行的指令。这比写在 wiki 里等着被人翻阅有效得多。6.2 设置可验证的完成标准Superpowers 的“技能化”思路很好但 AI 判断“完成”的标准和人类不完全一致。你觉得完成是“测试通过 代码走查 无新增依赖”AI 可能觉得“编译通过”就是完成。在团队内推行 Superpowers 时我建议把完成标准作为一个独立技能文件固定下来。比如definition-of-done.md里面写# Definition of Done 只有同时满足以下条件一个子任务才能标记为完成 - 相关单元测试全部通过且覆盖关键分支。 - 代码符合团队编码规范参见 java-project-standards。 - 没有新增未使用的依赖。 - 没有修改与当前任务无关的文件。 - 没有删除或重命名既有测试。这个文件一旦被 Codex 读取它的“完成”判断就有了明确边界不会出现“我觉得写完了”这种模糊状态。我们在团队里加了这条之后AI 生成代码的返工率降了大约三成。6.3 多 skill 共存时的优先级技能文件多了之后会出现冲突。比如通用 TDD 技能要求“先写失败测试”团队规范技能要求“所有公开方法必须有测试”这两者方向一致但另一个技能要求“禁止使用 Mockito”而 Codex 生成测试代码时却经常顺手用 Mockito冲突就来了。Codex 加载多个技能时并没有严格的优先级设计。它会把所有可用技能都视作参考然后根据上下文自行组合。所以我们做了一件简单而有效的事在AGENTS.md里明确写了“技能加载优先级”。例如# Priority Rules 当多个技能对同一个问题给出不同指导时优先级从高到低为 1. definition-of-done 2. java-project-standards 3. superpowers 内置的 TDD 技能 4. 其他通用技能这一行看起来简单但能省掉大量来回“掰扯”。Agent 不再随机选择规范而是有一个明确的冲突裁决顺序。6.4 团队共享与维护最后说一句维护的事。Superpowers 这一类技能方案不是“装完就不管了”。技能是文本文本就需要定期更新。我们团队的做法是每月抽半天把最近被 AI 踩过的坑整理成新的技能条目比如“禁止用 stream 处理大列表”、“生成接口文档时必须同步修改 OpenAPI 文件”。这些条目积累在团队私有技能仓库里新人直接用老手也省得反复强调。如果你一个人开发也可以做这件事不用等别人。每次遇到 Codex 在项目里犯的重复性错误就把它改成一条技能规则下一次它就不会再犯。这种体验带点“驯养个人助手”的感觉也正是 Superpowers 真正值钱的地方它不只是在给 AI 加能力更像是在帮团队把经验沉淀成一堆高密度的文本资产。我现在每天开 Codex 之前都会顺手看一眼技能目录里有没有新增内容。这种习惯说不上多高级但用了几个月之后Codex 产出的代码质量明显比之前更稳定当初那种“盯着它别乱来”的感觉也减轻了。如果你也被默认对话模式里的来回拉扯折磨过不妨照着这个流程试一次。 Superpowers挂载Codex CLI：用技能包驱动TDD与Java高效开发
一开始我在本地把 superpowers 装进 Codex CLI纯粹是因为受不了默认对话模式反复返工。你让 Codex 改一个 Java 方法它改了实现却忘了按约定跑测试你提醒一次它才补上补完之后又把无关的格式动了一堆。与其说这是在协作不如说是在盯人。后来我把 superpowers 作为一套技能目录挂到 Codex 的技能加载路径里情况才真正好转它开始自己拆任务、先写测试、再实现、再重构像一个有基本职业素养的同事而不是一个只会接话的聊天窗口。这篇算是一份个人实测记录不是官方文档。我会把安装方式、目录规划、Java 项目实战和踩坑排查都写清楚适合那些已经在用 Codex CLI、想进一步规范 AI 工作流的开发者。如果你主要写 Java第 4 和第 5 节可以直接当作业指导来用。1. 先搞清楚Superpowers 到底给 Codex 加的是什么能力1.1 一个反直觉的结论它不是插件而是“技能包”很多人一听“给 Codex 装 superpowers”会下意识以为是个 VSCode 插件、MCP 服务或者 npm 包。我最初也这么想结果 clone 下来一看项目里最多的东西是.md文件。Superpowers 本质上是一套“工作流指令集”。它通过 Markdown 文件定义各种技能每个技能文件里写清楚了这个技能在什么场景下触发、执行时先做什么后做什么、中间要输出什么中间产物、最后用什么样的验收标准来判断完成。Codex 作为 Agent 读取这套技能之后相当于拿到了一本非常细的作业手册。你可以把它理解成给实习生写的 S.O.P。实习生聪明反应快但不知道你公司的代码规范是先写测试再写实现不知道重构前后要跑完整套用例不知道改完接口还要顺手更新调用方。S.O.P 把这些流程固化成文本Agent 每次开工前先读一遍行为就从“自由发挥”变成了“按流程执行”。这也是为什么它叫 superpowersCodex 本身的能力天花板没有变但使用方式被重新组织之后产出质量明显提升。注意它不是黑魔法它改变的是工作流不是模型智商。1.2 为什么 Codex 原生对话做不到这些直接和 Codex 对话时它会根据上下文即兴决定下一步。如果用户不提测试它就默认你不需要测试如果用户说“帮我重构一下”它可能只改了一个文件剩下的地方靠猜。原生对话模式的问题不是模型能力不足而是缺少“强制步骤”。Superpowers 解决的是这个“缺少强制步骤”的问题。它的技能文件里会明确要求开始写业务代码前必须先写一个失败测试测试跑红之后才允许进入实现阶段实现通过后再进入重构阶段。每一步都有明确的输入输出Codex 不能跳过“跑测试”这个动作直接给你交代码。我试过在同样一台机器上用同一个 Codex 模型处理同一个 Java 需求。不开 Superpowers 时它给出的代码能编译但单元测试覆盖率只有 30%而且没有按项目里既有的异常处理风格来写。开了 Superpowers 并加载 TDD 技能后它先自己建了src/test/java目录写了完整的边界测试再实现主类最后跑mvn test还主动把 Integer 运算改成了 BigDecimal。差距就在流程。1.3 Superpowers 替你跑起来的三条核心工作流我实际用得最多的是三条工作流。第一条是 TDD测试驱动开发。这个技能会要求 AI 严格按“红灯-绿灯-重构”来走。红灯阶段只写测试不写实现绿灯阶段用最简代码让测试通过重构阶段清理重复代码和命名问题。第二条是任务拆解。面对一个比较大的需求比如“给现有模块加一个消息队列消费者”Superpowers 会先把这个需求拆成若干子任务每个子任务有明确的交付物和验收条件然后逐个执行。这个能力在长任务里特别重要因为 Codex 一旦上下文被拉长很容易忘记最初目标。第三条是自动代码审查。完成实现后技能会要求 Codex 自己扮演 reviewer检查潜在 bug、并发问题、异常处理漏洞和测试盲区。它会输出问题清单再根据清单逐条修复。这三条工作流可以单独用也可以串起来。我通常把三条串在一起使用先拆任务再对每个子任务执行 TDD最后做一轮 review。效果比单独开任何一条都要稳。2. 安装前必须想明白的目录规划与版本选择2.1 先检查你的本地环境在动手装之前我建议你先跑一遍环境检查。以下三个命令分别确认 Codex CLI、Git 和构建工具的状态codex --version git --version mvn --version如果你用的是 Gradle 项目就把最后一个换成gradle --version。这里有个容易忽略的点Codex CLI 本身是通过 npm 安装的所以 Node.js 环境也需要是正常的但只在安装阶段用到运行时不一定依赖 Node。我遇到过一个情况Codex 版本太老技能加载路径还不稳定导致软链接过去了也读不到。后来升级到新版本才恢复正常。所以如果你之后遇到“明明配置了却不起作用”的怪问题先怀疑版本再怀疑配置。2.2 用户级、项目级、全局三种安装位置的取舍安装 Superpowers 之前要决定放哪里。这个决定影响范围很大我见过不少人直接散装到一堆项目里最后每个项目都要维护一份很痛苦。用户级安装是把技能目录放到~/.codex/skills/下面所有项目都能用。单个开发者自己用我推荐这种方式。项目级安装则是放到某个仓库的.codex/skills/或.agents/skills/目录下会随仓库走团队提交代码时能一起同步。全局安装是把它当作系统级指令放到 PATH 或公共配置目录里适合公司内部统一推行的场景但维护成本最高。你可以先按一张表来判断安装位置生效范围适合场景维护成本用户级当前用户所有项目个人日常开发、试验新技能低项目级单个仓库团队项目、需要统一规范的仓库中全局系统级机器上所有用户公司开发机标准化高从我自己的经验看绝大多数开发者从用户级开始就够了。等你在团队里验证了某条工作流确实有用再把它下沉到项目级让每一个克隆仓库的同事都能自动拿到。2.3 我推荐的目录布局目录布局不复杂但有个结构问题值得提前想好Superpowers 自带的技能是公用的你自己后加的技能是私有的。如果混在一个目录里升级 Superpowers 时可能会把自定义内容覆盖掉。我是这么组织的~/.codex/ ├── config.toml ├── AGENTS.md └── skills/ ├── superpowers/ # 官方技能 ├── team/ # 团队私有技能 └── personal/ # 个人私有技能这样升级 Superpowers 时只需要替换superpowers这一个子目录team和personal完全不受影响。Codex 加载技能是读取整个skills目录的所以不同来源之间不会冲突只要技能命名唯一就行。3. 挂载 Superpowers 到 Codex CLI两条实测可行的路线3.1 路线一软链接到 Codex 全局技能目录我先说我自己最常用的方式。它基于用户级安装好处是升级方便、回滚方便而且不会把第三方代码散落到项目仓库里。第一步把 Superpowers 仓库克隆到一个固定位置git clone https://github.com/obra/superpowers.git ~/superpowers第二步在 Codex 的技能目录里创建一个软链接mkdir -p ~/.codex/skills ln -s ~/superpowers/skills ~/.codex/skills/superpowers这里有一个细节链接目标不是~/superpowers本身而是它内部的skills目录。因为 Codex 期望的是“技能目录下面直接放技能文件”而不是“技能目录下面再套一层仓库结构”。我第一次犯过这个错误链接到仓库根目录结果加载时一个技能都识别不到。第三步如果你是新版本 Codex通常还需要在配置里确认启用了 Agent Skills。在~/.codex/config.toml里加入[skills] enabled true不同版本的配置字段名可能不一样。最稳妥的办法是运行codex --help查看当前版本是否包含 skills 相关参数。如果没找到也不用慌很多版本会在检测到技能目录后自动加载。3.2 路线二放进项目级 .agents 目录如果你的团队成员都会 clone 同一个仓库项目级安装更合适。Codex 在项目目录下会读取.agents/skills/或者.codex/skills/具体看版本。你可以直接复制也可以用子模块引入。用 git submodule 的方式是cd your-project mkdir -p .agents/skills git submodule add https://github.com/obra/superpowers.git .agents/skills/superpowers然后用一条软链接再处理一层让技能文件位于.agents/skills/superpowers下面一层。如果直接 clone 到.agents/skills/superpowers你需要确认这里面直接是 Markdown 技能文件而不是又包含一个skills子目录。项目级安装最大的好处是“开箱即用”。新人 clone 仓库之后Codex 自动就带上了全部技能不用每个人手动去配。它的代价就是仓库里多了第三方代码如果你不喜欢 submodule也可以用脚本在初始化时自动 clone 和软链。3.3 修改配置与验证加载配置除了开关 skills还有一个容易被忽略的文件AGENTS.md。Codex 在开始任务前会自动读取当前目录和用户目录下的AGENTS.md你可以用它来声明技能加载规则。我习惯在用户级~/.codex/AGENTS.md里写这么一段# Agent Instructions - 开始任务前检查 ~/.codex/skills/ 下是否有与任务匹配的技能。 - 如果存在匹配技能必须按技能文件中的步骤执行不能跳过任何步骤。 - 涉及测试代码时优先遵循 TDD 技能的“红灯-绿灯-重构”流程。这段文本的作用是让 Codex 别偷懒。技能文件是“储备”AGENTS.md是“启动器”。两者配合Codex 才会真的去翻技能而不是你每次手动在对话里要求它读文件。验证是否加载成功我提供一个最简单的办法直接在 Codex 里问他“你当前有哪些可用的技能请列出技能名称和用途”。如果它正确说出了 Superpowers 里的几项技能说明加载链路已经通了。如果它一脸茫然就去查~/.codex/skills/目录结构和配置文件八成是路径套多了一层。4. 真刀真枪在 Java 项目里让 Superpowers 驱动 TDD4.1 先准备一个不会干扰 AI 的最小 Java 工程很多人在这一步就栽跟头工程里有一堆历史遗留代码、多模块依赖、自定义 parent POMCodex 一启动就被上下文塞满后面根本跑不起来。我建议你用一个“最小可复现工程”来验证 Superpowers而不是直接扔一个大仓库。最小工程要满足三个条件只有一个模块构建工具用 Maven 或 Gradle依赖尽量少src/main/java和src/test/java目录结构明确测试框架用 JUnit 5不要引入 Mockito、MockMvc 这类容易分散注意力的东西我用一个金额计算器来做实验。需求很简单支持金额的加法、减法、乘法且不能出现浮点精度问题。这类需求足够触发一次完整的 TDD 循环又不会让 AI 花太多时间在业务背景上。工程目录结构大概是money-calc/ ├── pom.xml └── src/ ├── main/java/com/example/money/ │ └── Money.java └── test/java/com/example/money/ └── MoneyTest.java注意初始状态只保留 Maven 配置和一个空模块两个 Java 类都不用写交给 Codex 来生成。4.2 用一句话需求触发完整工作流在 Codex 里输入一句话“在这个 Maven 工程里新增一个 Money 类金额用分存储支持加、减、乘要求所有运算不丢精度。请按照 TDD 技能执行。”如果你已经正确加载了 SuperpowersCodex 的第一步不会是直接创建Money.java而是先检查测试目录里有没有测试文件。发现没有后它会先创建MoneyTest.java。这个测试文件会覆盖至少五种情况金额加法正常进位金额减法出现负数乘法结果四舍五入到分大数相加不溢出字符串转金额时处理非法输入然后它才创建Money.java的实现类用long类型的字段保存“分”而不是用double。实现完成后再跑一次mvn test确认全部测试通过。这是不是看着很简单是的。但注意在没挂 Superpowers 之前同一句话进 Codex它大概率会先给你一个Money类里面用BigDecimal然后告诉你“用 BigDecimal 就不会丢精度”。它不会先写测试也不会验证边界。两种输出的差别就是技能流程带来的。4.3 我对输出产物的验收标准让 Codex 干完活之后我不会只看“测试通过”就收工。我有一套自己的验收清单针对 Java 项目重点检查以下项目领域类的核心状态是不是用了原始类型或不可变对象避免自动拆箱问题金额输入是否在构造函数里做了校验负数、null、非数字字符串有没有被拦截测试是否覆盖了“边界值”比如等于 0、正好进位、超过 Long 最大值是否遵循了项目既有的异常设计比如统一抛出IllegalArgumentException是否在实现阶段引入了不必要的外部库比如为了一个加法把整个 Guava 拉进来Superpowers 的 TDD 技能会让 AI 在“红灯”阶段先写失败测试这本身就保证了大多数边界会被覆盖。但 AI 不会替你决定业务规则比如“金额是否允许为负数”这事必须由你在需求里讲清楚。你在对话里说“金额不能为负”它就会把校验逻辑放进实现里你不说它可能就漏掉。4.4 如果第一步没跑通先查这四件事如果你像我一样满怀期待地输入需求结果 Codex 还是直接生成实现类完全没走 TDD先别急着怀疑工具炸了。按顺序排查第一技能是否真的被加载。回到第 3 章最后说的验证方法问一次“当前可用的技能”。第二AGENTS.md是否生效。如果你只配置了技能文件但没在AGENTS.md里声明“必须按技能执行”Codex 很可能会忽略它因为对它来说技能只是“可用参考”不是“必须流程”。第三当前工作目录对不对。如果你从~目录启动 Codex而不是从项目目录启动它可能读不到项目级配置也不会认为这是 Maven 工程。第四模型上下文窗口是否被塞满。如果刚才的对话已经很长了技能文件的加载会被截断工作流自然就走不完整。新开一个会话再试一次。我遇到的绝大多数问题都能靠“新开会话 明确让 AI 使用 TDD 技能”解决。5. Codex Superpowers 跑 Java 时我踩过的四个坑5.1 坑一Maven 还是 Gradle——AI 自己换了构建工具有一次我在一个 Maven 工程里让 Codex 完成一个模块开发结果它生成了一堆build.gradle文件还自作聪明地把目录结构调整成了 Gradle 布局。原因是我在自然语言里提了一句“用你熟悉的构建方式”它就直接选择了 Gradle。这很麻烦。因为 CI、IDE、同事的本地环境全是以 Maven 为准AI 擅自切换构建工具会导致整个分支不可用。根因是技能文件里只定义了 TDD 流程并没有限定“当前项目必须识别既有构建配置”。解决办法是在项目内AGENTS.md里写死# 构建规范 - 本项目使用 Maven禁止生成或新增 Gradle 相关文件。 - 所有新代码必须位于 src/main/java 和 src/test/java。 - 构建命令一律使用 mvn不使用 gradle。这条规则加进去之后Codex 不会再自由发挥。类似地如果你项目里用的是 Kotlin最好也把语言版本和构建命令写清楚。5.2 坑二误删手写测试的问题挂上 Superpowers 之后AI 的任务拆解能力变强但它对“哪些是它生成的、哪些是手写的”并没有可靠判断。某次重构时它把一批手写测试删掉了理由是“这些测试覆盖场景与生成的测试重复”。我回过神之后发现它其实不是真的想删而是技能的 review 环节要求它清理“冗余测试”它把“覆盖逻辑重复”和“直接删除”划了等号。这是 Agent 常见的过度总结。解决思路有两个。第一在手写的测试文件顶部加注释说明该文件是人工维护AI 只能追加不能删除例如// IMPORTANT: Manually maintained test. Do not delete or rewrite. Only append.第二在AGENTS.md里增加一条硬性规则“任何删除测试文件的操作必须经过用户明确批准不能自行判断。”这两条加进去之后我再没遇到过误删。5.3 坑三技能文件被带进 git 提交项目级安装 Superpowers 后如果你把它放进了.agents/skills/很容易在提交代码时不小心把整个技能仓库一并提交。我自己有一回发现提交记录里多了几百个 Markdown 文件全是第三方技能内容把仓库搞得又臭又大。这并不是说不能放项目级而是要在.gitignore里明确排除或者用 submodule 而不是直接复制文件。如果你想让技能随项目走我建议用 submodule并在仓库文档里写清楚如何初始化和更新如果你不想让技能进仓库就把它放进用户级目录项目内只通过AGENTS.md引用。我最终的选择是官方 Superpowers 放用户级团队私有技能放独立私有仓库项目只保留一份AGENTS.md引用指南。这样仓库干净升级也灵活。5.4 坑四上下文太长导致工作流中断Superpowers 的工作流步骤不少每一步都会产生大量输出。Codex 的上下文窗口虽然不小但在一个超过千行的 Java 工程里再叠加多轮对话很容易出现“后半段工作流被截断”的情况。表现是红灯测试还在绿灯实现已经结束了重构步骤直接消失。我的处理方式很简单一个任务只做一件事。不要让 Codex 在一个会话里同时完成需求分析、代码生成、测试、重构、文档更新。把任务拆小之后再用 Superpowers 的技能逐个执行。你可以手动拆也可以让它先执行“任务拆解”技能给你一份子任务清单然后你在新会话里逐个发起。这个习惯我非常推荐。不只解决上下文问题也让 Codex 每一步的变更都更可控代码 review 更容易。6. 从“能用”到“好用”把 Superpowers 变成团队规范6.1 把团队规范写进自定义 skillSuperpowers 自带的技能面向通用开发场景但每个团队都有自己的规矩数据库访问必须走某个封装类日志必须带 traceId接口返回必须包一层 Result。这些规矩如果只靠口头交代Codex 永远学不会。你应该做的是写自己的技能文件。放在~/.codex/skills/team/目录下命名如java-project-standards.md里面用步骤条形式写清团队规范。比如# Java Project Standards 当处理 Java 代码时必须遵循以下规范 1. 所有对外接口的返回类型必须是 ResultT禁止直接返回裸对象。 2. 日志必须包含 traceId禁止使用 logger 输出敏感字段。 3. 新增依赖前先检查 pom.xml 中是否已有相同功能依赖。 4. 异常处理统一使用 BizException禁止在业务代码里吞异常。 5. 单元测试类命名为 XxxTest所有公开方法必须有覆盖。写完之后Codex 每次在这个目录下启动都会自动读取相当于团队规范被标准化成了 Agent 可以直接执行的指令。这比写在 wiki 里等着被人翻阅有效得多。6.2 设置可验证的完成标准Superpowers 的“技能化”思路很好但 AI 判断“完成”的标准和人类不完全一致。你觉得完成是“测试通过 代码走查 无新增依赖”AI 可能觉得“编译通过”就是完成。在团队内推行 Superpowers 时我建议把完成标准作为一个独立技能文件固定下来。比如definition-of-done.md里面写# Definition of Done 只有同时满足以下条件一个子任务才能标记为完成 - 相关单元测试全部通过且覆盖关键分支。 - 代码符合团队编码规范参见 java-project-standards。 - 没有新增未使用的依赖。 - 没有修改与当前任务无关的文件。 - 没有删除或重命名既有测试。这个文件一旦被 Codex 读取它的“完成”判断就有了明确边界不会出现“我觉得写完了”这种模糊状态。我们在团队里加了这条之后AI 生成代码的返工率降了大约三成。6.3 多 skill 共存时的优先级技能文件多了之后会出现冲突。比如通用 TDD 技能要求“先写失败测试”团队规范技能要求“所有公开方法必须有测试”这两者方向一致但另一个技能要求“禁止使用 Mockito”而 Codex 生成测试代码时却经常顺手用 Mockito冲突就来了。Codex 加载多个技能时并没有严格的优先级设计。它会把所有可用技能都视作参考然后根据上下文自行组合。所以我们做了一件简单而有效的事在AGENTS.md里明确写了“技能加载优先级”。例如# Priority Rules 当多个技能对同一个问题给出不同指导时优先级从高到低为 1. definition-of-done 2. java-project-standards 3. superpowers 内置的 TDD 技能 4. 其他通用技能这一行看起来简单但能省掉大量来回“掰扯”。Agent 不再随机选择规范而是有一个明确的冲突裁决顺序。6.4 团队共享与维护最后说一句维护的事。Superpowers 这一类技能方案不是“装完就不管了”。技能是文本文本就需要定期更新。我们团队的做法是每月抽半天把最近被 AI 踩过的坑整理成新的技能条目比如“禁止用 stream 处理大列表”、“生成接口文档时必须同步修改 OpenAPI 文件”。这些条目积累在团队私有技能仓库里新人直接用老手也省得反复强调。如果你一个人开发也可以做这件事不用等别人。每次遇到 Codex 在项目里犯的重复性错误就把它改成一条技能规则下一次它就不会再犯。这种体验带点“驯养个人助手”的感觉也正是 Superpowers 真正值钱的地方它不只是在给 AI 加能力更像是在帮团队把经验沉淀成一堆高密度的文本资产。我现在每天开 Codex 之前都会顺手看一眼技能目录里有没有新增内容。这种习惯说不上多高级但用了几个月之后Codex 产出的代码质量明显比之前更稳定当初那种“盯着它别乱来”的感觉也减轻了。如果你也被默认对话模式里的来回拉扯折磨过不妨照着这个流程试一次。