我到现在还记得第一次在 Codex CLI 里装上 superpowers 之后跑那个任务的样子。之前它给我的感觉是很聪明但完全没有章法。你让它加个功能它立刻动手改代码测试红了就再改一版红了再改像一只反复撞玻璃的老鼠。装上 superpowers 之后同一个需求它第一件事不是写代码而是先停下来给你一份计划把任务拆成清单然后才开始动手。这个反差大到让我重新评估了AI 编码代理到底缺什么这个问题。如果你最近也在搜 superpowers 使用教程、codex cli 安装 superpowers、或者想在 Trae 国内版里装 superpowers skill说明你多半也遇到了类似的情况——AI 能写代码但写代码的方式不像一个成熟的工程师。这篇文章就是把我的安装过程、使用心得、以及踩过的坑一次性讲清楚。适合已经用过 Codex CLI、Claude Code 或 Trae Agent 模式、但对怎么让 AI 更稳定地干活还有困惑的人。1. Superpowers到底是什么它不是插件而是一套给AI编码代理的技能包体系1.1 它解决的核心痛点先说结论superpowers 不是一个独立应用也不是传统意义上的 IDE 插件。它本质上是一堆结构化的 Markdown 文件技能文件外加少量辅助脚本作用是给 AI 编码代理补上工作方法。你看现在的主流编码代理底层模型本身的代码能力已经不差了差的是工作习惯。比如拿到需求直接改代码不肯先想清楚方案测试挂了就盲目改不读报错、不定位根因改完不回归、不补充测试、不留提交记录需求模糊的时候不反问而是猜一个方向就开干这些问题模型能力越强反而越明显因为模型太想尽快给答案了。superpowers 的思路很简单既然模型擅长遵循指令那就把资深工程师的工作流程写成一套标准操作手册SOP让 AI 在动手前先加载对应的工作方法。这就是技能的含义。1.2 技能包与普通插件、系统提示词的本质区别很多人第一次接触会误解superpowers 是不是像 VS Code 插件那样装完就有按钮不是。它的运行方式更接近给 AI 加了一段临时的人设和流程约束。我习惯用一个类比普通的系统提示词比如 CLAUDE.md、AGENTS.md是给 AI 一个公司规章制度而 superpowers 的技能是具体工位上的操作手册。规章制度告诉它什么能做、什么不能做操作手册告诉它一个任务从开始到结束应该分几步走、每步做什么、做到什么标准才算完成。区别在于加载时机。技能不是一次性全部塞进上下文的而是按需激活。AI 判断当前任务符合某个技能的 description 时才去读取对应的 SKILL.md 文件把里面的流程指令加到当前的对话上下文中。这样做的好处是上下文不会被一大堆不相干的规则撑爆坏处是——如果判断错了该用的技能没触发那工作流就又回到老样子。这个后面我会讲怎么解决。这套体系最初主要是给 Claude Code 和 Codex CLI 用的作者是 Jesse Vincent仓库名叫 obra/superpowers开源在 GitHub 上。社区里火起来之后大家发现只要是支持技能目录 SKILL.md机制的编码代理都能用所以后来就有了在 Trae 里装 superpowers 的玩法。2. 拆开看技能包的结构SKILL.md、frontmatter 与触发机制2.1 一个技能文件内部长什么样如果你把 superpowers 仓库克隆下来会看到类似这样的目录结构superpowers/ ├── skills/ │ ├── writing-a-plan/ │ │ └── SKILL.md │ ├── test-driven-development/ │ │ └── SKILL.md │ ├── systematic-debugging/ │ │ └── SKILL.md │ ├── brainstorming/ │ │ └── SKILL.md │ ├── generating-commits/ │ │ └── SKILL.md │ └── root-cause-analysis/ │ └── SKILL.md每个技能就是一个文件夹里面最核心的文件是 SKILL.md。这个文件的头部有一段 YAML 格式的 frontmatter内容大致是这样--- name: test-driven-development description: 在编写任何实现代码之前先编写测试始终先运行测试确认失败再实现功能 ---下面就是正文正文是一段给 AI 看的工作规程比如 TDD 技能会写明红-绿-重构三个阶段的顺序、什么时候运行测试、测试失败时该做什么、不允许跳过失败验证直接写实现等等。2.2 编码代理是怎么读技能的这个机制非常像检索增强生成RAG只不过检索的对象是本地文件。具体流程是用户给 AI 下达一个任务AI 根据任务内容和所有已加载技能的 description 做语义匹配匹配到某个或某几个技能后AI 读取对应的 SKILL.md 正文正文中的流程指令作为当前任务的行为约束AI 按此执行所以在技能文件里description 写得好不好直接决定 AI 能不能在正确的时候用上正确的技能。写得太宽泛AI 会在不需要的时候也触发写得太具体该触发的时候又匹配不上。2.3 核心技能清单与适用场景我把仓库里最常用、我自己实战验证过的几个技能整理成了表技能名核心作用典型适用场景writing-a-plan动手前先输出实施计划与任务清单新功能开发、重构、跨文件改动test-driven-development先写失败测试再实现最后重构核心业务逻辑、容易被回归影响的代码systematic-debugging不猜测先收集证据再定位根因偶发 bug、线上异常、测试不稳定brainstorming先提出澄清问题再给出方案需求模糊、技术选型不确定时generating-commits按规范生成可读的提交信息代码提交前root-cause-analysis追溯问题根因而非修表面症状反复出现的同类故障我第一次看到这张清单的时候心里想的其实是这不就是正常开发流程吗是的正因为是正常流程才需要把它固化下来交给 AI。之前 AI 不按这个流程走不是因为它不会而是因为你没有明确要求它这么做。3. 在 Codex CLI 中安装 Superpowers从零到能用的完整链路3.1 安装前的准备工作我当时的运行环境是 macOS装了最新版的 Codex CLI通过 npm 全局安装的有可用的模型 API 配置。如果你还没装 Codex CLI先装好再说npm install -g openai/codex装完先确认版本并确保codex命令能正常对话。这一步别跳过因为整个 superpowers 安装过程如果出问题往往不是技能本身的问题而是 Codex CLI 版本太旧或者配置不完整。提示不同版本的 Codex CLI 对技能功能的支持程度不一样。我建议先用最新稳定版技能相关配置字段在不同小版本里改过好几次名字旧版本可能根本不识别。3.2 两种安装方式脚本一键装 vs 手动克隆官方 README 推荐的是安装脚本方式常见形式是curl -sSL https://install.superpowers.dev | bash脚本会检测你本地装了哪个编码代理然后把技能仓库克隆到合适的位置并写入对应的配置。如果你用的是 Codex CLI脚本基本会完成以下动作把 superpowers 仓库克隆到本地通常在~/.codex/superpowers或类似目录在 Codex CLI 的配置文件中追加技能目录路径输出一段说明告诉你哪些技能已经可用但脚本方式有个我不太喜欢的地方它默认把整套技能都装进去了有些技能我根本用不上。所以我更推荐第二种方式——手动克隆按需配置git clone https://github.com/obra/superpowers.git ~/superpowers然后打开 Codex CLI 的配置文件通常在~/.codex/config.toml在里面指定技能目录。不同版本的字段名不太一样我在 GitHub 上见过skills_dir、experimental_skills_path几种写法。我的做法是打开配置文件搜索skill关键字看看当前版本认哪个字段。如果实在找不到就去翻 Codex CLI 的官方文档或者在codex的 TUI 界面里找设置项。3.3 装完怎么验证让 AI 自己说每次装完我都习惯做一个快速验证不跑复杂任务就让它展示技能codex exec list your available skills and explain how you load them如果配置成功它应该能列出 superpowers 里的技能并且说清楚触发条件。如果它说我没有技能那基本就是配置没生效回到上一步检查路径。更实用的验证是直接跑一个小任务比如codex exec use your test-driven-development skill to add a validate_email function注意看它的输出顺序。没有技能的时候它会直接给你函数实现有 TDD 技能的时候它会先写测试再运行测试确认失败然后才写实现。看到这个顺序就说明技能真正生效了。3.4 安装过程中最常见的三个问题我帮朋友排查过几次安装失败问题基本集中在三处路径写错技能目录指向了仓库根目录而不是仓库里面的skills子目录。AI 需要的是装 SKILL.md 的那一层。配置字段不识别网上教程抄的字段名和你当前版本不一致。这个没别的办法以你本机codex --help输出的信息为准。权限问题Codex CLI 的沙箱模式可能限制了 AI 读取技能目录。如果你的命令明明发对了但 AI 说找不到技能文件检查一下沙箱配置是否允许读对应路径。4. 把 Superpowers 技能装进 Trae 国内版社区里最火的折腾方向4.1 为什么这么多人想在 Trae 里装技能Trae 国内版最近热度很高很多人把它当成主力 AI IDE 在用。它的 Agent 模式可以做多文件级改动、自动执行命令使用体验对中文用户相当友好。但用久了你会发现同一个问题Agent 默认工作流太直给——你让它改它就改缺少计划、测试、复盘这些环节。于是很多原本在 Codex CLI 里用 superpowers 的人就想着能不能把这套技能搬到 Trae 里。我在社区看到的热搜词trae work cn 安装 superpowers skill指的就是这件事。结论是可以但 Trae 的技能机制和 Codex 不完全一样不能无脑照搬。4.2 手动导入技能的具体步骤我实际试下来比较稳的流程是这样的把 superpowers 仓库克隆或下载到本地打开 Trae 的设置找到技能或技能市场相关的入口。不同版本的入口位置不太一样我记得有几个版本是把自定义技能放在 Agent 设置里可以直接指定技能目录指定技能目录时注意指向包含 SKILL.md 的层级。比如你想用 TDD 和计划这两个技能就把对应的test-driven-development、writing-a-plan文件夹放进去或者直接把整个skills目录指给它保存后在对话里要求 Agent使用 TDD 技能或先给我一份计划看它是否按技能流程走如果 Trae 版本里没有自定义技能目录入口还有一个社区里常见的替代方案把 SKILL.md 里的核心流程直接写进项目的AGENTS.md或 Trae 的项目规则文件里。虽然这样失去了按需加载的灵活性但对 Trae 来说反而更稳——因为 Agent 每次读项目规则时都能看到这些约束。4.3 Trae 里导入技能的常见问题排查我整理了社区里反馈最多的几种现象现象常见原因处理方式技能列表里看不到导入的技能目录层级不对或者当前版本不支持自定义技能目录检查是否指向了包含 SKILL.md 的层级换一个支持技能的版本Agent 能看到技能但不会主动用description 和 Trae 的匹配逻辑不兼容在对话里显式写明使用 xx 技能别指望它自动触发导入后报格式错误frontmatter 缺少字段或格式不规范打开 SKILL.md 检查 YAML 头部对照官方示例修正Agent 行为没变化技能和 Trae 内置的系统提示词冲突把技能核心流程写入项目规则文件优先级更高有个细节值得说Trae 国内版的技能机制迭代比较快网上教程经常过时。我的建议是别追求把整套 superpowers 都搬进去挑最需要的两三个技能手动复制即可这样即使 Trae 升级导致机制变化你维护成本也低。5. 实战视角TDD、写计划、系统化调试这三板斧怎么改变工作流5.1 TDD 技能实测一次真实的红-绿-重构过程我在一个内部工具项目里让 Codex CLI 用 TDD 技能实现一个解析简单 CSV 行的函数。没装技能前它的习惯是先给出一个完整实现然后问我还要不要补测试。装了之后整个流程变成了第一步它先写了一个针对空字符串、单字段、多字段、带逗号转义等场景的测试文件第二步它运行测试把失败结果贴给我看确认这些测试当前是红的第三步它才开始写实现每写一点就重跑一次测试直到全绿第四步它问我要不要做重构把重复的解析逻辑抽出来最让我意外的是第二步。以前它从来不会主动先跑一次失败的测试给我看这个动作看起来多余但实际上是整个 TDD 的灵魂确认测试真的在测、确认失败原因确实是功能缺失而不是测试写错。这一步保证了后面变绿是有意义的。5.2 写计划技能实测从闷头改到先给你看方案有一次我需要在一个老项目里加一个新的权限拦截逻辑涉及路由层、服务层和前端的一处判断。这种跨层改动以前让 AI 直接做我总得盯着它改完再 review特别累。superpowers 的 writing-a-plan 技能会让 AI 先输出一份实施计划包括改动涉及哪些文件、每步改什么、风险点在哪、怎么验证。而且它会把计划保存成任务清单每完成一项就勾掉一项我在对话里随时能看到进度。这个技能对我的价值不在于计划本身多完美而在于它把 AI 的思考过程外显了。它到底打算怎么改、有没有遗漏关键调用链我在它动手前就能看出来不需要等它改完再 review 一大坨 diff。对跨文件、跨模块的改动这个习惯能省大量返工时间。5.3 系统化调试技能实测告别瞎猜-乱改循环我最头疼的是偶发 bug。之前 AI 遇到测试偶尔失败的情况第一反应是可能是并发问题我加个锁试试。这种没有证据链的猜测十次有八次是错的。superpowers 的 systematic-debugging 技能强制 AI 按证据链走先完整读取报错信息和相关日志列出所有可能的假设然后设计一个小实验去验证最可能的假设验证通过才动手改改完还要复现几次原来的场景确认问题真的消失。我记得有个线上接口偶发 500 的问题AI 用这套流程锁定到是某个缓存 key 在特定并发量下会被提前淘汰而不是一开始猜的数据库连接池耗尽。这个结论靠的是日志时间戳对齐和一次人为制造并发压力的复现实验。说实话这套流程如果让我手动盯着 AI 做我会嫌烦但技能把它变成了默认行为之后反而省心。6. 用了几个月的经验总结收益最大的场景与不建议神化的地方6.1 哪些场景收益最大根据我的实际体验以下场景用 superpowers 收益最明显遗留代码加功能writing-a-plan 强制先梳理现有调用链AI 不会上来就乱改对正确性要求高的逻辑TDD 技能让 AI 先把测试想清楚实现反而不容易出错难复现的 bugsystematic-debugging 的证据链方法比模型天然倾向的猜测式改法靠谱得多团队协作项目统一的技能流程让 AI 产出的代码风格和验证方式都更一致6.2 不建议神化的地方和踩过的坑有没有不适合的场景有而且不少。纯临时脚本比如你只想快速格式化一份数据、写个一次性爬虫技能流程带来的额外轮次反而拖慢速度。这种情况下我会临时告诉 AI不要用任何技能。模型上下文窗口有限时技能文件本身会占用一定的上下文开销。如果模型本身能力偏弱塞太多技能指令反而压缩了它处理代码的空间效果适得其反。内置规则冲突Trae 或 Codex 自带的系统提示词如果和技能流程冲突比如 IDE 默认要求尽快给出代码表现就会时好时坏。解决方法是把技能要求写进项目规则文件让高优先级约束覆盖默认行为。技能匹配不稳定这是我最想吐槽的一点。description 写不好AI 就会在该用的时候不用在不该用的时候乱用。我的做法是在关键任务里显式点名技能不要依赖自动匹配。6.3 我的建议配置如果你刚开始接触我不建议把整套技能都装上。先装这三个writing-a-plan、test-driven-development、systematic-debugging。跑一两周等习惯了 AI 先计划、先测试、按证据调试的工作节奏再考虑加 brainstorming 或 generating-commits。配置上给所有编码代理统一维护一个技能目录比如放在~/superpowers然后让 Codex 和 Trae 都指向同一份。这样只需要维护一份技能文件升级也方便。我在实际使用中发现superpowers 真正改变的不是某个具体任务的结果而是我对 AI 编码代理的信任方式。以前它改完代码我总要仔细 diff、反复验证现在它走完 TDD 流程、留好测试、给出清晰的提交记录我 review 的负担轻了很多。它不会让 AI 突然变聪明但它能让 AI 把已经会的东西用得更像一个成熟的开发者。最后再分享一个小技巧把 superpowers 的技能触发说明比如涉及核心逻辑时必须先写测试写进项目的 AGENTS.md 里这样你团队里的其他人用同一个项目时AI 也会自动带上这套工作方式。这算是我这段时间折腾下来觉得性价比最高的一个附加配置你装上之后可以试试。