我做了三年多的 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 CLISuperpowers 目前主要服务对象是 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 的结构化描述甚至给复杂函数写使用说明。我的建议是把它作为每次重构完成后的“收尾动作”。一来一回既能验证代理是否真的理解了自己刚才的改动也能顺手把文档质量拉上来。唯一要注意的是文档里的“改动理由”部分代理经常写得太过“积极正面”好像每个重构都毫无风险这时候你的脑子得清醒风险点和妥协之处得自己判断。核心技能主要应用场景强烈推荐程度review-code代码合并前审查五颗星plan需求设计与任务拆解五颗星troubleshoot线上问题定位四颗星document-project文档更新与维护三颗星refactor 系列大规模代码重构四颗星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 当“方法论框架”用而不是当“死板的插件标准”用。你可以在自己的工具里提取其中的规划步骤、审查维度、心智模型条目融入你自己的提示词模板。它是充电源不是紧箍咒。工具与 Superpowers 的兼容方式使用难度Codex CLI官方支持原生集成低Claude Code通过读取技能文档间接使用中WorBuddy通过调用 codex 命令实现编排中自主开发的 AI 工具将技能文档内容注入系统提示词高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 这个名字背后真正的野心——它给的不是超能力而是获得超能力的方法。