如果你最近搜过“superpowers 使用教程”“codex superpowers”这组关键词，八成已经跟我一样，开始把 Claude Code 或 Codex CLI 当成日常写代码的搭档了。我最初接触 superpowers，就是因为被 AI 助手“写一半就跑偏”的尴尬折磨到不行：吩咐它改个订单模块，它能把购物车、优惠券、积分三个模块齐刷刷改一遍，最后还自信满满地说“已全部完成”。后来我才搞清楚，这其实不是模型变笨了，而是我把它放养了——没有流程约束，没有计划意识，没有测试兜底，再聪明的模型也只会给你一个“看起来合理但经不起推敲”的结果。
superpowers 这个名字很唬人，实际它也不是什么黑魔法，而是一套面向 AI 编程代理的工作流与技能包。它把“先规划、再测试、后实现、最后反思”这套工程师习惯，翻译成一个 Agent 能按步骤执行的技能集。这篇文章我会从它解决什么问题讲起，把安装、核心机制、实际跑一个 Java 重构案例、常见坑都过一遍，希望能帮你少走弯路。
1. 它到底解决的是 AI 写代码的什么问题
1.1 我最早用 Claude Code 写代码的挫败感
先说一次真实经历。我在一个 Spring Boot 项目里让 Claude Code 给订单金额计算加上“优惠券分摊”的逻辑。当时我是直接丢给它一句话：“帮我把优惠券分摊到订单明细里，注意别弄坏积分抵扣。”它答得很快，不到两分钟就输出了一版“改动”，看起来沾沾自喜。
结果代码评审的时候发现了问题：它把积分抵扣的顺序调换了，导致组合支付场景下用户多付了 4 分钱。更离谱的是，它还顺手把另一个无关的 DTO 字段命名改了，改得毫无必要。为什么会出现这种问题？因为模型在长对话里很容易丢失最初的目标边界。它以为自己在“帮用户改完整模块”，而不是“只改优惠券分摊这一处最小逻辑”。上下文越长，它就越是哪个文件都看一眼，哪个文件都想动一动，最终把一次本来很小的改动变成了“伪重构”。
当时我还没意识到，问题不在模型本身，而在工作流：我没有给它一个清晰的“影响面清单”，没有让它先写测试，也没有要求它最后自查 diff 是不是最小集合。这一切，恰好就是 superpowers 这类技能集想补上的。
1.2 superpowers 的设计理念：让助手像成熟工程师一样工作
superpowers 不是一个单独的“开挂命令”，它的核心是一组可以被 Agent 按需加载的技能文件，外加一套拆分任务、保存计划、调用子代理的框架。你可以把它的工作方式理解成：把一名 AI 助手从“愣头青实习生”培养成“按规范走流程的工程师”。
具体拆开讲，它强迫 Agent 在动手前回答几个问题：
- 这次改动的目标是什么？判断成功的标准是什么？
- 涉及哪些文件？哪些边界绝对不能碰？
- 是否可以先写一个会失败的测试，把“预期行为”锁定下来？
- 实现跑通之后，是否有回顾/反思步骤，用来检查自己是否改多了？
听起来很基础对吧？但恰恰是这些基础步骤，我们人类通常下意识会做，而 AI 不会。你把它们写成技能文件，等于把“做事的规矩”固化成了提示词。这就是 superpowers 最核心的理念：不要指望模型自动具备工程素养，而是把工程素养写进流程里。
1.3 适合什么人用
我实际体验下来，下面几类人用它会比较赚：
- 已经在用 Claude Code / Codex CLI，但觉得对话式编码不可控、经常改一半跑偏的人。
- 团队想统一 AI 编码规范的人，比如强制所有 AI 改动必须有测试、必须有计划文档。
- 想让 AI 跑长任务的人，比如“把支付模块整体重构一遍”，但又不敢完全放手，需要中间产物可追踪。
反过来说，如果你的工作只是“问几个语法问题”“写几个一次性脚本”，那 superpowers 对你可能偏重，杀鸡用牛刀了。
2. 安装与前置环境：从零到第一次召唤
2.1 环境准备中最容易忽略的细节
先说说环境。superpowers 的底层是跑在终端里的，所以不是所有设备都体验一致。我的建议顺序是：
- 已经有 Node.js 18 或更高版本，最好 20+。很多安装脚本和技能本身依赖 npm/npx。
- 已经装好 Claude Code 或 OpenAI Codex CLI，并完成登录。也就是说，你自己至少已经能在这个终端里跟 AI 对话。
- 有 Git，且当前项目已经是一个 Git 仓库。因为 superpowers 的计划恢复、diff 自检都严重依赖 Git 状态。
- 操作系统优先 macOS 或 Linux。Windows 用户我建议用 WSL，纯 Windows PowerShell 下会遇到路径分隔符和权限模型的额外麻烦，不是不能用，是坑更多。
2.2 安装命令到底怎么敲
我在不同版本里见过的安装入口不完全一样，这里给你两种最常见的：
# 方式一：npm 全局安装，会提供一个 superpowers 命令 npm install -g superpowers# 方式二：在 Claude Code 会话里直接装插件 /plugin install superpowers@latest如果你不想全局安装，也可以在某些版本里用 npx 方式直接执行，例如npx superpowers init。命令在不同小版本之间漂移得很厉害，所以我不建议你死记某一条命令，而是安装前先看一眼你拿到的仓库 README，以它写的为准。
装完之后，进入你的项目目录，执行初始化：
cd your-project superpowers init执行完，你会发现目录下多了一些东西，最常见的包括.superpowers/skills/技能目录，以及一个被追加了“superpowers 技能索引”的CLAUDE.md或AGENTS.md。如果你看到这些，说明安装成功了一半。
2.3 验证安装：让 Agent 自己说出会哪些技能
初始化只是把文件放好，真正要验证的是模型能不能感知到这些技能。我会先把当前终端关掉重开，然后进入项目目录打开 Claude Code，第一句话不问业务问题，而是问：
“这个项目启用了哪些技能？列出名称和触发条件。”
如果 superpowers 生效了，它会按照 CLAUDE.md 里的技能索引，给你列出一串技能名，比如 test-driven-development、design-doc、refactor-workflow 等。如果它回答“我没有看到任何技能”，大概率是CLAUDE.md没被正确加载，或者技能索引没有写到这份文件里。
这时候别急着怀疑模型，先去文件里看一眼：如果没有“superpowers 技能集”相关的章节，手动把技能索引文本追加进去即可。很多安装失败，其实只是“文件生成了一堆，但模型没读到入口索引”。
3. 核心运行机制：技能、记忆与子代理如何配合
3.1 技能是怎么被“按需加载”的
superpowers 里的“技能”，本质上是一个个带元信息的 Markdown 文件。每个技能文件头部有一段 YAML frontmatter，里面写了 name 和 description，正文就是让 Agent 照做的具体步骤、检查清单和输出模板。
举个例子，一个“设计文档”技能的头部大概长这样：
--- name: design-doc description: 在涉及多文件改动前生成设计文档；适合重构、新增模块、架构调整等任务 ---当你在对话里说“我要把支付模块重构一遍”，Agent 会先读到技能索引，再根据描述词“多文件改动、重构”命中 design-doc 这个技能，然后把整个文件的正文加载进上下文，开始按里面的模板生成设计文档。
这里的设计很巧妙：它不是把几十个技能一次性塞进上下文，而是靠描述匹配、按需加载。技能文件写得再多，也不会让每轮对话都变重。这就像你书架上放了一堆工具手册，需要拧水管时只抽水管那本，而不是背着整座图书馆去修水管。
3.2 记忆与计划文件：会话断了也能接上
我最开始用的时候，对“计划写进文件”这件事并不敏感，总觉得对话就是最好的状态。直到有一次重构到一半，终端崩溃，重开会话后 AI 完全不记得之前的上下文，我差点原地自闭。
superpowers 的思路不一样：它鼓励 Agent 把关键中间产物落盘，比如把设计文档、影响面清单、测试清单写进.superpowers/plans/目录。这样即使会话断了，重新打开后只要说一句“读取最新的计划文件，继续任务”，Agent 就能通过文件 + Git 状态恢复工作。
我自己实操下来，会在任务开头额外叮嘱一句：“每一阶段结束后，把结论写进.superpowers/plans/下带时间戳的文件。”这句话看着多余，实际救了我很多次。AI 的工作记忆是极不可靠的，但文件是可靠的。长任务能不能跑完，往往就取决于你是不是把该保存的都保存了。
3.3 子代理调用链：把大任务切成多人协作
superpowers 里还有一个我很喜欢的设计：子代理调用。面对“重构支付模块”这种大任务，主线程不会自己吭哧吭哧干，而是像项目经理一样拆分：
- 子代理 A：扫描现有代码，输出“涉及文件清单 + 影响面分析”；
- 子代理 B：基于新契约写测试，故意跑出红牌；
- 子代理 C：实现逻辑，把红牌变绿；
- 主线程：收拢结果，做最后 diff 自检。
每个子代理都带着明确目标启动，互不干扰。这比单线程对话强在两点：一是不会聊着聊着目标漂移；二是能并行处理耗时操作，比如在跑测试的同时，另一个子代理已经在分析下一个受影响模块。
3.4 权限分级：什么能自动跑，什么必须人确认
我见过太多“AI 把项目搞乱”的事故，说到底是权限放太宽。superpowers 的技能文档里虽然会约束 Agent 的行为，但工具调用权限还是握在你手里。我的习惯是分三档：
- 采集类命令：
ls、grep、cat、git diff、git log，直接放行。 - 修改类命令：
npm install、sed -i、rm、mv，先看计划里有没有列出来，再放行。 - 破坏性命令：
git push --force、全局格式化、批量重命名文件，必须人工确认。
不要嫌确认麻烦。真等到它把 lock 文件、无关配置文件改得面目全非的时候，你才知道什么叫真正的麻烦。
4. 用真实项目过一遍主流程：TDD 与重构
4.1 让 AI 先写测试再写实现：Java 订单模块案例
结合“superpowers java”这个高频搜索词，我用一个 Java 场景完整走一遍 superpowers 的 TDD 流程。
项目背景：Spring Boot 订单模块，金额计算逻辑散在三个 Service 里。需求是把优惠券分摊和积分抵扣统一成一条计算链路。我没有直接让它“开始改”，而是说：“我要重构订单金额计算，请先用测试驱动的方式输出计划，并先写红牌测试。”
它会先生成一个计划文档，里面可能包含：
- 圈定涉及文件：OrderService、CouponService、PointsService、几个 DTO。
- 定义输入输出契约：入参是什么，零头怎么处理，优惠券与积分谁先谁后。
- 写第一份 JUnit 测试，声明目标行为，但不实现。
预计算的用例大致长这样：
public class OrderAmountCalculatorTest { @Test void should_apply_coupon_then_points_on_order_amount() { OrderAmountInput input = new OrderAmountInput(100.00, 15.00, 2_000); OrderAmount result = new OrderAmountCalculator().calculate(input); // 100 - 15 = 85；2000 积分按规则抵扣 20 元 => 65 assertThat(result.finalAmount()).isEqualTo(65.00); assertThat(result.couponPart()).isEqualTo(15.00); assertThat(result.pointsPart()).isEqualTo(20.00); } }注意，这里测试不是“写完功能后再补”的测试，而是先写红、再写绿。superpowers 的 TDD 技能会要求 Agent 先让测试失败，然后才去实现。这一步对于老代码尤其有用：它会逼你把“到底期望什么行为”说清楚。我记得当时跑完红牌测试后，发现旧代码里有一条“金额 + 0.001 防浮点误差”的玄学逻辑，之前根本没人敢动，新测试直接把它暴露了。这就是契约的力量。
4.2 策略先行：codex superpowers 怎么接
有人会问，既然 superpowers 最初更多被 Claude Code 的用户使用，那 Codex CLI 里能不能用？答案是能，但接入方式稍微绕一点。
Claude Code 靠CLAUDE.md作为全局指令文件，Codex CLI 则读AGENTS.md。思路是一样的：把技能索引放到模型每轮会话必然能看到的地方，然后让它“遇到多文件改动先读技能文件，再动代码”。
我自己的轻量接入方式是：
- 在项目根目录放一份
AGENTS.md，里面写明“遇到多文件任务，先阅读.superpowers/skills/design-doc.md并按流程执行”。 - 把需要的技能文件放到
.superpowers/skills/目录。 - 在对话里显式说：“使用 design-doc 技能，先设计方案，再实施。”
Codex 的版本迭代也会变，有些版本支持自定义命令，有人会把技能调用封装成命令别名，用起来更顺。但核心永远是那句：只要能读文件、能执行命令、能注入系统提示的代理工具，都可以承载这套技能目录，只是触发方式不同。
我曾经整理过一份极简对照，遇事不决就看这张表：
| 对比维度 | Claude Code | Codex CLI |
|---|---|---|
| 全局指令文件 | CLAUDE.md | AGENTS.md |
| 技能索引写入位置 | CLAUDE.md 开头 | AGENTS.md 开头 |
| 技能触发方式 | 对话自然语义命中 | 需要显式告诉它去读技能文件 |
| 长任务拆分能力 | 原生 subagent 较成熟 | 需要脚本封装或依赖外部工具 |
| 适合人群 | 习惯交互式协作 | 习惯命令式、批处理式 |
这张表不一定永远精确，因为两边都在快速迭代，但思路是对的：Claude Code 更“自动”，Codex CLI 更“显式”。
4.3 重构与自检：让 AI 先提交方案再改代码
很多人以为让 AI 重构就是一句“帮我把 X 模块重构掉”，然后等结果。我用 superpowers 的习惯是走四步：
- 生成影响面清单。明确列出“会改哪些文件，哪些文件只读不改”。
- 对每处改动写理由。不允许出现“因为你说改”这种话。
- 跑完测试后进入评审模式，让 Agent 用挑剔的眼光看一遍自己的 diff。
- 确认改动是最小集合后，才允许提交。
最后这一步很容易被忽略。AI 写代码时经常“顺手”把格式化、重命名、注释调整混进来，让 diff 变得又大又难评审。superpowers 的反思技能会把“我是否是这次改动的最小集合”变成一个强制检查项。我在实际项目里用过这招后，评审 AI 生成的 PR，平均要看的文件数少了差不多一半。
5. 日常使用踩坑与解决：从配置冲突到长任务恢复
5.1 配置冲突：多个工具抢着写 CLAUDE.md
这是我在启用 superpowers 后碰到最早的坑。项目里同时有.cursor/rules、手写的CLAUDE.md、AGENTS.md，而 superpowers 初始化时会往CLAUDE.md里写技能索引。如果你原本的CLAUDE.md是一份精心维护的项目规范，它很可能被覆盖或干扰。
解决思路很简单，但很多人不知道：初始化之前先备份，初始化之后手动合并。不要把整份文件交给工具重写，而是只追加一个“superpowers 技能集”小节。如果你的项目同时给多个 Agent 工具用，我甚至建议把公共技能放到一个shared/目录，然后让各工具各自的索引文件都指向这个目录，避免“一份技能放三份副本”的同步噩梦。
5.2 权限提示：全放行 vs 步步确认
第一次跑 superpowers 的时候，你可能会被一连串工具调用提示吓到。这里我有一个经验值：
- 读操作全放，写操作先审，破坏性操作必停。
- 如果项目只有你一个人，且是实验性代码，权限可适度放宽，但至少保留“命令执行前只确认一次”模式。
- 子代理的工具调用比单线程多得多，日志会看起来很乱。我习惯把子代理内部的读写折叠成摘要，只看主线程的关键行动，否则看日志会看到头大。
记住一个原则：不是所有工具调用都值得批准，也不是所有批准都需要人工点一次。关键是让“危险动作”永远留在你手里。
5.3 长任务中断与恢复：文件就是救命稻草
前面说过，superpowers 把计划写进文件的思路我要再强调一遍。具体到恢复场景：
- 如果会话崩了，重新开一个窗口。
- 输入“我们之前在做订单模块重构，读取最新的计划文件并继续”。
- Agent 读到计划文件 + 当前 Git 状态，就能无缝接着跑。
这里的隐藏要求是，在任务进行过程中每一步都要保存。模型不会主动保存，所以我会在任务开始时明确加一句“每阶段结束把产出物写入 .superpowers/plans/”。没有落盘的步骤，恢复时就是一场空。我自己试过几次之后，已经把这句固化成了固定开场白。
5.4 关于“WorkBuddy 怎么用 superpowers”之类的疑惑
偶尔会看到有人问类似“WorkBuddy 怎么用 superpowers”这样的问题。其实答案不在某个具体工具里，而在“这个工具能不能读技能文件”。如果你的工具支持自定义命令、技能文件或至少能执行 bash，就能把这套技能目录挂进去；如果它既不能读文件也没有自定义命令入口，那就没法用。
不要把 superpowers 想成某个 GUI 工具里的一颗按钮。它的本质是一套流程 + 提示词资产，可以在 Claude Code 里用，也可以部分迁移到 Codex CLI 以及其它支持自定义技能与权限模型的 AI 编码工具里。工具间的差别主要在于触发与注入方式，而不是“能不能”。
5.5 别迷信最新版
我踩过的另一个坑是：为了追新功能，频繁升级 superpowers 技能包版本。结果就是某个技能的元信息字段格式变了，Agent 突然匹配不到技能文件，或者初始化脚本把目录结构重排了一遍，旧项目里引用的路径全部失效。
我的建议是：稳定使用你验证过的版本，升级前先在一个临时目录试跑。等到新版本在社区里讨论一段时间后再跟上也不迟。工具链这种东西，稳定压倒一切。
6. 实际体验层面的一些感受
这套工具用了大半年，我的结论是：它不会让你的代码库一夜之间变干净，但它能把失控的 AI 编码过程拽回正轨。最直接的变化是，AI 在动手前会先给我一份计划，在写实现之前会先有测试。即使它最后写出来的代码还是有小问题，流程也能把问题框在一个可控范围内，而不是让它顺着上下文一路跑偏。
如果让我只留一条使用建议，我会说：养成“先要点计划，再放权执行”的习惯。哪怕你暂时没装 superpowers，也先在对话里逼自己多问 AI 一句“你打算怎么改，涉及哪些文件，怎么验证”。你会发现，就这么一句，AI 写出来的代码质量就能上一个台阶。
而 superpowers 的功劳，就是把这句“多问一句”变成了默认流程，还顺便把计划、测试、反思这些好习惯都固化到了技能文件里。工具始终会迭代，命令名会变，目录结构会调，但“先规划、再测试、后实现、最后反思”这条主线，我认为在很长一段时间里都成立。
