Superpowers：给OpenAI Codex CLI装上工程素养技能系统

这阵子AI编程工具迭代得很快，但真正让我觉得“AI终于开始像工程师一样干活”的，反而不是某个大模型版本的更新，而是一个叫superpowers的开源项目。这个项目的定位很明确：它是给OpenAI Codex CLI加装的一套“技能系统”。如果你用过Codex CLI，应该有过这种体验——它确实能写代码，但更像一个记性不好、缺乏规划的临时工，你交代一句它做一步，稍微复杂点的任务就容易埋头乱撞，改坏了还意识不到。superpowers想解决的，就是这个问题。它不教你写prompt，而是把一套软件工程里的标准动作——任务规划、代码审查、测试驱动开发、批判性反馈——沉淀成可复用的技能文件，让Codex在动手之前先想清楚，在动手之后有检查点。这篇文章我会从设计思路、安装配置、技能原理解析到实战落地，完整拆一遍这个项目，适合已经在用或准备用Codex CLI、同时对代码质量有要求的开发者参考。

1. 项目全貌：给Codex CLI装上“工程素养外挂”

1.1 Codex CLI很好，但缺的不是智力是纪律

先聊一下Codex CLI本身。它是OpenAI推出的终端编程智能体，能直接读你项目的文件、执行shell命令、跑测试，相当于把你的整个代码库交到一个能理解自然语言的工程师手里。用过的朋友都知道，这个工具的上限很高，下限也很低。简单任务，比如“给这个函数加点参数校验”，它做得又快又稳；但一旦任务涉及多文件改动、需要先理解全貌再做决策，它就开始暴露问题：要么跳过测试直接改代码，要么改完不验证就跑，要么在某个分支里越钻越深，把原有的结构搅乱。

这不是模型智商不够，而是缺少工程纪律。真实的软件工程师为什么比AI写代码稳？不是因为他记得更多API，而是因为他有一整套流程：先看需求，再梳理现状，拆任务，写测试，小步改动，最后跑全量验证。这套流程不是天赋，是职业训练的结果。superpowers做的事情，本质上就是把这种职业训练浓缩成一套规则文件，在每次Codex对话开始时注入给模型，让它强制按工程方法论来工作。

1.2 “技能”不是一个功能，而是一套约束

superpowers的核心概念叫Skill（技能）。听起来很玄，实际上就是一个Markdown文件，里面写清楚“这个技能适用于什么场景、执行时分成哪几步、每一步要做到什么标准”。Codex在每次会话启动时，会读取项目里的AGENTS.md指令文件，superpowers通过这个机制把自己的技能库注册进去。于是AI在干活之前，会先看到一份“工作手册”，上面写着：遇到多步骤任务，请先调用规划技能；改完代码，请调用代码审查技能做自查；写新功能，请优先遵循测试驱动开发技能。

用生活里的例子类比，普通prompt像你口头跟一个厨子说“做桌菜”，厨子手艺可能很好，但做出来的菜全凭心情；superpowers则是给厨子一套标准菜谱，要求他先列菜单、称食材、按顺序下锅、每道菜出锅前试味。你说“做桌菜”，他走的是标准流程。你说“做个红烧肉”，他也知道要先焯水再炒糖色。这就是技能约束和自由发挥的区别。

这个设计有一个很聪明的地方：技能不是写死在程序里的，而是以普通文件形式存放的。这意味着你可以改内置技能，也可以新增自己的技能，甚至可以分享一套“前端重构专用技能包”给别人用。它把过去只能靠prompt模板沉淀的经验，变成了可以版本管理、可以评审、可以演进的工程资产。

2. 快速安装：5分钟跑通superpowers

2.1 前置条件：先有一个能用的Codex CLI

安装superpowers之前，你得先有Codex CLI，并且要能正常跑起来。以Mac环境为例，前提是Node.js版本不低于18，然后全局安装Codex CLI：

npm install -g @openai/codex

装完以后执行codex login，按提示完成账号认证。我在一台没有配过任何开发环境的机器上试过，Codex有一个依赖要注意：它需要本地的Git环境，因为很多任务都涉及diff和提交。如果Git没装好，后面跑技能时经常会卡在无法查看改动记录上。

