Superpowers：让AI编码代理从“会写代码”到“会干活”的技能包

我做了三年多的 AI 辅助编程，工具换了一茬又一茬，从 Copilot 到 Cursor 再到 Codex CLI，说实话都挺好用，但总有一种“差口气”的感觉——代理能写代码、能跑测试，可一旦涉及“先想清楚再动手”的环节，它就容易飘。直到我在 GitHub 上翻到superpowers这个项目，才意识到问题不在模型本身，而在于我们给代理的“工作语言”太简陋了。这个项目准确的叫法是Superpowers for AI Coding Agents，主要给 Codex CLI 这类终端型编码代理加装一套“技能包”，让代理从“会写代码”进化到“会干活”。这篇文章我打算把它的设计思路、安装流程、核心技能和使用心得完整拆一遍，尤其结合最近社区里讨论比较多的superpowers java、worbuddy 怎么用 superpowers这类实际场景，讲点能直接抄作业的东西。

1. 为什么我会盯上 Superpowers：从“能写代码”到“会干活”的差距

先说一个反直觉的结论：现在的大模型编码工具，短板恰恰是“太会写代码了”。

你让它实现一个排序算法，它刷刷给你几十行，效率比人高多了。但你让它“帮我把这个模块的重构方案想清楚，顺便评估一下风险”，它就容易陷入两种极端——要么给你一篇空洞的“最佳实践”套话，要么直接跳过分析和计划开始改代码。问题出在哪？出在代理的工作记忆和推理链太短，它没有一套结构化的“思考脚手架”。

我举个实际例子。之前用 Codex CLI 改一个支付回调的老模块，代码量不大，但牵涉到状态机、幂等、对账三个子系统。我直接在命令行里说“帮我优化一下这个模块”，代理吭哧吭哧改了十几个文件，跑测试全绿，逻辑却碎了——它把状态机的核心迁移删了，觉得那是“冗余”。这就是典型的“局部最优解”：它看到了代码，没看到业务约束。

Superpowers 解决的就是这个问题。它本质上是一个技能库 + 心智模型库 + 交互协议的组合体，让你能以“人指挥、代理执行”的方式，给 Codex CLI 下发更接近项目经理指令的复杂任务，而不是一句孤立的需求描述。

具体的机制后面我会细说，这里先下个结论：如果你只是想让 AI 帮你补全代码片段，Superpowers 对你没用；但如果你想让 AI 代理独立完成一整个任务闭环——理解需求、设计方案、拆解步骤、执行、自查——那它就是你缺的那层“项目管理壳”。

我是在今年年初一个周末的下午开始折腾这个项目的，从git clone到在 Java 项目里跑通完整的“审查 → 重构 → 验证”流程，前后花了大概三个小时。之后它在我的日常开发里逐渐反客为主，现在已经成了我 Codex CLI 环境的标配。

2. Superpowers 的底层逻辑：它到底给你的代理注入了什么

先给没接触过这个项目的朋友补个背景：Superpowers 是 GitHub 上的一个开源项目，作者是 Jesse Vincent（网名 obra），核心思路是给文本驱动的编码代理提供一套Markdown 格式的技能文档，文档里写清楚了代理在特定场景下应该遵循的思考流程、输出格式和操作边界。

2.1 技能包的本质：一套“可执行”的提示词工程

你可以把每个“技能”理解成一张给代理看的“岗位 SOP”。比如review-code这个技能，它会告诉代理：

• 先读取代码库结构和变更范围；
• 列出你认为有风险的 5 个点，先从“数据流”切入，而不是“代码风格”；
• 对每个风险点给出具体的文件、行号和修改建议；
• 最后输出一份带优先级的审查结论。

这些步骤本身不算什么高深的东西，但关键在于：它们被固化成格式化的 Markdown 文档，代理可以精确地“读到”并“遵循”。这和我们平时在提示词里随手写两句“请仔细审查代码”效果完全不同——后者是模糊的、一次性的；前者是结构化的、可重复的。

2.2 心智模型库：让代理学会“抓大放小”

除了具体技能，Superpowers 还带了一套“心智模型”文档。这名字听起来玄乎，其实就好比给代理灌输了“哪些事情优先级高、哪些事情必须做、哪些事情不能做”的原则。

