我刚把superpowers这个配置方案完整跑通了一遍，从安装到实际写 Java 项目，前后折腾了几个晚上。这玩意儿不是个独立软件，准确说是给 AI 编程助手（尤其是 Codex CLI）用的一套会话管理规则和提示词集合，让 AI 从"一次性问答机器人"变成"能拆解任务、分步实施、自己测试、自己提交代码"的流线型开发搭档。如果你用 Codex 或者类似 CLI 工具时总感觉答非所问、改代码东一榔头西一棒子，那这个方案值得花半小时配置一次。
先说结论：superpowers的核心价值有四个，一是把开发过程拆成"理解需求 → 制定计划 → 逐步实现 → 自检并提交"四个阶段；二是用结构化的 AGENTS.md 文件约束 AI 的行为边界；三是引入"命令回环"机制，让模型在关键节点主动调用内置脚本确认上下文；四是为 Java 等重类型项目提供专门的类型安全检查和测试循环增强。下面我把整套东西拆开讲清楚。
1. 项目整体设计与核心思路拆解
1.1 为什么会出现superpowers这类方案
用过 ChatGPT 类工具写代码的人都体会过那种"割裂感"：你让它改一个方法，它改完这处，却忘了另一处依赖它的地方；你让它加个功能，它一次性给你生成 300 行代码，里面有一半东西根本不是你想要的；你说"测试一下"，它就真只跑一次编译，报错了就甩给你一个日志让你自己查。问题的根源不在于模型能力，而在于调用方式——我们把它当成"问答工具"用，而不是"结对同事"用。superpowers就是从这个痛点切入：它不给模型增加新能力，而是给它一套"工作流程规范"。
这套方案的设计思路很像带实习生：安排任务前先讲清楚目标、清晰定义"完成"的标准，要求实习生先说打算怎么做再动手，做完一步检查一步，而不是一股脑儿交付完就等着你审。superpowers通过一套精心设计的提示词文件，把 AI 的行为从"回答问题"切换到"执行开发任务并实时汇报"。
1.2 与 Codex CLI 的关系和运行机制
superpowers最常见的使用场景是作为 OpenCode 或 Codex CLI 的会话配置。所谓"配置"，本质上就是几个 Markdown 文件——一个全局的AGENTS.md，一个放在项目根目录的项目级AGENTS.md，还有藏在.superpowers目录下的一组"技能包"提示词文件。它的运行机制说起来很朴素：启动 CLI 时会自动加载这些文件作为系统提示词的一部分，AI 的思考过程就被这些规范约束住了。
我画个类比你立刻明白：普通模式下的 AI 编程助手像一个知识渊博但手忙脚乱的助手，你问什么他答什么；加载了superpowers之后，它变成了一个"一板一眼的老工程师"——先背一遍流程，然后每一步都对照检查表执行。这个"检查表"就是.superpowers目录下的session-flow.md、command-loop.md这类文件。文件里全是自然语言指令，所以理论上任何支持自定义 system prompt 的 CLI 工具都能用这套东西。
1.3 它解决的典型问题清单
我自己用下来，下面四个问题是感受最明显的：
- 上下文丢失：AI 改了 A 文件就忘了 B 文件的耦合逻辑，
superpowers的"上下文刷新"机制会强制模型在关键节点重新读取源文件和摘要文件。 - 操作无规划：拿到需求就开写，写到一半发现路径走错了。方案里的 PLANNING 模式强制 AI 先输出实施计划，你确认后才动手。
- 测试与开发脱节：普通模式下 AI 经常"你说测试它才测"，这套方案把 TDD 循环内置进工作流，写完功能自动跑测试、根据失败信息回退修正。
- 提交信息混乱：AI 替你做 git commit 时信息写得像天书，这套方案里的 COMMIT 模式会按 convention 规范生成结构化提交信息。
2. 安装步骤与前置环境准备
2.1 你需要准备哪些基础环境
装了superpowers之后才发现，它本质上是个"体力活"，不需要编译、不需要装额外服务，但有几个前置条件缺一不可：
- Node.js 18+：Codex CLI 以及其他主流 AI 编程助手基本都是 Node 生态，装好之后
node -v确认版本。 - Git：提交功能依赖 Git 工作区状态判断，而且这方案里有些命令脚本要读取
git diff来决定下一步动作。 - Codex CLI 或兼容工具：目前跑通的是 OpenAI Codex CLI 的 0.2x 以上版本，老版本对 AGENTS.md 的加载机制支持不完整，建议直接装最新版。
- 一个实际的项目目录：别在空目录里试，找个有真实代码的仓库，最好是 Java/Spring 项目，因为后面的示例好展开。
装 Codex CLI 本身很简单：
npm install -g @openai/codex装完执行codex --version看版本号，同时跑一下codex login完成账号授权。如果你用的是 GitHub Copilot 的命令行版本或者别的 CLI 助手，原理也通，就是文件加载路径会略有差异，后面我会提。
2.2 克隆项目与初始化配置
superpowers是从 GitHub 上克隆下来的一组提示词模板，实际操作是把它复制到你的用户配置目录下：
git clone https://github.com/obra/superpowers.git ~/.superpowers克隆完之后建议看一眼目录结构，里面大概有这些内容：
~/.superpowers/ ├── AGENTS.md ├── skills/ │ ├── bootstrapping.md │ ├── planning.md │ ├── implementation.md │ ├── pre-commit.md │ └── ... └── scripts/ ├── context-summary.mjs ├── detect-test-framework.mjs └── ...初始化最关键的步骤是在项目根目录创建AGENTS.md，写上强制加载规则：
# AGENTS.md ## 项目行为约定 1. 开始任何编码任务前，先读取当前会话状态说明（如果有）。 2. 优先遵循 `.superpowers` 目录下的流程文件。 3. 每个功能实现必须伴随可运行测试。然后把项目模板里自带的AGENTS.md复制到你的项目根目录，它会引用~/.superpowers下的系统级规则。实际配置过程我录一个典型的：
# 把项目的 AGENTS.md 模板拷贝到当前目录 cp ~/.superpowers/AGENTS.md ./AGENTS.md # 创建技能目录，用于扩展项目级提示词 mkdir -p .superpowers提示：
AGENTS.md是 AI 编程助手的"公约文件"，不同工具读取优先级略有差异，但绝大多数都认。这个文件里写的每条规则都会被模型当作强约束来执行，别拿它当备忘录乱写。
2.3 常见安装坑位
我在装的过程中踩过几个坑，提醒你避一下。
第一个坑是克隆位置不对。一开始我把仓库克隆到了项目目录内，结果 Codex CLI 扫描项目文件时把这个仓库的一堆提示词也当成代码上下文送给了模型，既浪费 token 又干扰判断。正确的做法是放用户主目录的隐藏文件夹里，项目目录里只放一个引用它的AGENTS.md。
第二个坑是Codex CLI 版本太老。踩过之后我才注意官方更新日志，0.2x 以下版本根本不认识项目根目录的AGENTS.md，那整个方案就失效了。装完务必执行codex --version，旧版本用npm update -g @openai/codex升级。
第三个坑是忘记配置 Node 路径。有些脚本（比如context-summary.mjs）需要通过node命令调用，如果你的 Node 安装在非标准路径，CLI 的 PATH 里找不到，这些辅助功能就会静默失效。建议安装后先跑一下node ~/.superpowers/scripts/context-summary.mjs确认能正常输出。
3. 核心技能拆解与会话流程实操
3.1 四种核心模式的工作原理
superpowers把我使用 AI 编程的方式彻底重构成了四种模式，这套分类是它最值钱的地方：
| 模式 | 触发时机 | 模型行为 | 人需要做的事 |
|---|---|---|---|
| BOOTSTRAPPING | 每次会话开始时 | 读取项目结构、README、测试文件，生成上下文摘要 | 确认摘要是否准确 |
| PLANNING | 接到任务后、写代码前 | 输出分步实施计划，标注涉及文件和潜在风险 | 挑选或修改计划 |
| IMPLEMENTATION | 计划确认后 | 逐个实现小步骤，每步跑测试 | 观察输出、中途纠偏 |
| COMMIT | 功能完成、测试通过后 | 生成规范提交信息，执行 git commit | 审查提交内容 |
这四种模式不是分散的，而是串成一条固定流水线。会话里你只需要说"用 superpowers 做某某功能"，模型就会自动从 BOOTSTRAPPING 开始走流程。它的设计精妙之处在于，每种模式的切换不是靠人反复提醒，而是靠会话底部的"当前模式"状态标签——AI 每完成一个阶段节点，会主动宣布进入下一个模式。
3.2 以 Java 项目为例走完整流程
下面这节我拿一个真实需求讲，比如"给 Spring Boot 项目增加用户注册接口并附带单元测试"。按传统方式，你可能会直接抛给 AI 一句"帮我加个注册接口"，它甩给你几十行代码完事儿。用superpowers就会完全不同。
第一步，会话输入：
使用 superpowers 流程：给用户模块添加注册接口，要求用户名唯一、密码加密存储、返回标准化 JSON，并提供 Service 层单元测试。模型会先读取AGENTS.md，再走 BOOTSTRAPPING 模式，大概会输出这样一段摘要：
已读取项目上下文： - Spring Boot 3.2.4，Java 17 - 包结构：com.example.demo - 已有 UserController（仅查询接口） - 测试依赖已包含 JUnit5 和 H2 - 未发现 UserService 实现摘要确认无误后，模型主动切换到 PLANNING 模式：
实施计划： 1. 创建 UserRecord（DTO）封装请求参数 2. 创建 UserService 及实现类，注入 PasswordEncoder 3. 新增 register 接口，处理用户名重复异常 4. 编写 UserServiceTest，覆盖成功和冲突两个分支 5. 开启 H2 内存数据库验证 Repository 读写 6. 运行 mvn test 风险：需确保表结构自动初始化，如没有建表脚本需要新增 schema.sql你这时有三个选择：直接说"开始"，或者修改步骤，或者问清楚某个细节。确认后模型进入 IMPLEMENTATION，但不再是闷头写一堆文件，而是一个小步一个测试地推进。每完成一个步骤，它会汇报文件变更和测试结果，像这样：
已完成 UserRecord 创建，UserService 接口已定义，PasswordEncoder 已注入。 mvn test 当前输出：3 个测试通过，2 个测试待补。 下一步：实现 register 方法中的异常处理分支。全部跑完测试变绿，模型主动询问是否进入 COMMIT 模式。你确认后它给出提交信息建议：
feat(user): 新增用户注册接口 - 新增 UserRecord DTO 结构定义 - 实现 UserService 注册逻辑与唯一性校验 - 注入 BCryptPasswordEncoder 处理密码 - 补齐 Service 层单元测试这套流程走完，你会感觉 AI 不再是"工具"，更像是"干活有套路的老手"。
3.3 命令回环机制（Command Loop）
superpowers里最容易被忽略但实际很精妙的是它的命令回环机制。在流程文件中定义了一些内置命令，比如/context刷新上下文摘要、/test运行当前模块测试、/summary查看会话进度、/commit生成提交信息。命令不是摆设，模型会在特定阶段主动调用，背后是一系列 Node 脚本执行真实操作。
举个例子，模型在实现过程中判断自己"可能遗漏了关联模块"，它会输入：
[调用命令 /context]这个命令实际执行的是scripts/context-summary.mjs，脚本会扫描项目目录、重新生成一份CONTEXT.md摘要文件，然后模型读一遍这个文件来刷新自己对项目的理解。这招对"干着干着忘记全局结构"的病特别有效，尤其是大型 Java 项目动辄几十个类，token 窗口有限，模型到后期很容易捡了芝麻丢西瓜。
在 Java 项目里，文件多、依赖关系复杂，上下文膨胀问题尤其严重。我建议在AGENTS.md里主动启用这个机制，加一行：
在修改超过 5 个文件前，必须执行 /context 刷新摘要。这样能强制模型停下来检查全局状态，有效减少"改了半天发现方向错了"的窘境。
3.4 会话状态摘要的可视化与持久化
还有一个细节值得一说：superpowers会在项目目录生成一个SESSION.md，记录当前会话的阶段、已完成事项、下一步计划。这玩意儿看着简单，实际帮了大忙。比如你中途去开会，回来后 Codex CLI 的对话历史还在，但模型已经"忘了"刚才的思路；这时你只需要在会话里说"继续"，模型读到SESSION.md里的"已完成与未完成列表"，就能快速恢复状态，不需要你从头解释需求。
我强烈建议你养成的习惯是：每次让 AI 做稍微大一点的功能（改动超过 3 个文件），都要求它先更新SESSION.md再继续下一步。这不只是对 AI 有用，几天后再看这个文件，你也清楚当时项目推进到哪了。
4. 常见问题排查与避坑技巧
4.1 四个高频问题速查表
用这类方案难免碰到奇奇怪怪的现象，我整理了一个速查表：
| 现象 | 原因 | 解决方案 |
|---|---|---|
| 模型总是不走流程，直接甩代码 | 没有加载AGENTS.md，或加载被其他优先级更高的规则覆盖 | 检查codex --version；确认项目根目录AGENTS.md内容正确 |
| 会话做到一半说"上下文不足" | token 窗口撑爆，摘要文件没及时生成 | 手动执行/context，并减小提交消息历史长度 |
| 测试跑半天但全是编译错误 | Java 项目颗粒度大，模型一次性改了太多文件 | 在计划阶段打散步骤，强制每步只改 1-2 个文件且必须通过编译 |
| git commit 时提交流程中断 | 本地有冲突或暂存区有旧内容 | 检查git status，清空暂存区后重试 |
4.2 排查实录一：模型"失忆"问题
我在一次实现用户权限模块时，AI 写到中间突然开始改不相关的配置类，明显是忘了之前定的架构约束。当时SESSION.md里已经写明了"使用注解鉴权，不要动全局拦截器"，但模型就是跑偏了。排查后发现问题出在会话历史太长，早期约束被挤出上下文窗口了。解决办法是：
执行 /context，重新加载最新摘要，并明确提示：阅读 SESSION.md 中的约束章节。之后模型就回到正轨了。这个坑给我一个经验：凡是涉及项目架构的强约束，不仅要写在计划里，还要同步写进AGENTS.md项目规范里。这样就算模型忘了会话历史，每次新读项目文件时还能看到。
4.3 排查实录二：Java 项目的"回退陷阱"
Java 项目跑测试耗时高，模型实现完新功能跑测试报错时，经常会出现"回退式瞎改"——为了修一个错误开始动不相干的代码。比如我给 Service 层加方法时，测试报了个 H2 数据源初始化错误，模型没去查配置，反而去改实体类的字段命名，导致连锁编译错误。后来我在AGENTS.md里加了一条规则：
遇到测试失败时，先输出失败原因分析，再提出最小改动方案，禁止修改与失败无直接关联的文件。这个规则加上之后效果立竿见影。这类问题的本质是 AI 的"试错策略"和大工程的要求不匹配，通过规则把它纠正成"先分析、后最小化修改"是合理的解决方案。
4.4 独家避坑技巧
再分享几个不试根本不知道的小细节。
第一，注意.gitignore配置。SESSION.md和CONTEXT.md会随着会话更新，它们的变更频繁，很容易污染 commit 历史。我建议把这两个文件加进.gitignore，因为它们本质上是运行时产物，不需要入库。别让 AI 在 commit 时把这些摘要文件也提交进去。
第二，给 Java 项目单独建一个.superpowers/java-rules.md，里面写死类型安全和测试相关的要求。Java 是目前超级技能方案里优化最重的语言之一，很多提示词是为 Java 特性量身定做的，比如强制使用Optional禁止裸返回 null、Service 层必须接口与实现分离这种"约定俗成"的规则，你明确写进去模型就一定会遵守。
第三，控制每次会话的任务粒度。superpowers的设计假设是"一次会话解决一个完整功能"，如果你把"实现注册接口 + 完善用户列表 + 权限系统改造 + 修复三个 bug"全塞进一次会话，模型跑到后面效率明显下降。按功能拆分会话，每次只走完一条完整的"计划-实现-测试-提交"流水线，体验才最爽。
第四，记得定期清理旧项目里的.superpowers缓存。这方案在一些共享仓库里很容易泄露SESSION.md中的业务信息（因为摘要文件描述项目的逻辑、模块关系），团队协作时如果不希望这些信息被其他人看到，建议把缓存目录一并加入.gitignore。
5. 进阶玩法：把superpowers接到 Java 项目和团队工作流里
5.1 定制 Java 语言专属提示词
前面提到java-rules.md，这块值得单独展开。Java 项目跟 Python 或 JS 项目最大的差异是强类型和显式结构，AI 在 Java 项目里最容易犯的毛病有三个：返回空值、绕过接口直接调实现类、异常处理只打日志不抛出。针对这些痛点，我在AGENTS.md里追加了这几条规则：
- 所有公共方法返回类型必须使用 Optional 或显式异常，禁止返回 null 表示"无结果" - Service 层、Repository 层必须面向接口编程，禁止直接引用实现类 - 异常处理必须区分"可恢复"与"不可恢复"，可恢复的必须提供降级策略，禁止 catch 后只打印日志 - 每个新方法必须有对应单元测试，覆盖正常路径和异常路径加上这些规则之后，模型输出质量高了一个档次。尤其是"禁止返回 null"这条，配合 Java 的Optional能避免一大批运行时 NPE，这比让模型写 500 行业务代码有价值得多。
5.2 与 worbuddy 等团队协作工具的结合思路
热词里有个worbuddy 怎么用 superpowers，我推测你可能是团队协作场景下想统一 AI 助手的做事风格。这类工作流类协作工具本身负责把任务分发给不同角色，而superpowers恰好能补足"AI 作为执行者时缺少的标准作业流程"。实践中比较顺手的组合是：worbuddy 分配任务 → AI 助手加载AGENTS.md与superpowers规则 → 全员共享同一套"计划-实现-测试-提交"节奏。
这里要注意的是，团队场景下不要把AGENTS.md写得太长。我见过有人把几十条规则一次性塞进去，结果模型每次会话光读规则就耗掉大量 token，反而挤占了代码上下文。团队统一规范时，只保留 5~8 条最核心的约束，细节放在.superpowers目录下的分模块文件里按需引用，效果最好。
5.3 从单机到多人协作的配置复用
如果你想把这套配置推广给团队其他成员，最省事的方式是在项目仓库里维护一份.superpowers目录（不包含运行时生成的SESSION.md），配合根目录的AGENTS.md一起提交。新人进来克隆代码后，启动 Codex CLI 就能自动套用全套流程，不用各自本地操作。Git 管理的优势还在于：规则调整时大家都能看到 diff，想确认"这次流程改成什么样了"直接看提交记录就行，这也是提升团队 AI 协作效率非常实用的一步。
6. 一点个人经验：什么时候不该用superpowers
聊了这么多优点，最后想泼点冷水。superpowers不是银弹，它最不擅长的是"探索未知"和"快速原型验证"场景。比如你只是想确认某个新框架的 API 调用方式，或者临时写个小脚本处理数据，套上这么重的流程反而碍事——模型每走一步都要汇报、确认、测试，原本一句话能搞定的事拖成十分钟。遇到这种任务就该直接关掉方案，用普通模式快速问一句拿到结果就行。
我自己的使用习惯是"按任务选模式"：小改动、临时脚本，直接普通对话解决；涉及多文件、核心业务逻辑、需要长期维护的功能，才启动superpowers走全套流线。把流程当成工具而不是仪式，它才能真正提升效率。还有一点：随着模型能力迭代，这套提示词几乎每个月都有社区更新，你克隆下来的版本可以定期git pull拉取变更，好让 AI 的行为方式跟上最新实践。