装完之后建议先在任意一个项目目录跑一下codex，随便问一句“这个项目里最主要的模块是哪个”，确认它能正常读文件、回话、执行命令，再往下走。这一步不要省，因为我见过有人Codex本身没配好就装superpowers，结果怎么排查都以为是技能问题，最后发现是基础环境就没通。

2.2 安装superpowers：一条命令搞定

superpowers的安装方式非常简单，克隆仓库后直接跑安装脚本：

git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh

安装脚本做的核心事情有两件：第一，把整个skills技能库拷贝到你本地的Codex配置目录下；第二，在你当前项目的AGENTS.md里注入一段“引导说明”，告诉Codex“存在一套技能系统，遇到复杂任务时去技能库里找对应方案”。

装完之后怎么确认生效？很简单，找一个比较乱的项目，在终端里启动Codex，输入一句话：“我们来做一次多步骤任务，请使用规划技能。”如果安装成功，Codex的开场白会明显不一样，它会主动说“好的，我先使用brainstorming技能理清目标”，然后开始一步步跟你对齐，而不是直接上手改代码。

顺带提一下我在实际安装时遇到的坑：如果你之前手动改过Codex的配置文件，安装脚本在合并AGENTS.md时可能会提示冲突。解决办法是装之前先备份一下现有的AGENTS.md，装完以后人工检查合并结果，把自己之前的自定义配置保留下来。这也是开源工具常见的情况——它不是不强，而是不知道你本地已经改过什么。

3. 技能系统解剖：核心机制与自定义方法

3.1 一个技能文件长什么样

要理解superpowers，最直接的办法是打开一个技能文件看看。技能文件本质上是结构化的Markdown，我用一个简化过的例子来说明：

--- name: code-review description: 对已完成的代码改动进行系统性审查，找出潜在缺陷、风格问题和遗漏边界。适用于提交前自查或评审他人PR。 triggers: - 代码审查 - review code - 检查这次改动 --- # Code Review 技能 ## 执行步骤 1. 先获取当前分支与目标分支的diff，识别所有被改动的文件。 2. 逐个文件检查，重点关注：空指针风险、边界条件、并发问题、资源泄漏。 3. 检查测试是否覆盖了所有新增分支，标注没有测试保护的代码区间。 4. 输出审查结论，按“严重问题”“建议改进”“风格优化”三级分类，每条附上具体行号和修改建议。

这个文件有三个关键部分。frontmatter里的name是技能的唯一标识，description是技能的“自我介绍”，triggers是触发词列表。正文则是执行步骤，每一步都足够具体，模型读到之后就知道该干什么。

一个小细节值得注意：技能文件里尽量不要写过于空泛的话，比如“注意代码质量”“写出优雅的代码”，这种话谁的听着都对，但模型不知道具体要做什么。好的技能步骤应该像检查清单一样，可执行、可验证、有输出物。Codex本身已经很强了，它缺的正是这种“把空泛要求翻译成行动序列”的外部脚手架。

3.2 技能是怎么被Codex“看见”的

这个机制藏在Codex的AGENTS.md体系里。简单说，AGENTS.md是Codex在每个项目会话开始时自动读取的指令文件，里面写的规则相当于告诉模型“你在这个项目里干活需要遵循这些约定”。superpowers的安装脚本会在AGENTS.md里加一段类似这样的话：

你拥有一个技能库，位置在~/.codex/skills/目录下。当你遇到复杂任务时，先阅读相关技能文件，然后严格按照技能中定义的步骤执行。

这句话就是钥匙。Codex读到它之后，在回答问题前会先去看技能库里有什么，再根据任务类型选择匹配的技能。这也是为什么技能文件里的description要写得精准——它相当于技能的简历，模型靠它来判断“这个场景该翻哪本手册”。

触发方式有两种：显式触发和隐式匹配。显式触发是你在对话里直接说“使用某某技能”，模型会二话不说去读那个文件；隐式匹配则是模型根据当前任务自动判断，比如你说“帮我看看这次改动有没有问题”，它觉得这像code-review技能的活儿，就会自动去调用。隐式匹配的稳定性取决于description的措辞，这也是后面调试技能时最需要打磨的地方。

3.3 预置技能里最值得关注的三个

