先说结论：如果你已经在用 Codex CLI 这类 AI 编程助手，但总觉得它“时而聪明、时而智障”，大多数问题出在你没有给它一套稳定的工作方法。superpowers 这个开源工具，做的事情就是把这套“让 AI 稳定变强”的方法论，封装成可以直接加载的指令集。我没用太久，但已经明显感觉到交付质量上了一个台阶。这篇文章我会从它的核心设计思路、安装配置、Java 项目实战，到常见坑位梳理，完整过一遍。
1. 它到底是什么：解决 AI 编程的信任危机
1.1 先理解问题的根源
用过 Codex CLI 的人都有体会：它本身的能力底子很强，但输出质量非常不稳定。同一个需求，有时候它给出干净利落的实现，有时候却答非所问、思路混乱、甚至写出逻辑不通的代码。问题不在模型，而在缺少一个东西——稳定的工作框架。这就好比一个技术很强的工程师，如果没人告诉他项目规范、验收标准、协作流程，他发挥好坏全看当天状态。
superpowers 要解决的，就是这个“发挥不稳定”的问题。它不是模型，不是插件，也不是 IDE 扩展，而是一套基于 AGENTS.md 的指令增强体系。它通过加载大量精心编写的技能指令（skills），为 Codex CLI 注入一套“如何思考、如何拆解、如何写代码、如何验证”的完整方法论。简单说，它给 AI 配了一套 SOP（标准作业程序）。
1.2 核心工作机制是“自动装载”
这套系统最有意思的地方在于：它知道什么时候该用哪套方法。当你启动 Codex CLI 并授权读取 superpowers 目录之后，它会扫描你当前项目的结构，自动判断项目类型，然后装载对应的技能集合。比如识别到pom.xml或build.gradle，就加载 Java 项目专属技能；识别到package.json和特定目录结构，就加载前端技能。
这种“看菜下饭”的设计，精准地解决了 AI 编程中最常见的问题——用错方法论。在 Java 项目里，它知道先检查 Maven/Gradle 配置，再按 TDD 节奏写测试；在 Python 项目里，它知道先考虑虚拟环境和依赖管理。而不像裸 Codex CLI 那样，用一套通用逻辑去硬套所有场景。我之前在一个 Java 多模块项目里试过裸写，它经常搞混模块依赖关系，但有了 superpowers 之后，它会先读模块结构再动手。
1.3 为什么它叫“superpowers”
这个名字很直白——它就是要给 AI 编程助手“加超能力”。作者 Jesse Vincent（Obra）是资深 Perl 开发者出身，他对“工具思维”的理解非常深。他做了一个关键判断：当前 AI 编程的上限不是模型能力，而是使用方式。于是他把大量专业开发者的思维模式——比如先写测试再写实现、先做架构设计再写代码、先复现 Bug 再修复——全部转化成了 Codex CLI 能读取的指令文件。
这些指令文件不是简单的“提示词”，而是一套带有明确规则、判断流程、输出格式的技术规范。比如“拆分任务”这个动作，系统不会只是告诉 AI“你要拆分任务”，而是规定：必须输出一个包含 ID 的列表、每项必须有验收标准、完成后必须逐项勾选。这种约束力，才是质量稳定性的来源。读完它的源码和说明，最大的感受是：这背后是一个经验丰富的老工程师，在把他几十年的工程习惯数字化。
2. 环境准备与安装：把“超能力”装进 Codex CLI
2.1 前置条件清单
动手安装之前，先把基础环境确认好。用了一段时间之后，我的体会是：90% 的安装问题都出在前置条件没满足，而不是 superpowers 本身装不上。
| 依赖项 | 版本要求 | 说明 |
|---|---|---|
| Codex CLI | 最新版（0.2.0+） | 目前 superpowers 主要面向 Codex CLI 场景，旧版可能不兼容 |
| Git | 2.x 以上 | 克隆仓库和后续更新都需要 |
| 操作系统 | macOS / Linux / WSL2 | Windows 原生环境可能存在路径兼容问题 |
| 磁盘空间 | 200MB 以上 | 主要是技能文件和日志占用，其实不大 |
另外需要提醒：新版的 Codex CLI 支持配置文件形式的 AGENTS.md 引用，如果你的版本已经支持~/.codex/下的全局配置，那体验会顺畅很多。我最初用旧版走了不少弯路，大家直接装最新版就好。
2.2 安装与初始化全流程
整个安装过程不复杂，核心就两步：克隆开源仓、配置 AGENTS.md。具体操作如下。
# 1. 克隆项目仓库到本地 git clone https://github.com/obra/superpowers.git # 2. 进入项目目录，查看结构 cd superpowers ls -la # 你会看到 skills/ 目录，里面就是全部的技能指令 # 3. 把 skills 目录路径记下来，后面配置要用 # 比如：/Users/你的用户名/superpowers/skills pwd然后需要编辑或创建全局 AGENTS.md 文件。Codex CLI 会读取这个文件来决定加载哪些指令。如果你还没有这个文件，手动创建一个：
# 创建 .codex 目录（如果不存在） mkdir -p ~/.codex # 编辑 AGENTS.md（注意：不同版本路径可能不同，以你的 Codex CLI 实际配置为准） vim ~/.codex/AGENTS.md在文件里写入关键内容，目的是告诉 Codex CLI 到哪里找 superpowers 技能，以及启动时先读哪个入口文件：
# 加载 superpowers 技能库 读取 /你的绝对路径/superpowers/skills/ 下的所有技能定义 # 每次启动任务时，优先阅读 /你的绝对路径/superpowers/AGENTS.md这里有个很重要的细节：一定要用绝对路径，否则 Codex CLI 在不同工作目录下启动时会找不到技能文件。我第一次就是用了相对路径，结果换个目录就失灵了，排查了好一会儿。
2.3 验证安装是否成功
配置完之后，别急着开始写业务代码，先做一个快速验证。随便进入一个临时目录，启动 Codex CLI，然后输入一个简单的探测指令：
请列出你当前加载了哪些技能，以及它们的核心用途。如果安装成功，你会看到它输出的列表里有 TDD、Boss、Task、Git 工作流等相关技能名，并且能简要说明各自用途。如果它回答“没有加载任何特殊技能”或者“不清楚”，说明 AGENTS.md 路径配置有问题，回到上一步检查。
还有一个更实用的验证方法——让它完成一个带测试的小任务。比如在空目录里输入：“用 Python 写一个计算器 add 函数，先写测试再写实现”。如果看到它先创建 test 文件、再写实现、最后运行测试，说明 TDD 技能已经生效了。这个反馈是很直观的：它不再直接甩代码给你，而是严格按“测试先行”的节奏来。
注意：superpowers 的技能指令是剪不断理还乱的嵌套体系，主技能会调用子技能，子技能之间还有协作。第一次加载时 Codex CLI 可能需要多轮读取文件，稍等片刻再继续对话，不要急着打断它。
3. 核心技能拆解：Java 项目实战里怎么用
3.1 技能体系全景一览
superpowers 的技能体系，本质上是一个“方法论树”——从抽象的思维流程，到具体的语言操作，层层嵌套。用 Java 项目来举例，装完 superpowers 后最常用的核心技能大致有这几类。
| 技能名称 | 核心作用 | 适用场景 |
|---|---|---|
| TDD（测试驱动开发） | 先写失败测试，再写最小实现，最后重构 | 新增功能、修 Bug、接口开发 |
| Boss | 生成技术规格说明书，定义“做什么、为什么、怎么验收” | 新项目启动、大功能规划 |
| Task | 把大需求拆成可执行的小任务，每个任务有明确 ID | 复杂功能落地、多步骤改造 |
| Git 工作流 | 规范提交信息、自动做代码审查、合并前检查 | 日常开发、代码审查 |
| 调试与 Bug 修复 | 先复现问题、定位根因，再动手修复 | Bug 修复、线上问题排查 |
这套体系的设计灵魂在于“每一步都有输入和输出”。比如 Boss 模式生成的规格文档，就是 Task 模式的输入；Task 模式拆出的子任务，又是 TDD 模式的输入。环环相扣，每个环节的输出都服务于下一个环节，这种流水线式的设计，比单纯把需求丢给 AI 让它“自由发挥”要可靠得多。
3.2 TDD 技能：从“写代码”到“写行为”
我在一个 Spring Boot 项目中实测了 TDD 技能的效果，被它的严谨程度惊到了。以前的流程是：我描述需求，Codex CLI 直接生成一堆代码文件，然后我自己去跑测试看结果，经常返工。但加载 TDD 技能后，它的工作顺序变成了这样：
- 先读当前项目结构，识别出 Maven 工程、确认 Spring Boot 版本。
- 询问关键业务规则，把需求转化为测试用例。
- 编写测试代码（此时实现还不存在，测试会失败）。
- 运行测试，确认失败原因符合预期。
- 写最小实现代码，让测试通过。
- 运行全量测试，确认没有破坏其他功能。
以用户注册接口为例，它不会上来就写UserController和UserService，而是先写UserRegistrationTest，覆盖用户名为空、邮箱格式错误、重复注册等场景。测试全部失败后，才开始写实现。这逼着它先把需求理解透，再动手。实际效果也很明显：生成的代码几乎不用改就能跑通。
这里有一个挺反直觉的点：TDD 技能让 AI“多干活”了，反而交付更快了。原因在于它把返工成本前置了——与其写完一大坨代码再调试，不如先用测试定义清楚行为，实现过程就是“让测试变绿”，方向感强得多。
3.3 Boss 模式：大功能规划的正确打开方式
如果你想做一个稍微复杂的功能——比如“订单超时自动取消 + 退款”这种涉及定时任务、状态机、支付回调的功能，直接丢给 Codex CLI 写代码，大概率会漏掉边界情况。这时候需要启动 Boss 模式：它扮演“技术负责人”，先帮你把需求理清楚，输出一份技术规格说明书。
触发方式通常很直接，在对话里输入类似“使用 boss 模式规划这个功能”的指令，它会进入规划流程。它会问你一系列问题：业务规则是什么、超时时间多长、退款失败怎么处理、需要记录哪些日志。答完之后，它会生成一份结构化的规格文档，包含功能目标、技术选型、模块划分、验收标准。
这份文档的价值很大，因为我发现它生成的文档不是模板套话，而是基于当前项目实际情况的分析。比如它看到你项目里已有@Scheduled的用法，会自动沿用这个方案而不是建议引入新的框架。这种“基于上下文做决策”的能力，极大减少了方案落地的摩擦力。
拿到规格文档之后，你可以让它用 Task 模式拆任务。每个任务都有明确的 ID、输入、输出和验收标准。比如：
- TSK-001：定义订单状态枚举和超时字段
- TSK-002：实现超时扫描任务
- TSK-003：实现退款调用与失败重试机制
- TSK-004：补全集成测试
这份任务清单就是后续开发的“导航地图”，Codex CLI 每完成一项会勾选一项，你再也不怕它写着写着跑偏了。
3.4 Java 项目中的技能协同实战
Java 项目，特别是 Spring Boot 多模块工程，对 AI 来说是一个容易出错的场景。模块依赖、Bean 注入、配置项管理，任何一步乱了，编译就过不了。一个完整的项目交付流程应该是这样的：
跟着 Codex CLI 一步步走，你会发现它的行为模式完全不同。先让 Boss 模式产出设计文档，再让 Task 模式拆解任务，锁定 TDD 循环，用 Maven 逐步验证，最后走 Git 流程提交。这套流程下来，Codex CLI 更像一个“有经验的中级开发者在帮你打下手”，而不是一个“偶尔聪明偶尔迷糊的代码生成器”。
| 阶段 | 使用技能 | 关键产出 | 质量验证方式 |
|---|---|---|---|
| 需求分析 | Boss | 技术规格说明书 | 人工评审需求覆盖度 |
| 任务拆分 | Task | 带 ID 的任务清单 | 检查每个任务有验收标准 |
| 编码实现 | TDD | 测试 + 实现代码 | mvn test 全绿 |
| 质量保障 | Code Review | 审查意见与修改记录 | 人工确认无逻辑漏洞 |
| 提交合并 | Git Workflow | 规范提交记录 | 确认提交粒度合理 |
实际用下来的感受是，这五个阶段里 TDD 和 Task 的收益最明显，因为它们直接改变了 AI 的输出行为。Boss 模式更像是一位“设计师”，而 TDD 和 Task 是与之配套的“施工规范”。想在一个 Java 项目里完整体验这套流程，最推荐的方式是：拿一个你已经做完的老需求，重新用 superpowers 流程走一遍。对比两版实现的差异，你很容易发现自己原来的提示词缺了什么。
4. 常见问题与排查技巧实录
4.1 技能文件加载失败的三大原因
过程中最常遇到的，就是 Codex CLI 回答“我没有加载任何特殊技能”。排查思路基本围绕三个方向：路径、权限、版本。
路径问题是第一嫌疑。AGENTS.md 里写的路径多一个字符、少一个斜杠，都会导致加载失败。我建议大家把路径简化，直接放在用户目录下，然后测试所有目录都能读到。其次是权限问题，skills/目录和文件需要有可读权限，在 Linux 下尤其明显，跑一下chmod -R +r ~/superpowers解决。最后是版本问题，如果 Codex CLI 太老，可能不识别新型的 AGENTS.md 格式，升级到最新版本基本能解决。
4.2 TDD 流程被跳过的对症处理
有些时候，TDD 技能虽然加载了，但 Codex CLI 还是直接给你一大段实现代码，完全没有测试先行的过程。这通常不是技能没生效，而是它误判了当前任务场景。比如一个紧急 Bug 修复任务，它认为搞测试是浪费时间，就直接进入修复模式了。
如果你明确希望它严格执行 TDD，有一个很有效的纠正话术：“请严格遵循测试驱动开发流程，不要跳过测试编写环节。这个需求属于新增功能变更，必须先编写失败测试。”我的经验是，把“场景标注”说清楚，比单纯命令它更有效，因为它需要判断“什么场景用哪套规则”。
4.3 跨语言项目切换时的“技能串味”
如果你同时维护 Java 和前端项目，可能会遇见一个有意思的情况：在 Java 项目里，Codex CLI 突然使用 Python 项目里那套依赖管理思路。这本质上是技能装载时没有正确识别项目类型。
解决方法是，在项目根目录下放一个简单的.ai-config.md文件，里面写清楚项目技术栈。比如：
# 项目类型 Java / Spring Boot 多模块 Maven 工程 # 构建命令 mvn clean install # 测试命令 mvn test这相当于手动帮 AI 校正“坐标系”，比让它自己识别项目结构可靠得多。我在两个多语言项目上加了这份配置之后，“串味”问题基本消失了。
4.4 一份实用的避坑清单
| 坑点 | 表现 | 解决方案 |
|---|---|---|
| AGENTS.md 用了相对路径 | 换目录后技能丢失 | 全部改成绝对路径 |
| 技能文件只读权限不足 | 加载但不可用 | chmod -R +r修复 |
| 任务描述太模糊 | 技能不知该套哪套流程 | 明确说清“这是新功能还是修复 Bug” |
| 中途打断生成过程 | 指令树不完整 | 让它重新阅读入口文件 |
| 多项目并行开发 | 不同项目配置串了 | 项目根目录放.ai-config.md |
| 让 AI 自己选测试框架 | 生成的测试风格漂移 | 在技能规则里固定 JUnit 或 TestNG |
4.5 最好的调试方法：开新会话
最后分享一个经验，跟 superpowers 本身的机制无关，但非常影响实际体验——遇到诡异问题别在一个会话里死磕，直接开新会话。AI 编程助手的长对话有一个隐含问题：早期的错误理解会顺着上下文一路传播，后面怎么纠正都费劲。superpowers 这套技能体系，本身已经大幅减少这个问题，但如果你发现 AI 的行为越来越偏离预期，赶紧开新会话，让它重新加载技能库。这个简单的操作，能避免大量无效沟通。
另一个小技巧：在重要操作前，加一句“请先阅读本项目的 AGENTS.md 和相关技能定义”，强制刷新它的“工作记忆”。几次经验告诉我，这句提示经常能救回一次即将跑偏的任务。这也是我用了 superpowers 之后慢慢摸索出来的习惯——与其事后救火，不如事前把“工作规范”再强调一遍。