打个比方：代理就像一个刚入职的实习生，技能文档教它“每个任务怎么做”，心智模型教它“在遇到冲突时怎么判断”。比如其中一个心智模型是“不要过度工程化”，它会让代理在动手前先问自己：这个改动是不是超出用户需求了？有没有更简单的实现路径？这恰恰是上一节里我那个支付模块翻车场景的解药。

这里我强调一点：技能包和心智模型不是魔法，它们是优质提示词的系统化封装。理解了这一点，你就能明白为什么这个项目不是简单地把几十个提示词塞进一个文件，而是拆成了清晰的文件结构——因为代理在读取时也需要“导航”，结构清晰才能让它快速定位到当前任务真正需要的知识。

2.3 与 Codex CLI 的结合方式

Superpowers 和 Codex CLI 的结合方式很有特色：它定义了一套类似于代码语义的“标记语言”（在项目里叫semantic markdown），代理在输出时用特定的标签把“思考过程”、“最终答案”、“需要用户确认的问题”区分开。用户在终端里看到的是一个结构分明的输出：哪些是代理的推理、哪些是操作请求、哪些是最终交付物，一目了然。

这种方式的好处很明显：你不再需要从一大段 AI 生成的自然语言里“考古”关键信息了。代理自己就会把“我发现了问题X，建议方案Y，需要你授权执行Z”这样的信息打上标签，你可以像看工单一样快速决策。

这套结构组合起来，就把一个只会顺着话茬续写的语言模型，变成了一个“有章法、守规矩”的执行者。我个人体会最深的一点：它不是让代理变聪明，而是让代理变“靠谱”。

3. 安装与初始化：半小时让 Codex CLI 拥有 Superpowers

说了这么多原理，来点实际的。下面是安装配置的完整过程，我用自己的 macOS 环境为例，Windows 和 Linux 下大差不差，命令稍有出入但思路一致。

3.1 前置条件：先准备一个能跑的 Codex CLI

Superpowers 目前主要服务对象是 OpenAI 的 Codex CLI（开源的终端编码代理）。所以第一步是确保你本地已经有一个能正常工作的 Codex CLI 环境。

# 确认 codex 命令可用 codex --version

如果你还没装过，可以参考官方文档装一下。装完之后先随便跑一个简单任务，确保模型调用、网络、鉴权都正常。这一步别省略，Superpowers 是基于 Codex 环境的“上层建筑”，地基不稳后面全是坑。

3.2 克隆项目并运行安装脚本

Superpowers 提供了自动安装脚本，核心就两件事：把项目文件拉下来，然后注册到 Codex CLI 的启动配置里。

# 克隆项目到本地固定目录，我放在 ~/superpowers git clone https://github.com/obra/superpowers.git ~/superpowers cd ~/superpowers # 运行安装脚本，它会自动检测 Codex CLI 并写入配置 ./install.sh

我在第一次安装时碰到的唯一问题是脚本默认找~/.codex目录，而我的 Codex 配置在~/.codex/config.toml，路径本身没问题，脚本可以识别。如果你的 Codex 是用 Homebrew 装的且版本比较老，建议先更新到最新版再装。

安装完成后脚本会提示你“Superpowers 技能已安装”，同时在 Codex 的配置文件里多了一段引入 Superpowers 路径的内容。你可以自己打开config.toml验证一下：

cat ~/.codex/config.toml

里面应该能看到类似instructions和superpowers相关的配置段。如果没看到，说明脚本没写进去，可以手动把项目里的AGENTS.md文件路径加到 Codex 的instructions配置里，这是最直接的兜底方案。

3.3 基本验证：跑一次“技能清点”

安装完后，启动 Codex CLI，输入一条“清点技能”的指令，看它能不能正确识别 Superpowers 框架：

@superpowers 列出当前可用的技能清单

正常情况下，代理会返回一份结构化的技能列表，包括代码审查、任务规划、故障排查、文档生成等核心技能。能走到这一步，说明你的 Superpowers 环境已经通了。这一步花五分钟，比直接上手干活值多了——至少能确认代理真的加载了技能包，而不是假装理你。

4. 核心技能拆解：哪些技能值得日常高频使用

Superpowers 自带的技能数量不少，但我实际高频使用的其实就五六个。逐个说一下它们能干什么、怎么用、以及我踩过什么坑。

