superpowers：给 Codex CLI 装上专业级技能增强工作流

1. 先搞清楚superpowers 到底给你的 Codex 加了什么如果你和我一样每天大部分时间都泡在终端里靠 Codex CLI 写代码、改 bug、做重构那你大概率遇到过这样的场面Codex 能跑但总感觉差点意思。让它写个小函数、改个配置还行可一旦涉及“先读整个项目结构再定位问题再设计改动方案最后分步执行并验证”它就开始迷路。你得像带孩子一样一步步喂指令说一句动一下效率直接打对折。这个痛点我扛了大半年最后在折腾各种 Codex 增强方案时遇到了 superpowers。一句话讲清楚它是干什么的superpowers 是一个为 Codex CLI 设计的技能增强包通过给 Codex 预置一套系统化的思考框架、操作流程和任务分解规则让它在面对复杂编程任务时能够自动按“先规划、再执行、边做边验证”的专业工程师节奏工作。我一开始也没太当回事觉得不就是加几个 prompt 嘛。但用了一周之后说实话回不去了。这篇文章就把我的使用经验、踩过的坑、以及它背后那套“为什么有效”的逻辑一次性讲透。不管你是刚开始接触 Codex 的小白还是已经在生产环境里用它干活的熟手这篇文章都能给你一些参考。顺便说一句superpowers 本身不是独立的 AI 引擎它不替代 Codex更不是那种“装了就自动变强”的魔法插件。它的本质是一个精心设计的技能库 工作流规则集。你得先有一个能正常运行的 Codex CLI 环境然后把它“嫁接”上去。2. 为什么要装它开发者在命令行里的三个真实困境2.1 模型有知识但做项目没章法GPT 这类大模型的知识储备和代码生成能力其实早就不缺了。但真到了工程现场它的问题不是“不会写”而是“太急着写”。我自己实测过一个很典型的场景我让裸 Codex 改一个支付模块的异常处理逻辑。它二话不说“唰”地一下给我改出了一个新版本。看起来代码没毛病可一跑测试全挂了——因为它压根没看我在另一个文件里定义的老接口签名也不知道我这套服务的重试机制依赖什么状态字段。这种问题本质上是模型缺少一个“先看清楚再动手”的强制纪律。superpowers 解决的就是这个。它会给 Codex 注入一套行为规则先花时间看项目结构、读关键文件、找相关的接口定义然后在动手之前先输出一份“作战计划”。这听起来很朴素但在实际操作里这个“强制前摇”能救回大量无效产出。2.2 指令语言太含糊沟通成本爆炸跟 Codex 打过交道的人都有体会你说“优化一下这段代码”它给你优化了但优化的方向可能完全不是你想要的。你说“处理一下边界情况”它以为你说的只是入参判空结果并发和超时全没管。这不是模型笨而是人机沟通天然存在信息损耗。superpowers 的思路是把工程师常用的任务类型——比如调试、重构、写测试、做代码审查——预先拆解成一套标准化的指令模板。你只要说“用调试技能看一下这个 bug”它自己就会去执行“复现问题 → 定位日志 → 阅读相关代码 → 提出假设 → 验证修复”这条完整的链路不需要你额外解释每一个步骤。2.3 长任务的上下文管理失控还有个隐性问题很多人没意识到Codex 的上下文窗口虽然不小但真跑一个跨多文件的改动时模型很容易“忘记”前面说过的话。尤其是来回改上几轮之后它可能连自己第一轮定的方案都忘了。superpowers 对此的应对策略是把任务切成小步每步只做一个具体的动作做完一步就停下来“汇报”一次结果。这种“小步快跑”模式能把上下文消耗控制在一个相对健康的范围内让 Codex 在长时间任务里保持稳定而不是越到后面越飘。所以如果你只是拿 Codex 写点一次性脚本、做点小 demo那 superpowers 对你来说可能属于“锦上添花”。但如果你的目标是让 Codex 真正参与到一个正经项目的日常开发里那它绝对值得花半小时装上试试。3. 前置条件与安装实操3.1 环境要求先确认你的底子够不够按我自己的实践经验安装 superpowers 之前你最好先确认以下三样东西都齐了Node.js 环境Codex CLI 是构建在 Node.js 之上的superpowers 的安装脚本本身也是用 Node 写的。建议 Node 版本在 18 及以上太老的版本跑起来容易出现各种莫名其妙的兼容问题。Codex CLI必须已经安装且能正常登录使用。这个不用多说了superpowers 是“寄生”在它上面的。Git安装过程会从 GitHub 拉仓库所以 Git 是刚需。用下面的命令快速检查一下node -v npm -v codex --version git --version只要这几条命令都能正常输出版本号那就基本没问题了。3.2 正式安装比想象中简单我最初以为这种增强框架的安装会很折腾实际操作下来比装一个 npm 包复杂不了太多。核心就两步。第一步把仓库克隆到本地git clone https://github.com/obra/superpowers.git这个仓库会下载到你的当前目录下里面装的就是各种技能的定义文件、工作流规则和提示词模板。我建议把它放在一个固定的位置比如~/tools/superpowers因为后面配置路径的时候要用到。第二步运行安装脚本cd superpowers npm install装完之后脚本会自动检测你本地的 Codex CLI 配置目录并把 superpowers 的技能文件复制进去。整个过程饮料没喝完一杯就结束了。如果你用的是最新版的 Codex CLI配置目录一般在~/.codex。安装完成后你可以去这个目录里翻一翻能看到新增了不少和技能相关的子目录和文件。看到这些文件基本就说明安装成功了。3.3 安装之后先做个冒烟测试装完别急着直接上项目先做个最简单的冒烟测试确认这套“外挂”真的被 Codex 加载了。随便在一个项目目录里启动 codex然后输入这个指令我可以使用哪些技能请列出你能执行的全部技能名称。如果 superpowers 生效了Codex 会像报菜名一样列出所有预设的技能而不是回答“我不清楚”或“我没有额外技能”。我第一次看到那个长长的技能清单时说实话第一反应是“之前那半年我都在用个啥”。如果你这一步没通过大概率是配置文件的路径写错了或者 Codex CLI 版本太旧。先别慌往下看常见问题那一节里我会专门列排查步骤。4. 核心技能大拆解它到底给了 Codex 哪些“超能力”superpowers 的整个框架核心就是“技能”skills。每个技能都是一个专门的提示词模板里面写清楚了在特定场景下Codex 应该如何一步步操作。下面我挑几个我日常用得最多、感受最深的技能展开说说。4.1 调试技能从“瞎猜”到“按图索骥”这是我最喜欢的一个技能没有之一。裸 Codex 面对 bug天然倾向是“扫描代码 → 定位嫌疑点 → 直接改”。它跳过了最关键的“复现”这个环节导致很多修改都是基于猜测而不是基于证据。superpowers 的调试技能会给 Codex 一套完全不同的行动序列先让用户提供 bug 的复现步骤或者主动尝试复现。根据错误信息和现象倒推可能出问题的模块列出“嫌疑清单”。一次只查一个嫌疑点而不是一口气改十个地方。修复之后立刻重新跑测试或复现命令确认问题真的消失了。最后做一次“防回归检查”确认改动没有影响周边功能。我用它调过一个生产环境的内存泄漏问题。裸 Codex 给我的建议是“改这里、改那里”而挂上调试技能之后它第一件事是先让我把压测脚本跑起来然后盯着内存曲线分析最后定位到是一个静态缓存没有设置淘汰策略。整个过程和一位老工程师的排查思路几乎一致。4.2 测试技能不只是“写两个用例交差”很多开发者用 AI 写测试得到的东西都是“看起来不错但根本没测到点子上”的假测试。superpowers 的测试技能规则要严得多。它会要求 Codex 遵循以下原则先理解被测代码的输入边界和状态变化再决定测什么。测试用例必须覆盖正常路径、边界路径和异常路径缺一不可。写完测试后要主动跑一遍全量测试证明新测试会失败红然后再实现功能让它变绿。也就是标准的 TDD 节奏。绝不为了凑覆盖率而写无效断言。我自己用这个技能给一个老模块补过测试。它先把模块里所有分支条件列了一张表然后对着表一一设计用例最后跑出来的结果覆盖率比我手工写的还高。这种“列表驱动”的工作方式人类工程师做起来费时间但让 Codex 来做配上清晰的规则效果立竿见影。4.3 重构技能让代码变更变成“无痛手术”重构是最容易翻车的任务之一。改着改着功能没变但引入了一堆新的边界问题。superpowers 的重构技能强调的核心是“保持行为不变”。具体执行时它要求 Codex重构前先梳理当前代码的全部输入输出接口。先写一份“重构前后对照说明”明确改了哪些地方、没改哪些地方。每一处改动尽量独立成步避免“一把梭”。改完一步就编译或测试一次确保没跑偏。我拿它重构过一个历史遗留的订单状态机。原来是一大坨 if-else重构后变成了策略模式。整个过程Codex 分四五步走每走一步就跑一次测试我基本没操什么心最后泪流满面看着全部测试通过。过去我自己做这种重构心理压力巨大现在交给这套工作流明显从容很多。4.4 通用任务规划技能把模糊指令变成可执行清单除了上面那些专用技能superpowers 还内置了一个“通用任务规划技能”。这个是我觉得最实用的兜底方案。当你交给 Codex 一个比较大的任务比如“给这个项目加一个配置中心”时它会先拒绝直接动手而是启动规划流程拆解任务涉及的模块范围。列出可能受影响的历史代码。规划实施顺序先做什么、后做什么、最后验证什么。输出一份待办清单让用户确认后再开工。这个功能说白了就是把“AI 先思考再说”变成强制规则。一开始可能会觉得多了一步耽误时间但实际跑下来它节省的时间远远大于多花的那几秒。5. 实操演示用 superpowers 跑通一个完整功能开发5.1 任务背景为了更直观地展示这套框架的价值我拿一个比较有代表性的例子来走一遍全流程。假设我手上有一个 Node.js 写的文件处理服务现在需要新增一个功能当上传的文件超过 100MB 时服务要自动拒收并给调用方返回一个包含具体原因的错误信息。看起来是个小需求但涉及路由层、校验层、错误处理层至少要动四五个文件。5.2 用规划技能开局我先启动 Codex输入请用规划技能处理这个任务为文件上传接口新增大小限制超过100MB直接拒绝并返回错误提示。注意我没让它直接改代码而是先要求走规划技能。Codex 的回应很有意思。它没有立刻生成 diff而是先输出了一段分析当前上传接口路由位于src/routes/upload.js。文件接收逻辑由src/middleware/fileParser.js里的 multer 实例处理。错误响应结构定义在src/utils/response.js。需要修改的核心点multer 的 limits 配置、错误处理中间件、新增错误码。另外它还额外识别到一个我忽略的细节现有前端调用方可能只校验 HTTP 状态码不会读取响应体里的错误详情。所以需要同时确认是否需要调整 API 文档。看到这个我心里就给这套技能点了个赞——它考虑的比我还全面。5.3 分步执行与验证确认规划后我让它逐步执行。第一步修改 multer 配置加入limits: { fileSize: 100 * 1024 * 1024 }。我看了一眼没问题。第二步在统一错误处理里增加对LIMIT_FILE_SIZE错误码的捕获并映射到业务错误码。这个细节我挺满意因为它没有只改校验而是把链路末尾的错误处理也补上了。第三步Codex 自动生成了一个临时测试脚本模拟传一个 120MB 的文件验证接口真的会拒收并返回格式正确的错误信息。测试跑完确认返回了预期的 JSON这一步才宣告结束。整个过程走完Codex 只让我做了一次确认其余时间都是它在按计划推进。这要放在以前用裸 Codex估计我得追在后面反复纠正它“你没改到点子上”。5.4 小结这套流程为什么丝滑这套流程丝滑的核心原因在于 superpowers 把一个“功能开发”拆成了“理解 → 规划 → 改路由配置 → 改错误处理 → 测试验证”这样的小步。每一步的输入输出非常清晰Codex 模型的能力被充分聚焦在“单点执行”上而不是“全链路打包”成功率自然就上去了。6. 参数细节与工作流配置别忽略这些隐藏选项6.1 模型选择参数的实战建议superpowers 的性能表现跟 Codex CLI 背后的模型选择有直接关系。我的实测感受是Codex mini / 轻量模型跑简单脚本、单文件改动够用响应快。完整版 Codex 模型处理多文件、复杂逻辑重构时表现明显更稳。因为 superpowers 的规则很细需要模型有足够的推理能力去理解和遵循轻量模型容易出现“读懂了规则但执行跑偏”的情况。所以如果你有条件用完整版模型建议日常任务都跑在完整版上。体验完全不同。6.2 技能工作目录的规划技巧安装 superpowers 后技能文件默认放在 Codex 的配置目录里。我自己习惯做的一件额外操作是把技能文件纳入 Git 管理并用软链接指向固定目录。这样当 superpowers 发布更新时我只需要在固定目录里拉取最新代码然后重新链接一遍配置干净又不容易出错。ln -s ~/tools/superpowers/skills ~/.codex/skills这条命令的意思是把技能目录软链接到 Codex 的配置目录下。好处是你不用每次升级都手动复制文件。6.3 特定项目的“个性化技能定制”superpowers 支持自定义技能。如果你所在团队的代码规范很特殊或者你经常做某类重复性工作完全可以照着它的技能模板自己写一个。我举个真实例子我所在团队强制要求所有数据库查询必须走统一的 Repository 层。以前跟 Codex 说“帮我加个查询”它总是随手就在业务代码里直接写 SQL。后来我仿照 superpowers 的模板写了一个“项目规范技能”内容很简单任何涉及数据库操作的请求必须优先检查 Repository 层是否已有对应方法没有才允许新建且新建必须遵循命名规范。把这个技能丢进 skills 目录之后Codex 再也没在业务层直接裸写 SQL 了。这个功能的价值很值得你花时间研究。7. 常见问题与避坑指南基于真实踩坑经历7.1 安装后技能列表为空这个是最常见的问题。你问 Codex 有哪些技能它回复“没有发现可用技能”。我排查过的原因主要两个一是 Codex 配置路径不匹配。新版 Codex 可能用~/.codex但某些历史版本会用其他目录。二是安装脚本执行时权限不足导致技能文件没复制成功。处理好方法直接手动检查技能目录是否存在ls -la ~/.codex/skills如果目录不存在或者里面是空的就手动把仓库里的 skills 目录复制过来基本能解决。7.2 Codex 无视技能规则仍然自由发挥有朋友遇到过这种情况技能装好了Codex 也能列出技能名但你让它用某个技能干活时它不按照技能里的步骤来还是自己一顿乱写。这通常不是 superpowers 的问题而是 Codex CLI 本身没有在系统提示词里足够强调“必须遵循技能指令”。建议在 Codex 的AGENTS.md文件里加上一段强约束说明比如在执行任何任务前必须检查是否有匹配的可用技能如有必须严格按照技能中定义的步骤执行不得跳过任何环节。加完之后再重启 Codex CLI 试试一般就能纠正过来。7.3 任务跑得太慢步骤过多导致效率下降superpowers 的规则比较细小任务也会强制走规划流程确实会有一些体验上的“笨重感”。好在这个是可以调的。如果你只是想让 Codex 快速改个变量名、加个日志这种“一句话级任务”不必走完整技能流程。我的做法是对这类简单指令直接给一句“快速修改即可不用走规划流程”。这样既保留了 superpowers 的大任务处理能力又不牺牲日常小操作的效率。8. 把 superpowers 融入你的日常工作流8.1 我现在的推荐分工模式用了小两个月之后我总结出了一套很舒服的人机协作方式每天的小改小动不启动技能让 Codex 直接改。涉及跨文件的 feature 开发强制开启规划技能先讨论方案再动手。遇到线上 bug直接启动调试技能让它按“先复现、后定位、再修复”的步骤走。提交代码前开启代码审查技能让它以“严格同事”的立场找问题。这套流程用下来Codex 不再像一个需要我全程盯着的实习生更像一个能独立处理大块任务的同事。这个体验变化是整个工具链升级里最值得的部分。8.2 一个值得尝试的进阶玩法如果你有比较多的历史项目强烈建议在每个项目根目录都放一份AGENTS.md里面写清楚项目的技术栈、目录结构、关键约定然后再配合 superpowers 的技能规则一起用。我试过之后最大的感受是superpowers 提供了“通用工作流程”但 AGENTS.md 提供了“项目专属知识”。两者结合Codex 才能真正做到“既懂怎么干活又懂你这个活该怎么干”。用起来几乎可以覆盖从新功能开发到老代码维护的超大比例日常场景。按我现在的使用强度估算每天节省下来的“无效沟通 错误返工”时间至少一两个小时。如果你也在用 Codex CLI 干活并且对“AI 写代码总差点意思”有同感那你缺的可能不是更强的模型而是像 superpowers 这样一套能规范模型行为的东西。装一个花半小时大概率你会觉得值。