Superpowers：给Codex CLI加一层技能工作流，让AI编程不再丢三落四

最近在折腾 Codex CLI 的时候偶然看到 GitHub 上有个叫 superpowers 的开源项目光是名字就很对我的胃口。当时我在处理一个跨模块的重构需求Codex 单轮对话表现得很好但一连串任务执行下来总是丢三落四改完代码不跑测试、跑完测试不看输出、遇到报错不想上下文。superpowers 的核心思路一下子戳中了我——不是换一个更强的模型而是给现有的 agent 工具套一层“工作手册”。这个项目本身不是模型也不是插件而是一整套 Markdown 技能文件。它把软件开发里的常见动作比如任务规划、代码阅读、测试驱动、调试复盘拆成标准的流程指引让 Codex 在 agent 模式下能按流程走而不是凭感觉乱撞。我用了一段时间之后最直接的感受是以前是“盯着 AI 干活”现在是“给 AI 派活然后审结果”省心程度完全不在一个量级。这篇文章就把我实际安装、配置、使用、踩坑的过程完整记录下来给正在玩 Codex CLI 或者想给自家 agent 工作流加 buff 的朋友做个参考。1. 为什么会有 superpowersCodex 到底缺了什么1.1 Codex CLI 的能力边界Codex CLI 给我的第一印象是它是个聪明的结对程序员但不是个靠谱的项目负责人。单次对话里你让它修个 bug、写个函数它干得相当漂亮可一旦需求稍微复杂一点比如“把这个模块重构一下顺带补上测试再更新一下文档”它就开始飘了。不是能力不够而是缺少对任务的全局拆解能力。它会直接扑到最显眼的那行代码上改完就默认交付根本不回头检查测试有没有跑、有没有引入新问题。我自己用下来Codex 在几个方面的短板非常明显。第一它没有显式的任务规划机制给它一个多步骤需求它往往按“随机顺序”执行想到哪改到哪。第二它对项目结构的理解是零散的每次搜索文件像是碰运气经常搜到一堆不相关的工具函数反而错过了核心入口。第三它缺少“验证闭环”的意识写完之后不会主动跑测试、查 lint、做回归。这些问题不是模型的智商问题而是工作流问题。模型有知识、有推理能力但需要一个“流程外壳”去约束它的行为。还有一个隐藏问题Codex 默认的提示词是通用的它不了解你的项目规范、团队约定、验证标准。你可以把这些写进codex.md但大多数人的codex.md只是随便写了两句“你是一个编程助手”根本起不到行为约束的作用。superpowers 之所以有效就是因为它在这层把“流程约束”做深了而不是停留在“角色扮演”层面。1.2 superpowers 的思路技能包把流程变成显式指令superpowers 的设计初衷本质上是把“软件开发方法论”固化成模型看得懂的指令。项目里的每个技能文件都遵循一个固定的骨架这个技能在什么场景下触发、执行步骤是什么、每一步的输出格式是什么、有哪些注意事项。Codex 在启动时通过codex.md引用整个技能库之后每接到一个需求它就能在技能列表里找到最匹配的那个按里面的流程一步步走。这个思路像极了给一位聪明但散漫的员工发一本工作手册。手册不教他怎么写代码——这个他本来就会——而是教他怎么把一件大事拆成若干小事、每件小事的完成标准是什么、完成之后怎么自检。模型还是那个模型但有了这套流程约束输出的确定性就高多了。我在实际使用中最明显的一个体感是以前让 Codex 做一件事它总给我“我觉得这样没问题”的自信答复挂了 superpowers 之后它会主动跑测试、贴测试输出、告诉我哪一步验证失败了。值得强调的是superpowers 不是一个“伟大发明”它更像一个“工程化常识”。它把资深工程师带新人时反复强调的那套流程——先想清楚再动手、边做边验证、做完要复盘——翻译成了模型能严格执行的提示词。这种思路对任何 agent 类工具都适用只是 superpowers 选择先服务好 Codex CLI 这个生态。2. 安装部署从裸 Codex 到 superpowers2.1 环境准备Node、Git、Codex CLI 一个都不能少先说前置环境。我手头的开发机是 macOS Node.js 20 LTSCodex CLI 已经装好并完成了登录认证。如果你还没有装 Codex先装它再继续这里不展开。Codex 本身迭代很快建议先用npm install -g openai/codex把 CLI 升到最新版再搞 superpowers。我在旧版本上试过一次技能文件加载本身没问题但 agent 模式下对codex.md的读取偶尔会出现重复注入的怪现象升级之后才稳定。Node 版本也有讲究。superpowers 的加载脚本是 Node 实现的用了比较新的 ESM 语法Node 18 以下跑不了18 勉强能用但实测在 Node 20 LTS 上最稳。装之前用node -v看一眼版本太老的话先用 nvm 切一下别在这个环节浪费时间。如果你用的是 Windows大部分命令是通用的但路径写法要注意建议直接用绝对路径形式。2.2 三步接入clone、install、引用技能库整个安装过程不复杂但有几个关键点必须讲透。先把标准命令走一遍# 1. 克隆技能库到本地固定目录 git clone https://github.com/steipete/superpowers.git ~/.superpowers # 2. 进入目录安装依赖 cd ~/.superpowers npm install # 3. 在项目根目录的 codex.md 里引用技能库路径第三步是最关键的。Codex CLI 启动时会读取当前项目下的codex.md把它注入到对话上下文中。superpowers 的加载方式就是通过这个文件把技能库引进来。在你的codex.md中写一行绝对路径引用/Users/你的用户名/.superpowers/skills这里有个细节符号是 Codex 的引用语法后面接路径支持文件或目录。如果你让它引用整个skills目录那么目录下所有.md技能文件都会被拼接进上下文Codex 就能在需要时调用。如果你只想让某几个技能生效也可以只引用单个文件这点后面专门讲。为了确认是否加载成功可以随便起一个对话然后追问“你现在可用的技能文件有哪些”。如果它能把 skills 目录下的文件名列出来并简单说明用途说明注入生效了。如果它一脸茫然说明引用没成功优先检查路径和codex.md的位置。2.3 配置优先级与合并策略说到配置文件这里有一个很多教程都没讲的坑。Codex 的配置读取是有优先级的项目根目录的codex.md优先于全局的~/codex.md而~/.codex/config.toml负责模型、沙箱权限等底层设置。如果你之前已经写了一份自己的codex.md千万不要直接覆盖而是把旧内容和 superpowers 的引用合并在一起。我当时犯过一个错为了省事直接把我原来的codex.md删了只留一行引用。结果 Codex 丢失了项目里自定义的技术栈说明开始瞎猜依赖关系生成的代码风格和项目原有风格明显脱节。后来我把项目自身的约束写在最前面superpowers 的技能引用放在后面。不同版本的 Codex 对于同一个文件里的重复指令处理策略可能不一样有的拼接、有的后者覆盖所以配置完务必做一轮小验证让 Codex 复述一下你的项目约束和可用技能确认两者都生效了再放心用。3. 核心技能拆解这些“超能力”从哪来、怎么用3.1 Task Planning先输出计划再动代码superpowers 里我体感最强的技能是任务规划。技能文件会要求 Codex 在开始编码之前先按固定结构输出一份执行计划目标是什么、已知背景有哪些、涉及哪些文件、按什么顺序执行、每一步的完成标准是什么。这个设计直击 Codex 的痛点——它太急着动手了。实际使用中只要我给出一个稍具规模的需求Codex 就会先输出目标一句话、背景若干条、步骤若干点、完成标准若干条。虽然这个输出还是文本但它逼着模型在动手前把整个问题的地图画出来。有了地图后续执行就像按导航开车而不是凭感觉拐弯。我自己的经验是如果 Codex 生成的计划里步骤少于三步大概率是它把需求想简单了这时候我会在对话里追问“这一步的验证方式是什么”它能立刻补全。3.2 Code Reading把“人肉看代码”的经验固化下来第二个我常用的技能是代码阅读策略。Codex 对代码库的理解完全依赖于塞进上下文窗口的源码片段。如果项目有几百个文件它不可能全读所以这个技能会引导它采用“由外到内、逐层聚焦”的路径先看 README 和目录结构再定位核心入口文件然后沿着调用链往下追而不是随机抽样。这个阅读策略本质上是在模仿资深工程师看陌生代码库的方式。没有它Codex 容易陷入细节读一堆边缘工具函数忽略了核心架构有了它它至少“知道”自己应该先看哪一层。我在一个中型 Java 项目里试过Codex 在技能约束下先找到了 Controller 层入口再往下追 Service、Repository整个理解路径基本符合我当时带新人时给的建议。对于代码量大的项目这个技能的价值相当可观。3.3 Test-Driven Development让验证闭环成为默认动作第三个核心技能是测试驱动开发。Codex CLI 的 agent 模式本来就能自己跑命令但跑之前它往往不会多想——改了一个函数就敢直接跑完整测试套件完全不考虑要不要先做针对性验证。superpowers 里的验证技能会强制它在改动后按“最小验证路径”执行先跑针对性的单测再跑相关模块的集成测试最后在合适的时候跑全量回归。这段逻辑非常关键。因为 AI 改代码最常见的翻车方式是它靠推理判断“这没问题”而忘了用测试去证明。技能文件里通常会写明任何代码改动都必须有测试结果作为证据任何“我认为没问题”都不算完成。工具本身不阻止它但指令越明确模型执行就越到位。我见过最典型的场景是Codex 改完一个工具函数后主动执行了npm test -- --grep 该模块看到输出全绿才进入下一步。这个习惯一旦养成整个 agent 流程的可靠性会提升一个档次。3.4 其他值得关注的技能Reflection、Agenda、Debugging除了上面三个superpowers 里还有几个辅助技能值得一说。Reflection反思会在任务完成后要求 Codex 总结做了什么、没做到什么、学到了什么这个看似多余的流程其实是把当前对话里积累的上下文做一次“知识备份”对后续连续任务帮助很大。Agenda 技能用来维护一个长期的任务清单适合那种“今天先摸清方案明天再动手”的分阶段开发。Debugging 技能则提供了一套系统的排查流程先复现、再定位、再修复、最后回归避免 AI 靠猜来修 bug。我见过很多人一次性把所有技能全引用进去结果 Codex 在对话里的“选择困难”反而变严重了——就像给一个人发了十本手册他反而不知道该按哪本执行。我的建议是核心场景先只引 task-planning、code-reading、test-driven-development 这三个跑顺之后再根据项目类型逐步加上其他技能。这个道理和搭积木一样先有地基再盖楼。4. 自己动手写技能文件把经验沉淀成 md4.1 技能文件的通用结构用了一段时间 superpowers 之后你会发现它的技能文件并不是什么高深的东西而是一种结构化的 markdown 模板。理解了这个结构你完全可以在自己的项目里写专属技能。以我看过的技能文件为例一般包含这么几块技能名称一句话说清这个技能是干什么的适用场景什么时候该触发这个技能执行步骤按顺序列出的操作清单必须清晰无歧义输出格式每一步的输出长什么样统一格式方便后续解析注意事项这个技能下常见的坑、禁忌、边界这种结构本身就是一种沟通协议。你在写技能文件的时候其实是在对未来的 Codex 对话“预演”一套操作规程。写得好不好直接决定了模型执行时是“严格遵守”还是“糊弄了事”。4.2 定制一个团队规范技能案例我举个例子。在我维护的一个后端项目里团队要求所有接口必须先写 OpenAPI 注释再写实现代码测试里必须包含异常分支。这些规范以前写在 wiki 里Codex 根本不会主动去看。后来我把它们写成了一个api-contract.md放在项目docs/skills/目录下并在codex.md里通过引用这个文件。文件里我用 superpowers 同款结构写适用场景是“新增或修改 API 接口”执行步骤是“先写 OpenAPI schema再写 DTO 校验再实现 service最后在 controller 层补异常测试”注意事项里写明“不允许在 controller 里直接操作数据库”“时间字段统一使用 ISO 8601”。配置之后Codex 在处理接口需求时真的会先输出 schema 再写实现和以前完全两样。所以我的观点很明确superpowers 最大的价值不是它自带的那几十个技能而是它给你示范了一种“如何给 agent 写操作手册”的方法。项目里积累得越多AI 干活就越稳。而且这些东西都用纯 Markdown 写版本管理极其方便团队里每个人都能 review、都能改。4.3 别让技能文件变成“废话大全”写技能文件也有反面教材。最大的坑是写了一堆正确的废话比如“请写出高质量的代码”“注意代码规范”——这种指令模型无法量化等于没写。真正有效的技能文件里每一条都得是“如果 A就做 B”的明确规则最好还能带上正反例。比如“当修改数据库迁移文件时必须同时更新对应表的单元测试”比“要重视测试”有用十倍。另一个坑是文件过长。技能文件最终会注入对话上下文写得太长会占用宝贵的 context 窗口反而影响模型处理实际任务。我自己一般控制在 30 行以内每条指令都精炼到不可删减。如果一个技能文件需要超过 100 行我建议拆分成多个聚焦的小技能让模型按场景选择而不是一次性堆给它。5. 实操记录用 superpowers 完成一个带测试的真实功能5.1 需求背景与任务描述为了让你直观看到这套流程跑起来是什么样我记录一次完整的实操。我在一个 Express TypeScript 的 demo 项目里给 Codex 下了一个需求“增加一个GET /api/export/csv接口把当前内存里的用户列表导出成 CSV 文件下载。要求补上单元测试并更新 API 文档。”我只给了这一句话然后进入 agent 模式全程观察它怎么走。没有 superpowers 的时候我预期它会直接写路由、写导出函数可能跳过测试。这次加了 superpowers流程完全不一样了。5.2 执行过程全记录第一步Codex 先输出了任务计划目标确定背景列出已发现的users.ts数据模块和routes/目录结构步骤拆成“写 schema → 实现 CSV 序列化 → 挂载路由 → 补测试 → 更新 README”完成标准里写明“测试覆盖包含正常数据和含逗号的字段”。第二步它按计划先找到了users.ts和路由文件把现有代码结构看了一遍才开始动手。这里 skill 的作用很明显——它没有一上来就改代码而是先阅读相关文件确保实现风格和项目一致。第三步是关键。它写了一个csv.ts工具函数实现了基本序列化然后生成了一个测试文件。测试用例里包含了一行name: Alice, Inc.的数据。跑测试时果然挂了——CSV 没处理字段内的逗号导致列错位。Codex 看到失败输出后没有直接改代码了事而是回退到 debugging 流程复现问题定位到序列化函数再按 RFC 4180 的规则给字段加了双引号转义然后重新跑测试全绿。整个过程我没有手动介入一次。它自己完成了从实现、测试、失败、修复、回归的闭环这在挂 superpowers 之前几乎不可能看到。以前 Codex 跑测试失败多半会“嘴硬”或者直接改断言去迁就实现现在它会老老实实按流程找根因。这就是技能约束的力量。5.3 过程中暴露的边界与我的干预点虽然整体很顺但我也在几个节点做了干预。第一个是它在更新 README 时把整个接口文档的格式重排了一遍和项目原有的手写风格不符。我打断它说“保持原有文档格式只新增接口段落”它很快调整了。第二个是它在路由里直接用了一个硬编码的用户数组没有复用现有的getAllUsers()函数。我在 review 时发现后指了出来它随后改正并补了一个复用测试。这两个干预点说明superpowers 不能替你完全收管质量但它把“验证闭环”这件事做到了。你省下了盯测试、盯流程的精力把省下来的时间用在真正的代码 review 上。这本来就是人机协作该有的样子。6. 常见问题与避坑清单6.1 问题速查表我在不同项目里切换使用 superpowers踩过不少坑也看过社区里别人遇到的问题。整理成一张速查表方便你直接对照排查现象可能原因解决方案Codex 完全不知道技能文件存在codex.md里没有用引用技能库或路径写错用绝对路径重新引用并让 Codex 复述技能列表验证技能文件被重复加载上下文被塞满codex.md和全局配置文件都引用了同一个技能库统一在一个位置引用另一个删除指令冲突项目规范没有生效项目自定义约束和技能文件顺序不对或互相覆盖项目约束放前面用复述实测确认兼容性模型仍然跳过测试直接改代码没有启用 test-driven-development 技能或技能文件未引用单独引用 TDD 技能文件或在自己的规范里加上强制验证规则上下文不够用对话经常“失忆”技能库全部引入文件过多过长按需只引用单文件写精简技能拆分任务到独立会话6.2 上下文窗口管理别把技能库当百科全书随着技能文件越来越多上下文管理会成为一个现实问题。Codex 的上下文窗口虽然不小但技能库注入的内容是每次对话都要占用的固定开销。如果你把整个 superpowers 技能库的所有文件都引进去再加上项目自身的说明可能导致模型还没开始干活上下文已经用掉一大截。我的习惯是“按场景精简”。如果当前任务只是修一个 bug我只在codex.md里临时引用 debugging 和 test-driven-development 两个文件不引用全库。平时则保留 task-planning 和 code-readingTDD 看项目需要。你可以在~/.codex/config.toml里观察 token 使用情况逐步调整找到自己项目的平衡点。6.3 权限与安全边界设置Codex agent 模式可以执行命令这意味着如果项目目录里有恶意脚本或者模型误解了你的意图去跑了一条危险命令风险会放大。superpowers 本身不改变 Codex 的安全机制它只是让流程更规范但权限边界仍然需要你自己设好。我用的 Codex 版本在~/.codex/config.toml里能指定命令白名单比如只允许npm/test、git、ls、cat这类常规命令其他一律弹出确认。另外如果你在一个多人维护的仓库里跑 agent 模式建议先确认codex.md的修改不会影响其他人的使用体验。因为codex.md是跟随项目走的你加了 superpowers 引用之后团队其他人如果没装技能库可能会加载失败。我在公司内部项目里一般是把技能库路径写在注释里或者通过.gitignore排除个人配置避免给队友添麻烦。6.4 版本迭代带来的兼容性问题Codex CLI 和 superpowers 都在快速迭代今天的配置方式可能三个月后就变了。我自己就经历过一次Codex 更新后改了对引用目录的解析方式导致我原来的配置失效。处理这类问题没有快捷方式只能养成两个习惯一是升级 Codex 前先看一眼官方 changelog二是升级后立即跑一遍“技能加载验证”对话确认没坏再继续工作。另外如果在 GitHub 上发现 superpowers 仓库里的技能文件和你的版本理解不一致以你 clone 下来的实际内容为准。我的做法是把技能库 fork 一份到自己名下然后把锁定的版本用在我这边这样即使上游更新也不会影响我的稳定使用。这个习惯对长期使用特别重要。7. 一点小技巧收尾让 Codex 替你总结技能配置最后分享一个我最近觉得非常省事的小技巧每次我调整完codex.md的技能引用之后会顺手让 Codex 用三句话总结一下“当前会话的可用技能和触发条件”然后我把这段总结粘贴到项目的CHEATSHEET.md里。下次新开一个对话或者队友接手项目只需要看一眼这个速查文档就能快速知道当前配置了什么技能、什么场景该用什么。这个做法的额外好处是相当于给每个项目建立了一份“agent 行为契约”比让人去翻源码猜配置直观得多。我在几个项目里试过之后觉得这几乎是零成本、高回报的习惯推荐你也试试。毕竟 superpowers 这类工具再怎么强大最终还是要靠人在关键时刻做出判断把它管好用好它才真正称得上“超能力”。