4.1 代码审查技能（review-code）

这是一个我几乎每天都会用到的能力。用法非常直接：指定文件或目录，让代理做一次“深度审查”。

@superpowers review-code --scope src/payment

这个技能给我的最大价值是它会分多个维度输出审查结论：数据流风险、并发一致性、错误处理、边界条件、可维护性，每个维度都有具体的文件和行号定位。相比裸 Codex 直接说“review”，它输出的内容更有条理，而且它会把“必须要改的问题”和“建议优化项”分开标记，我通常只需要看第一类。

使用上有个小技巧：审查单个文件时，在指令里补充项目的上下文，比如“这是一个高频交易回调模块，注意幂等性和日志完整性”。代理会根据你的补充调整审查重点，输出质量明显提升。

4.2 目标拆解与任务规划技能（/plan）

这个技能解决的是我开头说的那个“代理一上来就写代码”的问题。使用方式是先给代理一个模糊的目标，不要提具体改法：

@superpowers plan 目标是：重构通知发送模块，降低重复发送风险，要求兼容现有接口，两周内完成

代理会先输出一份“需求澄清”列表——哪些信息明确、哪些信息需要你补充、哪些是相互冲突的约束。确认之后，它才会产出分阶段的实施计划，每阶段包含改动文件范围、验证方式、回滚方案。这个流程体验下来非常像在带一个思路清晰的中级开发，而不是在用一个无脑代码生成器。

4.3 故障排查技能（troubleshoot）

这个技能特别适合线上问题复盘或 Debug 场景。和直接把报错信息丢给 Codex 不同，troubleshoot技能会让代理遵循一个完整的排查链路：先收集证据、再定位根因、给出验证假设的方案、最后才是修复建议。

比如我在一次环境变量导致的服务启动失败场景里，代理没有直接告诉我“把配置改了”，而是先问了三个问题：这个环境变量在哪些实例上缺失？服务日志中最早出现异常的时间点？这次的发布是否涉及配置变更？这三个问题一问，问题的根源就清晰了大半——不是环境变量缺失，而是新版本代码里多了一个必填项，老实例没同步更新。

4.4 文档生成与维护技能

这个技能对我们的价值是消灭“文档之债”。它可以基于代码变更记录自动生成更新日志（changelog）、维护 README 的结构化描述，甚至给复杂函数写使用说明。

我的建议是把它作为每次重构完成后的“收尾动作”。一来一回，既能验证代理是否真的理解了自己刚才的改动，也能顺手把文档质量拉上来。唯一要注意的是，文档里的“改动理由”部分，代理经常写得太过“积极正面”，好像每个重构都毫无风险，这时候你的脑子得清醒，风险点和妥协之处得自己判断。

4.5 心智模型对技能的实际增益

套用技能不等于万无一失，我遇到过代理在plan时给出了漂亮的步骤，却在执行到第三步时因为局部代码复杂而把方案悄悄简化了的情况。后来看日志发现，它在简化前其实“思考”了一段，但没有触发“是否偏离原方案”的心智模型。

解决路径是我主动给 Mindset（心智模型）加了自定义条目：当执行路径偏离已确认的计划时，必须停下来向用户汇报，而不是自行修正。这个条目加进去之后，代理“自作主张”的频率直线下降。所以说，心智模型不是装饰，是硬约束，尤其是“偏离计划须汇报”之类的条目，对复杂任务的完成质量至关重要。

5. 实战演练：superpowers 在 Java 项目中的数据流排查

上面说的都是单项技能，这节我来还原一段完整的 Java 项目实战，给大家看看 Superpowers 怎么把“模糊问题”逐步变成“精确修复”。这也是最近搜索热词里superpowers java出现的背景之一——很多人装了 Superpowers 后第一反应就是拿去处理 Java 工程，而 Java 工程的“重”正好能让这套方法论发挥最大价值。

5.1 问题描述与初步探查

我接手的一个老项目最近经常出现偶发的缓存穿透，现象是高峰期部分请求响应时间从 50ms 直接飙到 2s。由于项目用了多级缓存（本地 Caffeine + 远程 Redis），各个环节都有嫌疑。

我没有直接开troubleshoot，而是先让代理用plan技能把排查思路理了一遍。代理输出了一份分阶段的排查方案：第一阶段看本地缓存命中率、第二阶段看 Redis 连接池使用率、第三阶段看数据源热点 key 分布。

