最近我几乎每天都在用 Codex CLI 写代码但说实话默认状态下的 Codex 给我一种指哪打哪但绝不多做一步的感觉——你让它写个函数它就只写那个函数你让它修个 bug它常常只堵住眼前这一个窟窿。后来我把 superpowers 这套配置挂上去整个工作流才真正顺了。这篇文章不聊虚的直接把 superpowers 是什么、怎么装、怎么用、在 Java 项目里怎么配合讲透如果你也在折腾 codex superpowers 这类增强玩法照着做就行。1. Superpowers是什么给Codex CLI装上资深工程师的工作习惯1.1 先聊聊Codex CLI用起来的真实感受OpenAI 的 Codex CLI 本质上是把 GPT 系列模型搬进了终端让它能读文件、跑命令、改代码、调用 git。它的底子很好但我实际用下来的最大感受是它太听话了。你给它一条非常具体的指令它能给你非常具体的输出质量还不差可一旦你给的指令比较宏观比如帮我优化一下这个模块的性能它就容易敷衍——随手改一个明显不痛不痒的地方然后告诉你优化完成。这其实不是模型能力不够。GPT 系列模型的推理能力是够的问题出在工作习惯上。默认的 Codex 没有一套稳定的做事流程该不该先读项目文档、要不要先写测试、改代码前该不该搜索所有相关调用点、提交 git 前要不要做一次自检——这些事情它全凭临场发挥你 prompt 写得好它就干得好prompt 写得松它就糊弄。我猜这也是很多人的共同体验Codex CLI 像是一个有潜力但缺乏职业素养的实习生而不是一个稳定输出的资深工程师。1.2 superpowers的核心思路不在模型在提示词superpowers 这个项目本质上就是若干个精心设计的系统提示词system prompt和技能文档通过 Codex CLI 的配置文件注入给模型。它不改变模型本身也不改变 Codex CLI 的底层代码而是通过上下文工程把模型的工作方式从被动应答扭转为按一套成熟流程主动做事。我用一个生活化的类比解释一下同样一个人你跟他在咖啡馆闲聊他可能东一句西一句但如果你给他一份面试官的答题框架让他按先讲风险、再讲方案、最后给落地步骤的顺序回答他的输出立刻会变得结构化。superpowers 干的就是这件事它给 Codex 的是一整套如何当一名靠谱工程师的答题框架。这套提示词通常很长可能包括接到任务后先做什么、在什么情况下要主动追问、写代码前要不要先补测试、失败时怎么排查、提交 git 时 commit message 怎么写、如何在大型代码库里定位相关代码等等。与其说它是超能力不如说它是职业习惯注入器。1.3 适合谁、解决什么问题先说结论如果你只是偶尔打开 Codex 问几个语法问题那 superpowers 对你帮助有限但如果你把 Codex 当作日常写代码的主力工具尤其是在真实项目里跑测试、改 bug、做重构那这套东西能明显减少你的返工对话。它解决的是这几类痛点指令太粗时Codex 容易偷懒或跑偏superpowers 强制它先列计划再动手。在陌生代码库里Codex 经常不读项目文档就猜superpowers 引导它先建立上下文。写完代码不验证导致你还要手动跑测试才发现挂了superpowers 会把自测写进默认流程。一次改动牵扯多个文件时Codex 容易漏改superpowers 的小步提交和自检机制能兜住。我个人的建议是已经能熟练使用 Codex CLI 的人完全可以无痛上车对命令行还不熟的新手最好先跑通 Codex 基础用法再上 superpowers否则你很难判断到底是配置问题还是使用方法问题。2. 安装与环境配置从零到能用的完整流程2.1 前置环境先把Codex CLI装好superpowers 只是配置前提是你得有一个能用的 Codex CLI。我接触到的常见安装方式是 npm 全局安装命令大致如下npm install -g openai/codex装完之后先登录codex login它会打开浏览器让你授权完成后在终端里验证一下codex --version如果版本号能正常打出来基础环境就算 OK 了。这里提醒一句Codex CLI 的版本迭代很快不同版本的配置字段兼容性偶尔会出问题后面遇到配置不生效时第一反应应该是看版本而不是怀疑提示词写错了。2.2 拉取superpowers并理解目录结构接下来从 GitHub 拉取 superpowers 项目到本地。我用的是固定目录方式方便全局引用git clone https://github.com/obra/superpowers.git ~/.superpowers不同的版本目录结构略有出入但核心内容大致分三类一是主系统提示词文件二是按场景拆分的技能文档skill比如测试驱动开发、代码审查、git 提交规范等三是安装或配置说明文档。我实际用下来的理解是这些技能文档不是让 Codex 每次全都读一遍而是作为可被调用的知识库。主提示词里会告诉模型当你需要写测试时参考 test-driven-development 技能模型在执行任务时按需加载对应文档。这种模块化设计很聪明既保证了主提示词的可读性也避免了把所有内容一股脑塞进上下文导致 Token 浪费。2.3 挂载系统提示词配置逐行解析Codex CLI 的全局配置在~/.codex/config.toml。我在安装 superpowers 时踩过的最大的坑就是不知道该往哪个字段里写提示词。后来反复试下来最稳妥的做法是直接改system_prompt字段。一个最小可用的配置长这样model gpt-5 system_prompt 你是一名具备资深经验的软件工程师遵循以下工作准则 1. 接到任务后先制定简短计划必要时向用户确认。 2. 动手改代码前先阅读项目中的 AGENTS.md 和 README。 3. 需要写功能时优先考虑测试驱动开发先写失败测试再实现。 4. 执行每个 shell 命令前用一句话解释为什么要执行它。 5. 每次改动后运行相关测试并报告结果。 6. 所有代码改动遵循最小变更原则不顺手重构无关代码。 7. 你不确定的事情要直接承认不要编造。 把 superpowers 项目里的完整提示词内容替换进去或者直接用一个 shell 命令把文件内容拼进配置都可以。我习惯的做法是保留一个独立的提示词文件比如~/.superpowers/codex_prompt.md然后在 config.toml 里通过程序化方式把它读入这样后续更新提示词不用反复编辑配置。配置写完后重启 Codex CLI 会话然后可以先用一个简单问题验证直接问它你当前的工作准则里第一条是什么。如果它能准确回答出来说明系统提示词已经生效。3. 超能力模块拆解每一层提示词到底改变了什么3.1 为什么一份提示词能改变模型行为很多人第一次听到靠提示词就能变强会怀疑模型能力如果没变提示词凭什么改变结果其实这里的关键在于大语言模型的输出质量是模型权重 上下文 采样策略共同决定的。模型权重是固定的但上下文可以极大地影响它调用自身能力的方式。system prompt 在 Codex CLI 里属于最高优先级的上下文模型对它的遵循程度通常高于用户后发的普通指令。所以当你把必须先写测试、必须解释每条命令、必须最小化变更这些规则写进去模型在每次生成回答时都会把它们当作默认考量。这就像一个人能力不变但如果他在做事前先收到一张工作前检查清单他的行为会明显变得有条理。系统提示词与其说是给模型增加知识不如说是给模型增加工作前的检查清单。3.2 核心能力模块详解我把常用的几个能力模块整理成了对照表方便你理解默认 Codex 和挂载 superpowers 后的差异场景默认Codex的常见行为挂载superpowers后的行为收到一个模糊需求直接猜测并开始写代码先列出计划遇到关键歧义会主动提问进入陌生项目直接搜索目标关键词可能漏看约定先读 AGENTS.md、README再确认构建和测试命令开发新功能写实现代码可能不补测试优先按 TDD 流程先写失败测试再实现执行 shell 命令直接执行不解释先用一句话说明意图危险命令会追加确认修改多个文件后改完即止不验证主动运行相关测试汇报结果提交 git可能一次提交大量改动拆分为小步提交commit message 有明确规范其中让我感受最明显的是主动验证这一条。默认 Codex 写完代码后很少会立刻想到跑一遍测试尤其在测试耗时较长的项目里它倾向于我觉得没问题。但 superpowers 会把验证当作必选动作这一点直接改变了我对 AI 编程助手的信任度——一个写完就跑测试的 AI和一个写完说应该可以了的 AI给人的安全感完全不同。3.3 在Java项目中的应用要点热词里出现了 superpowers java我特意在 Java 项目里做了测试。先说结论superpowers 本身是语言无关的但它对 Java 项目的效果取决于你有没有在项目层把 Java 的约定告诉它。Java 项目和 Python/JS 项目差别很大构建工具可能是 Maven 或 Gradle测试可能是 JUnit 4 或 5代码风格上有 package 层级和严格的访问修饰符。如果项目层没有文档说明模型默认会按它最熟的通用做法来很可能给出能编译但不符合项目惯例的代码。所以在 Java 项目里我建议在仓库根目录放一份精简的 AGENTS.md内容不需要多关键是让 Codex 知道这些约定# AGENTS.md - 构建命令mvn -q compile - 测试命令mvn -q test - 单个测试mvn -q -DtestClassName#method test - 代码风格遵循阿里巴巴P3C规范4空格缩进拒绝魔法值 - 包结构按 com.company.module 组织controller/service/repository 分层 - 新功能必须附带JUnit测试覆盖率不低于80%挂上之后你在 Java 项目里给 Codex 派活它就会先读这份文件然后用 Maven 跑测试而不是凭空猜一个python test.py出来。这个配合方式让我觉得superpowers 真正聪明的不是让模型变强而是让模型愿意先看说明书再动手。4. 实战用Superpowers完成一个Java工具类并跑通测试4.1 实操场景与准备为了把过程讲清楚我准备了一个最小的 Java Maven 工程里面只有一个空目录和一个pom.xml依赖了 JUnit 5没有写任何业务代码。任务指令是给这个项目添加一个金额格式化工具类要求把数字格式化为带千分位和两位小数的字符串并编写测试确保负数、小数、大数都正确。在没有挂载 superpowers 时我试过一次同样的指令Codex 直接在 src/main/java 下生成了一个MoneyFormatter.java然后象征性地写了一个只覆盖正整数的测试跑完就算了测试覆盖明显不够。挂载 superpowers 后整个流程完全不同我下面按实际交互拆开讲。4.2 完整交互过程与关键细节第一步Codex 先输出了一段计划大致逻辑是先读 pom.xml 确认 Java 版本和 JUnit 依赖再检查源码目录是否存在没有则创建随后为任务设计测试用例最后实现并运行测试。这一步就是 superpowers 最典型的计划先行行为。它不是急着写代码而是先把要做什么、按什么顺序做列出来。我在实操中的体会是这一步不仅是形式它真的能减少返工——因为我可以在它动手前就指出测试框架要用 JUnit 5不用事后再改。第二步它创建了测试目录和测试文件测试类名是MoneyFormatterTest里面写了四个测试方法正整数千分位、负数保留括号或负号、小数值四舍五入、超过万亿的大数边界。这里我要夸一下它主动把负数和小数单独列为用例这是默认 Codex 经常漏掉的。第三步才开始写实现类。它写了MoneyFormatter内部用String.format和DecimalFormat结合处理避免了浮点运算的精度问题。这一步的执行顺序特别重要先看到测试失败再写实现最后跑测试——这本身就是测试驱动开发的节奏。第四步运行测试。它执行了mvn -q test测试通过后没有立刻说完成而是又执行了一次全量测试确认没有影响其他类最后还提示我可以把工具类放进util包下以符合现有分层约定。这个多走一步去对齐项目结构的行为在默认 Codex 上我基本没见到过。4.3 质量对比挂载前后行为差异同样是写一个工具类并测试这个任务挂载前后的行为差异很明显对照项默认Codex挂载superpowers后是否先列计划否直接写代码是且计划结构清晰测试用例覆盖少往往只有正向场景多覆盖负数、小数、边界是否主动运行测试不一定取决于任务措辞是默认必做是否对齐项目约定很少关注主动读 AGENTS.md 并遵循完成后的汇报已完成附带测试结果和后续建议我并不是说默认 Codex 做不到这些而是说它时灵时不灵灵感来了全都有没灵感就敷衍。superpowers 的价值是把这些行为从偶然变成必然。这就像老司机和新手的区别两者都能开到目的地但老司机每次都会看后视镜、打转向灯新手则是看心情。5. 常见问题与排查技巧踩过的坑和对应解法5.1 配置挂载后不生效这是我见过最多的问题很多人改完 config.toml 后跑codex exec hello发现模型行为和以前一模一样然后就以为 superpowers 没用。我排查下来百分之七八十的原因都是没有重启会话。Codex CLI 在启动时会读取配置文件如果你在同一个会话里改了配置它不会热加载。必须退出交互式会话重新进入或者重新执行新的 exec 命令。另外如果你同时存在项目级配置和全局配置项目级配置里的内容会叠加或覆盖部分系统提示需要留意AGENTS.md的优先级。还有一个隐蔽问题有些版本对system_prompt字段会做截断或转义如果提示词文件里含特殊字符可能导致解析失败。我建议先用一个简单的英文提示词测试配置链路是否通畅再替换完整超能力提示词。5.2 上下文与Token消耗控制挂载超长系统提示词最直接的副作用就是 Token 消耗上升。每个请求都会带上完整的 system prompt如果你还把所有技能文档都塞进提示词一次对话的上下文还没开始干活就已经占了不少额度。我的做法是主提示词精炼 技能文档按需引用。主提示词只放通用工作准则各场景的详细规则放进独立文档通过指令告诉模型需要时再读。具体到 config.toml可以这样控制模型选择model gpt-5-mini日常小任务我用轻量模型配合精简提示词只有重大重构或者排查复杂问题才切到完整版。这样 Token 消耗能降不少而且响应速度更快。5.3 多项目、多语言环境的配置协同如果你像我一样同时维护 Java、Python、前端项目会面临一个问题某些超能力准则在 Java 项目里合适在 Python 项目里可能水土不服。比如强制 4 空格缩进这种规则在 JavaScript 项目里通常没问题但在 Python 项目里虽然是 PEP8 标准却也未必符合团队已有习惯。我的解决方案是把语言相关的差异全部下沉到各项目自己的 AGENTS.md 中全局的 superpowers 只保留与语言无关的工程素养比如计划先行、命令解释、最小变更、测试验证。这样每个项目加载自己的 AGENTS.md 后Codex 会自动切换行为模式。5.4 问题速查表症状可能原因解决动作模型行为没有变化配置未重启会话退出 codex 重新进入或重开 exec提示词不完整配置文件转义问题改用文件拼接方式载入Token 消耗过快prompt 太长且模型偏大精简主提示词按需引用技能文档测试命令跑错项目缺 AGENTS.md在仓库根目录补充构建测试命令说明模型过度谨慎不敢动手提示词限制了太多操作给提示词增加低风险操作可自主执行豁免条款git 提交被阻止提示词要求小步提交但改动过大拆分任务或调整提交频率规则这些坑我在一个个项目里都踩过列出来就是希望你能少走弯路。尤其是提示词导致模型变得过度谨慎这一点很容易被忽略——有些 superpowers 配置会强调风险确认结果模型连创建目录都要问你一遍反而拖慢速度。解决方法是把规则的语气从任何操作前都必须确认改成仅对不可逆或影响全局的操作进行确认。6. 用了三周后的真实体感与配置建议说实话superpowers 并没有让 Codex 变成什么都会的天才它做到的是让 Codex 变成一个稳定、可预期的同事。以前我要求自己把 prompt 写得很细才敢放手让 Codex 干活现在我可以给出一个更宏观的任务因为它自己的流程会帮我兜住细节。这种体验上的变化比单次代码质量的提升更有价值。最后分享两个实操建议。第一不要一上来就全盘照抄别人的完整提示词先用两天默认配置记录下它让你最不满意的两三个行为再针对性添加规则。这样你才能真正理解每一条提示词在改变什么而不是把 superpowers 当黑盒。第二维护一个自己的custom_superpowers.md把你在项目里反复重复的规则沉淀进去比如提交信息必须带 JIRA 单号或收到需求先评估数据表变更这些个人化规则叠加到通用提示词上效果往往比原版还实用。踩过几次坑之后我的体会是AI 编程助手的上限由模型决定但下限由 prompt 和配置决定。superpowers 这类项目的出现本质上是在告诉我们——工具好不好用很多时候不在于工具本身而在于你怎么用它。 
长河君 · 2026/10/15 19:21:34 · 阅读 1.2k Codex CLI增强神器Superpowers：从安装到Java项目实战
最近我几乎每天都在用 Codex CLI 写代码但说实话默认状态下的 Codex 给我一种指哪打哪但绝不多做一步的感觉——你让它写个函数它就只写那个函数你让它修个 bug它常常只堵住眼前这一个窟窿。后来我把 superpowers 这套配置挂上去整个工作流才真正顺了。这篇文章不聊虚的直接把 superpowers 是什么、怎么装、怎么用、在 Java 项目里怎么配合讲透如果你也在折腾 codex superpowers 这类增强玩法照着做就行。1. Superpowers是什么给Codex CLI装上资深工程师的工作习惯1.1 先聊聊Codex CLI用起来的真实感受OpenAI 的 Codex CLI 本质上是把 GPT 系列模型搬进了终端让它能读文件、跑命令、改代码、调用 git。它的底子很好但我实际用下来的最大感受是它太听话了。你给它一条非常具体的指令它能给你非常具体的输出质量还不差可一旦你给的指令比较宏观比如帮我优化一下这个模块的性能它就容易敷衍——随手改一个明显不痛不痒的地方然后告诉你优化完成。这其实不是模型能力不够。GPT 系列模型的推理能力是够的问题出在工作习惯上。默认的 Codex 没有一套稳定的做事流程该不该先读项目文档、要不要先写测试、改代码前该不该搜索所有相关调用点、提交 git 前要不要做一次自检——这些事情它全凭临场发挥你 prompt 写得好它就干得好prompt 写得松它就糊弄。我猜这也是很多人的共同体验Codex CLI 像是一个有潜力但缺乏职业素养的实习生而不是一个稳定输出的资深工程师。1.2 superpowers的核心思路不在模型在提示词superpowers 这个项目本质上就是若干个精心设计的系统提示词system prompt和技能文档通过 Codex CLI 的配置文件注入给模型。它不改变模型本身也不改变 Codex CLI 的底层代码而是通过上下文工程把模型的工作方式从被动应答扭转为按一套成熟流程主动做事。我用一个生活化的类比解释一下同样一个人你跟他在咖啡馆闲聊他可能东一句西一句但如果你给他一份面试官的答题框架让他按先讲风险、再讲方案、最后给落地步骤的顺序回答他的输出立刻会变得结构化。superpowers 干的就是这件事它给 Codex 的是一整套如何当一名靠谱工程师的答题框架。这套提示词通常很长可能包括接到任务后先做什么、在什么情况下要主动追问、写代码前要不要先补测试、失败时怎么排查、提交 git 时 commit message 怎么写、如何在大型代码库里定位相关代码等等。与其说它是超能力不如说它是职业习惯注入器。1.3 适合谁、解决什么问题先说结论如果你只是偶尔打开 Codex 问几个语法问题那 superpowers 对你帮助有限但如果你把 Codex 当作日常写代码的主力工具尤其是在真实项目里跑测试、改 bug、做重构那这套东西能明显减少你的返工对话。它解决的是这几类痛点指令太粗时Codex 容易偷懒或跑偏superpowers 强制它先列计划再动手。在陌生代码库里Codex 经常不读项目文档就猜superpowers 引导它先建立上下文。写完代码不验证导致你还要手动跑测试才发现挂了superpowers 会把自测写进默认流程。一次改动牵扯多个文件时Codex 容易漏改superpowers 的小步提交和自检机制能兜住。我个人的建议是已经能熟练使用 Codex CLI 的人完全可以无痛上车对命令行还不熟的新手最好先跑通 Codex 基础用法再上 superpowers否则你很难判断到底是配置问题还是使用方法问题。2. 安装与环境配置从零到能用的完整流程2.1 前置环境先把Codex CLI装好superpowers 只是配置前提是你得有一个能用的 Codex CLI。我接触到的常见安装方式是 npm 全局安装命令大致如下npm install -g openai/codex装完之后先登录codex login它会打开浏览器让你授权完成后在终端里验证一下codex --version如果版本号能正常打出来基础环境就算 OK 了。这里提醒一句Codex CLI 的版本迭代很快不同版本的配置字段兼容性偶尔会出问题后面遇到配置不生效时第一反应应该是看版本而不是怀疑提示词写错了。2.2 拉取superpowers并理解目录结构接下来从 GitHub 拉取 superpowers 项目到本地。我用的是固定目录方式方便全局引用git clone https://github.com/obra/superpowers.git ~/.superpowers不同的版本目录结构略有出入但核心内容大致分三类一是主系统提示词文件二是按场景拆分的技能文档skill比如测试驱动开发、代码审查、git 提交规范等三是安装或配置说明文档。我实际用下来的理解是这些技能文档不是让 Codex 每次全都读一遍而是作为可被调用的知识库。主提示词里会告诉模型当你需要写测试时参考 test-driven-development 技能模型在执行任务时按需加载对应文档。这种模块化设计很聪明既保证了主提示词的可读性也避免了把所有内容一股脑塞进上下文导致 Token 浪费。2.3 挂载系统提示词配置逐行解析Codex CLI 的全局配置在~/.codex/config.toml。我在安装 superpowers 时踩过的最大的坑就是不知道该往哪个字段里写提示词。后来反复试下来最稳妥的做法是直接改system_prompt字段。一个最小可用的配置长这样model gpt-5 system_prompt 你是一名具备资深经验的软件工程师遵循以下工作准则 1. 接到任务后先制定简短计划必要时向用户确认。 2. 动手改代码前先阅读项目中的 AGENTS.md 和 README。 3. 需要写功能时优先考虑测试驱动开发先写失败测试再实现。 4. 执行每个 shell 命令前用一句话解释为什么要执行它。 5. 每次改动后运行相关测试并报告结果。 6. 所有代码改动遵循最小变更原则不顺手重构无关代码。 7. 你不确定的事情要直接承认不要编造。 把 superpowers 项目里的完整提示词内容替换进去或者直接用一个 shell 命令把文件内容拼进配置都可以。我习惯的做法是保留一个独立的提示词文件比如~/.superpowers/codex_prompt.md然后在 config.toml 里通过程序化方式把它读入这样后续更新提示词不用反复编辑配置。配置写完后重启 Codex CLI 会话然后可以先用一个简单问题验证直接问它你当前的工作准则里第一条是什么。如果它能准确回答出来说明系统提示词已经生效。3. 超能力模块拆解每一层提示词到底改变了什么3.1 为什么一份提示词能改变模型行为很多人第一次听到靠提示词就能变强会怀疑模型能力如果没变提示词凭什么改变结果其实这里的关键在于大语言模型的输出质量是模型权重 上下文 采样策略共同决定的。模型权重是固定的但上下文可以极大地影响它调用自身能力的方式。system prompt 在 Codex CLI 里属于最高优先级的上下文模型对它的遵循程度通常高于用户后发的普通指令。所以当你把必须先写测试、必须解释每条命令、必须最小化变更这些规则写进去模型在每次生成回答时都会把它们当作默认考量。这就像一个人能力不变但如果他在做事前先收到一张工作前检查清单他的行为会明显变得有条理。系统提示词与其说是给模型增加知识不如说是给模型增加工作前的检查清单。3.2 核心能力模块详解我把常用的几个能力模块整理成了对照表方便你理解默认 Codex 和挂载 superpowers 后的差异场景默认Codex的常见行为挂载superpowers后的行为收到一个模糊需求直接猜测并开始写代码先列出计划遇到关键歧义会主动提问进入陌生项目直接搜索目标关键词可能漏看约定先读 AGENTS.md、README再确认构建和测试命令开发新功能写实现代码可能不补测试优先按 TDD 流程先写失败测试再实现执行 shell 命令直接执行不解释先用一句话说明意图危险命令会追加确认修改多个文件后改完即止不验证主动运行相关测试汇报结果提交 git可能一次提交大量改动拆分为小步提交commit message 有明确规范其中让我感受最明显的是主动验证这一条。默认 Codex 写完代码后很少会立刻想到跑一遍测试尤其在测试耗时较长的项目里它倾向于我觉得没问题。但 superpowers 会把验证当作必选动作这一点直接改变了我对 AI 编程助手的信任度——一个写完就跑测试的 AI和一个写完说应该可以了的 AI给人的安全感完全不同。3.3 在Java项目中的应用要点热词里出现了 superpowers java我特意在 Java 项目里做了测试。先说结论superpowers 本身是语言无关的但它对 Java 项目的效果取决于你有没有在项目层把 Java 的约定告诉它。Java 项目和 Python/JS 项目差别很大构建工具可能是 Maven 或 Gradle测试可能是 JUnit 4 或 5代码风格上有 package 层级和严格的访问修饰符。如果项目层没有文档说明模型默认会按它最熟的通用做法来很可能给出能编译但不符合项目惯例的代码。所以在 Java 项目里我建议在仓库根目录放一份精简的 AGENTS.md内容不需要多关键是让 Codex 知道这些约定# AGENTS.md - 构建命令mvn -q compile - 测试命令mvn -q test - 单个测试mvn -q -DtestClassName#method test - 代码风格遵循阿里巴巴P3C规范4空格缩进拒绝魔法值 - 包结构按 com.company.module 组织controller/service/repository 分层 - 新功能必须附带JUnit测试覆盖率不低于80%挂上之后你在 Java 项目里给 Codex 派活它就会先读这份文件然后用 Maven 跑测试而不是凭空猜一个python test.py出来。这个配合方式让我觉得superpowers 真正聪明的不是让模型变强而是让模型愿意先看说明书再动手。4. 实战用Superpowers完成一个Java工具类并跑通测试4.1 实操场景与准备为了把过程讲清楚我准备了一个最小的 Java Maven 工程里面只有一个空目录和一个pom.xml依赖了 JUnit 5没有写任何业务代码。任务指令是给这个项目添加一个金额格式化工具类要求把数字格式化为带千分位和两位小数的字符串并编写测试确保负数、小数、大数都正确。在没有挂载 superpowers 时我试过一次同样的指令Codex 直接在 src/main/java 下生成了一个MoneyFormatter.java然后象征性地写了一个只覆盖正整数的测试跑完就算了测试覆盖明显不够。挂载 superpowers 后整个流程完全不同我下面按实际交互拆开讲。4.2 完整交互过程与关键细节第一步Codex 先输出了一段计划大致逻辑是先读 pom.xml 确认 Java 版本和 JUnit 依赖再检查源码目录是否存在没有则创建随后为任务设计测试用例最后实现并运行测试。这一步就是 superpowers 最典型的计划先行行为。它不是急着写代码而是先把要做什么、按什么顺序做列出来。我在实操中的体会是这一步不仅是形式它真的能减少返工——因为我可以在它动手前就指出测试框架要用 JUnit 5不用事后再改。第二步它创建了测试目录和测试文件测试类名是MoneyFormatterTest里面写了四个测试方法正整数千分位、负数保留括号或负号、小数值四舍五入、超过万亿的大数边界。这里我要夸一下它主动把负数和小数单独列为用例这是默认 Codex 经常漏掉的。第三步才开始写实现类。它写了MoneyFormatter内部用String.format和DecimalFormat结合处理避免了浮点运算的精度问题。这一步的执行顺序特别重要先看到测试失败再写实现最后跑测试——这本身就是测试驱动开发的节奏。第四步运行测试。它执行了mvn -q test测试通过后没有立刻说完成而是又执行了一次全量测试确认没有影响其他类最后还提示我可以把工具类放进util包下以符合现有分层约定。这个多走一步去对齐项目结构的行为在默认 Codex 上我基本没见到过。4.3 质量对比挂载前后行为差异同样是写一个工具类并测试这个任务挂载前后的行为差异很明显对照项默认Codex挂载superpowers后是否先列计划否直接写代码是且计划结构清晰测试用例覆盖少往往只有正向场景多覆盖负数、小数、边界是否主动运行测试不一定取决于任务措辞是默认必做是否对齐项目约定很少关注主动读 AGENTS.md 并遵循完成后的汇报已完成附带测试结果和后续建议我并不是说默认 Codex 做不到这些而是说它时灵时不灵灵感来了全都有没灵感就敷衍。superpowers 的价值是把这些行为从偶然变成必然。这就像老司机和新手的区别两者都能开到目的地但老司机每次都会看后视镜、打转向灯新手则是看心情。5. 常见问题与排查技巧踩过的坑和对应解法5.1 配置挂载后不生效这是我见过最多的问题很多人改完 config.toml 后跑codex exec hello发现模型行为和以前一模一样然后就以为 superpowers 没用。我排查下来百分之七八十的原因都是没有重启会话。Codex CLI 在启动时会读取配置文件如果你在同一个会话里改了配置它不会热加载。必须退出交互式会话重新进入或者重新执行新的 exec 命令。另外如果你同时存在项目级配置和全局配置项目级配置里的内容会叠加或覆盖部分系统提示需要留意AGENTS.md的优先级。还有一个隐蔽问题有些版本对system_prompt字段会做截断或转义如果提示词文件里含特殊字符可能导致解析失败。我建议先用一个简单的英文提示词测试配置链路是否通畅再替换完整超能力提示词。5.2 上下文与Token消耗控制挂载超长系统提示词最直接的副作用就是 Token 消耗上升。每个请求都会带上完整的 system prompt如果你还把所有技能文档都塞进提示词一次对话的上下文还没开始干活就已经占了不少额度。我的做法是主提示词精炼 技能文档按需引用。主提示词只放通用工作准则各场景的详细规则放进独立文档通过指令告诉模型需要时再读。具体到 config.toml可以这样控制模型选择model gpt-5-mini日常小任务我用轻量模型配合精简提示词只有重大重构或者排查复杂问题才切到完整版。这样 Token 消耗能降不少而且响应速度更快。5.3 多项目、多语言环境的配置协同如果你像我一样同时维护 Java、Python、前端项目会面临一个问题某些超能力准则在 Java 项目里合适在 Python 项目里可能水土不服。比如强制 4 空格缩进这种规则在 JavaScript 项目里通常没问题但在 Python 项目里虽然是 PEP8 标准却也未必符合团队已有习惯。我的解决方案是把语言相关的差异全部下沉到各项目自己的 AGENTS.md 中全局的 superpowers 只保留与语言无关的工程素养比如计划先行、命令解释、最小变更、测试验证。这样每个项目加载自己的 AGENTS.md 后Codex 会自动切换行为模式。5.4 问题速查表症状可能原因解决动作模型行为没有变化配置未重启会话退出 codex 重新进入或重开 exec提示词不完整配置文件转义问题改用文件拼接方式载入Token 消耗过快prompt 太长且模型偏大精简主提示词按需引用技能文档测试命令跑错项目缺 AGENTS.md在仓库根目录补充构建测试命令说明模型过度谨慎不敢动手提示词限制了太多操作给提示词增加低风险操作可自主执行豁免条款git 提交被阻止提示词要求小步提交但改动过大拆分任务或调整提交频率规则这些坑我在一个个项目里都踩过列出来就是希望你能少走弯路。尤其是提示词导致模型变得过度谨慎这一点很容易被忽略——有些 superpowers 配置会强调风险确认结果模型连创建目录都要问你一遍反而拖慢速度。解决方法是把规则的语气从任何操作前都必须确认改成仅对不可逆或影响全局的操作进行确认。6. 用了三周后的真实体感与配置建议说实话superpowers 并没有让 Codex 变成什么都会的天才它做到的是让 Codex 变成一个稳定、可预期的同事。以前我要求自己把 prompt 写得很细才敢放手让 Codex 干活现在我可以给出一个更宏观的任务因为它自己的流程会帮我兜住细节。这种体验上的变化比单次代码质量的提升更有价值。最后分享两个实操建议。第一不要一上来就全盘照抄别人的完整提示词先用两天默认配置记录下它让你最不满意的两三个行为再针对性添加规则。这样你才能真正理解每一条提示词在改变什么而不是把 superpowers 当黑盒。第二维护一个自己的custom_superpowers.md把你在项目里反复重复的规则沉淀进去比如提交信息必须带 JIRA 单号或收到需求先评估数据表变更这些个人化规则叠加到通用提示词上效果往往比原版还实用。踩过几次坑之后我的体会是AI 编程助手的上限由模型决定但下限由 prompt 和配置决定。superpowers 这类项目的出现本质上是在告诉我们——工具好不好用很多时候不在于工具本身而在于你怎么用它。