先说结论如果你和我一样常常在终端里跟 Codex 这类 AI 编程助手打交道迟早会撞上一个共同的瓶颈——它“能说但不能干”。单次问答看起来很聪明一旦丢进真实的项目里它就变成了一只迷路的猫不知道先去读哪个文件不敢自己跑命令改完代码也不帮你检查编译。superpowers 这个项目就是冲着这个缺口来的。它不是一个新的模型也不是什么黑科技而是一套给编码代理“装手脚”的技能系统。这篇内容我会从原理讲到安装再到真实项目里的落地用法最后把那些文档里不会写、只有实际踩过才会知道的坑也都交给你。适合谁看如果你正在用 Codex CLI或者身边有人在讨论“superpowers 安装”“superpowers 使用教程”这类话题那说明你已经盯上这套玩法了。如果你是 Java 开发者这篇尤其值得看因为 Java 项目的构建链路长、依赖关系复杂恰恰是最能体现“超能力”价值的场景。当然就算你暂时没在用 Codex只要你对“怎么让 AI 代理真正参与开发”这件事感兴趣下面这套思路也会对你有启发。1. superpowers 到底是什么为什么大家都在装它很多人第一次听到 superpowers以为它是一个能“开挂”的脚本装上之后 Codex 就能自动写完整项目。真相没那么玄但比想象中更有用。我理解它实际上是两层东西的组合一层是“技能”skills也就是一批用 Markdown 写成的、给 AI 看的操作说明书另一层是“工具脚本”负责把文件读写、搜索、命令执行这些动作做成 AI 能直接调用的接口。你可以把它想象成给一个新来的实习生发了一本手册手册里写着“遇到多文件重构时先读这几章按顺序执行”同时又给了他一个工具箱里面有扫描仪、投影仪和各种小工具让他不用瞎猜就能看到项目全貌。本来 AI 只能靠上下文里的零星代码去猜现在它可以按图索骥一步步完成从“理解现状”到“动手修改”再到“验证结果”的全流程。大家之所以热衷于装它是因为默认状态下的编码代理在真实项目里实在太“裸”了。它是通过对话窗口工作的看不到仓库全貌不知道文件目录长什么样也没法安全地执行批量操作。你能在对话里喂给它的上下文又有限项目一大它就开始丢三落四。superpowers 的解决思路不是加大上下文窗口而是给 AI 一套“方法”——先探索、再规划、后执行并且把所有中间步骤都控制在工具脚本能处理的范围内。说白了它不是把 AI 变聪明而是把 AI 放进一个更靠谱的工作流程里。这也解释了为什么市面上同类的 skill 项目越来越多大家慢慢意识到编码代理的瓶颈早就不是“能不能生成代码”而是“能不能像一个正常工程师那样工作”。2. 先别急着装它的工作原理决定了你能不能用好我在各种社群里看到过一种现象有人兴冲冲装完用了十分钟就删了理由是“没什么感觉”。这通常不是因为工具不行而是因为他没用对。所以在讲怎么安装之前我想先花点篇幅把原理聊透。你理解了底层机制后面用起来就会顺手很多排查问题也知道从哪儿下手。2.1 核心结构技能文档 工具脚本先拆开看“技能文档”这部分。它本质上是一份高度结构化的 Markdown通常会包含这个技能适用什么场景、使用前提是什么、要按什么步骤执行、每一步该调用什么命令、最终怎么验证结果。例如一个“探索项目结构”的技能会写清楚“先运行 tree 命令查看目录深度再读取 build.gradle 或 pom.xml 提取模块信息最后输出依赖关系摘要”。工具脚本则负责把底层能力暴露给 AI。它可能提供这样几个能力读取指定文件的某一段内容避免把所有代码都塞进上下文在项目目录里执行 shell 命令并把输出截断到合理长度在 commit 之前自动生成变更摘要方便你审查。这些脚本当然不是必须的但有了它们AI 的执行力才真正跟上。这里想强调一个容易忽略的点技能文档不是写给人看的是写给模型看的工作规范。模型不会一字不差地背下来但会在决策时反复参考它。所以文档写得越清晰、越结构化模型的行为就越稳定。你要是随随便便写两行“帮我看看项目”那模型大概率还是会回到“自由发挥”的状态。2.2 它和普通 prompt 模板的本质区别我自己也玩过很长一段时间的 prompt 模板就是那种“你现在是一个资深 Java 架构师请……”式的开头。早期觉得挺有用后来发现一个问题模板是静态的任务一变模板就不太灵了。superpowers 这套设计的核心差异在于“动态路由”。AI 不是每次都背一整本模板而是先读一个很短的“技能索引”再根据当前任务选择合适的技能文档按需加载。就像工具箱里有很多格子它先看标签再抽对应那层抽屉而不是把所有工具全抱在身上。这样既省上下文又能保持每项任务都有明确的执行路径。更大的区别是“验收”这件事。普通 prompt 模板只会告诉模型“请给出建议”技能文档则会要求它“必须运行测试直到 grep 到 BUILD SUCCESS 才算完成”。这一点在真实工程里极其重要因为模型特别容易在自我感觉良好的时候停下来只有明确写出验收标准它才会去做本来懒得做的事。2.3 为什么 Codex 尤其适合这套玩法先说个可能有些朋友没注意到的细节Codex 本身就是一个 agent 形态的工具它能自己执行命令、读文件、写文件而不仅仅是在聊天框里输出代码。superpowers 本质上是在放大这种 agent 能力所以二者天然契合。另外Codex 的使用场景通常就是终端里的开发任务不会要求用户去记忆一大堆聊天上下文。你给它一份技能目录它就自动在那个体系里工作用起来很顺。而 Java 项目因为构建工具复杂经常需要反复运行 Maven/Gradle 命令正好能发挥这套“先探索再执行”的优势——AI 可以先跑 dependency:tree 看清依赖再决定改哪一层而不是闭着眼睛改 pom.xml。如果你只是在网页聊天窗口里用模型那 superpowers 的意义确实不大因为模型根本没有与项目交互的通道。这也解释了为什么所有相关讨论几乎都集中在 Codex 这类 agent 工具上。3. 从零安装环境准备和实际命令好原理讲完开始动真格。我会以常见的命令行安装方式为例假设你用的是 macOS 或 LinuxWindows 用户建议开 WSL 再继续因为很多脚本依赖 Unix 风格的文件路径和命令。整体流程不复杂但每一步都有它存在的理由我会顺着讲下来。3.1 装之前先确认这几样东西首先你得有一个能跑起来的编码代理 CLI。无论你用的是codex还是别的类似工具先保证在终端里敲命令能正常唤起并且已经用自己账号的 API 访问权限配置好了登录。这一步别跳过很多“装完啥反应都没有”的案例最后发现是 CLI 本身就没连上服务。其次环境里要装好 Git 和一个现代版本尽量新一点的 Node.js 运行时。Git 用来克隆代码Node.js 则是因为大量脚本都基于 JavaScript/TypeScript 生态。如果你平时主要写 Java可能没怎么碰过 Node不用慌装一个 Long Term Support 版本基本不会出错。最后建议把项目根目录统一固定比如~/.superpowers。我第一次装的时候随手扔在 /tmp 下后来重启一次机器全没了配置里还留着旧路径排查了半天。固定路径以后后续所有配置都可以写成绝对路径省心很多。3.2 克隆与初始化环境确认无误后直接克隆仓库到固定目录。在终端里执行git clone https://github.com/your-org/superpowers.git ~/.superpowers cd ~/.superpowers npm install把仓库路径换成你实际要使用的项目地址即可。如果你用的是发行版或者别人维护的 fork路径会有出入但流程基本一致。npm install是初始化依赖的关键一步没跑这个后面的辅助脚本多半会因为缺包而直接报MODULE_NOT_FOUND。装完之后我建议你先看一眼目录结构。正常情况下会有一个skills或类似命名的子目录里面装着各种 Markdown 技能文件同时会有一个入口文件例如index.js或者cli.js它负责跟 Codex 的环境做对接。你不需要把每一行代码都看懂但至少要知道这些文件在哪后面排查“技能加载失败”时会用到。3.3 让 CLI 加载技能配置路径仓库装好不代表 Codex 会自动用它关键在于把技能入口接入编码代理的指令系统。大多数 CLI 工具都支持一个“全局说明文件”Codex 在这个环节一般会读取项目里的AGENTS.md或者在用户目录下寻找对应的配置。我们要做的就是让这个说明文件把 superpowers 的技能目录“指”给模型。你可以创建一个全局说明文件内容大概是你是一个拥有 superpowers 的开发助手。 在开始任何涉及多文件修改、代码探索或构建趋势分析的任务前 必须先去读取 ~/.superpowers/skills 目录下的技能索引 并选择与研究任务匹配的技能文档。 技能文档里会提供具体的执行步骤和验收标准。 读完才能动手否则禁止直接输出代码。注意不同版本的工具对全局说明文件的位置要求可能不一样如果你照着做却没生效优先查你所用 CLI 的官方文档看它是读AGENTS.md还是读别的文件名。这个动作本身也是在训练你去理解工具的加载机制以后换别的 agent 时能举一反三。3.4 验证安装配置完别急着干大活先做一次最小化验证。重新打开一个会话直接问模型一句“你当前有哪些可用的 superpowers请列出 skills 目录下的文件名。”如果你配置成功它会输出诸如explore-project.md、run-tests.md之类的结果甚至还会解释每个技能适用场景。如果它回答“我没有看到任何技能文件”那基本能确定是说明文件路径不对或者技能目录权限异常这时候就回到上一步去排查。这一步看似简单但能帮你把“环境问题”和“使用问题”隔离开后面再怎么折腾都不至于两眼一抹黑。4. 从零到一在真实项目里跑通一次“带超能力”的编码任务装好了只是热身。我见过太多人装完就追问“下一步呢”其实最好的办法是立刻找一个不重要的项目完整跑一遍流程。下面我以一个简单的 Java Maven 项目为例带你把整个链路串起来。选择 Java 不是因为 superpowers 偏爱 Java而是因为这种项目最考验 agent 的“组织能力”。4.1 选一个简单的实验项目我建议你新建一个没有历史包袱的 GitHub 仓库里面放一个最小的 Maven 项目包含几个类、几个互相调用即可。为什么要这样做因为真实的大型项目里模型一旦读入太多无关文件容易在上下文里迷路你很难判断到底是 superpowers 没用还是项目本身太复杂。先用最小的项目验证流程再一步步扩大战场这是最高效的路径。实验开始前先把终端开在项目根目录下确认mvn -v能正常运行。这一步的意义在于你后续指挥 AI 执行构建命令时所有输出都是真实环境反馈而不是模型脑补的“应该能编译通过”。4.2 第一个任务让 AI 先规划再动手打开 Codex 会话输入类似这样的指令使用 superpowers 的 explore 技能先扫描 src/main/java 下的文件结构 然后找出类之间的依赖关系输出一份简短的重构建议清单。先不要修改任何代码。注意我在提示里刻意加了“先不要修改任何代码”。这是为了让模型遵循技能文档中的“探索前置”流程而不是一上来就热情地帮你改代码。正常情况下它会先读取技能文件接着调用 shell 命令查看目录树、读取关键类、搜索 import 语句最后才给出建议。你看到它真的执行了命令、而不是直接输出一大段建议时基本就说明 superpowers 已经生效了。你会感觉它像个实习生先围着项目转了几圈再开口说话。这种“先沉默探索再给结论”的节奏跟我们人类工程师的处理方式非常像。4.3 为什么“先探索再动手”能救你可能有人会觉得这个流程是不是太啰嗦让 AI 直接改代码不是更快吗我的观点是直接让 AI 改代码改小项目就像让新人写个工具函数确实快但一旦涉及多文件、多模块它没有全局视图就开始动手产生的幻觉代码和“幽灵依赖”会让你后面花更多时间去收拾。superpowers 的价值在于把“探索”变成硬性步骤。它逼着 AI 先回答“项目里面有什么”“这些代码之间什么关系”然后才允许它说“我认为应该怎么改”。这一步把很多幻觉提前扼杀了因为模型一旦看过真实的目录结构和文件内容它就不会再凭空捏造一个类名。我自己用过一段时间后最明显的感受就是它“一本正经胡说八道”的频率大幅下降。4.4 Java 场景的进阶用法如果你的实验项目已经跑通可以再上一个台阶尝试让 AI 做一次“依赖清理”。比如输入使用 superpowers 的 inspect-dependencies 技能 运行 mvn dependency:tree -Dscopecompile 过滤出所有未被 java 源码 import 的依赖给出可移除清单。这个任务在人类工程师手里都要花一番功夫但对 superpowers 来说它只要按技能文档指示先跑构建命令、再把输出重定向到临时文件、再用搜索工具检查每个依赖是否被引用就能给出有理有据的结果。你不会再看到它“猜一个答案”而是能看到它每一步的依据。再进阶一点你还可以让它配合git diff做增量修改先查看工作区变更再决定下一步动作。这个领域其实很值得自己慢慢探索Java 项目的 Maven 依赖分析、Gradle 任务清单、代码覆盖率报告等场景都能变成新的技能文档攒得越多你手里的“超能力”就越顺手。5. 三个让 superpowers 真正“好用”的设置习惯不少朋友用了一阵后说“能跑但没感觉到效率起飞”。我观察下来问题多半不在工具本身而在使用习惯。下面这三个习惯是我自己从反复折腾里总结出来的你也可以把它当成一份使用 checklist 来看。5.1 把技能目录当成产品来维护默认的技能文档写得很通用但每个团队的项目结构千差万别。我的建议是先不动原生的核心技能新建一个“业务技能”子目录把你项目特有的操作流程写成新技能例如“如何发布内部 Java 库”“如何清理未使用的资源文件”“如何按团队规范生成数据库迁移脚本”。记录技能的时候保持一个模板场景、前提、步骤、验收。你写得越规整模型跑起来越稳定。我见过有人把技能写成一篇小作文结果模型读了半天找不到重点后来改成清单式步骤效果立竿见影。这件事本质上是在给你的 AI 同事做培训材料花的时间一定会在后面省回来。5.2 不管用什么前端先统一底层配置现在市面上已经有各种图形化前端有人也会在类似 WorBuddy 或 IDE 插件里接入同一套编码代理。很多人误以为换了前端就得重新配一遍 superpowers其实不是。底层的说明文件和技能目录完全可以复用。我个人的做法是把 superpowers 的路径固定下来然后在每个前端工具的配置文件里都指向同一份AGENTS.md。这样不管我是用原生 CLI、还是图形界面AI 看到的行为和技能完全一致两套配置不会“漂移”。如果你只在 GUI 里配了一份、在终端里又配另一份很快就会发现两边表现不一致到时候排查起来特别痛苦。5.3 设置护栏默认不给全部权限AI 代理最让人担心的一点是它太主动了一上来就改一堆文件。superpowers 让它的执行力变强这既是好事也是风险。我强烈建议在说明文件里加上一条护栏除非用户明确同意否则所有修改操作都先提交到一个新分支或者使用git worktree隔离工作区。给 AI 开一个新分支、让它在一个完全不影响主代码的目录里折腾这个习惯能让你放心把任务交出去。哪怕它真的改坏了你也只需要丢弃分支不会污染主分支更不会把半成品推到远程。等确认改动没问题再让 AI 生成 diff 给你审查并合并。这套流程应该成为默认操作而不是可选项。6. 我踩过的坑和排查记录附速查表最后这部分送上一份实打实的“踩坑记录”。我尽量还原当时的现象和排查逻辑希望帮你少走几个来回。6.1 坑一加载了但像没加载一样症状模型还是直接给答案完全无视技能文件。排查时我一开始怀疑是配置文件没生效后来在会话里问了句“你读过 AGENTS.md 吗”它回答说没读到。最终定位到问题我把说明文件放在了错误路径Codex 并不读取那个名称。换成正确路径后立刻恢复正常。记住验证加载状态直接问模型“你读了哪些文件”比翻配置更快。6.2 坑二AI 把技能当摆设还是直接输出代码这通常不是配置问题而是说明文件里的指令不够硬。如果你只写“建议参考技能”模型大概率不会当成强约束。我在说明文件里改成“涉及多文件修改的任务必须先选择技能并执行步骤一否则禁止输出任何代码”行为才稳定下来。写指令时要用“禁止”“必须”这类硬词不用“可以”“建议”。6.3 坑三上下文太长老是截断Java 项目里特别常见一跑mvn dependency:tree就是上千行输出模型读着读着就截断了。我的解法是先让 AI 把命令输出重定向到临时文件再用搜索工具去检索关键内容而不是全文读入。你可以在技能文档里提前写好“所有长输出必须重定向然后只读取匹配行”这样从源头控制上下文。6.4 常见问题速查表症状可能原因解决方案技能文件列不出来说明文件路径未生效检查 CLI 的全局说明文件位置确认指向正确目录命令执行报 MODULE_NOT_FOUND依赖没装全回到 superpowers 目录执行 npm install模型无视技能直接发挥指令不够强硬在说明文件里加“禁止/必须”类约束长输出把上下文塞爆命令直接输出到终端强制重定向到文件再分片检索修改经常破坏主分支没有启用隔离机制默认新建分支或 worktree确认后再合并图形界面里行为不一致多端配置漂移固定同一份 AGENTS.md所有前端都指向它6.5 一点个人体会我用 superpowers 有段时间了最大的体会是它不会让 AI 突然变成一个天才工程师但确实能让它从一个“偶尔惊艳、时常失控”的话痨变成一个“按流程办事、主动验证”的普通助手。这个转变听起来没那么性感但在真实项目里的价值非常大。它让你手底下的 AI 变得可预测、可审查、可复用。如果你打算在团队里推广不用急着把所有人都教会。先找一两个愿意折腾的同事把你们项目的特有技能文档写起来大家一起维护。慢慢地这套东西会从“工具的使用指南”升级成“团队的工程规范”。到那时候你回头看今天这个标题应该会理解大家为什么把它称为 superpowers——真正让你拥有超能力的其实是你围绕它所建立起来的那套工作方法。