这个方案本身并不惊艳，但代理按照标记语言把“每一阶段的预期产出”和“需要我提供的辅助信息”都列了下拉菜单式的选项，执行起来非常顺滑。

5.2 用代码审查技能定位“可疑代码”

在第二阶段的 Redis 连接排查中，我让代理聚焦CacheService.java做深度审查。结果它发现了三处可疑点：

第一处：get流程中，本地缓存未命中后直接查数据源并回填 Redis，没有加分布式锁。高并发下多个线程同时回填，虽然不是穿透根因，但增加了无谓的 Redis 写压力。

第二处：Redis 连接复用配置里max-total设置成了 20，但 Spring Boot 默认的 Lettuce 连接池在高峰期可能出现等待，这部分和“穿透”的表现对不上，却是性能隐患。

第三处：热点 key 没有做“空值缓存”处理。当数据库中不存在对应记录时，每次请求都会直接打到 DB，这在冷门 key 场景下问题不大，但请求量一大就会变成“缓存击穿”。

代理在输出审查结论的时候，对每一处都标注了“触发条件”“影响面”和“修复建议”，还判断了哪些是当前问题的直接原因、哪些是间接隐患。省去了我逐行翻代码的时间。

5.3 修复阶段的心智模型约束

在让它执行修复之前，我在指令中强调了约束：必须保持接口兼容，不允许改动表结构，不允许扩大改动范围。代理在执行时确实“克制”了很多，没有顺手去重构不相干的代码——这应该归功于心智模型文档中“最小变更原则”的约束。

修复完成后，代理自动写了一段验证代码，模拟 100 并发请求对缓存击穿场景进行回归。测试结果从最开始的 85% 超时降到了 2% 超时，效果非常明显。

5.4 实战后的教训总结

这一轮走下来，我的核心感想有三条：

第一，不要跳过规划阶段。即使在“快速定位一个 bug”这种看似简单的场景里，先让代理出 plan 再执行，产出质量比直接问它“怎么修”高得多。原因是规划阶段会强制代理做信息收集和假设验证，而不是一上来就猜。

第二，Java 项目的静态信息，代理吃得比想象的准。它读 Maven 依赖树、Spring 配置、注解定义的能力都不错，但在“运行时行为”上仍然可能出错。我在这个案例里就没有完全信任它对 Lettuce 连接池的推断，最后还是自己加了监控指标验证。

第三，修复完不是结束，要让它产出一段“变更说明”。用superpowers document-change技能可以把这次改动的背景、方案、风险、验证结果整理成一段 commit message，直接粘贴进 PR 描述，省了很多写文档的功夫。

6. 第三方工具的接入：WorBuddy 等工具怎么和 Superpowers 协作

最近在社区里看到不少worbuddy 怎么用 superpowers这类问题。WorBuddy 是近期讨论度比较高的一款 AI 工作流编排工具，大家问的核心其实不是某个具体工具，而是“我能不能把 Superpowers 的技能包接到自己习惯的 AI 工具链里”。这节咱们拆开讲。

6.1 核心思路：Superpowers 是“技能层”，不是“运行时”

很多人刚接触 Superpowers 时会误以为它是一个独立软件、一个需要单独打开的应用。其实不是。它是一套纯文本的技能定义和提示词框架，真正的“运行时”是 Codex CLI 或任何兼容的编码代理。

这意味着什么？意味着只要你使用的工具能读取 Markdown 格式的指令，并且支持自定义系统提示词或技能注入，理论上就能把 Superpowers 的思维框架“搬”过去。

WorBuddy 这类工作流工具的核心能力是“编排多个任务步骤”。它和 Superpowers 的结合方式很自然：你用 WorBuddy 定义工作流的外层结构（比如“提交代码 → 触发审查 → 运行测试 → 生成变更日志”），其中每一步的具体执行逻辑，调用的是 Superpowers 技能规范定义好的行为。

6.2 一个可参考的接入方式（以 Codex CLI 为桥）

如果你是 WorBuddy 的用户，最简单的接入方式是：在 WorBuddy 的工作流节点中，调用本机的codex命令，并在命令参数里指定 Superpowers 的输出规则和上下文目录：

