最近一段时间我几乎逢人就推荐一个东西给手头的 Codex或者 Claude Code看你习惯用哪个装上 superpowers。你第一次听到这个名字可能会觉得夸张但它解决的事情非常具体——默认状态下AI 编码代理更像一个问一句答一句的实习生你让它改什么它改什么你不说它就不动甚至你说得不明确它还能给你改出一堆偏离方向的东西。superpowers 的核心是一套技能库skills它把调试、重构、测试驱动开发、写实施计划这些职业习惯变成一个个独立的 Markdown 指令文件让 AI 在需要的时候按需加载对应的方法论。这篇文章是我自己从安装、配置到日常使用的完整记录包括踩过的坑、排查技巧以及在 Java 项目里的真实落地方式。不管你用的是 Codex 还是 Claude Code只要你想让 AI 从能聊天变成会干活这篇都适合你。1. 先搞清楚背景superpowers 到底在解决什么问题1.1 为什么现在的 AI 编码代理总觉得不够聪明我先说一个可能很多人都有的感受用 Codex 或者 Claude Code 写点小脚本、改点小 bug体验确实惊艳。但一旦任务是给这个模块加一个完整功能或者帮我把这个服务的性能问题彻底查一遍它就开始拉胯了。不是模型能力不够而是它没有自己的工作节奏。你问它一个问题它给一个答案你再问它再答。整个过程完全依赖你来喂指令就像带一个技术很好但没有经验的实习生你不告诉他先看哪段代码先写哪个测试他就只能凭感觉东敲一下西敲一下。更麻烦的是很多 AI 编码代理对任务的理解是单向的。你说修复登录超时问题它可能第一反应就是改超时时间配置而不是先去复现、定位、验证。问题在于大语言模型天生是预测下一个词的机器它倾向于给你一个看起来合理的答案而不是执行一套严谨的工程流程。想要让它按流程走你必须想办法把流程塞进它的思考过程里。superpowers 就是在这个背景下出现的。我在 GitHub 上看到这个项目的时候第一反应是这不就是一堆提示词吗但真正用起来后发现它跟普通提示词完全不是一个量级的东西。它由 Jesse VincentGitHub 用户名 obra发起最初是给 Claude Code 做的后来也完整支持 Codex CLI。项目的思路非常朴素把优秀工程师的工作方法拆成一个个独立的技能每个技能用一个 SKILL.md 文件描述AI 在对话过程中根据任务需要主动去读这些文件然后按照文件里的流程来工作。1.2 技能机制从全局提示词到按需加载为了让你理解这套设计的精妙之处我打个比方。传统的 prompt engineering 就像你给一个全科医生写了一份超长的岗位说明书里面同时包含内科、外科、儿科、皮肤科的所有操作规范。先不说这份说明书写不写得完就算写完了医生在接诊一个感冒患者的时候脑子里还得同时装着心脏手术的流程这对决策质量是巨大的干扰而且上下文窗口也撑不住。superpowers 的做法完全不同。它把医生的各种能力拆成独立科室每个科室一份规范。患者来了先判断是哪个科的问题再调出对应的规范来执行。在 AI 编码代理的场景里这个科室就是技能文件夹规范就是 SKILL.md。代理在对话中发现自己需要调试能力就会主动去读 debugging 技能的 SKILL.md需要写计划就去读 writing-plans 的技能文件。按需加载的最大好处是上下文窗口里永远只有当前任务真正需要的那一套方法论不会因为规则太多而互相干扰。我实际测试下来还有一个感受技能加载不只是一个把文件塞进上下文的动作它会明显改变 AI 的对话风格。比如加载了 debugging 技能之后AI 遇到问题会先尝试复现然后列假设接着验证而不是一上来就给你改代码。这种行为风格的变化比它具体说了什么更重要因为行为风格决定了整个任务的执行质量。1.3 它不是什么先把预期管理做好在讲安装之前我先把边界说清楚免得你装完觉得被坑了。superpowers 不改变底层模型。它不会让你手里的 GPT 模型突然变成另一个更强的模型它改变的是模型的工作方式。同一个模型加载了技能和没加载技能处理同一个任务的表现可以差很多但它的知识上限、推理能力天花板不变。另外它也不是自动化魔法。不要以为装上之后你输入一句帮我完成这个项目它就能全程自主搞定所有事情。它仍然需要你提供上下文、确认计划、在关键节点做决策。它真正省下的是那些重复沟通成本你能不能先看看代码你能不能先写个测试你能不能先告诉我思路——这些它自己会做了。明确这一点之后我们再往下聊安装和配置才不容易跑偏。我的判断是如果你平时只是拿 AI 写点一次性脚本superpowers 的价值有限但如果你在真实项目里长期使用 AI 代理它带来的体验提升是非常明显的。2. 安装与配置看似简单坑其实不少2.1 环境准备需要什么、不需要什么第一次装的时候我犯了所有急性子都会犯的错没看 README直接 git clone 下来就跑安装脚本。结果脚本弹了一堆交互式问题我选错了目录后面又得重来一遍。如果你也想装先把前置条件准备好五分钟能搞定。一个能正常工作的 Node.js 环境。版本建议 18 以上因为安装脚本和一些辅助解析逻辑依赖新版特性老版本容易在一些边角报错。已经装好并完成登录认证的 Codex CLI 或 Claude Code。注意光装了不行得能用起来。装完没登录过后面的技能链接即使配好代理也起不来。能正常访问 GitHub。这个看起来是废话但在我帮朋友装的时候发现公司内网环境、代理环境经常在这一步卡住。clone 不下来后面全白搭。操作系统方面没必要太讲究。macOS、Linux 都行Windows 用户建议直接用 WSL省得碰到符号链接权限和路径分隔符问题。我自己在 macOS 和 Ubuntu 上都跑过没遇到明显的环境差异。2.2 完整安装命令与交互选项含义安装流程本身不复杂推荐的方式是 clone 到独立目录再执行安装脚本git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh脚本运行后会先检测你机器上装了哪些 AI 代理工具然后进入交互式问答。我把它问的几个问题翻译成人话要配置给哪个代理选项包括 Claude Code、Codex或者两个都配。如果你平时两个都用建议直接选全部省得以后切换工具的时候技能不可用。技能装到用户全局目录还是当前项目目录全局目录意味着你机器上的所有项目都能用这套技能项目目录则只对当前文件夹生效。是否需要安装配套的编辑器/CLI 插件检测到相关插件环境时会问这一项不确定就直接默认。这里我要重点说第二项因为这是最容易让人事后后悔的决策。如果你只是想试试水选当前项目目录没问题装错了也不影响别的工程。但如果你决定长期用我个人建议直接选全局目录。原因很简单你不可能预料到哪个项目明天就会用到它全局装上之后在任何项目里都能直接享受技能加持不需要再回仓库里折腾一遍。我一开始图省事选了项目目录后来换全局的时候还要手动清理旧符号链接反而更麻烦。2.3 全局与项目级安装的取舍逻辑关于全局和项目级的选择我再说透一点。全局安装的本质是在你的用户配置目录比如~/.claude/skills或~/.codex/skills里创建一批指向 superpowers 仓库的符号链接。这样做的好处是技能文件只有一个副本更新 superpowers 仓库就能全局生效不会出现每个项目里技能版本不一致的混乱。项目级安装适合一种情况你希望某一个项目使用特定版本的技能、或者团队统一锁定一套技能集避免某个成员更新技能导致行为不一致。这种情况下把技能放进项目仓库配合 AGENTS.md 或 CLAUDE.md 一起提交确实能实现团队层面的统一约束。但说实话对个人开发者来说全局安装的收益远大于项目级我建议大家默认选全局。安装完成后验证一下符号链接是否真的建出来了ls -la ~/.claude/skills # 或者 ~/.codex/skills如果能看到类似debugging - /path/to/superpowers/skills/debugging的条目说明文件层面已经通了。2.4 装完后的最低验收清单文件链接有了不代表 AI 就真的学会了。我每次装完新环境会做这么两步验证第一步是直接开一个 Codex 或 Claude Code 会话输入一句话请查看你的可用技能列表告诉我你加载了哪些能力。如果它回答里提到了 superpowers、SKILL.md、或者具体的技能名比如 debugging说明链路是通的。如果它只是泛泛地说我可以写代码、可以分析问题那基本可以断定它没读到技能目录。第二步是逼它实际加载一个技能。比如我有一个 bug 要调查请先加载 debugging 技能再开始分析。注意观察它的回应方式加载成功的话它会先复述一下技能的核心流程或者告诉你接下来会按什么步骤走。如果你看到它直接开始给代码修改建议说明技能加载被忽略了绝大多数情况是配置路径错误后面排查章节我会详细讲。3. 核心机制拆解SKILL.md 与技能体系3.1 一个技能就是一个文件夹别觉得它神秘很多人第一次看到 superpowers 的仓库结构时会被吓到觉得这里面东西太多了。其实剥开来看每一个技能就是一个普通文件夹里面最重要的文件就一个SKILL.md。拿 debugging 技能举例打开 SKILL.md 你会发现它本质上是一篇写得非常好的 Markdown 文档包含几个固定部分技能用途在什么场景下该加载这个技能。工作流程用有序步骤描述整个调试过程比如先复现、再收集信息、再列假设、再验证、最后修复。行为约束明确写清楚不要在没有复现的情况下修改代码这类反面清单。输出格式告诉 AI 在向用户汇报时应保持什么结构比如先输出调查过程再输出结论和修复建议。这个文件的长度通常在几十行到几百行不等完全由人编写和迭代。它既不是代码也不是什么额外的模型参数就是一份经过反复打磨的方法论说明书。但它之所以有效是因为它被放在了 AI 代理能主动读取的位置并且项目通过约定告诉 AI这些技能可供你使用。到这里你就明白了superpowers 并没有什么黑魔法。它的聪明之处不是发明了新机制而是找到了一个极其高效的表达方式把资深工程师的经验结构化地喂给了模型。3.2 加载原理与上下文窗口的优化之道那 AI 到底在什么时机去读这些文件这个问题我研究过也问过第一作者结论是靠的是 SKILL.md 文件头部的特殊标注以及代理自身的工具调用能力。具体来说AI 编码代理本身有读取本地文件的工具能力superpowers 通过系统级的说明告诉代理你有一批技能可用技能的元数据在 xx 目录当用户的任务符合某个技能的场景时你应当主动读取该技能的 SKILL.md并严格遵循其中的流程。 当代理决定读取某个 SKILL.md就是把一整段方法论加载进了当前会话的上下文窗口。这就是技能加载的全过程。这种设计的上下文效率远高于把所有技能一次性注入。我算过一笔账superpowers 里我有十几个常用技能每个 SKILL.md 平均几千字符如果全部塞进系统提示词一次会话的上下文成本会暴涨到不可用的程度。而按需加载模式下大部分时间里上下文窗口里根本没有技能内容只有当你需要调试时debugging 的方法论才会被读进来用完也可以逐步被新内容顶出窗口不会长期占用。3.3 常用技能深度解析哪些最值得打开我之前说过不要一次全开但为了让你有一个全局视野我把最核心的几个技能逐一讲一下这样你在选择时心里有数。debugging 是我用得最多的技能。它的流程设计非常老派先复现问题再收集运行数据通过二分定位到根因最后才动手修复。这个流程看起来平淡无奇但对 AI 来说极其重要。模型天生是答案生成器不给它流程约束它会跳过调查直接给修复这是很多 bug 反复修不好的根本原因。加载 debugging 技能之后AI 会主动要求复现路径和日志而不是闭着眼睛改代码。writing-plans 的价值则在于方向把控。每次接一个复杂任务它会要求 AI 先阅读相关代码列出实施步骤、涉及文件、风险点然后等你确认。这个先计划后动手的习惯能帮你拦下大量跑偏。我试过让 AI 不写计划直接做和写了计划确认后再做返工率不是一个数量级。test-driven-development 技能把经典的 TDD 流程带进了 AI 会话。先写失败测试、再实现、再重构这个流程对人类工程师都很反直觉更何况对模型。但技能文件里写得很清楚AI 执行起来竟然比人类更守纪律因为它不会嫌麻烦。我实测用这个技能处理一个 Java 后端模块测试先行确实能显著减少回归问题。还有 checkpointing 和 work-in-progress这两个技能解决的是一切模型的通病——上下文记忆。checkpointing 会让 AI 把任务进度写到本地文件work-in-progress 则让它在会话中持续维护一个未完成清单。这两个技能组合使用基本能让你随时中断、随时恢复长任务后面实操章节我会给具体用法。3.4 Java 项目里怎么落地从构建命令到调试流程现在聊一下很多人搜的 superpowers java。很多朋友关心这套东西在 Java 工程里是否适用我的回答是语言无关但准备工作要做足。Java 项目跟 Node 或 Python 项目最大的区别是构建体系复杂动不动就是 Maven 多模块、Gradle 多子项目AI 不知道你的构建命令就寸步难行。superpowers 的技能文件里可不会写你的项目怎么编译。我强烈建议你在项目根目录的 AGENTS.md或 CLAUDE.md里把构建信息写清楚比如测试命令: ./gradlew test --tests com.example.ClassName 单元测试运行: ./gradlew test 构建打包: ./gradlew build 依赖解析: ./gradlew dependencies写清楚了AI 在调试时就不用瞎猜命令。别小看这一步我见过太多案例AI 以为项目用的 Maven一直在敲 mvn test结果项目其实是 Gradle每次都是报错然后换一个命令效率极低。把构建命令写进项目上下文这个坑直接绕开。至于调试流程Java 项目通常是这些场景编译失败、测试失败、依赖冲突、运行期异常、性能问题。不管哪种superpowers 的 debugging 技能都能起到流程刹车的作用。我处理过一个真实的 Spring Boot 服务偶发超时问题AI 没有一上来就改超时配置而是按 debugging 技能先要求复现再建议抓线程栈最后定位到一个过小的线程池。这个过程如果靠普通对话AI 大概率已经开始给你改配置了。还有一个小技巧Java 工程一般会生成很多日志和构建产物我会在 prompt 里明确告诉 AI不要全仓库扫描重点看 src 和 build.gradle / pom.xml避免它把上下文窗口浪费在一堆无关文件上。这个对控制 token 消耗非常重要。4. 完整实操用一套黄金工作流把 superpowers 用起来4.1 会话开场白别让它瞎跑先定向装了 superpowers 之后第一件事是改变你和 AI 的对话习惯。很多人的默认开场是帮我写一个 XX这没问题但对复杂任务来说把期望讲清楚会更好。我自己的标准开场是先不要动手写代码。请查看项目结构然后加载 writing-plans 技能为以下任务写一个实施计划。计划要包含涉及的文件、修改步骤、风险点写完先给我确认。这段话有三个关键点。第一先不要动手写代码是给 AI 上刹车防止它一上来就改文件。第二加载 writing-plans 技能是触发技能机制让它把计划方法论读进来。第三写完先给我确认是设置检查点确保方向不对时我能及时纠正。实测下来这个开场能让 AI 的输出质量提升一个档次。它会把任务拆成步骤而不是直接给一大段代码让你自己去消化。你确认计划的过程也是帮助它理解你真实需求的过程——很多需求最初就是模糊的有了计划稿你自己也能看清哪里想清楚了、哪里还没想清楚。4.2 计划 TDD 执行我最推崇的黄金组合实操中最值钱的组合拳是writing-plans 做计划test-driven-development 做执行checkpointing 做保障。一个中等复杂度的功能我通常按下面的步骤走让 AI 读仓库结构用 writing-plans 输出实施计划。我审查计划增删步骤明确边界。确认计划后让 AI按照 TDD 流程开始实现。AI 先写一个失败的测试运行确认是红色。再写实现代码直至测试变绿。如果涉及重构让 AI 在测试保护下小步调整。每完成一个阶段用 checkpointing 技能把状态记录到文件中。这条链路走下来AI 的工作不再是一阵乱拳而是一条有节奏的生产线。它也不会问你下一步做什么因为计划里已经写好了。你要做的就是在关键节点审查结果。我用这个流程处理过一个改造任务给内部管理后台加一个导出功能。整个任务涉及后端接口、异步任务、权限控制、前端按钮。按以前的用法AI 大概率会闷头把前后端都改了然后留下一堆我没法确认的修改。但用了这套流程后它在计划阶段就暴露了一个我没想到的边界问题权限校验放在哪个层级。这个问题要是在代码写完后再发现返工成本高得多。4.3 checkpoint 与多会话恢复让长任务不再失忆AI 对话最让人头疼的一点是一旦上下文超了或者你不小心关了终端前面聊的全部归零。checkpointing 就是专门对付这个的。它的工作原理很简单技能会要求 AI 在特定时机把你的任务状态写入一个本地文件通常叫 checkpoint.md 或者类似的名字。文件内容大致包含当前目标、已完成步骤、进行中的工作、遇到的问题、下一步计划。当你的会话中断重新打开终端后只需要对它说读取 checkpoint.md继续之前的工作。AI 就会读取文件恢复上下文接着上次的进度往下走。这个体验和以前这咱们刚才说到哪了的对话相比完全是质变。不过这个技能需要调教一下不然它会记录得太碎。比如把更新了 README 错别字也写进目标里既占用文件空间也会在恢复时干扰 AI 对优先级的判断。我在会话一开始就会附加一句checkpoint 只记录与本次交付目标相关的关键状态琐碎操作不用记。这句话能让 checkpoint 的含金量高很多。还有一点要注意如果你在多人协作的仓库里干活把 checkpoint 文件加进 .gitignore。我已经吃过亏了AI 自动生成的 checkpoint.md 被提交进代码仓库还顺着 merge request 流到了主干看起来非常业余。4.4 一次会话别加载太多技能贪多嚼不烂superpowers 用熟了以后你会忍不住一次给 AI 布置好几个技能请加载 debugging、code-review、refactoring、TDD一起把这个问题解决。我试过几次结果都不理想。原因是模型在多个方法论之间切换是有成本的。每个技能都有自己的流程约束同时激活三四个它们会在冲突的时候互相干扰。比如 debugging 要求先验证再动手code-review 要求发现所有潜在问题refactoring 要求保持行为不变三个技能同时激活AI 可能在还没复现问题的时候就开始大谈代码坏味道然后给你列出一堆重构建议。我的经验是一次会话里保持两到三个技能是最佳甜点区。核心技能比如计划或调试常驻辅助技能按需临时加载用完就让它结束该技能回到常规模式。这样既享受了多技能的好处又不至于让模型精神分裂。5. 常见问题与排查技巧实录5.1 一张表解决 90% 的安装/加载问题我整理了这段时间被问得最多的问题做成速查表你可以直接对着排查。现象可能原因处理方式技能符号链接不存在安装时选错了目录重跑 install.sh或手动 ln -s 建链接AI 提到技能但没有加载上下文里看不到技能目录检查路径配置确认 ~/.claude/skills 存在加载技能后行为没变化会话有缓存或环境变量覆盖开新会话重试检查自定义提示词安装脚本卡在交互选项终端不支持图形化交互设置环境变量跳过交互或换一个终端Java 项目里 AI 一直猜测构建命令项目上下文没写清楚在 AGENTS.md 里写明 gradle/maven 命令checkpoint 文件被提交进 Git没有忽略该文件加入 .gitignore 并清理历史记录5.2 技能不生效的几个隐蔽原因速查表覆盖了表面问题我再讲三个更难发现的坑。第一个是技能被同名文件夹干扰。很多项目里自带了一个空的 skills 目录结果代理按路径搜索时优先命中这个空目录全局技能的链接反而没被读取。解决方法是把项目内的 skills 目录重命名或者确认代理的技能搜索顺序。第二个是上下文缓存。Codex 和 Claude Code 都会对已经读取过的上下文做缓存尤其是同一个会话内AI 不会反复读 SKILL.md。如果你中途修改了技能文件或者刚装好技能就在旧会话里测试很可能发现行为没变化。这时候别怀疑配置错了先开一个新会话再说。第三个是你自己的自定义提示词太强势。如果你在系统提示词里写了很多你必须怎样怎样的规则模型会把这些规则和技能流程混合执行甚至直接优先执行你的指令把技能晾在一边。我的建议是系统提示词里只写业务性和安全性的硬规则把工作流方法论的管理权交给 superpowers二者不要重叠太多。5.3 上下文超长与 token 成本失控的对策技能按需加载已经大幅降低了上下文压力但大型仓库场景下还是会因为 AI 主动读文件太多而爆窗口。我常用的几个手段缩小阅读范围。明确说只读 src/main/java/com/example/service 目录下的文件其他不要看比了解这个项目有效得多。用 git 历史代替全文。让 AI 执行git log --oneline -20看提交历史快速了解演进过程不需要把所有代码读一遍。长任务分段。把一次交付拆成多个阶段每阶段结束用 checkpoint 保存状态然后开新会话继续。这既省上下文又让每段对话都聚焦。监控 token 消耗。我一般会留意每轮对话的输出长度如果 AI 开始输出大段分析和重复读文件及时打断并让它收敛任务范围。成本这块我也说句实话装上 superpowers 之后单次会话消耗的 token 确实会变多因为 AI 干的活多了、分析过程长了。但总体成本反而可能下降因为返工和无效代码量大幅减少。我个人的经验是复杂任务用这套流程整体支出比裸用 Codex 还要省原因是做对一次的成本永远低于改错三次。6. 实操心得与进阶玩法6.1 我的个人技能清单与使用习惯如果只保留三个技能我会选 writing-plans、debugging、checkpointing。这三者构成一个最小闭环先有方向再能执行最后能续命。几乎所有的中等复杂度任务都能靠这三位搞定。code-review 和 refactoring 我按需启用。它们很好用但容易让 AI 在没有明确重构需求的时候主动挑战代码风格制造无谓的大 diff。我的习惯是明确到只 review 我指出的文件或只重构这一段逻辑不要动其他部分。checklists 技能我平时不用但在发布版本、做数据迁移这类高风险操作时会让它生成清单并逐项确认这比人工列清单更不容易遗漏。6.2 自定义团队技能的推荐做法superpowers 真正的杀手锏是你可以给它加技能而且门槛低到离谱。我给团队写过一个 release-prep 技能内容就是发布前的检查事项版本号是否递增、更新日志是否补充、测试套件是否全绿、依赖是否有安全更新。做法很简单在技能目录下新建一个文件夹写一个 SKILL.md 就可以。# Release Prep 当用户需要准备版本发布时加载本技能。流程如下 1. 检查 CHANGELOG.md确认本次版本的变更均已记录。 2. 检查版本号确保符合语义化版本规则。 3. 运行完整测试套件确认所有测试通过。 4. 扫描依赖列出有版本更新的库和潜在兼容性风险。 5. 将以上信息整理成一份发布确认清单交给用户确认。写自定义技能有三个原则单一职责、流程明确、可验证。一个技能只做一件事步骤用有序列表每个步骤要能明确判断完成与否。这样写出来的技能模型才容易理解和执行。你现在打开任何一个内置技能的 SKILL.md都能看到这个风格的影子照着写基本不会错。6.3 最后分享几个实在的避坑技巧安装阶段建议把 superpowers 仓库单独放在一个目录不要放在项目工程里否则每次切换项目都要重新配置路径。我自己的做法是放在~/tools/superpowers脚本装完后再全局链接。使用阶段遇到大任务时先在对话里明确输出要求比如计划的每一步都要写清楚涉及的文件和验证方式。这能显著降低事后返工的概率。我试过有时候 AI 的计划写得太抽象每个步骤都是优化相关逻辑这种废话加了这句话之后输出质量明显变好。还有一个通用技巧对于 Java 这类编译型项目遇到诡异问题时让 AI 先把报错日志完整读一遍再说话不要让它根据印象猜测。很多AI 改错代码的案例其实都是因为上下文里没有足够的报错信息它只能基于概率补全一个错误答案。我自己用下来的体会是superpowers 真正改变的不是模型而是工作方式。它让 AI 编码代理从问一句答一句变成了有节奏地推进任务。虽然它不能替代人类的判断但至少省下了大量重复沟通的成本。如果你也受够了 AI 答非所问、动不动就大改代码我觉得给它装上这套技能是目前性价比最高的升级方式。最后一个小建议别一次全开先挑最痛痛的场景用起来比如让 AI 带着 debugging 技能去查一天 bug你会发现它比想象中实用得多。
最近一段时间我几乎逢人就推荐一个东西给手头的 Codex或者 Claude Code看你习惯用哪个装上 superpowers。你第一次听到这个名字可能会觉得夸张但它解决的事情非常具体——默认状态下AI 编码代理更像一个问一句答一句的实习生你让它改什么它改什么你不说它就不动甚至你说得不明确它还能给你改出一堆偏离方向的东西。superpowers 的核心是一套技能库skills它把调试、重构、测试驱动开发、写实施计划这些职业习惯变成一个个独立的 Markdown 指令文件让 AI 在需要的时候按需加载对应的方法论。这篇文章是我自己从安装、配置到日常使用的完整记录包括踩过的坑、排查技巧以及在 Java 项目里的真实落地方式。不管你用的是 Codex 还是 Claude Code只要你想让 AI 从能聊天变成会干活这篇都适合你。1. 先搞清楚背景superpowers 到底在解决什么问题1.1 为什么现在的 AI 编码代理总觉得不够聪明我先说一个可能很多人都有的感受用 Codex 或者 Claude Code 写点小脚本、改点小 bug体验确实惊艳。但一旦任务是给这个模块加一个完整功能或者帮我把这个服务的性能问题彻底查一遍它就开始拉胯了。不是模型能力不够而是它没有自己的工作节奏。你问它一个问题它给一个答案你再问它再答。整个过程完全依赖你来喂指令就像带一个技术很好但没有经验的实习生你不告诉他先看哪段代码先写哪个测试他就只能凭感觉东敲一下西敲一下。更麻烦的是很多 AI 编码代理对任务的理解是单向的。你说修复登录超时问题它可能第一反应就是改超时时间配置而不是先去复现、定位、验证。问题在于大语言模型天生是预测下一个词的机器它倾向于给你一个看起来合理的答案而不是执行一套严谨的工程流程。想要让它按流程走你必须想办法把流程塞进它的思考过程里。superpowers 就是在这个背景下出现的。我在 GitHub 上看到这个项目的时候第一反应是这不就是一堆提示词吗但真正用起来后发现它跟普通提示词完全不是一个量级的东西。它由 Jesse VincentGitHub 用户名 obra发起最初是给 Claude Code 做的后来也完整支持 Codex CLI。项目的思路非常朴素把优秀工程师的工作方法拆成一个个独立的技能每个技能用一个 SKILL.md 文件描述AI 在对话过程中根据任务需要主动去读这些文件然后按照文件里的流程来工作。1.2 技能机制从全局提示词到按需加载为了让你理解这套设计的精妙之处我打个比方。传统的 prompt engineering 就像你给一个全科医生写了一份超长的岗位说明书里面同时包含内科、外科、儿科、皮肤科的所有操作规范。先不说这份说明书写不写得完就算写完了医生在接诊一个感冒患者的时候脑子里还得同时装着心脏手术的流程这对决策质量是巨大的干扰而且上下文窗口也撑不住。superpowers 的做法完全不同。它把医生的各种能力拆成独立科室每个科室一份规范。患者来了先判断是哪个科的问题再调出对应的规范来执行。在 AI 编码代理的场景里这个科室就是技能文件夹规范就是 SKILL.md。代理在对话中发现自己需要调试能力就会主动去读 debugging 技能的 SKILL.md需要写计划就去读 writing-plans 的技能文件。按需加载的最大好处是上下文窗口里永远只有当前任务真正需要的那一套方法论不会因为规则太多而互相干扰。我实际测试下来还有一个感受技能加载不只是一个把文件塞进上下文的动作它会明显改变 AI 的对话风格。比如加载了 debugging 技能之后AI 遇到问题会先尝试复现然后列假设接着验证而不是一上来就给你改代码。这种行为风格的变化比它具体说了什么更重要因为行为风格决定了整个任务的执行质量。1.3 它不是什么先把预期管理做好在讲安装之前我先把边界说清楚免得你装完觉得被坑了。superpowers 不改变底层模型。它不会让你手里的 GPT 模型突然变成另一个更强的模型它改变的是模型的工作方式。同一个模型加载了技能和没加载技能处理同一个任务的表现可以差很多但它的知识上限、推理能力天花板不变。另外它也不是自动化魔法。不要以为装上之后你输入一句帮我完成这个项目它就能全程自主搞定所有事情。它仍然需要你提供上下文、确认计划、在关键节点做决策。它真正省下的是那些重复沟通成本你能不能先看看代码你能不能先写个测试你能不能先告诉我思路——这些它自己会做了。明确这一点之后我们再往下聊安装和配置才不容易跑偏。我的判断是如果你平时只是拿 AI 写点一次性脚本superpowers 的价值有限但如果你在真实项目里长期使用 AI 代理它带来的体验提升是非常明显的。2. 安装与配置看似简单坑其实不少2.1 环境准备需要什么、不需要什么第一次装的时候我犯了所有急性子都会犯的错没看 README直接 git clone 下来就跑安装脚本。结果脚本弹了一堆交互式问题我选错了目录后面又得重来一遍。如果你也想装先把前置条件准备好五分钟能搞定。一个能正常工作的 Node.js 环境。版本建议 18 以上因为安装脚本和一些辅助解析逻辑依赖新版特性老版本容易在一些边角报错。已经装好并完成登录认证的 Codex CLI 或 Claude Code。注意光装了不行得能用起来。装完没登录过后面的技能链接即使配好代理也起不来。能正常访问 GitHub。这个看起来是废话但在我帮朋友装的时候发现公司内网环境、代理环境经常在这一步卡住。clone 不下来后面全白搭。操作系统方面没必要太讲究。macOS、Linux 都行Windows 用户建议直接用 WSL省得碰到符号链接权限和路径分隔符问题。我自己在 macOS 和 Ubuntu 上都跑过没遇到明显的环境差异。2.2 完整安装命令与交互选项含义安装流程本身不复杂推荐的方式是 clone 到独立目录再执行安装脚本git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh脚本运行后会先检测你机器上装了哪些 AI 代理工具然后进入交互式问答。我把它问的几个问题翻译成人话要配置给哪个代理选项包括 Claude Code、Codex或者两个都配。如果你平时两个都用建议直接选全部省得以后切换工具的时候技能不可用。技能装到用户全局目录还是当前项目目录全局目录意味着你机器上的所有项目都能用这套技能项目目录则只对当前文件夹生效。是否需要安装配套的编辑器/CLI 插件检测到相关插件环境时会问这一项不确定就直接默认。这里我要重点说第二项因为这是最容易让人事后后悔的决策。如果你只是想试试水选当前项目目录没问题装错了也不影响别的工程。但如果你决定长期用我个人建议直接选全局目录。原因很简单你不可能预料到哪个项目明天就会用到它全局装上之后在任何项目里都能直接享受技能加持不需要再回仓库里折腾一遍。我一开始图省事选了项目目录后来换全局的时候还要手动清理旧符号链接反而更麻烦。2.3 全局与项目级安装的取舍逻辑关于全局和项目级的选择我再说透一点。全局安装的本质是在你的用户配置目录比如~/.claude/skills或~/.codex/skills里创建一批指向 superpowers 仓库的符号链接。这样做的好处是技能文件只有一个副本更新 superpowers 仓库就能全局生效不会出现每个项目里技能版本不一致的混乱。项目级安装适合一种情况你希望某一个项目使用特定版本的技能、或者团队统一锁定一套技能集避免某个成员更新技能导致行为不一致。这种情况下把技能放进项目仓库配合 AGENTS.md 或 CLAUDE.md 一起提交确实能实现团队层面的统一约束。但说实话对个人开发者来说全局安装的收益远大于项目级我建议大家默认选全局。安装完成后验证一下符号链接是否真的建出来了ls -la ~/.claude/skills # 或者 ~/.codex/skills如果能看到类似debugging - /path/to/superpowers/skills/debugging的条目说明文件层面已经通了。2.4 装完后的最低验收清单文件链接有了不代表 AI 就真的学会了。我每次装完新环境会做这么两步验证第一步是直接开一个 Codex 或 Claude Code 会话输入一句话请查看你的可用技能列表告诉我你加载了哪些能力。如果它回答里提到了 superpowers、SKILL.md、或者具体的技能名比如 debugging说明链路是通的。如果它只是泛泛地说我可以写代码、可以分析问题那基本可以断定它没读到技能目录。第二步是逼它实际加载一个技能。比如我有一个 bug 要调查请先加载 debugging 技能再开始分析。注意观察它的回应方式加载成功的话它会先复述一下技能的核心流程或者告诉你接下来会按什么步骤走。如果你看到它直接开始给代码修改建议说明技能加载被忽略了绝大多数情况是配置路径错误后面排查章节我会详细讲。3. 核心机制拆解SKILL.md 与技能体系3.1 一个技能就是一个文件夹别觉得它神秘很多人第一次看到 superpowers 的仓库结构时会被吓到觉得这里面东西太多了。其实剥开来看每一个技能就是一个普通文件夹里面最重要的文件就一个SKILL.md。拿 debugging 技能举例打开 SKILL.md 你会发现它本质上是一篇写得非常好的 Markdown 文档包含几个固定部分技能用途在什么场景下该加载这个技能。工作流程用有序步骤描述整个调试过程比如先复现、再收集信息、再列假设、再验证、最后修复。行为约束明确写清楚不要在没有复现的情况下修改代码这类反面清单。输出格式告诉 AI 在向用户汇报时应保持什么结构比如先输出调查过程再输出结论和修复建议。这个文件的长度通常在几十行到几百行不等完全由人编写和迭代。它既不是代码也不是什么额外的模型参数就是一份经过反复打磨的方法论说明书。但它之所以有效是因为它被放在了 AI 代理能主动读取的位置并且项目通过约定告诉 AI这些技能可供你使用。到这里你就明白了superpowers 并没有什么黑魔法。它的聪明之处不是发明了新机制而是找到了一个极其高效的表达方式把资深工程师的经验结构化地喂给了模型。3.2 加载原理与上下文窗口的优化之道那 AI 到底在什么时机去读这些文件这个问题我研究过也问过第一作者结论是靠的是 SKILL.md 文件头部的特殊标注以及代理自身的工具调用能力。具体来说AI 编码代理本身有读取本地文件的工具能力superpowers 通过系统级的说明告诉代理你有一批技能可用技能的元数据在 xx 目录当用户的任务符合某个技能的场景时你应当主动读取该技能的 SKILL.md并严格遵循其中的流程。 当代理决定读取某个 SKILL.md就是把一整段方法论加载进了当前会话的上下文窗口。这就是技能加载的全过程。这种设计的上下文效率远高于把所有技能一次性注入。我算过一笔账superpowers 里我有十几个常用技能每个 SKILL.md 平均几千字符如果全部塞进系统提示词一次会话的上下文成本会暴涨到不可用的程度。而按需加载模式下大部分时间里上下文窗口里根本没有技能内容只有当你需要调试时debugging 的方法论才会被读进来用完也可以逐步被新内容顶出窗口不会长期占用。3.3 常用技能深度解析哪些最值得打开我之前说过不要一次全开但为了让你有一个全局视野我把最核心的几个技能逐一讲一下这样你在选择时心里有数。debugging 是我用得最多的技能。它的流程设计非常老派先复现问题再收集运行数据通过二分定位到根因最后才动手修复。这个流程看起来平淡无奇但对 AI 来说极其重要。模型天生是答案生成器不给它流程约束它会跳过调查直接给修复这是很多 bug 反复修不好的根本原因。加载 debugging 技能之后AI 会主动要求复现路径和日志而不是闭着眼睛改代码。writing-plans 的价值则在于方向把控。每次接一个复杂任务它会要求 AI 先阅读相关代码列出实施步骤、涉及文件、风险点然后等你确认。这个先计划后动手的习惯能帮你拦下大量跑偏。我试过让 AI 不写计划直接做和写了计划确认后再做返工率不是一个数量级。test-driven-development 技能把经典的 TDD 流程带进了 AI 会话。先写失败测试、再实现、再重构这个流程对人类工程师都很反直觉更何况对模型。但技能文件里写得很清楚AI 执行起来竟然比人类更守纪律因为它不会嫌麻烦。我实测用这个技能处理一个 Java 后端模块测试先行确实能显著减少回归问题。还有 checkpointing 和 work-in-progress这两个技能解决的是一切模型的通病——上下文记忆。checkpointing 会让 AI 把任务进度写到本地文件work-in-progress 则让它在会话中持续维护一个未完成清单。这两个技能组合使用基本能让你随时中断、随时恢复长任务后面实操章节我会给具体用法。3.4 Java 项目里怎么落地从构建命令到调试流程现在聊一下很多人搜的 superpowers java。很多朋友关心这套东西在 Java 工程里是否适用我的回答是语言无关但准备工作要做足。Java 项目跟 Node 或 Python 项目最大的区别是构建体系复杂动不动就是 Maven 多模块、Gradle 多子项目AI 不知道你的构建命令就寸步难行。superpowers 的技能文件里可不会写你的项目怎么编译。我强烈建议你在项目根目录的 AGENTS.md或 CLAUDE.md里把构建信息写清楚比如测试命令: ./gradlew test --tests com.example.ClassName 单元测试运行: ./gradlew test 构建打包: ./gradlew build 依赖解析: ./gradlew dependencies写清楚了AI 在调试时就不用瞎猜命令。别小看这一步我见过太多案例AI 以为项目用的 Maven一直在敲 mvn test结果项目其实是 Gradle每次都是报错然后换一个命令效率极低。把构建命令写进项目上下文这个坑直接绕开。至于调试流程Java 项目通常是这些场景编译失败、测试失败、依赖冲突、运行期异常、性能问题。不管哪种superpowers 的 debugging 技能都能起到流程刹车的作用。我处理过一个真实的 Spring Boot 服务偶发超时问题AI 没有一上来就改超时配置而是按 debugging 技能先要求复现再建议抓线程栈最后定位到一个过小的线程池。这个过程如果靠普通对话AI 大概率已经开始给你改配置了。还有一个小技巧Java 工程一般会生成很多日志和构建产物我会在 prompt 里明确告诉 AI不要全仓库扫描重点看 src 和 build.gradle / pom.xml避免它把上下文窗口浪费在一堆无关文件上。这个对控制 token 消耗非常重要。4. 完整实操用一套黄金工作流把 superpowers 用起来4.1 会话开场白别让它瞎跑先定向装了 superpowers 之后第一件事是改变你和 AI 的对话习惯。很多人的默认开场是帮我写一个 XX这没问题但对复杂任务来说把期望讲清楚会更好。我自己的标准开场是先不要动手写代码。请查看项目结构然后加载 writing-plans 技能为以下任务写一个实施计划。计划要包含涉及的文件、修改步骤、风险点写完先给我确认。这段话有三个关键点。第一先不要动手写代码是给 AI 上刹车防止它一上来就改文件。第二加载 writing-plans 技能是触发技能机制让它把计划方法论读进来。第三写完先给我确认是设置检查点确保方向不对时我能及时纠正。实测下来这个开场能让 AI 的输出质量提升一个档次。它会把任务拆成步骤而不是直接给一大段代码让你自己去消化。你确认计划的过程也是帮助它理解你真实需求的过程——很多需求最初就是模糊的有了计划稿你自己也能看清哪里想清楚了、哪里还没想清楚。4.2 计划 TDD 执行我最推崇的黄金组合实操中最值钱的组合拳是writing-plans 做计划test-driven-development 做执行checkpointing 做保障。一个中等复杂度的功能我通常按下面的步骤走让 AI 读仓库结构用 writing-plans 输出实施计划。我审查计划增删步骤明确边界。确认计划后让 AI按照 TDD 流程开始实现。AI 先写一个失败的测试运行确认是红色。再写实现代码直至测试变绿。如果涉及重构让 AI 在测试保护下小步调整。每完成一个阶段用 checkpointing 技能把状态记录到文件中。这条链路走下来AI 的工作不再是一阵乱拳而是一条有节奏的生产线。它也不会问你下一步做什么因为计划里已经写好了。你要做的就是在关键节点审查结果。我用这个流程处理过一个改造任务给内部管理后台加一个导出功能。整个任务涉及后端接口、异步任务、权限控制、前端按钮。按以前的用法AI 大概率会闷头把前后端都改了然后留下一堆我没法确认的修改。但用了这套流程后它在计划阶段就暴露了一个我没想到的边界问题权限校验放在哪个层级。这个问题要是在代码写完后再发现返工成本高得多。4.3 checkpoint 与多会话恢复让长任务不再失忆AI 对话最让人头疼的一点是一旦上下文超了或者你不小心关了终端前面聊的全部归零。checkpointing 就是专门对付这个的。它的工作原理很简单技能会要求 AI 在特定时机把你的任务状态写入一个本地文件通常叫 checkpoint.md 或者类似的名字。文件内容大致包含当前目标、已完成步骤、进行中的工作、遇到的问题、下一步计划。当你的会话中断重新打开终端后只需要对它说读取 checkpoint.md继续之前的工作。AI 就会读取文件恢复上下文接着上次的进度往下走。这个体验和以前这咱们刚才说到哪了的对话相比完全是质变。不过这个技能需要调教一下不然它会记录得太碎。比如把更新了 README 错别字也写进目标里既占用文件空间也会在恢复时干扰 AI 对优先级的判断。我在会话一开始就会附加一句checkpoint 只记录与本次交付目标相关的关键状态琐碎操作不用记。这句话能让 checkpoint 的含金量高很多。还有一点要注意如果你在多人协作的仓库里干活把 checkpoint 文件加进 .gitignore。我已经吃过亏了AI 自动生成的 checkpoint.md 被提交进代码仓库还顺着 merge request 流到了主干看起来非常业余。4.4 一次会话别加载太多技能贪多嚼不烂superpowers 用熟了以后你会忍不住一次给 AI 布置好几个技能请加载 debugging、code-review、refactoring、TDD一起把这个问题解决。我试过几次结果都不理想。原因是模型在多个方法论之间切换是有成本的。每个技能都有自己的流程约束同时激活三四个它们会在冲突的时候互相干扰。比如 debugging 要求先验证再动手code-review 要求发现所有潜在问题refactoring 要求保持行为不变三个技能同时激活AI 可能在还没复现问题的时候就开始大谈代码坏味道然后给你列出一堆重构建议。我的经验是一次会话里保持两到三个技能是最佳甜点区。核心技能比如计划或调试常驻辅助技能按需临时加载用完就让它结束该技能回到常规模式。这样既享受了多技能的好处又不至于让模型精神分裂。5. 常见问题与排查技巧实录5.1 一张表解决 90% 的安装/加载问题我整理了这段时间被问得最多的问题做成速查表你可以直接对着排查。现象可能原因处理方式技能符号链接不存在安装时选错了目录重跑 install.sh或手动 ln -s 建链接AI 提到技能但没有加载上下文里看不到技能目录检查路径配置确认 ~/.claude/skills 存在加载技能后行为没变化会话有缓存或环境变量覆盖开新会话重试检查自定义提示词安装脚本卡在交互选项终端不支持图形化交互设置环境变量跳过交互或换一个终端Java 项目里 AI 一直猜测构建命令项目上下文没写清楚在 AGENTS.md 里写明 gradle/maven 命令checkpoint 文件被提交进 Git没有忽略该文件加入 .gitignore 并清理历史记录5.2 技能不生效的几个隐蔽原因速查表覆盖了表面问题我再讲三个更难发现的坑。第一个是技能被同名文件夹干扰。很多项目里自带了一个空的 skills 目录结果代理按路径搜索时优先命中这个空目录全局技能的链接反而没被读取。解决方法是把项目内的 skills 目录重命名或者确认代理的技能搜索顺序。第二个是上下文缓存。Codex 和 Claude Code 都会对已经读取过的上下文做缓存尤其是同一个会话内AI 不会反复读 SKILL.md。如果你中途修改了技能文件或者刚装好技能就在旧会话里测试很可能发现行为没变化。这时候别怀疑配置错了先开一个新会话再说。第三个是你自己的自定义提示词太强势。如果你在系统提示词里写了很多你必须怎样怎样的规则模型会把这些规则和技能流程混合执行甚至直接优先执行你的指令把技能晾在一边。我的建议是系统提示词里只写业务性和安全性的硬规则把工作流方法论的管理权交给 superpowers二者不要重叠太多。5.3 上下文超长与 token 成本失控的对策技能按需加载已经大幅降低了上下文压力但大型仓库场景下还是会因为 AI 主动读文件太多而爆窗口。我常用的几个手段缩小阅读范围。明确说只读 src/main/java/com/example/service 目录下的文件其他不要看比了解这个项目有效得多。用 git 历史代替全文。让 AI 执行git log --oneline -20看提交历史快速了解演进过程不需要把所有代码读一遍。长任务分段。把一次交付拆成多个阶段每阶段结束用 checkpoint 保存状态然后开新会话继续。这既省上下文又让每段对话都聚焦。监控 token 消耗。我一般会留意每轮对话的输出长度如果 AI 开始输出大段分析和重复读文件及时打断并让它收敛任务范围。成本这块我也说句实话装上 superpowers 之后单次会话消耗的 token 确实会变多因为 AI 干的活多了、分析过程长了。但总体成本反而可能下降因为返工和无效代码量大幅减少。我个人的经验是复杂任务用这套流程整体支出比裸用 Codex 还要省原因是做对一次的成本永远低于改错三次。6. 实操心得与进阶玩法6.1 我的个人技能清单与使用习惯如果只保留三个技能我会选 writing-plans、debugging、checkpointing。这三者构成一个最小闭环先有方向再能执行最后能续命。几乎所有的中等复杂度任务都能靠这三位搞定。code-review 和 refactoring 我按需启用。它们很好用但容易让 AI 在没有明确重构需求的时候主动挑战代码风格制造无谓的大 diff。我的习惯是明确到只 review 我指出的文件或只重构这一段逻辑不要动其他部分。checklists 技能我平时不用但在发布版本、做数据迁移这类高风险操作时会让它生成清单并逐项确认这比人工列清单更不容易遗漏。6.2 自定义团队技能的推荐做法superpowers 真正的杀手锏是你可以给它加技能而且门槛低到离谱。我给团队写过一个 release-prep 技能内容就是发布前的检查事项版本号是否递增、更新日志是否补充、测试套件是否全绿、依赖是否有安全更新。做法很简单在技能目录下新建一个文件夹写一个 SKILL.md 就可以。# Release Prep 当用户需要准备版本发布时加载本技能。流程如下 1. 检查 CHANGELOG.md确认本次版本的变更均已记录。 2. 检查版本号确保符合语义化版本规则。 3. 运行完整测试套件确认所有测试通过。 4. 扫描依赖列出有版本更新的库和潜在兼容性风险。 5. 将以上信息整理成一份发布确认清单交给用户确认。写自定义技能有三个原则单一职责、流程明确、可验证。一个技能只做一件事步骤用有序列表每个步骤要能明确判断完成与否。这样写出来的技能模型才容易理解和执行。你现在打开任何一个内置技能的 SKILL.md都能看到这个风格的影子照着写基本不会错。6.3 最后分享几个实在的避坑技巧安装阶段建议把 superpowers 仓库单独放在一个目录不要放在项目工程里否则每次切换项目都要重新配置路径。我自己的做法是放在~/tools/superpowers脚本装完后再全局链接。使用阶段遇到大任务时先在对话里明确输出要求比如计划的每一步都要写清楚涉及的文件和验证方式。这能显著降低事后返工的概率。我试过有时候 AI 的计划写得太抽象每个步骤都是优化相关逻辑这种废话加了这句话之后输出质量明显变好。还有一个通用技巧对于 Java 这类编译型项目遇到诡异问题时让 AI 先把报错日志完整读一遍再说话不要让它根据印象猜测。很多AI 改错代码的案例其实都是因为上下文里没有足够的报错信息它只能基于概率补全一个错误答案。我自己用下来的体会是superpowers 真正改变的不是模型而是工作方式。它让 AI 编码代理从问一句答一句变成了有节奏地推进任务。虽然它不能替代人类的判断但至少省下了大量重复沟通的成本。如果你也受够了 AI 答非所问、动不动就大改代码我觉得给它装上这套技能是目前性价比最高的升级方式。最后一个小建议别一次全开先挑最痛痛的场景用起来比如让 AI 带着 debugging 技能去查一天 bug你会发现它比想象中实用得多。
