最近我几乎每天都在用 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 -Dtest=ClassName#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 这类项目的出现，本质上是在告诉我们——工具好不好用，很多时候不在于工具本身，而在于你怎么用它。