codex exec --config ~/.codex/config.toml \ --sandbox danger-full-access \ "使用 superpowers review-code 技能审查 src/main/java 下的变更"

这样 WorBuddy 负责触发流程，Codex 和 Superpowers 负责执行“智能”部分，两边各司其职。我在实验中发现，这个模式下还有额外好处：因为 Superpowers 的输出结构是高度格式化的，WorBuddy 后续节点可以直接解析它的输出文本，把审查结论自动变成待办事项分派给下一步。等于说，你顺手把“AI 生成的结果”喂给了自动化流程，形成了闭环。

6.3 给“工具链党”的一个忠告

如果你习惯用多个 AI 工具（Codex、Claude Code、各种工作流平台），别指望每个地方的体验完全一致。Superpowers 的技能文档最初是为 Codex 的标记语言设计的，迁到其他模型上时，模型对语义标记的理解程度、遵循程度都会打折扣。我在 Claude Code 上试过部分技能，效果还行，但输出格式偶尔会跑偏，需要我手动纠正。

建议是：把 Superpowers 当“方法论框架”用，而不是当“死板的插件标准”用。你可以在自己的工具里提取其中的规划步骤、审查维度、心智模型条目，融入你自己的提示词模板。它是充电源，不是紧箍咒。

7. 从“能用”到“好用”的细节：自定义技能与心智模型的实战配置

等基础功能用顺手了，你就会开始琢磨一件事：怎么把 Superpowers 调教得更贴合自己的项目和个人习惯。我自己常用的招有三个，每个都是踩过坑换来的。

7.1 自定义项目级技能的两种姿势

Superpowers 支持你新建自己的技能文档，路径在skills/目录下。一个技能文件通常包含三个部分：触发条件、执行步骤列表、输出格式模板。

第一种姿势是“行为规范型”。比如我写了一个handle-legacy-code技能：当代理检测到目标文件的代码年龄超过两年、改动次数多于 20 次时，必须优先输出“这段代码为什么长这样”的历史分析，再考虑改动。这对老项目特别友好，能让代理先理解“屎山之所以是屎山”的原因，而不是一上来就把代码推平。

第二种姿势是“交互流程型”。比如我要求代理在生成任何涉及数据库迁移的代码前，先输出一份包含“表结构变更对比”和“回滚脚本”的独立审查文档，等我说“确认”之后才动代码。这个习惯让我阻止了好几次差点酿成大祸的误操作。

7.2 维护一份你的“项目宪法”

Superpowers 支持全局心智模型文件，这是我最喜欢的部分。我把它称为“项目宪法”——里面写的是这个项目不可动摇的原则，例如：所有对外接口变更必须兼容旧版本，必要时使用适配层；数据库字段不允许软删除，一律增加deleted_at；性能优化必须在注释里写明“为什么快”。

这些规则不一定来自团队文档，更多是我从多年代码评审里提炼出来的血泪教训。因为代理对上下文的记忆是有限的，每次对话都临时提醒，效果远不如固化在全局心智模型文件里。你把规则写得越具体，代理就越少在关键时刻“犯浑”。

7.3 让代理在动手前“先说清楚”

Superpowers 有一套心智模型特别有用：“探索优先于行动”。我给它加了很具体的实现：当代理面对信息不完整的任务时，必须先输出一个“不确定性清单”，列出它不知道但需要知道的事实，并附上获取这些事实的方案。没做完这一步，代码一行都不能写。

这个约束的效果可以用一个词概括：克制。代理不再是一个想到什么就写什么的“快枪手”，而是一个会先问“你说的 worker 数量是 5 个还是 50 个？当前是分钟级任务还是秒级任务？数据源头是 Kafka topic A 还是 B？”的谨慎执行者。对复杂任务来说，这种“先对齐再执行”的行为带来的价值提升，远大于任何代码生成速度的优化。

7.4 版本管理与团队共享

最后提一个经验：如果你的团队也想使用 Superpowers，千万别把技能文档和心智模型只留在某一个人的本地。把它放进 Git 仓库的skills目录下，跟着代码库走。这样每次 code review 的时候，团队成员不仅 review 代码，还能顺便 review 这些技能定义——相当于把“AI 的行为准则”也纳入了团队规范。