superpowers自带了一批预置技能，我不逐个列了，挑三个在实战中最常用的出来说。

第一个是brainstorming（头脑风暴与规划）。它强制Codex在动手写代码之前先和你对齐目标，梳理现有代码结构，列出任务拆解和风险点，直到你确认方案之后才进入执行阶段。用这个技能跑多文件重构，最大的感受是“AI不再闷头改了”，它会自己说出“我发现这里有一处隐式依赖，需要连同API返回结构一起改，你确认一下”这种话。

第二个是test-driven-development（测试驱动开发）。它约束的是“先写测试再生产代码”的顺序。具体执行时，Codex会先根据你对功能的描述设计测试用例，把测试写出来，跑一遍确认失败（因为功能还没实现），然后才开始写实现代码，最后再跑测试直到通过。这套流程对防守回归问题非常有效。我自己的体验是，用TDD技能写出来的代码，测试覆盖率明显高于自由发挥，而且由于测试先行，API设计反而更干净。

第三个是critical-feedback（批判性反馈），这个技能特别有意思。它允许并鼓励Codex对你的方案提出反对意见，并且必须用“事实+理由+替代方案”三段式来表述。打开这个技能之后，Codex不再是应声虫，比如我让它往某个类里加功能，它会说“加在这里会导致这个类的职责过重，我建议拆出一个新模块，理由是……”。很多说AI写代码“没主见”的人，其实不是模型没主见，而是没有收到“允许反驳”的指令。这个技能就是干这个的。

3.4 自定义技能：把团队规范变成AI的工作流

用了一段时间内置技能之后，你大概率会想写自己的技能。这比想象中简单，因为格式非常自由，本质上就是写一份“操作手册”给模型看。

我自己的经验是，自定义技能特别适合用来固化团队规范。比如你所在团队要求所有新增接口必须带OpenAPI注释、核心业务必须写集成测试、发版前必须跑迁移脚本检查——这些事情靠口头叮嘱永远有人忘，但写成技能文件之后，每次Codex执行相关任务都会自动带上这套约束。

给一个我自己写的技能做参考：

--- name: add-rest-endpoint description: 新增REST API接口时使用。适用于在Controller层添加新端点、在Service层实现业务逻辑、补充OpenAPI文档的场景。 triggers: - 新增接口 - 写一个API - add endpoint --- # 新增REST接口 1. 阅读项目已有的Controller代码，确认路由前缀、统一返回体、异常处理方式，新端点必须保持一致风格。 2. 在Service层实现业务逻辑，Controller只做参数接收和结果包装，不写业务。 3. 为新增端点编写OpenAPI注解，包括请求参数、响应码、错误码含义。 4. 写一个集成测试覆盖成功路径和至少两个失败路径，运行测试确认通过。 5. 完成后汇报：端点路径、请求示例、测试结果。

写完之后放到技能库目录下，下次Codex看到“帮我加一个查询用户订单的接口”这类需求时，就会自动加载这个技能。这个过程让我意识到，所谓AI编程提效，真正的杠杆不在于模型本身多强，而在于你能不能把自己的工程经验以机器可执行的方式表达出来。

有一个写技能文件的重要提醒：技能文件不是越长越好。因为技能库里的所有路径是注册在Codex的初始指令里的，如果每个技能都洋洋洒洒几千字，会占用大量上下文窗口，反而拖慢模型响应、影响主任务表现。好的技能应该控制在简洁可执行的量级——步骤清晰、关键约束明确、输出物具体，不要塞对模型没用的背景故事。

4. 实战：写一个“安全重构”技能并跑通它

4.1 场景设定：改造一个Java状态机

理论讲了半天，不如动手做一个技能出来。我选一个在Java项目里很典型的重构场景：订单状态机。初始代码里状态流转全写在一个大方法里，用switch分支判断当前状态和操作，决定下一个状态。

