1. superpowers 到底是什么一套给 AI 编程代理的方法论技能包最近圈子里到处都在聊 superpowersCodex CLI 装 superpowers、Trae 安装 superpowers skill 这类搜索词突然扎堆出现。说实话我第一次看到这个名字是有点抵触的——超能力听起来营销味太重。但当我真的把这套 skills 接入本地的 Codex CLI跑完一个完整的重构任务之后我的判断变了这不是玄学这是把资深工程师的工作方法以提示词工作流的形式硬塞进了 AI 的脑子里。1.1 一个技能仓库为什么能火成这样superpowers 本质上是开源作者 Jesse VincentGitHub 账号 obra维护的一套技能集合。它最早是给 Claude Code 的 skills 机制用的后来因为 Codex CLI、Trae 这类工具陆续支持了 skills 规范社区里开始大量搬运、安装于是codex cli 安装 superpowerstrae work cn 安装 superpowers skill这类教程需求一下子就起来了。它跟普通插件完全不是一个物种。插件是给你加功能按钮superpowers 则是给 AI 编程代理加工作习惯。它里面躺着的是一堆 markdown 文件每个文件就是一个技能告诉 AI 在特定场景下应该按照什么流程干活。没有任何编译过程没有运行时依赖纯粹靠一套精心设计过的指令文本就能显著改变 AI 写代码的方式。这一点恰恰是它最反直觉的地方一个没有任何代码的仓库居然能提升代码质量。秘密就在于它修改的不是工具能力而是 AI 的行为策略。1.2 技能包里到底装了哪些超能力我直接说我在仓库里看到的核心技能不同版本会增删但主干基本是这些技能名称它让 AI 干什么典型触发场景brainstorming先发散再收敛列出多种方案和取舍而不是上来就写代码新功能设计、架构选型writing-plans把大任务拆成带验收标准的小步骤形成可执行计划接到一个跨多文件的重构任务executing-plans严格执行既有计划不跑偏、不擅自扩大范围按计划实施多个步骤systematic-debugging按复现-定位-假设-修复-验证的流程排查问题测试挂了、功能行为异常test-driven-development先写失败测试再写实现最后重构需要新增接口或修复回归using-subagents教主代理如何把子任务委派给子代理并给出清晰的上下文大型任务需要并行调研多块内容writing-design-docs在动手前产出设计文档明确约束、接口和风险涉及核心模块的改动communicating-with-humans让 AI 知道什么时候该停下来问人而不是自作主张需求有歧义、权限受限时单看名字会觉得全是正确的废话但关键在于每个技能内部不是一句口号而是一套可执行的流程。比如 systematic-debugging 会要求 AI 先复现问题、收集证据、形成假设再做最小改动最后补回归测试每一步都有明确的输出模板。这就是把老工程师脑子里的隐性经验显性化成 AI 能循着走的路标。1.3 为什么是 skills 而不是 plugin理解 superpowers 的价值得先理解 skills 这个机制。一个 SKILL.md 文件通常长这样开头是 YAML 格式的 frontmatter里面写了技能的名字和描述正文是完整的工作步骤、检查清单、输出模板。AI 代理在启动时会把这些技能的描述加载进上下文当它判断当前用户请求和某个技能描述相匹配就会调出那个技能的完整指令来执行。这套设计的好处是技能即文本文本即代码。你可以把技能放进 Git 仓库里做版本管理可以 fork 出来改成自己团队的风格可以只挑选其中几个放进项目也可以自己照着格式写新技能。相比传统插件需要维护二进制兼容性skills 的门槛低到会写 Markdown 就能参与。superpowers 之所以叫 superpowers就是因为它把软件工程里最值钱的那套思维方式——先想清楚再做、小步验证、系统化排错——打包成了开箱即用的技能文本。你不需要给 AI 写几千字的 system prompt只要让它能用这些技能就行。2. 没有结构化的 AI 程序员和接入了 superpowers 的 AI 程序员差距在哪我见过太多人抱怨AI 写代码像实习生毛手毛脚。但问题往往不在模型本身而在你给它的工作方式。把同样的 GPT 级别模型丢给一个完全没有流程约束的会话和一个装着 superpowers 的会话产出质量能差出一个级别。2.1 AI 写代码的默认行为和资深工程师差在哪大模型写代码的默认路径是快问快答收到你的指令顺着概率生成一段看起来合理的代码然后停在那里等你验收。它默认你只要答案不要过程。所以你会看到这些典型毛病不读现有代码结构就直接改、改完不跑测试、遇到报错就换个写法瞎试、修一个 bug 顺手把别的逻辑也动了。资深工程师不是这么干活的。拿到需求先确认边界改动前先看调用链写代码先想测试怎么设计出问题先复现再定位。这套习惯不是天赋是多年被坑出来的肌肉记忆。问题在于这些习惯很难用一句你认真点教给 AI——它每次对话都是新的一句叮嘱只对当前回合有效。superpowers 解决的正是这个问题把工作习惯固化成语义清晰的技能描述让它常驻在 AI 的上下文里每次遇到对应场景自动生效。相当于你给每个 AI 会话都配了一个带教导师傅。2.2 从直接改代码到先写计划再动手我接入 superpowers 之后感受最明显的变化是 AI 不再急着动手了。以前我让它给用户模块加一个 Redis 缓存层它顶多问一两个问题就开始改文件改完给你一段 summary。如果运气不好缓存策略选错、失效逻辑漏了、序列化方式跟现有代码不搭后续全是补丁套补丁。现在我会明确说先 brainstorm 一下方案然后写计划。AI 会先列举几种缓存策略的优缺点结合当前项目的 Redis 客户端版本和数据结构给出推荐方案接着 writing-plans 技能会把整个改动拆成引入依赖-封装缓存客户端-改造数据访问层-补测试-跑全量回归几个步骤每步都写清楚验收标准。它甚至还知道在计划里标注哪些文件不能动避免我原有的业务逻辑被顺手改坏。这种先计划后动手的模式真正把不可控的一次性生成变成了可控的多阶段执行。你可以在任何一步喊停而不是等它把一坨代码糊你脸上。2.3 把幻觉按下去的反馈回路TDD 与系统化调试AI 最大的问题不是不会写代码而是不知道自己写得对不对。它生成代码的时候没有运行一下看看的本能除非你明确要求。superpowers 里的 test-driven-development 技能本质上是把红-绿-重构这套反馈回路塞给了 AI。它会让 AI 在写实现之前先写出失败的测试运行确认测试真的失败红再写最小实现让测试通过绿最后做清理重构。这个过程中 AI 不得不反复执行测试命令每次执行结果都是新的事实输入幻觉就很难存活。systematic-debugging 技能也是一样的逻辑。它禁止 AI 凭空猜原因要求先复现、再收集证据、形成假设、验证假设、最小修复、补回归测试。我实测过几个顽固 bugAI 在遵循这套流程时定位到根因的概率明显高于它自由发挥的时候。核心原因很简单每一步都基于证据而不是基于概率生成。3. 在 Codex CLI 上装 superpowers完整实操记录说完了原理直接上干货。如果你跟我一样主力工具是 Codex CLI下面这套安装流程可以照着抄。不同 Codex 版本的配置字段名偶尔会有差异我会在关键位置提醒你怎么自查。3.1 前置条件先把 Codex CLI 本身跑起来装 superpowers 之前Codex CLI 你得先能用。一般通过 npm 全局安装npm install -g openai/codex装完先验证版本顺便确认登录状态codex --version codex login这里有个容易忽略的点Codex CLI 会读取项目根目录和用户主目录下的AGENTS.md作为长期指令后续 superpowers 的加载和它强相关。所以最好先确认一下~/.codex目录存在不存在就手动建一下mkdir -p ~/.codex前置条件就这些。请注意Codex CLI 版本迭代非常快skills 支持是近几个版本才逐步完善的如果你的版本太老后面配置了也不会生效建议先升级到最新版。3.2 拉取 superpowers 仓库确认目录结构接下来把 superpowers 仓库克隆到本地。放在哪都行我习惯放用户目录下方便多个项目共用git clone https://github.com/obra/superpowers.git ~/superpowers拉完之后先别急着配置看一眼目录结构ls ~/superpowers ls ~/superpowers/skills正常情况下skills目录下会有若干个文件夹比如brainstorming、writing-plans、systematic-debugging这些每个文件夹里都有一个SKILL.md文件。你可以随便打开一个看看格式head -40 ~/superpowers/skills/systematic-debugging/SKILL.md确认 frontmatter 里的name和description字段都正常后面的正文是给 AI 的完整指令。这一步很重要很多安装失败其实是仓库没拉完整或者分支不对导致 skills 目录是空的。3.3 把技能接入 Codex 的两种方式接入方式不外乎两种复制/软链到 Codex 默认技能目录或者在配置文件里显式指定技能目录。我建议优先用软链这样以后git pull更新 superpowers技能自然就更新了不用重复复制。方式一软链到~/.codex/skillsmkdir -p ~/.codex/skills ln -s ~/superpowers/skills/* ~/.codex/skills/方式二在~/.codex/config.toml里指定技能目录。Codex 的配置文件默认在~/.codex/config.toml编辑它加上一行# 技能目录可配置多个路径 skills_dir [ /Users/你的用户名/superpowers/skills, ]注意不同 Codex 版本的字段名可能不一样有的版本叫skills_dir有的版本用[skills]表格配置。如果你写完配置后启动报错先跑一下codex --help看当前版本支持哪些配置项或者直接查官方文档确认字段名不要盲目照抄。3.4 验证技能到底加载没有装完别高兴太早先验证。在任意项目目录下启动 codex然后问它一句话列出你当前可用的 superpowers 技能以及每个技能的触发条件。如果 AI 能列举出 brainstorming、writing-plans、systematic-debugging 这些东西说明技能已经进入它的上下文了。如果它说我没有这些技能优先自查三件事技能目录路径是否写对、是否用了绝对路径、Codex 版本是否支持 skills。还有一个更快的验证方式直接给它一个任务比如帮我 brainstorm 一下订单超时自动关闭功能然后观察它有没有按照 brainstorming 技能的流程走——先列出方案、再做对比、再给建议。如果它还是直接甩代码那基本可以断定技能没加载成功。4. 在 Trae中文版上装 superpowers图形界面环境下的安装思路Trae 这边的安装逻辑和 Codex CLI 不太一样。Trae 是图形化 IDE技能目录不会像 CLI 那样直接暴露在配置文件里但你依然能找到只是得换个思路。4.1 先找到 Trae 的技能目录别靠猜Trae 中文版trae.com.cn 下载的那个版本更新速度很快每一个小版本的技能目录位置都可能变。我踩过最大的坑就是看了个老教程照着路径去找结果目录根本不存在。比较靠谱的找法有两种。第一种是看 Trae 设置里有没有技能或Skill相关的入口如果有通常设置面板里会直接显示技能目录的路径或者提供从文件夹导入技能的功能那就直接用它。第二种是自己去常见目录碰运气Windows 上通常在%APPDATA%\Trae\User\skillsmacOS 上通常在~/Library/Application Support/Trae/User/skills如果这两个路径都不存在别硬找。打开 Trae 的帮助菜单查看版本号然后去官方文档里搜对应版本的技能目录说明。图形化 IDE 的这种路径变更光靠经验是猜不准的以官方文档为准。4.2 复制技能文件并让 IDE 认出来找到技能目录之后操作就简单了。把 superpowers 里的技能文件夹复制过去git clone https://github.com/obra/superpowers.git ~/superpowers cp -r ~/superpowers/skills/* /你的Trae技能目录/复制完一定要重启 Trae让它重新扫描技能目录。这一步很容易被忽略因为 IDE 不像 CLI 那样每次启动都重新读上下文它可能只在启动时加载一次技能。重启之后打开 Trae 的 AI 对话面板同样用列出你当前可用的 superpowers 技能来验证。如果列表为空检查每个技能文件夹内部是不是真的有SKILL.md文件注意大小写和文件名都不能错。Trae 对技能目录结构的校验比 Codex 严格少了文件它可能直接跳过整个技能。4.3 用项目规则补一脚AGENTS.md / 项目说明我在 Trae 里实际使用时的经验是光有技能文件还不够还得让 AI 知道这个项目里应该优先用技能。Trae 支持项目级规则配置一般是在项目根目录放一个AGENTS.md或者通过 IDE 里的项目规则入口添加具体名称看你的版本。我一般会在项目规则里写这么一段# AI 工作约定 本项目开发时请优先使用 superpowers 技能 - 新功能设计先用 brainstorming 技能再写计划。 - 代码改动涉及逻辑变更必须先补测试遵循 TDD 流程。 - Bug 修复使用 systematic-debugging 技能先复现再修复。 - 大任务使用 writing-plans 拆解步骤逐步执行。这段文字的作用是给 AI 一个额外的触发偏好。因为技能是靠语义匹配触发的有可能某个任务描述不够清晰AI 没意识到该用技能。项目规则里写清楚相当于提前打了招呼触发率会高很多。5. 装上之后怎么用让 superpowers 真正改变日常开发装技能只是开始真正值钱的是你怎么用它。我用了几个星期之后总结出一套比较顺手的触发方式和工作流分享出来供你参考。5.1 一句话唤起技能触发机制与推荐话术superpowers 的技能触发靠的是描述匹配不是严格的命令解析。所以你不用背什么指令只要在话里带上场景关键词AI 大概率会调出对应技能。我实际测下来比较稳定的触发句式先用 brainstorming 过一下这个问题写计划拆成步骤每步都要验收标准用 TDD 的方式来加这个接口系统化调试别瞎猜原因这个任务比较大派个子代理去调研依赖库的最新用法关键技巧是把技能名直接说出来。虽然它支持语义匹配但显式点名是最不容易出错的。就像你带实习生直接说按我们排错的流程走一遍比说你仔细查查效果好十倍。5.2 一个完整流程演示从头脑风暴到执行计划拿一个真实任务举例。假设我要给现有的订单模块加一个超时自动关闭功能。放在以前我会直接让 AI 写代码然后陷入无穷无尽的补测和修 bug。现在我是这么走的第一步触发 brainstorming。我输入用 brainstorming 技能分析一下订单超时自动关闭的实现方案要考虑定时扫描和延迟队列两种思路。 AI 会列出两种机制的优劣、复杂度、对现有架构的影响最后给一个推荐。这个过程可能花几分钟但能帮我避免选错技术方向。第二步让它写计划。我输入基于刚才的结论写一个执行计划拆成可验证的步骤。 这时候 writing-plans 会给出设计数据表字段、实现扫描逻辑、编写超时处理任务、补充单元测试、联调验证。每步都带验收标准。第三步让它按计划执行。我会说开始执行计划先做第一步。 执行过程中它会主动跑测试、报告进度而不是一次性把七个步骤全做完然后丢给你一个巨大的 diff。整个过程可控、可回溯出问题能精准定位到是哪一步偏了。5.3 系统化调试实战让 AI 停止瞎猜调试是 superpowers 最能体现价值的地方。我遇到过一个诡异的问题某个定时任务偶尔会丢数据但日志里找不到报错。以前我给 AI 描述这个现象它大概率会猜测是不是并发问题是不是事务没提交然后给一堆疑似修复。现在我只说一句用 systematic-debugging 技能来查。 它就开始正经干活了先要求我提供必现步骤和最近一次发生的日志然后缩小范围到定时任务的分页查询逻辑形成游标在并发场景下被重复消费的假设再写一段最小复现代码来验证。最后定位到的根因是分页游标没有加锁跟它最初的猜测方向差了十万八千里但流程硬是把我带到了正确答案。这个技能最厉害的地方不是它多聪明而是它逼着 AI 按证据链走。只要流程不走样再离谱的 bug 也能一步一步缩小到可定位的范围。5.4 子代理协作什么时候该放权什么时候该收权using-subagents 这个技能值得单独说。现代代码代理基本都支持子代理也就是主代理拆分任务后派出多个子代理并行处理。但大多数人不怎么会用要么所有任务都自己扛要么一股脑全派出去导致上下文乱套。superpowers 里的 using-subagents 技能会教 AI 判断什么样的任务适合委派独立性强、上下文边界清晰、可以并行验证的任务比如调研三个开源库的 API 差异整理某个目录下的 TODO 注释。而涉及全局架构决策、跨模块改动的任务它会让主代理自己保留控制权。我自己用下来的原则是调研类任务放心放权代码生成类任务谨慎放权跨文件重构尽量别放权。子代理失控的典型表现是它拿到模糊指令后瞎发挥所以这个技能还会要求主代理在委派时写清楚目标、边界、输出格式。你看到的效果就是子代理干活规规矩矩不像以前那么容易跑偏。6. 踩坑记录与我的真实使用建议最后这部分全是真金白银换来的教训。装上 superpowers 不等于一劳永逸以下几个坑我基本都踩过。6.1 技能没被触发先查这三处我把常见问题整理成一张表排查顺序从上往下症状大概率原因解决办法技能完全没进入上下文AI 不知道 superpowers技能目录配错/没软链成功/版本不支持用绝对路径重新配置升级工具到最新版技能在上下文里但任务里不触发任务描述和技能 description 匹配度不够显式说出技能名比如用 systematic-debugging触发了但只走了一半流程上下文太长AI 在长对话中丢失了技能细节新开会话或者把大任务拆小Trae 里完全识别不到技能目录结构不对或 SKILL.md 缺失逐个检查技能文件夹确保结构完整这里最容易被忽略的是第二条。就算技能加载成功了AI 也不是每个任务都会主动用。它每天处理大量普通请求如果描述匹配度不够它宁可走默认路径。所以我的习惯是重要任务永远显式点名技能。6.2 装上之后上下文暴涨试试技能裁剪superpowers 全量技能有十几个每个技能的 description 都会被加载进 AI 的上下文再加上正文被调取时占用的 token上下文开销确实不小。对于短对话无所谓但对于长任务token 很快会吃紧。我的做法是按项目裁剪技能。比如纯前端项目把 systematic-debugging、TDD 这些留着writing-design-docs 这种偏后端的就可以先移出去。你只需要在技能目录里建一个disabled文件夹把不用的技能移进去就行。等到需要时再移回来比删除仓库里的文件安全得多。别舍不得技能不需要全装着。让 AI 在更小的上下文里把核心技能用透远比塞一堆用不上的技能更高效。6.3 哪些任务不该用 superpowers不是所有任务都适合走 superpowers 流程。我最近有个体会越是简单机械的任务流程化反而越拖沓。比如把这个按钮的颜色从蓝色改成绿色把第三行的变量名改一下这种一句话能说清楚的小改动你非要它先 brainstorm、再写计划、再 TDD纯粹是浪费时间和 token。superpowers 的价值在大任务、复杂任务、容易翻车的任务上小改动直接当普通 AI 用就好。还有一种情况也别用你只是想快速验证一个想法能不能跑通处于随便玩玩的阶段。这时候流程会打断你的思路等它走完计划你的灵感可能早就凉了。先放飞再收拢等想法定型了再用 superpowers 做正式落地。6.4 定制你自己的第一个技能用一段时间之后你大概率会发现 superpowers 里的技能不完全符合自己的项目习惯。这时候别忍着自己写一个。写技能的门槛低到离谱在技能目录下新建一个文件夹里面放一个SKILL.mdfrontmatter 写清楚名字和描述正文写流程步骤完事。我举个例子我给自己项目写过一个小技能叫api-change-checklist内容是要求 AI 在修改任何 API 时必须检查兼容性、更新接口文档、补充版本迁移说明。这个技能解决的是我团队真实痛点——API 改了没人通知前端。自己写技能的时候有两点经验一是 description 一定要写具体宁可啰嗦因为 AI 靠它判断什么时候触发二是正文里的步骤宁多勿少把你能想到的检查点全列上AI 不会嫌多只会照着执行。我现在的真实使用习惯是新项目接手先装 superpowers然后立刻根据团队规范裁剪和补充技能。它不是一个固定工具更像一套可塑的工作方法论框架。你往里填什么它就帮你把什么变成 AI 的肌肉记忆。这套东西用顺了之后你再回头去看那种裸奔状态的 AI 会话会明显感觉差点意思——不是模型不行是没人教它该怎么干活。