我踩过的坑是：有一次我改了全局心智模型里关于错误处理的一个规则，忘了同步给另一个还在用旧配置的同事，导致他那边代理的代码风格和团队风格冲突了很久。后来我们约定，凡是涉及心智模型的变更，必须走 PR + 评审流程，才算真正把这套工具的收益放到了最大。

8. 踩坑实录：安装到适配期最容易翻车的三个环节

任何工具从安装到稳定使用，总会有一段“痛并快乐着”的适应期。说说我遇到过、也看到社区里高频出现的三个坑，帮大家提前避雷。

8.1 配置路径对不上导致的“假安装”

install.sh脚本并不是万能的。最典型的情况是：脚本试图往 Codex 的默认配置目录写入路径，但你的 Codex 是通过 Flatpak、Snap 或自定义编译方式安装的，配置文件根本不在默认路径，脚本写入失败，却没有给出足够的警告，最后你以为装好了，实际上代理压根没加载任何技能。

判断方法很简单：装完以后跑一次技能清点，如果代理回答里没有出现 Superpowers 的任何关键词，基本就是没装上。这时候别急着自行修，先把config.toml的实际位置找出来，然后手动在~/.codex/config.toml的[model]或instructions段加入技能目录的索引路径。我通常会直接备份原配置再动手，出问题方便回滚。

8.2 模型能力不足导致的“技能空转”

Superpowers 的技能设计默认假设你用的是能力较强的模型（例如 GPT-5 级别或 Claude 的顶级型号），并且模型能遵循较长的系统指令。如果你用的是轻量模型或老版本模型，可能出现的情况是：技能文档它读了，但行为完全不受约束，输出形式不遵循标记语言，审查深度也明显不够。

解决办法不是给它加大提示词，而是直接在config.toml里把模型切换成能力更强的那个，或者降低对技能遵循度的期望，把任务拆成更小块交给代理。技能文档再精美，也架不住模型“理解力不足”。

8.3 代理过度依赖“技能名”产生的思维定式

这可能是最微妙的一个坑。当你用久了plan技能，就会发现代理几乎在所有任务上都喜欢先输出一大段“计划”，哪怕你只是让它改一个变量名。它在用一个“正确”的程序来回避直接输出答案，这个现象在心理学上叫“程序性拖延”，在 AI 代理身上也同样存在。

我的应对方式很朴素：把任务按规模分类。小于 10 行的改动，直接用普通对话交给代理，不套技能；中等级别任务，开 review-code 或 refactor 技能；只有真正复杂的任务，才动用 plan 和完整心智模型。不要让锤子把所有东西都当成钉子。

这个取舍很关键。工具是为了让流程更顺，而不是让流程更臃肿。对简单任务套复杂流程，反而是给自己找麻烦。

9. 围绕 Superpowers 的更多可能性：从个人助手到团队基建

谈到这儿，Superpowers 能做的其实已经不局限于“帮我写代码”了。我开始把它当作一个可以持续积累的“团队知识库”——每次踩到新坑、形成新规范，就写进技能文档或心智模型，慢慢地，代理的行为越来越贴近团队里一个优秀工程师的思考方式。

举个例子。我们团队最近在推进一个老系统的微服务拆分，涉及十个以上服务的边界划分和依赖治理。我手动整理了一套“服务拆分审查”技能：要求代理在评审一个服务时，必须同时输出“当前依赖矩阵”“拆分后的环形依赖风险”“数据归属分析”“迁移兼容性评估”四个维度。这个技能在团队里跑了一个月，几个原本会引发系统性风险的拆分方案都被提前拦了下来。

这种积累方式的好处在于，它不依赖具体某个人记得所有规矩，规矩都在技能库里，所有人都能用，所有 AI 会话也都能继承。不管团队里来了几个新人，还是你换了电脑重新部署环境，拉一下仓库，跑一下安装脚本，整套“智慧”就回来了。

如果你刚接触这个项目，我的建议是不要急着把全部技能都塞给代理，而是先装好基础环境，选择一个最痛的使用场景（通常是代码审查或任务规划），跑熟一个技能，再逐步叠加。工具是死的，流程是活的，真正让 AI 编程上台阶的，不是某个神奇的仓库，而是你为自己项目量身定制的“规则密度”。这大概也是 Superpowers 这个名字背后真正的野心——它给的不是超能力，而是获得超能力的方法。