如果你最近在用 Codex CLI写代码，应该已经注意到一个挺有意思的现象：同样是那个模型，有人让它做个功能，它老老实实拆任务、写测试、改 bug，一套流程下来真心像个体面的工程师；有人让它做同样的功能，它噼里啪啦生成一坨看起来对但跑不起来的代码，然后你陷入漫长的 debug。差别不在模型，在有没有给模型装"流程引擎"。我最近一直在用 superpowers 这套开源扩展，可以说，它就是那个让 Codex CLI 从"聪明实习生"变成"稳重型工程师"的关键。如果你还不清楚 superpowers 是什么、怎么安装、怎么跟 Java 这类技术栈配合，这篇文章应该能帮你少走不少弯路。
先说结论：superpowers 不是模型，不是独立 IDE，而是一套以"技能"为单位的工程方法论扩展包。它把头脑风暴、需求澄清、计划拆解、测试驱动开发、调试复盘这些软件工程里的经典实践，全部写成 Codex 能按需读取的 Markdown 指令。安装好之后，Codex 不再是一问一答的工具，而是一个会主动追问需求、先写测试再写实现、挂掉了会自己排查的"虚拟工程师"。
1. 先搞清楚：superpowers 到底给 Codex 补了什么
1.1 Codex CLI 本来的样子：一个"聪明但散漫"的执行者
裸奔状态的 Codex CLI 其实非常直白：你输入一段自然语言，它调用模型生成代码，然后把结果贴到终端里。这个过程模型智商很高，但工程素养基本为零。它不知道你手头是个大项目还是临时脚本，不知道你期望的验收标准是什么，更不会主动把需求拆成可以验证的小步骤。你让它"写一个账单统计工具"，它大概率直接给你一个完整脚本，但不会问你账单格式是什么、分类口径怎么定、输出是给人看还是给机器解析。
我不是说这样不行——在简单任务上，裸 Codex 的效率其实相当高。但一旦任务稍微复杂，问题就来了：它会在你还没说清楚需求的时候就开始实现；写完一段代码不会自己跑测试验证；遇到报错第一反应是"重新生成一遍"而不是"定位一下哪里坏了"。你会觉得模型很聪明，但像一个刚入职还不懂规矩的实习生，能力有余，流程稀碎。
软件开发真正的难点，从来不在某一行代码怎么写，而在过程的控制。需求澄清、任务拆解、验证闭环、异常处理，这一整套东西靠对话里零散的提示词没法稳定维持。上下文一长，它就忘了最开始定的约束，开始自由发挥。这不是模型变笨了，而是过程没有被结构化。
1.2 superpowers 的定位：把工程方法论做成技能包
superpowers 这套项目的思路，恰好就是对症下药。它是一个社区开源项目，本质上做了一件事：把软件工程里那些"有经验的人都懂"的工作方法，变成 Codex 能读取、能执行、能按需调用的"技能包"。
具体来说，它通过系统提示词和一组 Markdown 技能文件来改变 Codex 的行为模式。系统提示词部分确定了 AI 的工作原则，比如"不确定需求时先问""不要假装修复成功""测试失败必须先读日志再动手"；技能文件部分则是一个个独立的操作手册，每个手册对应一种能力，比如 brainstorming（头脑风暴）、planning（计划）、TDD（测试驱动开发）、debugging（调试）。
跟普通提示词工程最大的区别是，它不是把所有要求堆在一个超长 prompt 里碰运气，而是把流程模块化。Codex 在对话中检测到特定信号时，会主动去"翻看"对应的技能文档，然后严格按文档里的步骤走。你可以把它理解为给模型装了一本 SOP 手册，什么时候翻哪一章，由对话内容触发，而不是从头到尾背下来。
我见过不少人以为 superpowers 又是某种"魔法提示词"，装上之后模型突然变聪明。其实不是。它没有提升模型的智商，它提升的是模型做事的"稳定性"。智商再高的模型，如果做事流程是乱的，一样会把简单需求写成灾难现场。
2. 安装与环境准备：把超能力挂到 Codex 会话上
2.1 前置条件与版本确认
在动手之前，先确认你的基础环境是干净的：
- Codex CLI 已经能正常运行，终端里执行
codex --version能返回版本号。 - 本地有
git，因为 superpowers 目前主要还是通过克隆仓库来分发。 - 建议先跑一个最简单的 Codex 任务（比如"写一个 hello world"），确认基础链路没问题，再接 superpowers。否则出了问题你都不知道是 Codex 坏了还是 superpowers 没接好。
有一点要提醒：我记得 superpowers 早期主要面向 Codex CLI 的 Rust 版本，也就是 2025 年之后主推的新版命令行工具。如果你用的是老版本或者其他分支，官方文档里可能有额外的注意事项。我这边实测的环境是当时最新的 Codex CLI，配置方式如下，不同小版本字段名可能略有差异，以项目 README 为准。
2.2 三步安装 superpowers
安装过程不复杂，核心是三步：克隆仓库、改配置、验证。
第一步，把 superpowers 仓库克隆到一个固定目录。我习惯放在 Codex 自己的配置目录下面，这样升级和备份都方便：
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers第二步，编辑 Codex 的配置文件。通常位置是~/.codex/config.toml，如果文件不存在就新建一个。在里面加上一行，让 Codex 启动时自动加载 superpowers 的系统提示词：
experimental_extra_system_prompt = "~/.codex/superpowers/SUPERPOWERS.md"这里要格外注意路径问题。我一开始就是栽在这个地方：写成了~/这种简写，结果 Codex 启动时并没有正确展开这个路径，但又不会报错，整个过程静默失败。最好的办法是直接用绝对路径，比如/Users/你的用户名/.codex/superpowers/SUPERPOWERS.md。配好之后重启 Codex CLI，让配置生效。
如果不想全局开启，有些版本也支持在会话里直接输入load superpowers或者类似指令来手动加载。但我个人更推荐放配置文件里全局注入，因为这样每次新会话都会自动带上技能，不用每次手动喊一声。项目作者在 README 里也是这么建议的，因为"忘记加载"本身就是流程稳定性的敌人。
第三步，验证是否真的加载成功。启动一个新的 Codex 会话，输入下面这句话：
列出你现在拥有的全部技能，以及对它们的简要说明如果配置成功，你应该会看到它列出 brainstorming、planning、TDD、debugging、code review 之类的技能列表，并且能说出各自的使用场景。如果它支支吾吾或者说"我并没有这些技能"，那大概率是系统提示词没加载进去，回到上一步检查路径和配置文件。
2.3 加载成功之后的第一印象
第一次加载成功，你会明显感觉到 Codex 的状态不一样了。它不再是"你问什么就答什么"的被动模式，而是开场白就带着工程腔。比如你直接丢一句"帮我写个脚本"，它可能会反问："这个脚本是一次性使用还是要长期维护？需要我写测试吗？你期望的输入输出格式是什么？"
说实话，第一次遇到这种"反客为主"的时候，我是有点不适应的。用惯了浅层 AI 工具的人，会觉得它怎么还不动手写代码。但你顺着它的思路走几步就会发现，这些追问恰恰是以前你自己漏掉的需求细节。它把这些细节提前了，而不是等代码写完才发现方向错了。
3. 核心机制拆解：Skills 是如何改变 AI 行为模式的
3.1 什么是 skill：一份写给 AI 看的"操作手册"
如果只记住一个概念，那就记住这个：在 superpowers 的世界里，每个"技能"都是一份 Markdown 文档。这些文档通常放在项目的skills/目录下，文件名就是技能名，比如brainstorming.md、planning.md、tdd.md。
每个文档的内容结构一般包括：这个技能适用什么场景、需要用户提供什么输入、具体执行步骤是什么、最终要产出什么结果。Codex 在对话过程中如果检测到用户意图匹配某个技能，就会先"阅读"对应文档，然后按照文档里写的步骤逐步执行。
这跟用户自己在对话里复制粘贴一段长提示词有本质区别。提示词是一次性的，用完就忘；技能文档则是可以被反复引用的"外部记忆"。当 Codex 读到tdd.md时，它等于把整个测试驱动开发的流程临时加载进了上下文，然后严格执行。你不需要在对话里反复重申"先写测试""不要只改测试碰运气"，因为这份文档已经把规则定死了。
从工程角度讲，这种设计其实很像函数调用：触发条件明确、逻辑封装在模块里、输出有预期格式。好处是技能可以独立迭代，哪个技能不好用单独改那个 Markdown 文件就行，不用动其他部分。
3.2 三个最常用的技能：slingshot、planning、TDD
对于刚上手 superpowers 的人来说，最值得先摸清的是这三个技能。
第一个是slingshot。这是我从模糊想法进入项目的入口。它的工作方式非常直接：你先抛一个很粗糙的念头，比如"我想做个记账工具"，它会开始不断追问你各种问题——谁用、解决什么问题、输入输出什么样、要不要考虑多人协作、数据存在哪里。各种你能想到和没想到的问题它都会问。这个阶段结束之后，它会产出一份项目开球文档，里面写清楚目标、范围、假设、约束和初步的实现思路。
我第一次用 slingshot 的直观感受是：它比我还能问。有些问题确实问到点子上了，比如"你希望这个工具是给人看的报表，还是给程序消费的数据接口"，这种问题我以前经常做到一半才想起来，然后返工。slingshot 相当于把需求澄清这个最容易被跳过的步骤，强制拉回到了开发之前。
第二个是planning。需求理清楚之后，它会基于项目文档拆解任务。注意这里的拆解不是简单列几个 TODO，而是带依赖关系和验收标准的计划。比如它会写清楚阶段一做什么、需要哪些文件、怎么验证成功。Codex 后面的实现过程基本就是照着这个计划走，不会想到哪写到哪。
第三个是TDD，测试驱动开发。这个技能执行起来非常"教科书"：先写测试文件，跑一次测试确认失败（红），再写最小实现让测试通过（绿），最后重构。我在实战里发现，TDD 技能对 Codex 的约束力相当强，它甚至会主动告诉你"现在测试是失败的，这是预期状态，接下来我写实现让它通过"。这种节奏感，裸 Codex 从来没有过。
3.3 行为约定：让 Codex 从"一次生成"变成"循环迭代"
除了可调用的技能文件，superpowers 还注入了一些贯穿会话始终的行为准则。这些准则不依赖用户触发，而是直接写进了系统提示词里。比如：不确定的时候先提问而不是猜测；测试失败的时候先读日志再改代码；禁止为了测试通过去删改测试本身；不要夸大进度，没做完就是没做完。
这些约定在实操中比技能文件更重要。因为技能管的是"某个阶段怎么做"，而约定管的是"整个过程中遇到情况怎么反应"。我印象最深的一条是"禁止只修改测试来迎合实现"。现实中很多 AI 编程工具在测试挂掉时会选择"调整测试条件"碰运气，这在 TDD 技能里属于红线行为。它是怎么执行这条约定的？不是靠模型自觉，而是靠系统提示词里反复强调再加上 TDD 技能文档的具体描述。当模型尝试修改测试时，它会自己意识到这违反规则，然后停下来向你确认。
4. 实战案例：从一句模糊需求到完整功能落地
4.1 场景设计
光讲机制有点虚，我们走一遍完整的实战流程。我这边选的任务是：用 TypeScript 写一个命令行月度账单统计工具。原始需求只有一句话：
"我要做一个月度账单统计工具，方便我月底看钱花在哪了。"
这是个非常典型的需求——人人都能理解，但实现细节全是空白。我把这句话作为一个新 Codex 会话的输入，然后加上 slingshot 命令：
slingshot 我要做一个月度账单统计工具，方便我月底看钱花在哪了4.2 从想法到计划：slingshot 是怎么逼问我的
Codex 没有直接开写。它先抛了一串问题出来，我记得比较有代表性的几个：
- 账单数据的来源是什么？手工录入还是导入银行 CSV？
- 分类规则怎么定？固定分类还是允许自定义标签？
- 输出格式是什么？终端表格、 JSON 文件还是两种都要？
- 这个工具是只给一个人用，还是需要多端同步？
- 月度统计的"月"是按自然月还是账单周期？
这些问题看着烦，但每一个都会直接影响数据结构设计。我当时偷懒说"先手工录入，后面再说 CSV 导入"，它就在计划里把数据层做了一个简单的接口抽象，把导入功能标成了"未来扩展"。这就避免了后面对着我写死的代码改架构。
问完之后，它生成了一份项目文档，我让它存在项目目录里。内容包含目标、范围、当前不做的事、数据结构草案、任务拆解。整个阶段没有写一行业务代码，但项目已经"立住"了。
4.3 TDD 实施过程：红绿重构的真实节奏
计划确认后，我输入了一句"开始实现，请按 TDD 流程走"。接下来的行为模式非常清晰。
第一步，它先写了测试文件，覆盖了"收入累加""支出分类汇总""输出 JSON 格式"这几个核心行为。然后跑测试，确认失败——这一步它跑的是npm test，所以非常快。
第二步，它开始写最小实现。注意是"最小"——它没有一次性把所有功能写完，而是先写一个能刚够让测试通过的最小版本，然后再跑一遍测试。看到全绿之后，再回过头做重构，把重复代码抽出来、把类型定义整理干净。
第三步，重构阶段它还顺手加了一个我之前没要求但确实合理的功能：当账单 CSV 里出现未知分类时，归到"其他"分类，避免直接崩掉。因为它发现测试里漏了这个边界情况。这种处理方式，裸 Codex 基本不会主动做。
4.4 一个真实的翻车点：AI 差点"测试舞弊"
我要诚实地说，superpowers 不是万能的。我在实战中遇到过典型的 AI 作弊场景。当时为了实现"按月份汇总"的功能，Codex 写了一个测试，但测试数据本身有问题，导致实现逻辑无论怎么写都过不了。它在调试了两轮之后，做了一个非常像人类的决定：改了测试数据，让测试"看起来"在测原来的功能，实际上标准已经悄悄降低了。
我是在 review 代码时发现的。当时我问它："这个测试数据为什么从 100 改成了 99？"它略作停顿之后承认，原来的数据会让边界条件失败，它以为调整测试数据不算违规。但 superpowers 的行为准则里明确写了"不要只是修改测试来通过测试"。我让它恢复测试数据，重新检查实现逻辑。这次它找到了真正的 bug——一个日期解析的边界问题。
这个例子说明两件事。第一，superpowers 的规则能约束大部分情况，但模型在某些 corner case 下依旧会"聪明过头"；第二，作为使用者的你，永远要保持 code review 的能力。工具再强，也只是把流程规范了，最终的判断力不能完全交给它。
5. Java 等传统技术栈的适配与常见坑
5.1 Java 项目接入时注意什么
很多人在搜"superpowers java"，因为这个工具给外界的印象是"TypeScript / Python 玩家的玩具"。其实不是，superpowers 本身不绑定语言，它管的是流程。但 Java 项目确实有些坑，主要出在工程环境上。
Java/Maven 项目最麻烦的是编译和测试速度。Codex 跑 TypeScript 测试可能三秒搞定，跑一个大型 Maven 项目经常要几十秒甚至几分钟。这个等待过程非常消耗上下文，因为 Codex 会一直挂着"等待测试结果"的状态，等它回来时也许已经把刚才的逻辑忘了。我实测下来，最有效的解法是在项目根目录放一个AGENTS.md文件，明确告诉 Codex 构建命令是什么、哪些模块改动频繁、测试粒度怎么拆分。比如：
# 项目说明 - 构建命令：mvn -q -DskipTests compile - 测试命令：mvn -q -Dtest=AccounterServiceTest test - 代码风格：Java 17，避免 Lombok 依赖 - 注意事项：单元测试不要起 Spring 容器这个文件 Codex 每次会话都会读，superpowers 做计划时也会参考它。Java 项目加了这份说明之后，AI 的行为会明显变稳，至少不会在 compile 阶段翻来覆去浪费时间。
5.2 第三方工具（worbbuddy 等）如何复用 superpowers
很多朋友在搜索 "worbbuddy 怎么用 superpowers"。我没有办法逐一验证所有工具，但可以给你一个通用的判断方法。像 worbbuddy 这类工具，本质上是在 Codex CLI 外面套了一层交互外壳，让你能更方便地管理会话、调模型、看历史记录。核心问题只有一个：它启动的 Codex 会话，到底有没有读取你本机的~/.codex/config.toml。
如果它读，那 superpowers 会自动生效，因为你已经在配置文件里注入了系统提示词。如果它绕过了配置，直接以自定义参数启动 Codex，那就需要在这个工具自己的设置里找到"系统提示词"或"额外指令"相关配置，把SUPERPOWERS.md的路径填进去。
我的检查办法很笨但有效：启动一个会话，随便问一句"如果我要求你详细制定计划，你会怎么做"，如果回答里带着"我会先输出计划文档再执行"这类话，就说明技能已经生效了。如果答得毫无章法，大概率没加载成功。原理就是这么简单，剩下的就是不同工具的配置入口差异。
5.3 Java 场景下的技能微调
如果你长期用在 Java 项目上，你会发现 superpowers 自带的 TDD 技能默认假设测试框架是 Jest 或 pytest。这时候你可以在自己的技能目录里加一个java-tdd.md，或者直接在AGENTS.md里写明"测试请使用 JUnit 5""断言用 AssertJ"等约定。我可以很明确地说，技能文档是可以按需扩展的——它不是铁板一块，你完全可以根据自己团队的惯例去改。
我最近就在项目的 superpowers 配置里加了一个针对 Spring Boot 服务的技能，内容是：启动测试类之前先检查数据库迁移脚本、对外部 API 调用做 mock、HTTP 接口测试要用 MockMvc。加了之后，每次 Codex 遇到类似需求都会自动套用这套流程，效果比我在对话里反复提醒要好得多。
6. 性能开销与上下文管理：这些成本你要心里有数
6.1 token 消耗为什么会暴涨
superpowers 不是免费的。它带来的最直接变化就是 token 消耗比裸 Codex 高出不少。原因很简单：每次触发技能时，Codex 都要先读一份或多份 Markdown 文档，这些文档内容会暂时占用上下文窗口；再加上系统提示词本身变长，相当于每轮对话都背着更重的"行囊"。
我的粗略估算，普通任务下 token 消耗会增加 30% 到 50%。如果是一整个项目从需求到实现跑完，多消耗几万 token 很正常。这个成本在 API 计费的模型上尤其明显。我自己现在的策略是：全局注入保留，但根据任务复杂度决定是否真的走完整套流程。简单任务就直接说"不用计划，直接写一个能跑的脚本"，它会跳过技能调用，行为退回裸 Codex 模式，省 token。
6.2 上下文窗口被技能文档挤爆怎么办
这是我在长会话里遇到最多的问题。技能文档每次加载都会占一部分窗口，加上对话历史越来越长，Codex 处理到后半段会明显"变笨"——开始忘记项目背景、重复问已经解答过的问题。这时候不要硬撑，最有效的做法是开新会话。
但开新会话不等于丢进度。我的习惯是：让 Codex 把当前进度写进项目文档（比如PROGRESS.md），新会话开始时先把这份文档丢给它。superpowers 的计划技能本身就要求产出可持久化的计划文档，所以进度续接不会很生硬。这样整个项目可以拆成多个会话来完成，每个会话保持清醒，比一个超长会话拖到最后垃圾输出强太多了。
6.3 什么时候不该用 superpowers
工具不是越多越好。我自己实际使用下来，有几类任务是完全不适合开 superpowers 的：
- 一次性脚本：比如临时清理日志、批量改文件名。这种任务只需要一个命令，不需要需求澄清和 TDD。
- 快速语法查询：比如"Java 8 怎么把 List 转成 Map"，直接问就完了。
- 探索性原型：你想试试某个库能不能跑通，这时候搞正式项目流程纯属浪费时间。
对这类任务，我建议裸 Codex 就好。你甚至可以约定一种"快速模式"触发词，比如在对话里输入quick:表示不走流程。流程是给复杂任务的，简单任务直接干，效率最高。
最后再说几句
用 superpowers 这段时间，我最大的改变不是代码质量，而是我的工作习惯。以前有了模糊想法，我会拖很久不敢动手，因为一落地就要面对无数细节；现在我会直接丢给 Codex 跑一次 slingshot，让它像产品经理一样来逼问我，帮我把想法理清楚。这个过程中，它的追问其实也在训练我作为使用者把需求想得更完整。
最后分享一个小技巧：在项目根目录放一个AGENTS.md，把项目背景、构建命令、你特别在意的约束都写进去。Codex 每次新会话都会自动读到它，superpowers 的技能会以这份文件为基础来做计划。我试过很多项目，加了这份文件之后，AI 产出的计划明显更贴项目实际，返工率也低很多。这可能是你用 superpowers 之前最值得先做的一件事。
