如果你最近在折腾 Codex CLI大概率绕不开 superpowers 这个名字。我第一次看到这个项目时以为又是哪个中二病发作的玩具仓库直到连续三次被 Codex 在不该改的地方自作主张改了代码才老老实实去研究它。superpowers 本质上是一套挂在 Codex CLI 上的技能增强包把“先思考再动手、先计划再编码、先测试再重构”这一整套工程师的工作习惯做成了 agent 能按需调用的显式技能。它适合所有对 AI 编程助手有更高要求的人不想让 AI 变成“你说一句它改一段”的运气型选手而是希望它像一位靠谱的结对程序员先跟你对齐需求再动手写代码最后还能自查。这篇就从一个实际使用者的角度讲讲 superpowers 是什么、怎么装、怎么用以及我踩过的那些坑。1. superpowers 到底是什么为什么值得装1.1 从 Codex CLI 的短板说起Codex CLI 本身是个非常爽快的工具在终端里起一个会话用自然语言描述需求它就能直接改文件、跑命令、提交代码。问题也恰恰出在这个“爽快”上。默认状态下Codex 拿到一个任务往往会立刻跳到“写代码”那一步而不是先问清楚你要什么、现有代码的约束是什么、边界条件有哪些。结果就是小需求它处理得又快又好稍微复杂一点的需求它就容易过度设计、改错文件、或者写出逻辑对但风格完全不属于你的代码。我举个最典型的例子。有一次我让它给一个数据处理脚本加个日志功能它直接顺手把脚本里的函数参数签名全改了还顺带引入了一个新的第三方依赖美其名曰“更好的架构”。我当时血压就上来了我只想打几条日志你把我整个函数的对外接口都动了下游调用脚本全得跟着改。这种问题本质上不是模型不行而是缺少一个“先约束、再执行”的工作流程。1.2 superpowers 的定位把工程师习惯变成显式技能superpowers 要解决的就是上面这个流程缺失的问题。它不是换个更强的模型也不是改几句 prompt而是提供了一套可触发的技能skills。你可以把技能理解成 agent 的“工作手册”每个技能都包含一份结构化的指令文档告诉 Codex 在某种场景下应该按什么步骤行动、每一步要产出什么、要避免什么。举个例子superpowers 里有一个 brainstorming头脑风暴技能。当你触发它时Codex 不会急着写代码而是先跟你来回讨论需求把目标、约束、非目标、可能的方案都列出来直到你说“可以了”它才进入下一步。这就像你找一位资深工程师讨论方案对方不会一上来就敲键盘而是先跟你把问题本身想清楚。这种设计思路比单纯往系统 prompt 里塞一堆“你要仔细思考”要靠谱得多。因为技能是按需加载的平时不占用上下文窗口的宝贵空间只有你明确触发时才生效。它相当于给 agent 配置了一套“工作状态”需要头脑风暴时切到头脑风暴模式需要写代码时切到执行模式模式之间互不干扰。1.3 哪些人最适合装它我从实际体验出发觉得下面三类人收益最大。第一类是被 Codex 坑过的人。如果你已经遇到过 agent 乱改代码、改完不告诉你、跑了测试才发现挂了的场景superpowers 至少能把“乱来”的概率压下去一大截因为它的技能里强制带上了“执行前先确认影响范围”之类的检查步骤。第二类是带项目的人。不管你是个人开发者还是团队里的技术负责人都可以把 superpowers 当作“团队规范外部化”的载体。以前你写一堆团队约定文档指望每个成员都读现在你可以把这些约定做成 skill让 agent 在动手前自动读一遍、自动执行。第三类是刚接触 AI 编程的新手。新手最大的问题不是不会写 prompt而是不知道一个正经的编码流程应该长什么样。superpowers 把“思考—计划—编码—测试—自查”这个流程变成了 agent 的默认动作新手跟着它走一遍能直观感受到一个靠谱的编码流程是怎么运作的。2. 设计思路拆解为什么是“技能包”而不是更长更复杂的 Prompt2.1 传统 prompt 工程的三个死穴在 superpowers 之前我试过很多“调教” Codex 的办法最典型的就是写一个超长的系统 prompt把“你要先思考、再写测试、再实现、最后自查”所有这些规则全部写进去。效果有一点但问题也很明显。第一上下文被长期占用。几千字的规则塞在 prompt 里每次对话都要带着不但烧 token还容易把真正重要的项目上下文挤出去。Codex 的上下文窗口是有限的花在规则上的空间越多留给代码和文件内容的空间就越少。第二规则之间容易冲突。我写过“在动手前必须确认需求”又写过“要主动发现问题并解决问题”结果 agent 经常在“要不要主动加功能”这件事上精神分裂。它分不清哪些场景该保守、哪些场景该主动。第三规则是静态的无法按场景切换。写代码时的行为准则和做需求讨论时的行为准则本来就该不一样。单个 prompt 很难优雅地做到这种切换往往顾此失彼。2.2 skills 机制的两个关键设计superpowers 的 skills 机制恰好避开了上面三个问题。第一个关键设计是按需加载。技能文件放在磁盘上不占对话上下文。只有当你在对话里用skill-name的方式触发时Codex 才会去读对应的技能文档然后按照里面的步骤执行。其他时间这些文档就像图书馆里的书躺在架子上不会干扰正在进行的对话。第二个关键设计是工作流拆解。superpowers 没有试图用一个大而全的“万能技能”覆盖所有场景而是把编码工作拆成了多个小而专的技能。每个技能只负责一个环节环节与环节之间有明确的输入输出。比如 brainstorming 的产出是“清晰的需求说明”planning 的输入是“需求说明”产出是“分步实施计划”到了写代码阶段再由 implementation 技能按照计划逐步执行。这种拆解的好处在于你可以把不同技能组合出适合自己项目的流程。做的项目偏探索性质可以多走 brainstorming做的项目偏维护性质可以直接跳过头脑风暴用 TDD 技能硬约束测试先行。灵活性比一个全流程 prompt 高得多。2.3 我眼中 superpowers 的技能清单superpowers 具体包含哪些技能不同版本会有些差异但核心的几类基本是固定的。我基于自己用的版本整理一个常常被用到的清单技能类别主要作用我常用的触发场景Brainstorming需求澄清、方案探索新功能前期、需求模糊时Planning把需求拆成可执行步骤标注风险和依赖需求基本明确后动手前TDD / Test-Driven强制先写测试再写实现小步循环模块逻辑复杂、回归风险高时Debugging按“复现—定位—修复—验证”流程处理 bug遇到偶现问题或诡异报错Code Review从可读性、健壮性、安全性角度自查代码提交前自查或审查 agent 产出Explaining解释某段代码或某个概念读陌生代码、写技术说明注意这个清单并不是固定的。superpowers 的仓库本身也在快速迭代而且它允许你自定义技能。我后来就把自己团队的一些代码规范也做成了自定义 skill复用同一套机制。这也是它比普通 prompt 模板强的地方它是一套可以生长的框架。3. 安装与基础配置3.1 前置条件检查在动手安装之前先把环境检查一遍能省掉后面一大半的排障时间。第一要么你已经装好了 Codex CLI并且确认能在终端里正常跑起来。我用的版本是当时最新的安装过程中没遇到大的兼容性问题但如果你用的是很早的版本建议先升级因为 skills 机制是后面才逐步完善的能力。第二机器上要有 git因为 superpowers 的安装本质上就是从 GitHub 把仓库克隆到本地目录。第三确认你知道 Codex CLI 的配置目录在哪里。在 macOS 和 Linux 上通常是~/.codexWindows 上需要看实际安装路径。这个目录里通常有你的配置文件、日志以及 skill 文件的存放位置。3.2 安装步骤把技能仓库放进 Codex 的 skills 目录superpowers 的安装思路非常简单你只需要把这个技能仓库放到 Codex CLI 能读到的skills目录里然后在配置里声明启用即可。我在自己的机器上是用手动方式装的步骤如下。第一步进入 Codex CLI 的配置目录查看是否已经存在skills子目录。如果没有就自己建一个cd ~/.codex mkdir -p skills第二步克隆 superpowers 仓库到skills目录下。注意目录名最好保持仓库原本的名字先后顺序不要搞错否则后面 Codex 识别技能时可能找不到cd ~/.codex/skills git clone https://github.com/obra/superpowers.git第三步进到克隆下来的目录里确认结构和 README。以我当时拿到的版本为例仓库里有skills子目录里面是一堆以技能名命名的文件夹每个文件夹里有一个SKILL.md文件。这个SKILL.md就是技能的核心文档Codex 靠它来理解这个技能什么时候用、怎么用。第四步更新 Codex 的配置文件让 agent 能发现这些技能。不同版本的 Codex 配置方式略有不一致我当时是在配置里声明了额外的技能目录或者直接把默认路径指向了~/.codex/skills。最稳妥的办法还是打开 Codex 的配置文件看一眼看它支持哪些字段。这里我给一个通用的配置片段参考# ~/.codex/config.toml 中相关片段按你的版本调整 [skills] enabled true paths [~/.codex/skills]第五步重新启动 Codex CLI 会话输入superpowers或直接问它“你能用哪些技能”看它能不能正确列出。如果能列出说明安装成功了。如果你不想手动折腾官方 README 里也提供了一键脚本核心动作和我上面做的差不多无非是帮你自动完成 clone 和目录检查。我的建议是第一次装的时候手动来一遍你对整个目录结构会有更直观的认识后面出了问题也更容易排查。3.3 在 Trae 等 AI IDE 里使用这套 skills热搜词里提到了 Trae我也试过在 Trae 这类 AI IDE 里用 superpowers。思路其实和 Codex CLI 类似就是让 IDE 里的 agent 也能读到这套技能文档。Trae 有自己的规则和技能配置入口不同版本的入口位置会变。我当时的实践是在项目根目录下建一个.trae/skills目录把 superpowers 仓库的内容放进去然后在 Trae 的 Agent 设置里加了一条自定义指令声明“你可以使用项目内.trae/skills目录下的技能技能文件是 SKILL.md”。这样在 Trae 里对话时提到某个技能名它就会去读取对应文档并按流程执行。不过说句实在话IDE 里的技能机制比 Codex CLI 要新一些稳定性也差一点。我遇到过技能文档读不到、目录路径识别不了的情况通常把路径改简单些、或者在自定义指令里写得更明确就能解决。如果你主要在 IDE 里开发可以把它当成一个“增强提示”来用但不要指望它像在 Codex CLI 里那样无缝。4. 上手实战从需求到落地的完整工作流4.1 一个具体场景给 Python 脚本加批量重命名功能光讲概念太虚我拿一个真实的例子来走一遍流程。当时我有一个 Python 脚本功能是扫描指定目录下的文件按日期归档到不同子目录。现在我想给它加一个批量重命名功能把文件名里的空格替换成下划线同时把大小写规范化。这个需求看起来简单但其实有几个模糊点要不要递归处理子目录重命名过程中遇到重名怎么办要不要先输出一份“将要执行的操作”让用户确认这些如果不提前想清楚让 agent 自由发挥它往往会选一个“看起来最聪明”的方案而未必是你想要的。4.2 跟着技能走一遍brainstorm → plan → TDD → implement → review我在 Codex CLI 里新建会话第一句就触发了 brainstorming 技能superpowers-brainstorm 我想给现有的归档脚本加批量重命名功能帮我梳理需求和边界条件Codex 没有立刻写代码而是开始问我问题归档脚本现在是怎么遍历目录的重命名规则是全局统一还是可以按文件类型细分遇到目标文件名已存在时是跳过、覆盖还是自动加后缀要不要支持“先预览再执行”的 dry-run 模式这些问题很多我一开始确实没想清楚。聊了几轮之后它产出了一份简洁的需求说明列出了功能目标和几条明确的非目标比如“本次不处理文件内容只改文件名”。需求敲定后我接着触发 planning 技能superpowers-plan 基于刚才的需求说明生成实施计划这次 Codex 的输出变成了一份分步计划。它没有直接开始改文件而是把任务拆成了几步先阅读现有脚本的目录遍历逻辑确定在哪里插入重命名逻辑再设计重命名函数参数包括是否递归、冲突处理策略然后编写单元测试覆盖几种典型的冲突场景最后修改主流程把重命名功能接入命令行参数。每一步后面都标注了涉及的文件和风险点。接下来进入 TDD 技能环节。我触发superpowers-tdd 先写测试Codex 就真的先写了一个测试文件覆盖了空格替换、大小写归一化、文件名冲突加后缀这几个用例。我第一次跑测试的时候当然是失败的因为功能还没实现。然后它才在测试的约束下一步步把实现代码补上每补一个用例就跑一次测试直到全绿。这个过程看着有点慢但那种“不知道它在改什么”的焦虑感确实消失了。最后我在提交前触发了 review 技能superpowers-code-review 请审查这次改动它把改动过的地方列了一遍指出重命名函数里有一个边界情况没处理当目标文件名和原文件相同比如已经是hello_world.py规则处理后还是这个名字时会走一遍无意义的 rename 操作虽然不至于报错但最好判断一下直接跳过。这个小问题我自己 review 很可能会漏掉。4.3 实际效果与关键参数调优经过上面这一套流程最终的代码质量和可读性确实比“直接让 Codex 改”要高。更重要的是整个过程里我始终知道它在干什么、下一步要干什么而不是像以前那样等着它一次性吐出一大堆 diff然后我再心惊胆战地 review。如果想调整这套流程的执行风格可以关注几个参数。第一个是模型选择技能里的大量思考步骤对模型的推理能力有一定要求太弱的模型在 brainstorming 阶段容易流于形式问的问题都是泛泛的我至少会用一个推理能力强一点的模型实际体验会明显不一样。第二个是对话里的明确度触发技能时尽量把话说清楚比如“基于刚才的需求说明生成计划”“先写测试再实现”不要让 agent 猜你的意图。第三个是迭代的颗粒度TDD 技能默认喜欢小步循环如果你嫌它太啰嗦可以在触发指令里加一句“步骤可以合并但测试必须保留”效果会好很多。5. 常见问题与排查技巧实录5.1 装完技能不生效多半是目录和命名问题装完 superpowers 发现对话里触发没反应我遇到过的原因基本集中在三处按出现频率排序第一是目录路径不对。Codex 找技能时大概率是从配置的skills根目录往下找。如果你把仓库释放成了~/.codex/skills/superpowers/superpowers/skills/xxx这种嵌套结构它可能就找不到了。简单排查办法是在配置目录里执行find . -name SKILL.md看文档路径是否符合预期。第二是命名不一致。Codex 触发技能时用的名字通常来自 SKILL.md 里的 frontmatter比如name字段而不是目录名。如果目录叫superpowers-think但文档里的 name 写的是think那你在对话里敲superpowers-think可能就触发不了得敲think。我当时就在这个细节上卡了一会儿。第三是配置没生效。改完配置文件记得重启会话CLI 工具通常不会热加载技能列表。如果还不行可以试着把配置里的技能路径改成绝对路径排查是相对路径解析的问题。5.2 agent 还是乱写代码是技能没用对吗有人装上 superpowers 之后发现Codex 该乱写还是乱写。这种情况先检查触发方式技能是需要显式触发的不是说装上它就自动接管所有行为。你如果只是像以前一样直接说“帮我加个功能”没有用唤起任何技能superpowers 实际上根本没参与那行为自然和以前一样。另外技能只是定义了“流程”不代表“结果一定正确”。比如 brainstorming 技能帮你把需求聊清楚了但如果你在需求确认阶段就给了错误信息后面计划做得再漂亮也是错的。用技能的时候自己也要保持判断力不能全交给 agent。5.3 一个容易忽略的坑多套 skill 互相冲突superpowers 不是唯一的技能包很多人还会装其他技能或自己写一些技能。这时候要特别注意技能之间的冲突。我有一次把 superpowers 的 planning 技能和一个自制的“代码风格自动修复”技能同时放在配置里结果 planning 技能要求“只规划不改代码”而风格修复技能默认“看到不符合规范就立即改”两个技能同时在一次任务里被触发agent 的行为变得非常混乱它在规划阶段偷偷改文件改完又假装没改。这种问题的排查思路很简单临时把其他技能移出目录只保留 superpowers看问题是否消失。如果确认是冲突那就在触发时更精确地指定技能名或者修改其中一个技能的触发条件让它们不要在同一任务里同时起作用。6. 我踩过的坑和长期使用心得6.1 哪些技能我常驻哪些我关掉了用了几个星期之后我对 superpowers 的态度从“新鲜”变成了“按需使用”。现在我最常用的是 planning、TDD 和 code review 这三个基本上每次要动一个有逻辑复杂度的模块都会按这三个技能走一遍。Brainstorming 我反而用得不多因为日常很多需求其实已经很明确了再让 agent 反问我十来个问题会显得有点拖沓。相比之下debugging 技能我一开始觉得很实用后来发现它更适合那种难复现的诡异 bug简单的报错直接丢给 Codex 让它查反而更快。Explaining 技能我基本是关掉的因为我有自己的技术文档习惯不太需要 agent 用固定模板给我解释代码。这也说明 superpowers 不是一个“装上就别动”的包。它每个技能都是独立的你可以按自己的使用习惯调整把不用的技能挪出目录或者修改 SKILL.md 里的描述让它的触发条件更贴合你的场景。6.2 把它改造成自己的团队 SOPsuperpowers 给我最大的启发不是某个技能本身而是“把工程规范文档化、让 agent 按文档执行”这个思路。后来我自己写了一套团队技能把代码提交信息格式、分支命名规范、上线前的自检清单都做成了 SKILL.md 文件放进和 superpowers 相同的技能目录里。团队里的同事用 Codex CLI 时也能自动加载这些规范agent 写出来的东西就带上了团队的烙印。这里有个小技巧SKILL.md 前面的一段 frontmatter 一定要写清楚这个技能的适用场景和触发词因为 agent 在判断“什么时候该用这个技能”时就靠这些元信息。描述写得太抽象agent 会在不该触发的时候触发写得太具体它又会错过一些边缘场景。我一般会写一两行场景描述然后再加两三个典型的触发例子效果比较稳。6.3 最后一次建议先小项目练手如果你准备上手 superpowers我最后的建议是别拿正在跑的生产项目做第一次试验。找个玩具项目或者新建一个临时目录在里面把 brainstorming、planning、TDD 这几个技能完整走一遍感受一下每个阶段 agent 的行为边界。等你熟悉了一套流程之后再把它用在真实项目上就不容易出现“技能没触发成功但你已经让它动手改了代码”这种被动局面。根据我的个人体会superpowers 这类技能包不是“装上就变强”的外挂它更像是一套脚手架能把你平时写代码时那些“心里知道但说出来很费劲”的流程变成 agent 可以理解和执行的指令。花一个下午把它跑通后面每次和 AI 结对编程都会省心不少。