public OrderState transition(OrderState current, OrderEvent event) { switch (current) { case CREATED: if (event == PAY) return PAID; if (event == CANCEL) return CLOSED; break; case PAID: if (event == SHIP) return SHIPPED; if (event == REFUND) return REFUNDED; break; // 后续省略... } throw new IllegalStateException("非法状态转移: " + current + " + " + event); }

这个方法刚写出来时还好，一旦状态和事件越来越多，加需求的人就开始害怕——改一处担心漏掉另一处，加一个状态要在这个switch里找到所有相关分支，测试不好写，逻辑也不好读。重构目标是用策略模式把这套逻辑按“状态”拆开，每个状态自己管理它能处理的事件和转移结果，把大switch消灭掉。

这类重构最大的风险是改变行为。代码结构怎么改都好说，但如果重构过程中漏了一个分支行为，线上就会出现诡异的订单状态错乱。所以这个场景特别适合交给superpowers来做——它天生擅长按计划分批改动，而且能强制每一步都跑测试验证。

4.2 编写技能：把重构拆成六步

我新建了一个技能文件，命名为safe-refactor-state-machine，放在技能库目录下。技能描述里写明适用场景和触发词，正文则拆成六个步骤：

1. 梳理现状：读取订单状态相关的全部代码，列出所有状态、所有事件和当前转移规则，画出一张完整的规则表。
2. 检查测试：运行现有的测试套件，确认重构前全部通过；找出测试没有覆盖的状态转移分支，记录下来。
3. 设计映射：定义状态对应的策略接口和各个状态类，确定状态下放后的职责边界。
4. 渐进迁移：一次只迁移一个状态的行为，将对应分支的实现复制到新状态类中并适配，然后立刻运行全部测试。
5. 删除旧逻辑：所有状态迁移完成、测试全部通过后，再删除原switch方法，替换为策略查找表。
6. 复核收尾：跑全量测试证明行为不变，最后用git diff检查改动只涉及结构不涉及业务规则。

每个步骤都写明了验收标准，比如第四步的验收标准是“该状态的迁移分支全部由新类接管，且全量测试通过”。这样写的好处是，Codex在执行过程中能自己判断“这一步做完了没有”，而不是走完流程就算完。

4.3 调用过程与效果观察

技能文件写好之后，我在项目目录下启动了Codex，输入：

使用safe-refactor-state-machine技能，对OrderStateMachine里的状态机逻辑做一次重构，目标是把switch结构替换为策略模式。

Codex的回应方式和平时明显不同。它没有直接开始改代码，而是先输出了一段项目现状梳理，把当前状态枚举、事件枚举、所有转移规则列成表格，然后问我对“拆分粒度”有没有特别要求。确认之后它开始写测试，把现有的状态转移测试跑了一遍，标注出有两个边界分支没有被覆盖。

接着它按顺序迁移状态。每迁移完一个状态，它就自动跑一次测试套件，把通过的截图信息放在对话里。这个过程中我没有催它，也没有纠正它，它像一条流水线一样自己推进。全部迁移完成后，它主动执行了一遍全量测试，然后生成了git diff摘要给我做人工复核。

我重点检查了diff里的转移规则，逐条对照原始逻辑，确认没有语义变化。整个重构过程大概用了几分钟，中间Codex做得比较到位的一点是：在迁移到REFUNDED状态时，它发现原方法里“PAID状态接收REFUND事件才进入REFUNDED”，但新状态类里“REFUNDED状态自己不应该再处理任何事件”，这个边界原本在switch里看不出来，策略化之后反而暴露了设计上“允许从其他状态直接退款”的隐藏分支。它把这个疑问提了出来，而不是闷头照抄。这种“发现问题并主动汇报”的行为，正是技能系统设置的检查点起的作用。

这段经历给我的感受是：superpowers真正改变的不是AI写代码的速度，而是AI在复杂改动面前的可靠程度。自带检查点的技能流程，把“重构不出错”从碰运气变成了流程保障。

5. 问题排查：技能不触发、中途跑偏怎么办

5.1 高频故障速查表

用superpowers一段时间后，我总结了一些常见问题，先给一张速查表，再展开聊几个典型的。

5.2 技能不触发时的三个排查路径

技能不触发是问得最多的问题。我之前遇到过一回，技能文件和路径都确认没问题了，Codex就是不读取。后来排查下来，原因是项目根目录下面有一个旧的AGENTS.md文件，把superpowers生成的指令覆盖了——Codex的机制是项目级AGENTS.md优先于全局配置，如果项目里已经存在一份更具体的指令，superpowers里的技能库路径可能不会被读取。

排查路径我一般按三步走：第一步，启动Codex时开启调试模式或直接查看当前加载的AGENTS内容，确认技能库路径有没有进去；第二步，在对话里让Codex“列出你当前可用的所有技能”，看它的回答里有没有提到技能库；第三步，检查技能文件本身的frontmatter格式，YAML里如果有非法字符，模型可能在解析时就跳过了。大多数情况下问题出在前两步，格式问题相对少见。

还有一个我学到的技巧：不要直接用“使用技能”这种含糊说法，最好把技能描述里的关键词带进你的需求里。比如技能文件里本来写明了“适用于重构状态机”，你说“我有一个状态机需要重构，请按你的技能方案来”，命中率会高很多。这其实是给模型降低判断成本，它不用猜你到底想不想用技能。

5.3 技能执行中途跑偏，怎么拉回来

AI执行技能跑到一半脱离清单，这是另一个让我一开始很头疼的问题。典型场景是：Codex在按步骤执行时遇到一个错误，于是自己“灵机一动”开始修别的东西，或者因为觉得当前步骤太难直接跳过去做了另一个任务。出现这种问题的根源，往往不是模型不听话，而是技能文件里“该做什么、不该做什么”写得不够硬。

我后来会在写技能时加一条明确规则：

在完成任务之前，不要做任何不在步骤清单中的额外操作。遇到目标和现实不符的情况，停下来向用户汇报，等待指示。

这句话很短，但效果立竿见影。它的作用是给模型的自由发挥划清边界。AI的问题从来不是能力不足，而是缺少刹车机制。技能系统本质上就是一套不断的刹车系统：每一步做完都有检查点，不符合预期就停下来汇报，而不是任由模型自我感觉良好地一路冲下去。

另一个减少跑偏的方法是控制技能粒度。把一个大技能拆成几个小技能，比在单个长文档里写几十个步骤要稳定得多。长技能的问题是上下文里步骤太多，模型容易“忘记”自己走到哪一步了；拆细之后每个技能只需要专注一件小事情，每一步之间还可以人为设置确认点。

5.4 技能库的长期维护经验

最后聊一下长期使用的维护心得。技能库不是一次建好就完事的，它需要随项目演进。我自己的习惯是每个迭代结束之后做一次技能反思：这段时间有没有重复教AI做同一类事情？有没有遇到“每次都要重新叮嘱一遍”的场景？如果有，就把它们沉淀成一个新技能，或者补充进现有技能的相关步骤里。

维护时要特别留意技能之间的冲突。比如TDD技能要求先写测试后写代码，但某些探针调试场景可能更需要先快速验证思路。遇到这种情况，我会在技能文件的描述里写明“不适用于快速原型验证”，避免技能之间抢活。

还有一个建议：技能文件放在Git里管理。技能本质上是你团队工程文化的资产，跟代码一样值得版本管理。每次修改技能后就提交一次，把commit message写清楚，比如“新增REST接口技能，补充Controller层风格约束”。这样出了问题时可以回溯，新成员入职时也能通过阅读技能库快速了解团队规范。

一些体感上的总结

在多个实际项目里跑过superpowers之后，我个人最大的感慨是：这类技能系统，比模型本身的更新更能影响AI编程的体验。模型的能力就像一个运动员的体能，状态会有起伏，但决定比赛输赢的往往是战术执行——什么时候该冲、什么时候该稳、什么时候该停下来确认。superpowers提供的正是这套战术框架。

实际运行中我会注意一个分寸：不是所有任务都值得套技能。简单的问询、一次性的调试命令、纯探索性任务，直接跟Codex对话就好，强行套技能反而像用杀鸡刀宰牛、用流程拖死效率。技能库的设计初衷是处理复杂任务和重复工作，这两个场景是它价值最大的地方。

如果你正准备去GitHub上找superpowers试试，我的建议是：装好之后不要急着建一堆自定义技能，先把预置技能用熟练，在真实项目里感受“有流程”和“没流程”的差别，再根据自己踩过的坑慢慢沉淀技能。工具本身是免费的，真正值钱的是你通过使用它提炼出来的那套个人工作流，那才是你自己的superpowers。