过去半年我把大部分代码工作都交给了终端里的 AI 助手最常用的两个是 Claude Code 和 Codex。说实话单论单次回答这些模型已经很聪明了可一旦任务变成一个功能、五个文件、三处依赖改动它们的表现就开始飘要么漏掉需求要么中途改主意要么自己悄悄缩水。直到我装了一整套叫 superpowers 的技能包情况才真正稳定下来。这篇文章不是官方文档的翻译而是我自己从安装到实战的一线记录。我会先讲清楚 superpowers 解决的是哪一类问题再给出完整安装流程、核心技能拆解、一个 Java 项目的真实执行轨迹最后把踩过的坑和取舍心得都翻出来。适合那些正在用 Claude Code / Codex 做真实项目、并且受够了 AI 发挥不稳定的人。1. 为什么大模型已经这么强还需要一套 superpowers显式技能与隐式能力的区别1.1 原生 Agent 的能力天花板不在模型在调用方式模型很强这没什么好争论的。但终端 Agent 的日常使用方式本质上是每次请求都把任务临时丢给模型让它零样本发挥。你可以把这种情况想成一个聪明但没受过训练的新人单点问题它答得很漂亮可一旦任务变成一个功能要动五个文件、还要兼容旧数据、还要补测试它的每一步决策都在临时碰运气。普通 prompt 往往第一步还行到第三步就开始和第二步冲突第五步干脆把最初的需求忘了。superpowers 做的就是把这些稳定流程写成技能文件。它不是让模型变得更聪明而是让模型在正确的场景里按照已经被验证过的流程去执行减少自由发挥的空间。我对能力天花板的理解也因此改变了模型的基础智力早就够用缺的是调用方式。就像同一个员工给他一份清晰的 SOP 和让他每次都临场发挥产出的稳定性完全不同。1.2 技能的本质一段带触发条件的 Markdown 操作手册superpowers 里的技能skill本质上就是一个带 frontmatter 的 Markdown 文件。frontmatter 里的name和description是模型判断什么时候该触发它的关键正文是具体的执行步骤。下面是一个简化版的技能文件结构--- name: brainstorm_plan description: 当需求不明确、存在多个实现方案、或者需要先做方案设计再开始写代码时使用 when_to_use: 在动手编码之前如果我不确定怎么做先运行这个技能 version: 1.0.0 --- ## 执行步骤 1. 收集所有已知约束和验收条件 2. 列出至少 3 个候选方案禁止只给一个答案 3. 对每个方案做优劣势对比标记风险 4. 选型并输出分步实施计划这里有一个容易被忽略的细节CLAUDE.md 里通常只放技能索引完整技能文件是按需读取的。这非常关键。如果一开始就把几百行步骤塞进系统提示每轮对话都会白白烧掉大量 token而按需加载既省上下文又让技能文件可以随意扩充。description写得好不好直接决定 AI 会不会在正确的时机调用它。我见过太多技能不生效的案例最后查下来都是 description 太空泛模型根本判断不出该用。1.3 和 prompt 模板、IDE 插件的区别很多人会把 superpowers 理解成一个高级 prompt 模板库或IDE 插件其实都不是。它们之间有本质区别我用一张表说明维度prompt 模板IDE 插件superpowers触发方式靠用户手动复制粘贴靠 UI 按钮或快捷键模型按对话语义自动触发载体散落各处的文档专有配置和代码项目内可版本管理的 Markdown生命周期一次性使用绑定 IDE 版本可跟随项目仓库长期维护对模型可见性依赖用户临时提供模型通常看不见模型从 CLAUDE.md 感知并按需加载superpowers 更贴近 Agent 的工作方式它不是给人类看的文档也不是给 IDE 的插件而是给模型自己在运行时读取和执行的技能操作系统。这也是为什么它能同时被 Claude Code、Codex 这类终端 Agent 复用而 IDE 插件往往换一个编辑器就废了。2. 安装 superpowers十分钟跑起来的完整过程2.1 前置条件终端 Agent 已经能正常工作安装 superpowers 之前请先确认你的终端 Agent 环境是好的。我假设你已经装好了 Claude Code 或 Codex并且登录账号能正常对话。如果这一步还没搞定先去把 CLI 跑通否则后面排查起来会很痛苦。另外建议检查一下 Node.js 版本一般 18 以上就没问题。执行node -v确认。还有一个小建议第一次安装时先在一个干净的项目目录里做不要一上来就在公司老项目里折腾避免现有 CLAUDE.md 和 superpowers 的说明互相干扰把安装问题和工作问题混在一起。2.2 获取技能包并规划目录把仓库克隆到本地我习惯放在~/.superpowersgit clone https://github.com/obra/superpowers.git ~/.superpowers然后你需要把里面的技能文件放到正确的位置。这里有两个选择全局目录~/.claude/skills/所有项目都能用适合个人通用技能。项目级目录your-project/.claude/skills/跟随仓库提交适合团队协作时统一行为。我的习惯是项目级优先。团队场景下技能库应该像代码一样走 review、走版本管理这样才能保证每个人拿到的是同一套 AI 工作流。全局目录只放那些我在任何项目里都想用的通用技能比如 brainstorm_plan。目录结构大概长这样your-project/.claude/ ├── CLAUDE.md └── skills/ ├── brainstorm_plan.md ├── research.md ├── subagent.md └── implement.md如果你用的是 Codex情况稍微不同Codex 没有原生.claude/skills这个约定但可以通过 AGENTS.md 注册具体我放到后面跨工具兼容那节细说。2.3 在 CLAUDE.md / AGENTS.md 里告诉模型技能存在这一步最容易被跳过但恰恰是最关键的。技能文件放在目录里不会自己生效你必须在 CLAUDE.md或 Codex 的 AGENTS.md里明确告诉模型这里有 superpowers 技能什么时候该去读取。我一般会在 CLAUDE.md 的靠前位置写这么一段# superpowers 使用说明 本环境安装了以下技能存放在 .claude/skills/ 目录 - brainstorm_plan当需求不明确、存在多个方案、需要先设计方案时使用。 - research当需要调查代码、依赖、或外部信息时使用。 - subagent当任务较大、需要拆分成独立子任务并行处理时使用。 - implement当计划已确定、需要按步骤落地代码时使用。 当用户请求适合某个技能时先读取对应技能文件的完整内容再严格按步骤执行。不要在不需要时主动加载所有技能。为什么要放靠前位置因为模型读取项目说明时通常按文件顺序逐段处理前面的内容权重更高。如果你把这段说明埋在 CLAUDE.md 后半部分模型很可能在真正决策时已经忽略了它。Codex 环境同理写在 AGENTS.md 开头。2.4 验证安装先触发一次轻量技能验证链路安装完成后先别急着做正式任务花两分钟验证链路是否通。启动 Claude Code直接问根据 CLAUDE.md你能使用哪些 superpowers 技能各自应该在什么时候使用如果一切正常模型应该能准确列出技能名称和触发场景。如果它说我没有这些技能按这个顺序排查技能文件是否真的放在.claude/skills/下文件名拼写有没有错。CLAUDE.md 里的技能说明是否被其他内容覆盖或截断。当前会话是不是从旧对话继续的如果是先开启新会话。验证完索引再实际触发一次轻量技能。比如输入请使用 brainstorm_plan 技能帮我分析当前目录结构规划如何新增一个健康检查接口。观察模型行为它应该先读取技能文件然后按照技能里的步骤输出候选方案和计划而不是直接甩给你一段代码。到这里安装就算真正完成了。3. 核心技能逐个拆解plan、research、subagent、implement 的配合逻辑3.1 brainstorm_plan需求模糊时先穷举再收敛我用的最多的技能是 brainstorm_plan。它解决的是需求说不清楚的问题。以前直接让 AI 写代码它总喜欢第一个想到的方案而 brainstorm_plan 强制它先做发散收集约束、列出至少三个候选方案、对比优劣势、标记风险最后才输出计划。这个设计很反直觉但有实际价值。模型默认倾向于给一个答案可真正好的方案往往藏在那些被淘汰的选项里。技能通过强制步骤让模型把为什么选这个而不选那个说清楚相当于逼它把自己的思路暴露出来你才能有机会纠正方向。我通常会在 prompt 里直接点名使用 brainstorm_plan 技能帮我对“订单备注”功能做方案设计。 约束数据库是 MySQL接口需要兼容旧客户端备注长度不超过 500 字。3.2 research先查清楚再动手research 技能解决的是不懂装懂的问题。让 AI 直接改代码时它经常凭训练数据里的印象猜测 API、依赖项、项目结构结果改出来的东西根本编译不过。research 技能要求它在给出结论前先列出需要确认的事实清单然后逐个通过文件检索、搜索等手段验证并附上出处。这个技能很适合接手陌生代码库。老项目里经常有各种历史包袱某个字段叫status但取值范围是 0 到 3某个接口要兼容五年前的客户端。如果 AI 没做 research 就直接动手几乎必然出错。我在实战中发现research 的输出质量取决于你给它的调查范围。提示词越具体它的调查越聚焦比如帮我查一下 OrderMapper 里现有的 update 方法叫什么、参数是什么就比查一下项目的数据库操作方式要好得多。3.3 subagent用独立上下文跑子任务避免主线程注意力被稀释subagent 是我认为整个超能力体系里最巧妙的设计。当一个任务要改多个模块时如果让主线程从头到尾包办它到了后期往往记不住前期的决策上下文也越来越乱。subagent 的做法是把任务拆成几个子任务每个子任务用独立上下文执行最后再把结构化结果汇报给主线程。类比一下一个项目经理不会自己去写所有代码而是把清晰的任务分派给几个工程师每个人只关注自己那一亩三分地最后汇总。子代理之间互不干扰主线程也只接收总结大大降低了上下文爆炸的风险。但 subagent 对任务拆分质量要求很高边界不清的子任务汇总时会出现重复和冲突。我后面在实战案例里会具体讲到这个问题。3.4 implement把计划落地成代码而不是边写边编implement 技能负责把已经确定的计划变成代码。它的核心要求是按步骤执行、每实现一步就对照验收条件遇到偏差要么调整计划要么明确告诉用户而不是默默改写需求。很多 AI 越写越偏就是因为缺少这一步的自我校验。在实际使用中implement 通常不是孤立的。它会接收 brainstorm_plan 输出的计划结合 research 的调研结果最后执行代码变更。如果只是让 AI 直接写代码它大概率会在实现过程中灵机一动加了点新逻辑而走了 implement 流程后它会严格对照计划清单改动范围变得可控。3.5 它们不是固定流水线而是一套可组合的决策表这些技能并不是必须按顺序执行才能生效它们更像是一套积木模型根据任务类型决定组合方式。我总结了一个简单的决策表任务类型推荐技能链需求不明确的新功能brainstorm_plan - research - implement未知代码库中的 bug 修复research - implement大规模跨模块重构research - brainstorm_plan - subagent - implement简单单点修改不需要技能直接让 AI 改模型通常会自己判断但你也可以在 prompt 里指名调用减少不确定性。我一般会在重要任务开始时用一句话用 brainstorm_plan 先做方案这就相当于给 AI 上了个保险。4. 实战案例用 superpowers 在一个 Java 项目里新增 REST 接口4.1 任务描述与环境光讲理论不落地很容易虚我拿一个真实做过的 Java 项目案例来说。项目背景是 Spring Boot 3.2 MyBatis-Plus 的订单服务代码库里已经有Order实体、OrderMapper、OrderController这些类。需求是新增一个更新订单备注的接口PATCH /orders/{id}/remark请求体是 JSON 格式的{remark:...}备注最长 500 字需要更新数据库的 remark 字段并且补上单元测试。这个需求看起来很小但涉及实体变更、DTO、Controller、Service、Mapper、单测六个文件如果不做任何规划直接让 AI 写经常会出现改了 Controller 忘了实体这类问题。4.2 执行轨迹plan - research - subagent - implement第一步我触发了 brainstorm_plan使用 brainstorm_plan 技能为“更新订单备注”接口设计方案。 约束使用 Spring Boot 3.2兼容旧客户端需要单测。技能输出的方案表里给了三个候选A 是新增 DTO Service 方法B 是直接在 Controller 里 set 字段C 是做一个通用 update 接口。最终推荐 A并标出了风险点旧版客户端如果传了 null会把备注清空这需要你在计划里明确null 到底算不算合法输入。这个风险点我确实没想到是技能强制发散后才暴露出来的。第二步触发 research。我先让 AI 查几件事Order实体里是否已经有 remark 字段、OrderMapper现有 update 方法、Controller 统一返回结构、项目里单测的写法。这一步输出的结论是实体没有 remark 字段需要加Mapper 有现成的updateById单测用的是 MockMvc。这些事实让后续 subagent 不需要再浪费时间猜测。第三步拆 subagent。我把任务拆成了三个subagent A改Order实体和OrderMapper。subagent B新增UpdateRemarkRequestDTO、OrderController接口、OrderService方法。subagent C写 MockMvc 单测。每个 subagent 我都明确要求了边界只改 src/main/java不要动 pom.xml不要动其他 Controller 的接口。这个边界声明非常关键少了它子代理就会自由发挥。第四步implement 合并。三个子代理各自产出了 diff我合并后跑了一次mvn test。第一次测试果然挂了DTO 上忘记加Size(max500)校验注解导致超长文本没有被拦截。AI 根据报错日志修正了代码最终实现的 Controller 长这样PatchMapping(/{id}/remark) public ResultVoid updateRemark(PathVariable Long id, RequestBody Valid UpdateRemarkRequest request) { orderService.updateRemark(id, request.getRemark()); return Result.ok(); }4.3 实测中最花时间的不是写代码而是边界澄清整个流程下来真正花时间的不是 AI 写代码那几分钟而是边界澄清。我在这个项目里踩到了三个坑subagent A 越过了边界改了 pom.xml虽然只是加了一个依赖但如果不是我及时看 diff后面排查依赖冲突会非常痛苦plan 阶段没有定义remark 传空字符串是否允许导致写单测的子代理和改实体的子代理用了两种理解两个子代理用了相同的测试数据合并时发生了冲突。superpowers 并没有神奇地消除这些问题但它把问题提前暴露在了 plan 阶段。更重要的是它让 AI 在遇到模糊点时不再瞎猜而是会回到计划里检查甚至直接问用户。我的建议是在 brainstorm_plan 输出计划后花两分钟手动补上那些你不希望 AI 自行决策的边界条件再进入 implement。一次投入后面少走很多弯路。5. 踩坑记录技能不触发、上下文爆炸、跨工具兼容5.1 技能不触发先检查 description再检查目录技能不触发是我见过最多的问题。排查顺序很重要我的经验是先确认会话是否读取了正确的 CLAUDE.md / AGENTS.md直接让 AI 复述内容。再确认技能目录位置、文件名和 CLAUDE.md 中的描述是否一致。检查description是否写得足够具体。想想当前任务是不是简单到模型判断不需要技能。最后重启 CLI、开启新会话再试一次。我遇到过最典型的案例某个技能的 description 写得笼统只写了Use this skill for planning anything结果模型把什么请求都当成 planning频繁误触发改成当需求不明确或存在多个实现方案时使用后触发率才恢复正常。description 就像技能的门牌号门牌号写错了模型当然找不到门。5.2 技能文件太多导致上下文爆炸有人觉得技能越多越好结果把几十个技能文件全塞进项目然后在 CLAUDE.md 里把每个技能的完整内容都贴出来。这是很常见的反面教材。技能说明占用的上下文空间会在每轮对话中被重复计算token 消耗暴增同时模型的注意力也会被稀释反而开始忽略关键指令。正确做法是CLAUDE.md 只放技能索引完整技能文件按需读取核心技能控制在 10 到 15 个以内不常用的技能归档到子目录需要用的时候再让模型去读。我在项目里维持 8 个技能左右运行明显比 30 个技能时稳定。5.3 Codex 与 Claude Code 的兼容差异很多人问superpowers 是不是只能用在 Claude Code 上我在 Codex 里也试过。两者确实有差异主要体现在约定上项目Claude CodeCodex技能目录约定原生支持.claude/skills/没有统一约定需要在 AGENTS.md 声明入口文件CLAUDE.mdAGENTS.md触发方式模型根据说明自动 cat 技能文件同样可以 cat但更依赖显式说明我在 Codex 项目里的做法是在 AGENTS.md 里写清楚# superpowers 使用说明 本环境有一套技能目录 .claude/skills/包含 brainstorm_plan、research 等技能。 当任务类型匹配技能描述时先执行 cat .claude/skills/skill_name.md 读取完整内容再按照技能步骤执行。这样 Codex 就能通过显式指令找到技能文件。所以如果你同时用多个终端 Agent完全可以共用一套技能文件只需要分别为入口文件补一份说明。5.4 模型升级后技能失效这是比较隐蔽的坑模型升级后对长文本指令的遵循方式可能变化导致原来描述精确的技能开始不起作用。我遇到过新版本模型对 frontmatter 的解析粒度变化技能文件本身没动但触发率明显下降。我的应对方案是给技能文件加version字段然后在模型大版本升级后跑一遍冒烟测试用一个最简单的小任务走完技能流程看它是否正常触发。不通过就微调 description 的措辞而不是怀疑整个方案。技能库是需要持续维护的资产不是装完就一劳永逸。6. 我的使用心得什么场景值得用什么场景别硬套6.1 我用它最多的地方现在我的主力场景有三个跨模块重构、新功能从想法到落地、接手陌生代码库之前的调研。这三个场景有个共同点任务复杂到先想清楚再做的价值远大于快点动手。以前让 AI 直接写 API十个里有四个会漏参数校验和错误处理现在只要先走一遍 plan research基本不会漏因为技能强制它在动手前把边界过一遍。另外我还做了一次实践把团队里反复出现的数据库迁移 review流程固化成了一个自定义技能AI 在检测到迁移脚本时会自动检查索引缺失、超大表风险、回滚方案等问题。这个效果比任何口头提醒都稳定计算机不会忘记执行步骤。6.2 别硬套的场景superpowers 也不是万能的。碰到单行 bug、快速验证、聊天式答疑这种小任务我会直接让 AI 改不走技能流程。原因很简单技能加载本身就有一段说明和读取过程小任务硬套技能会在流程上浪费大量 token模型也显得啰嗦。怎么判断如果这个任务五句话能讲清楚就不值得启动技能链如果一件事要改三个以上文件、影响多个模块、或者需求还说不清楚那就老老实实用 superpowers。判断标准应该是任务复杂度而非项目规模。6.3 最后分享一个小习惯我现在每次开新项目第一件事就是把 superpowers 装好但第一时间会删掉一半用不上的技能。技能不是越多越好而是要跟项目形态匹配。后来我逐渐养成了一个习惯每次遇到AI 表现得特别好的流程就把它固化成一个新的技能文件放进项目里共享给团队。看着 AI 稳定地执行着自己沉淀下来的流程再想想以前每次都要在 prompt 里反复解释的时光我觉得当初花几十分钟研究安装和配目录非常值。