聊聊最近一直在折腾的一个东西——Superpowers。如果你最近在关注 Codex CLI、Claude Code、Trae 这类 AI 编码助手应该经常在 GitHub 和开发者社区刷到这个词。它不是一个编程语言也不是某个前端框架而是一套面向 AI 编码助手的技能包Skills核心代码在 GitHub 的 obra/superpowers 仓库里现在已经被很多人装进自己的 AI 工作流。围绕superpowers 怎么装、怎么用、有什么用社区里的讨论一直很热尤其是 Codex CLI 用户几乎每隔几天就有人在问安装教程。简单说Superpowers 解决的是 AI 编码助手最常见的毛病上来就动手改代码、改了就跑、跑挂了再瞎修、循环几次后把自己绕晕。它把人类工程师那套先问清楚需求再写方案再写测试再写实现再审查的严谨流程封装成了结构化指令让 AI 在动键盘之前先想清楚我在解决什么问题、边界在哪、怎么验证。这篇文章是我自己折腾了将近两周的完整记录覆盖它到底解决了什么问题、三端安装配置、核心技能怎么用以及我踩过的坑。适合正在用或者准备用 Codex CLI、Claude Code、Trae 的开发者也适合那些觉得AI 写代码不靠谱但又不想放弃的人。1. Superpowers 到底是什么不是魔法是一套可复用的工作流技能包1.1 从提示词到技能AI 编码助手的进化以前我们用 ChatGPT 写代码靠的是提示词Prompt你把需求写清楚它给你一段代码。到了 Codex CLI、Claude Code 这一代工具本身已经能跑终端命令、读写文件、跑测试跑脚本相当于模型长了手脚。但长了手脚也带来了新问题它太容易自己动手了。你让它帮我修一下登录接口它可能直接打开代码就开始改改完后告诉你搞定。但实际呢它也许只改了一个分支没考虑错误返回没跑测试甚至把别的模块改坏了。这里面的核心矛盾是模型擅长生成代码但需要改哪几处代码这个决策需要的是工程判断而不是语言生成。技能Skills机制就是冲着这个矛盾来的。它的思路很简单把一些经过验证的、可重复的工作方法比如头脑风暴写计划测试驱动开发根因分析预先写成结构化的说明文件告诉模型在什么场景下应该启动哪个方法、按什么步骤执行、每步要产出什么。你可以把技能理解成给 AI 用的岗位 SOP。人类新员工入职也这样不是靠脑子记住所有流程而是先看部门手册遇到什么情况翻开对应章节照着做。AI 的技能就是这本手册。1.2 Superpowers 技能全家桶Superpowers 这个项目最有意思的地方是它不是给你单个技能而是给了一套互相配合的技能全家桶。我整理了一下仓库里的核心技能brainstorming需求还不清晰时先通过提问澄清目标、限制条件、验收标准而不是急着给方案。writing-plans把任务拆成一条条的实现计划计划里描述改哪个文件、做什么改动、怎么验证但不写具体代码。implementing-changes按照计划逐步改代码每完成一步就验证一步不允许一口气改完。test-driven-development严格的测试先行流程走红-绿-重构循环。debugging遇到 bug 时先建立可复现的失败场景再定位根因不靠猜。root-cause-analysis问题修复后继续追问为什么会发生避免治标不治本。code-review像老同事一样审代码从逻辑、边界、安全、性能几个维度过一遍。security-review针对安全敏感改动做专项审查。refactoring在不改变外部行为的前提下优化代码结构。每个技能都是一个文件夹里面放着 SKILL.md 文件有的还有配套的模板和示例。技能之间还有依赖关系比如 implementing-changes 会引用 writing-plans 生成的计划TDD 技能又会在修改功能时主动插进来。这套技能编排的思路也是它和普通提示词模板最大的区别不是一个技能走天下而是一套流程彼此咬合。1.3 谁在用、用在什么场景从我看到的社区反馈Superpowers 的典型用户其实不是不会写代码的普通人反而是本来就有工程经验的开发者。最常见的几种用法让 Codex CLI 实现一个新功能但不想让它一顿乱改希望它先给方案、先写测试。团队里用 AI 助手处理维护性任务比如修 bug、补测试、重构老代码但因为代码库复杂AI 很容易改错地方。在 Trae 这类集成开发环境里希望 AI 的行为更像一个真实的结对程序员有问有答而不是一个代码生成器。2. 为什么 Coding Agent 需要 Superpowers让模型慢下来、想清楚2.1 AI 写代码最常见的五种翻车方式先说说没有技能控制时AI 编码助手最容易翻车的五种情况我自己全踩过。第一需求没澄清就动手。你说加一个导出功能它默认按自己的理解实现了一个 CSV 导出但你要的其实是 Excel 模板导出甚至还要按部门权限过滤数据。返工成本极高。第二改动范围失控。一个看起来很小的问题AI 可能顺手改了三个文件还动了格式化配置。提交记录一拉满屏都是无关 diff。第三没有测试全靠看着像。AI 改完代码自己读一遍觉得没问题就宣告完成根本没跑测试。等检查流程跑挂了才发现基础功能被它顺手改没了。第四调试靠猜。出 bug 了AI 不是先复现而是直接从代码日志里猜一个原因改一行再猜一个再改一行。运气好能蒙对运气不好把正常代码也改坏了。第五没有计划没有回退路径。AI 一旦进入边改边想模式改着改着自己也忘了改过什么出了新问题没法定位。这五种情况有一个共同的根源模型太快了快到没有建立上下文-方案-验证的闭环。Superpowers 干的事情本质上就是强制它把这个闭环补上。2.2 技能机制的原理SKILL.md 与显式工作流那么技能在技术上是怎么落地的呢现在主流的编码 AgentCodex CLI、Claude Code、Trae 等都开始支持一种基于 Markdown 的技能格式。一个技能就是一个文件夹里面最关键的是 SKILL.md 文件它分两部分YAML frontmatter 和正文。frontmatter 里写着技能的名称和描述描述最重要因为模型就是靠这段描述来判断什么时候该用这个技能。正文里则是详细的工作流程说明包括步骤、检查清单、输出模板。举个例子一个简化版的 brainstorming 技能文件大概长这样--- name: brainstorming description: 当需求不清晰、存在多种实现路径或者需要先收集需求时使用。用在写代码之前。 --- # Brainstorming 技能 当你需要开始一个功能开发时必须执行以下步骤 1. 列出你已知的信息。 2. 列出你不知道、需要向用户确认的问题按重要性排序。 3. 一次只问一个问题等待用户回答后再继续。 4. 当需求信息足够时用列表输出需求确认结果并请用户确认。 5. 用户确认后才能进入计划阶段。这个文件被放到 Agent 的技能目录之后Agent 在每次对话开始时都能看到所有技能的描述。当它判断当前任务匹配某个技能描述时就启动这个技能把它的正文当作即时指令来执行。说白了SKILL.md 就是一种会被模型自动读取并按需执行的高级提示词。但它和普通提示词的区别在于它是结构化的、按场景索引的、可共享可安装的而且技能之间可以互相引用形成方法论。2.3 为什么先计划再编码能显著提升质量讲原理可能过于抽象我举个真实体会。有一次我让 Codex 修复一个权限校验的 bug。按默认行为它直接找到了权限判断的函数改了一行说已修复。但实际上这个 bug 出现在调用链的上游权限判断本身没写错是传给它的参数错了。用 Superpowers 之后情况完全不同它先启动 brainstorming 问了我三个问题——复现步骤是什么预期行为和实际行为分别是什么这个接口被哪些地方调用了然后写了一份 plan写明先确认调用链再做最小修改最后跑了一次复现测试确认修复有效。整个过程看着会慢一些因为多了一轮问答和计划但总时间反而缩短了一次通过没有返工也没有引入新问题。这一点其实不难理解。你在公司里评审需求、写技术方案不是流程主义而是为了把错误假设消灭在动工之前。AI 写代码本质上是连续做决策决策质量取决于它掌握的信息是否足够。多问一轮问题、多写一份计划就是在让它在更完整的信息上做决策。3. 安装与配置实操Codex CLI、Claude Code、Trae 三端实测3.1 前置准备环境与目录Superpowers 本质上就是一堆 Markdown 文件所以安装它不需要编译、不需要装依赖但需要你确认两件事Agent 工具已经能正常跑以及你清楚它读取技能的目录位置。目前主流工具的技能目录大致是工具技能目录说明Codex CLI~/.codex/skills/新版支持路径可能随版本调整Claude Code~/.claude/skills/也可通过插件市场安装Trae配置目录下的 skills 文件夹在设置中可查看具体路径我以 macOS / Linux 系统为例Windows 用户在%USERPROFILE%下对应路径操作逻辑完全一样。需要说明的是这个目录结构在不同版本之间偶尔会调整建议先执行codex --version或claude --version确认版本再到官方文档里看一眼 skills 目录是否有变化。3.2 Codex CLI 安装 Superpowers 的两种方式我先说 Codex CLI 的操作因为这个场景最近问的人最多。第一种方式git clone 后建立符号链接最稳推荐。# 1. 把 superpowers 仓库克隆到本地 git clone https://github.com/obra/superpowers.git ~/superpowers # 2. 确保 Codex 技能目录存在 mkdir -p ~/.codex/skills # 3. 把仓库里的 skills 目录下的每个技能链接进去 ln -s ~/superpowers/skills/brainstorming ~/.codex/skills/brainstorming ln -s ~/superpowers/skills/writing-plans ~/.codex/skills/writing-plans # ... 其他技能同理为什么要用符号链接而不是直接复制因为后续你git pull拉取仓库更新时链接目录里的内容会自动更新省得每次升版本都重新覆盖一遍。如果你只是想先体验某个技能也可以只链接一两个不用全量装。第二种方式如果你的 Codex CLI 版本内置了 skills 管理命令可以直接用。例如有些版本支持codex skills install obra/superpowers如果你的版本提示没有这个子命令就退回第一种方式没必要为了这个特意升级。装完之后自己读一下技能目录确认每个技能下都有 SKILL.mdls ~/.codex/skills/brainstorming/看到 SKILL.md 文件说明这一步没问题。如果目录是空的检查一下前面的符号链接命令有没有执行成功。3.3 Claude Code 安装市场Marketplace方式Claude Code 这边有个更省事的路子插件市场。在 Claude Code 会话里直接执行/plugin marketplace add obra/superpowers-marketplace /plugin install superpowerssuperpowers-marketplace安装完成后可以用/plugin查看已安装的插件。这类插件机制的好处是它会把技能文件放到正确的位置并处理好版本关系不用你自己去管目录结构。如果你不想用插件市场也可以走手动路线把技能目录复制到~/.claude/skills/下效果是一样的。插件的底层其实就是帮你做这些文件的搬运。3.4 Trae 导入 Superpowers skillTrae 这边的情况稍有不同。Trae 的 skill 功能入口一般在设置或者 AI 配置面板里你可以先找到它的技能管理页面看看是否支持从本地目录导入。如果支持导入直接把~/superpowers/skills里对应技能文件夹选中即可。如果只支持指定目录扫描把技能文件复制到 Trae 的 skills 目录下重启一下客户端通常在会话中就能感知到技能。我实测下来的经验是Trae 版本迭代比较快技能功能的名称和入口可能在某些版本里还不叫 skills而是叫技能市场或者扩展能力。找不到就直接在应用内搜索框搜技能两个字一般都能带出来。3.5 安装后如何确认技能已生效装完别急着干活先做两个小验证。验证一文件层面。确认技能文件确实存在且格式正确。SKILL.md 的 frontmatter 里必须有 name 和 description如果少了 description模型很可能根本不知道这个技能什么时候该用。验证二行为层面。新开一个对话故意用一句模糊的话开头比如我想给我的项目加一个搜索功能。如果技能生效Codex 或者 Claude 应该会主动进入 brainstorming 流程开始向你提问而不是直接甩给你一段实现代码。如果它毫不犹豫就开始写代码通常说明技能没有被加载。这时候可以先检查目录、检查文件名再看是否需要在工具的配置文件里手动启用技能目录。4. 核心技能使用指南从头脑风暴到代码审查4.1 brainstorming让 AI 先问问题再给方案我最喜欢也最推荐大家先试的技能是 brainstorming。它的作用是强制 AI 在拿到一个模糊需求时先做信息收集。实操中你会发现它不是随便问问题而是有一套逻辑先确认目标你要解决什么问题再确认边界哪些事不做再确认验收标准怎么算完成再确认约束性能、兼容性、安全性。这里有个使用技巧不要把 brainstorming 看成和 AI 聊天把它看成和一位新加入项目的同事对齐需求。需求里的坑它不一定能替你想全但你可以在它的问题之外补充项目里特有的上下文比如你们技术栈的版本、历史包袱、团队约定。你给的上下文越具体它后面写出来的计划就越贴近实际。我见过不少人用 brainstorming 时觉得它太啰嗦这时候你可以直接告诉它请把问题数量压缩到五个以内它会在保持流程的前提下加快节奏。技能是死的人是活的。4.2 writing-plans把大任务拆成可执行计划当需求确认完毕Superpowers 会让你进入 writing-plans 阶段。这个阶段有一个很有意思的设定计划里不允许写具体代码只能描述要改哪个文件、改动方向、验证方式。这个限制非常反直觉但非常有用。因为一旦允许 AI 在计划里写代码它就会过早陷入实现细节忽略了对整体结构的影响评估。而只写方向性描述能逼着它先整理出完整的改动地图一共有几个文件要动它们之间的关系是什么改这个会不会影响那个。生成计划之后一定要自己读一遍。我把这个环节比喻成评审队友的设计文档。你不需要理解每一行但你要能看出来它说的改动是否覆盖了需求有没有明显多余的改动有没有漏掉测试。读计划花五分钟能帮你省下后面两小时的返工。如果计划里有你不认同的地方直接指出来。比如这个改动会影响老接口的兼容性计划里没有考虑它会立刻调整计划。这个沟通成本非常低比起让它闷头改完再回退要划算得多。4.3 TDD 工作流测试先行实现后至如果说 brainstorming 和 writing-plans 是想清楚那 TDD 技能就是稳落地。TDD 技能的执行顺序非常严格先写一个会失败的测试红再写恰好能让它通过的最简实现绿然后重构重构。每一条功能点都走这个循环。刚开始用的时候我觉得这个过程有点死板但后来发现对 AI 特别合适。原因是 AI 一次性生成的代码往往过度自信它倾向把一整段完整实现直接写出来里面藏着一堆假设。TDD 的小步循环把假设拆碎了每一步都有测试兜底哪一步假设错了立刻就能发现。使用 TDD 技能时要注意不要跳过写测试这一步直接要求 AI用 TDD 帮我改这个功能但不用写测试了。我试过一旦跳过测试所谓的 TDD 就退化成普通的改代码之前的质量保障也就没了。另一点经验是如果项目里还没有测试框架TDD 技能会先问你要不要搭一个最小可用的测试环境。这个环节建议让 AI 来做因为它对主流框架的初始化流程比你搜索来的教程更完整。4.4 debugging 与 code-review收尾阶段的利器debugging 技能的作用是让 AI 不靠猜来修 bug。它的标准动线是先复现问题再缩小范围再定位根因再修改再验证。我自己最受益的是先复现这一步。以前我会直接描述 bug 现象让 AI 猜原因。但现象往往只是表象比如页面白屏可能有一百种原因。Superpowers 的 debugging 技能会要求先给出稳定的复现步骤或最小复现用例然后从数据流、调用栈一点一点找源头。配合 root-cause-analysis 技能它还会在修复完成后追问一句这个问题的根因是什么以后怎么避免这看起来像是废话但当你翻代码提交记录时会发现大部分 bug 都是同一个根因反复踩坑。多这一步能帮你把经验沉淀下来。code-review 技能则适合在改完代码后主动跑一遍。你可以在对话里直接说请使用你的 code-review 技能审一遍我刚才的改动。它会从逻辑正确性、边界条件、安全问题、性能损耗、代码风格几个维度给出意见。这个技能我建议所有用 AI 写代码的人都养成习惯——AI 写代码的好处是快但快带来的问题就是粗糙审查恰好能补上这块短板。5. 常见问题与排查技巧实录5.1 技能文件装了但模型就是不执行这是问得最多的问题。文件在、目录对但 AI 还是秒回一段代码完全不走流程。我的排查顺序是这样的先确认技能描述里是否写了明确的触发条件。如果 description 写得模棱两可模型可能觉得当前场景不需要启动技能。其次是确认你是不是在同一个会话里继续了旧对话。技能通常在新对话开始时加载最完整旧对话里上下文已经被污染模型可能早就忘了技能的存在。最后如果还不行就在指令里点一下请使用 superpowers 中的 brainstorming 技能开始这个过程。给模型一个明确的技能名通常比让它自己判断更可靠。这也算是一个使用技巧不要把技能当成玄学它本质上是给模型的指令指令边界越清楚执行效果越好。5.2 技能目录不对 / 权限问题有些时候你会发现技能在 Claude Code 里能用但 Codex CLI 里找不到。这大概率是目录放错了。每个工具的技能目录是独立的不会互相共用所以同一个技能要在每个工具里各装一遍。这不是 bug而是设计如此。权限问题则通常发生在用ln -s创建符号链接的时候。如果链接指向的源路径不存在或者链接创建在受保护的目录里技能文件就会显示为缺失。用ls -l看一眼链接是否指向有效路径是排查这个问题最快的方式。还有一个容易被忽略的点技能文件夹名和使用时的技能名要保持对应。如果你把 brainstorming 的文件夹改成了my-brainstorm那模型可能依然只认brainstorming这个名字导致技能无法被触发。文件名最好不要动。5.3 技能之间的优先级与冲突Superpowers 的技能不是每个任务都全量启动而是按场景触发。但偶尔会出现两个技能的描述都匹配当前任务的情况AI 可能会同时启动它们导致行为混乱。遇到这种情况我的做法是在指令里明确指定优先顺序比如先使用 brainstorming 收集需求需求确认后使用 writing-plans 输出计划计划确认后再进入实现阶段。把流程顺序写清楚模型一般会严格照做。注意Superpowers 不是银弹。如果你的项目连测试框架都没有TDD 技能会执行得很别扭如果需求本身含糊不清brainstorming 问再多的题也无济于事。技能能规范流程但不能替代你对业务的理解。5.4 更新与回退如何跟随 upstream 版本Superpowers 仓库更新频率不低作者经常修技能文件的细节。使用符号链接安装的话更新非常简单cd ~/superpowers git pull如果你之前是直接复制的文件更新就要重新覆盖一遍所以我前面才推荐符号链接。但更新也可能带来意外某个技能的行为和你习惯的不一样了。如果你更喜欢旧版本可以在仓库里用git log找到历史提交把对应技能的文件单独签出覆盖回去。这个操作不复杂但需要你对 git 基本命令有点数。我的建议是不是所有更新都需要跟如果当前版本用着顺手完全可以锁在某个 commit 上等有大版本更新时再统一升。最后再分享一个我个人的使用习惯。我并没有给每个项目都装 Superpowers而是在需要多文件、多步骤、涉及老代码的任务里才显式启用它一些极小的、单文件的改动直接让 AI 对着明确指令做反而更快。工具是拿来用的不是拿来供着的知道什么时候该收起它也是一种调度能力。折腾了这两周我最深的体会是AI 编码助手的上限其实不取决于模型本身有多聪明而取决于你有没有给它一套正确的做事方法。Superpowers 就是把这套方法装了进去。无论你最后用的是它的完整全家桶还是只挑一两个技能融入自己现有工作流都建议你至少试一次 brainstorming——当 AI 第一次没有急着写代码而是先开口问你你的需求是什么的时候你就明白这个项目为什么叫 superpowers 了。
