1. 项目全貌superpowers 到底给 Codex 加了什么1.1 先说你遇到的问题Codex 明明很强为什么总差一步最近 AI 编程工具简直是爆发式增长OpenAI 的 Codex CLI 算是我用得比较顺手的一个它能直接落在终端里读代码库、改文件、调命令比那些只能在对话框里聊天的助手实在太多。但实际用久了你会发现一个很尴尬的问题Codex 很聪明可它更像是你问一句它做一步的高级实习生而不是一个能独立交付任务的成员。你让它改个接口它真就去改接口改完之后要不要跑测试、要不要做回归、要不要把影响面梳理一遍它默认不会主动干。遇到稍微复杂的任务比如给这个 Java 服务加一个限流功能并且补上测试它要么一股脑写一堆你觉得不对劲的代码要么在某个细节上来回打转最后还得你亲自收拾烂摊子。其实根源不在 Codex 本身而在于它缺少一套工作方式。这正是 superpowers 这个开源项目想要解决的事。它不是一个全新的 CLI而是建立在 Codex CLI 之上的一套增强框架给 Codex 装上技能Skills、工具场Toolground和自由职业模式Freelancer Mode让 AI 从回答问题的助手变成能接活、会规划、有验收标准的执行者。简单说superpowers 重新定义了 Codex 的工作流程先研究、再计划、然后分批执行、最后自测和交付。这套思路对经常和 AI 结对写代码的人非常受用。1.2 superpowers 的核心设计技能、工具场、自由职业模式我把 superpowers 拆开看它最核心的三个模块各司其职。第一个是技能Skills。你可以把技能理解成给 Codex 写好的岗位说明书它是一组带元数据的 Markdown 文件写在~/.codex/skills目录下。技能里写明了自己擅长什么、什么场景能被触发、具体按什么步骤执行、需要注意哪些坑。Codex 在开始干活之前会先扫一遍技能库看当前任务命中了哪个技能然后加载对应的操作指引。比如你想让 Codex 给你维护一个 Java 项目的构建发布流程你可以写一个java-build技能把 Maven 的打包命令、环境变量规范、发布前的检查清单全部写进去从此凡是涉及构建的任务Codex 都会自动按这套标准来。第二个是工具场Toolground。项目里会初始化一个隔离目录里面放了浏览器模拟器、终端模拟器等工具环境。Codex 可以先在这一层反复练习和使用工具比如试跑一条命令、观察输出、调整参数而不会直接污染你真实的终端和系统。我自己的理解是这有点像给飞行员配了一台模拟机先在安全环境里折腾够了再上真机犯错成本低很多。第三个是自由职业模式Freelancer Mode。这是 superpowers 最有辨识度的设定。它会引导 Codex 像一个独立的自由职业者那样接一个任务先读文档了解背景然后写一份PLAN.md计划把任务拆成带编号的子任务之后按顺序执行每完成一步就检查一次最终汇总 diff 展示结果。这个模式最大价值是让 Codex 的工作变得可审核、可中断、可回退你始终知道它在做什么、做到哪一步了。1.3 适合谁用不只是写代码快的人我身边经常有人问这个 superpowers 是不是只适合那些天天写业务代码的程序员我觉得不完全对。它更适合的是那种工作流本身就比较重的人。比如你维护着多个项目每个项目有一堆约定俗成的规范你就很值得把规范沉淀成技能文件让 Codex 每次都遵守再比如你经常让 AI 处理大批量、重复性的重构任务自由职业模式的计划-执行-验证机制能明显减少改到一半发现思路错了的问题。即使你是初学者也不用觉得门槛高。superpowers 的技能体系本身就是以 Markdown 文本写的你不一定非得会复杂的插件开发只要会写步骤说明就能定制一套自己的 AI 工作流。而且它完全开源整个工作方式透明可见这比那些黑盒的一键生成工具让我放心得多。我真正上手之后的感觉是它没有让 Codex 变得更聪明但让 Codex 变得更有章法而有章法在工程实践里往往比聪明更重要。2. 安装与初始化配置2.1 前置条件先有一个能跑的 Codex 环境在装 superpowers 之前你本机必须先装好 Codex CLI并且确认它能正常对话。这一步不复杂但有几个坑值得说。首先Codex CLI 需要 Node.js 环境建议用比较新的 LTS 版本我实测在 Node 18 以下偶尔会遇到依赖安装的兼容问题。其次Codex 需要配置好 API 凭据通常是通过环境变量或者登录会话的方式完成认证装 superpowers 时会复用这套认证机制所以先确保codex hello能正常回复再往下走。有件事很容易被忽略Codex CLI 的版本和 superpowers 的兼容性。因为 superpowers 本质上是给 Codex 提供额外上下文的封装层它依赖 Codex 某些会话行为如果 Codex 更新得太激进接口可能会有变化。我自己的做法是先在项目 README 里确认它推荐的 Codex 版本范围再用对应版本。踩过一次 Codex 升级后某些命令带参数失效的坑之后我学乖了凡是这种工具链组合我先锁定版本而不是每次都追最新。2.2 安装 superpowers 本体安装 superpowers 本身不复杂。项目常见的安装方式是通过 npm 全局安装这样superpowers命令就会被注册到系统里。装完之后第一步是初始化它会帮你创建~/.codex下的几个目录skills目录用于存放技能文件superpowers目录用于存放框架本身的配置与内置技能。这里我建议你装完以后别急着用先花五分钟看一看初始生成的配置结构。因为 superpowers 最核心的目录树就是后面所有功能的载体理清楚目录结构之后后续排查问题会轻松很多。我自己的习惯是把skills目录用软链到我的一个 dotfiles 仓库里这样技能配置可以随身携带换机器也不怕丢。这个方式不是官方要求的但对长期用户很实用。安装过程中如果遇到权限报错通常是 npm 全局目录权限问题一般加sudo或者配置好 npm 的 prefix 路径就能解决。如果遇到网络超时国内环境下可以考虑配置 npm 镜像这一步大家应该都熟我就不展开了。2.3 初始化技能库与配置参数安装完成后通常会有一步初始化或者引导。这一步会做三件事第一在~/.codex/skills下铺好一组默认技能第二生成配置文件里面可以设置默认的自由职业模式开关、工具场目录位置、调试日志级别等第三可能还会提示你安装一些依赖工具比如用于代码检索的rg、用于结构化输出的jq之类的命令行工具。这里我要强调一个容易被忽略的配置日志级别。默认配置的日志比较克制只有出问题时你才希望看到更多细节。我建议在日常使用中保持默认真出问题再把日志级别调到 debug。因为 superpowers 在自由职业模式下本来就会输出很多中间状态日志级别太高会很吵反而干扰判断。另外如果你是 Java 用户可以在配置文件里留出JAVA_TOOL_OPTIONS或者 Maven 镜像相关的说明段把这些环境内容写进技能说明里比每次对话时口头提醒 AI 要可靠得多。初始化完之后建议随手跑一条superpowers --version或者等价的状态命令确认一切正常。如果它能够显示出版本号和技能数量说明基础链路已经通了。2.4 配置凭据为什么还要管 GitHub tokensuperpowers 里有一块内容专门处理凭据Credentials它会读取你机器上已有的 GitHub、npm 等 token用它们来执行涉及远程仓库和包发布的技能。这块一开始我嫌麻烦想跳过后来发现对于 Java 项目特别有用——当 Codex 需要往公司私有 Maven 仓库推包或者从私有仓库拉依赖时没有正确配好凭据它就会卡在认证环节反复报错。配置凭据的原理不复杂superpowers 会在本地维护一个凭据访问接口技能描述里可以用占位符引用某个凭据框架会在执行时对应注入。出于安全考虑它默认不会把 token 明文写进对话上下文而是以环境变量或临时文件的形式交给具体的命令去用。我的建议是如果只是本地开发GitHub token 按最小权限生成即可别给全仓库读写权限。还有一点不要把.codex目录下的凭据缓存提交到 git 仓库里这个目录我一般会写进.gitignore。3. 核心功能拆解与实操3.1 技能Skills是如何工作的以 Java 项目为例技能是 superpowers 的灵魂。每个技能就是一个目录目录下至少有一个SKILL.md文件。文件开头是 YAML 格式的元数据至少包含name技能名和description描述描述里会写清楚什么场景下应该使用这个技能Codex 就是靠这个描述做匹配的。正文部分则是 Markdown写具体的执行步骤、约束条件和注意事项。我来举个例子假设你要给 Java 项目配一个发版前检查的技能。SKILL.md 大致会这样组织元数据里写当用户提到发版、release、打 tag 时使用此技能正文里先要求执行mvn clean verify跑完整测试再要求检查target/下产物是否齐全接着要求比对版本号和 git tag 是否一致最后列出常见的失败原因和绕行方案。Codex 一旦命中这个技能就会像照着 SOP 执行一样把整条流程走完而不是东一榔头西一棒子。写技能的时候有几个细节直接影响效果。第一描述要具体最好包含触发场景里的关键词太泛的描述会让 AI 在无关任务上也尝试加载反而增加噪音。第二步骤要可操作不要写确保代码质量良好这种无法验证的话要写执行mvn clean verify且所有测试通过。第三可以适当给反面示例也就是不要做什么比如不要在未跑完全部测试的情况下执行 deploy。我试过之后发现反面约束在 AI 执行里面的价值非常大。另一个实用技巧是可以把技能做成组合式。比如在java-release技能里引用java-build技能和git-tag技能Codex 会自动把它们串起来执行。这样你不用在一个文件里堆砌所有内容而是像搭积木一样维护一组小技能整改起来也方便。我的经验是单个技能文件超过 100 行之后AI 的遵循度会下降拆成多个互相引用的技能反而更稳。3.2 自由职业模式从执行命令到交付任务自由职业模式是我用得最多的功能。它的执行逻辑很有意思Codex 不是直接跳到改代码那一步而是严格走接单-调研-计划-执行-验收-交付这条链路。我第一次完整跑下来的时候最大的感受是它终于不急了而是像人一样先看全局再动手。具体跑起来是这个流程你给它一个任务描述比如给用户模块增加一个基于 Redis 的登录限流单 IP 每分钟最多 30 次并补充单元测试和 README 说明。它会先在项目里搜索相关代码搞清楚登录接口的位置、现有的 Redis 封装、测试框架的写法然后生成一个PLAN.md里面列出子任务清单、每个子任务的变更范围、涉及的文件、验收标准。这个计划你可以直接编辑和批注改好了它再按计划执行。执行阶段是分步的每完成一个子任务它会停下来检查比如编译是否通过、测试是否新增、有没有破坏其他模块。全部完成之后它会汇总一个 diff 说明告诉你改了哪些文件、为什么这样改、哪些是计划里没有的额外调整。这种模式的价值在于中途任何一步你觉得不对都可以喊停纠正计划的成本远低于纠正一堆错误代码的成本。我强烈建议第一次用的时候故意给它一个稍微超出能力范围的任务然后观察它怎么拆解和兜底。我自己试过一个重构工具类并保持对外行为不变的任务它把原来的类翻了个底朝天计划里甚至标出了三个潜在的破坏性变更点这比我自己动手前梳理得还细。不过也要说实话这个模式对任务的复杂度有要求简单到一句话就能改完的代码走这套流程会显得笨重自由职业模式更适合本身就需要计划和验收的中大型任务。3.3 工具场Toolground与隔离环境工具场这个概念我刚开始不太理解觉得多了一层抽象有点多余。后来看到一个场景才体会到它的价值当 Codex 需要学习使用一个新工具的时候与其让它直接在你的真实终端里反复尝试不如给它在隔离目录里提供一个模拟环境让它先在这里把命令摸熟了再接触真实项目。这就像学车先在驾校场地里练而不是直接上闹市马路。具体使用上工具场会初始化一个toolground目录里面有预设的工具使用场景比如会模拟一个终端会话Codex 可以先在里面跑命令试错观察输出找到正确用法。它还包含浏览器模拟器可以在里面测试前端渲染效果不用真的打开浏览器。这套设计和自由职业模式是搭配的执行阶段 Codex 可以在工具场中先做小范围验证再去改真实代码把破坏性降到最低。但这个设计也不是没有代价。隔离环境本身会占用额外的磁盘空间工具场目录在多次迭代后可能体积膨胀我遇到过几次磁盘吃紧的问题解决办法就是定期清理工具场目录或者调整它的位置到一块空间更大的磁盘。另外如果任务需要访问真实网络服务比如连数据库、连外部 API工具场里的模拟终端不一定能完全模拟出来这时候还是要让任务走真实环境。所以我的建议是把工具场当成练习场而不是生产环境真实凭证和线上操作始终别进隔离区。3.4 工作流Workflows把流程固化下来自由职业模式之所以能稳定地走完计划-执行-验收靠的是 superpowers 内置的一组工作流定义。工作流说白了是一套预设的流程脚本细化到每个阶段 Codex 该做什么决策、该调用哪些技能、该生成什么中间产物。默认的工作流包括初始化流程bootstrap、计划流程planning、构建流程build、研究流程research等。有意思的是这套工作流本身是可以改的。你可以根据自己团队的节奏调整比如你们团队要求所有变更必须先更新文档再改代码那就在 build 工作流里把这个步骤插进去如果你们要求 release 必须走 CI 而不是本地构建也可以在工作流里写死。这种可定制性比那些只能填参数的插件要灵活得多。我个人的体会是工作流尽量不要大改先跑熟默认流程再逐步往里加自己的约束。因为工作流改动影响的是所有任务的行为改得太多太激进Codex 的执行路径会变得不可预测。我踩过的坑是在工作流里加了一个每步都执行全量测试的约束结果一个小修改引发了十几分钟的等待效率反而下降。后来改成按影响范围决定测试范围效果好了很多。4. 常见问题与排查方法4.1 技能加载不出来或匹配不到这是最常遇到的问题。技能文件写好了但 Codex 就是不按技能执行好像根本没看见一样。我遇到这种情况第一反应是检查技能元数据里的描述是否足够精准。Codex 加载技能是靠描述去匹配任务意图的描述写得太泛或者和任务关键词差异太大模型很可能跳过它。比如技能描述里写的是Java 项目的构建发布流程而任务说的是帮我打个包发个版本匹配度就不够改为当用户要求打包、发布、打 tag、发版本时使用就会好很多。另一个常见的坑是技能文件格式问题。YAML 开头的元数据必须严格闭合缺少name或description字段会导致整个技能被忽略。我自己的排查方法是先查看 superpowers 的状态输出看它加载了哪些技能再手动检查 SKILL.md 的 YAML 部分是否有格式错误。有时候问题出在编码上文件用了带 BOM 的 UTF-8解析器会出问题用普通 UTF-8 保存就能解决。4.2 自由职业模式中途卡住或反复重试自由职业模式跑着跑着卡住是让我最头疼的问题。典型表现是计划写好了执行到某一步总是失败然后 AI 自己反复尝试消耗大量 token 却没有进展。这种局面的根源通常在于验证标准设置得不合理。比如计划的验收条件是单元测试覆盖率达到 80%这个目标本身无法用一条命令直接检查AI 就会卡在如何验证覆盖率上。我的解决办法是先把子任务切成更小、可验证的单元。哪怕多拆几步只要每步都能明确验证成了还是没成AI 就不会原地打转。此外还可以在计划阶段直接给 AI 明确的操作边界比如如果某个子任务尝试三次仍然失败停止并报告当前进展不要自行扩大修改范围。这样即使卡住它也会停在你可控的位置而不是越偏越远。4.3 工具场目录占用空间过大工具场跑久了目录体积膨胀是个实际烦恼。它里面会累积模拟浏览器的缓存、模拟终端的日志、各种中间产物一段时间不清理能占据好几个 GB。我现在的习惯是每周用一句命令清空工具场里超过一周的临时文件或者直接把整个toolground目录删掉再让 superpowers 在下次运行时重新初始化。由于工具场里的东西都是可再生的不需要像代码那样保留历史版本删了完全不可惜。另外一个建议是把工具场目录从项目目录里挪出来放到系统的临时目录或者专门给缓存用的磁盘分区这样既不污染项目目录也不会被误提交进 git。尤其当你同时用多个项目时让工具场跟随项目目录会导致每个项目都有一份重复的缓存太浪费。4.4 和已有 Git 工作流冲突superpowers 会自动和 git 打交道在自由职业模式里会生成计划文件、检查 diff、可能还会创建提交。如果你自己原本有 git 工作流比如用 conventional commits、或者有 pre-commit 钩子两者可能会冲突。我遇到过的是superpowers 自动生成的提交信息不符合我们仓库的规范导致 CI 直接失败。解决思路是在技能或配置里显式说明提交规范比如所有提交信息必须以feat:、fix:、docs:之一开头并附带简要描述。Codex 对指令的遵循比我预期要好只要你把规则写在它每次执行都会读取的地方它后续生成的提交就会合规。另外如果你更想完全掌控 git 操作可以在配置里关掉它的自动提交功能让它只改代码不做提交等你 review 完 diff 再手动提交。这样虽然多一步操作但安心很多。5. 从会用到用得趁手我的几点实操体会讲了这么多最后我想聊几个纯粹属于个人经验层面的东西未必在项目文档里能找到。第一个体会是技能文件要持续迭代不要一次性写完就想一劳永逸。我刚开始用 superpowers 时写的第一个技能执行了几次之后发现有很多边界情况没考虑到是在实际跑任务中不断补充不要做某事遇到 XX 情况时需要先确认 XX这类约束之后它才真正变得可靠。这跟我带新人很像初期靠文档约束后期靠 review 反馈反哺文档。想要 superpowers 用得顺手核心功夫不在装环境而在维护技能库。第二个体会是大任务拆小任务收益比你想象的大。自由职业模式本身就倡导把任务拆小但我的经验是还可以拆得更细。一个被我拆成 8 个子任务的 Java 项目改造比 3 个大步骤的版本顺利得多。原因不难理解子任务越小验证成本越低模型出错的范围越窄回归调整的代价也越小。哪怕是让 Codex 处理一个看似简单的任务我也会在计划阶段多问一句这个步骤的验收标准是什么它能说出来我就敢让它跑。第三个体会是把 superpowers 纳入自己的日常开发流程而不是偶尔用一次。如果你只是偶尔玩一下每次都需要重新磨合它的行为会觉得又慢又别扭当你持续用它处理项目里的真实任务技能库和工作流会随着使用越来越贴合你的习惯这种越用越顺的积累效应才是它真正的价值所在。如果你也在用 Codex或者对 AI 编程助手的工作方式感到不满足我建议你花一个下午安装试一下。先不追求复杂技能跑一个中等规模的任务感受一下自由职业模式的节奏再慢慢把手头的规范沉淀成技能文件。你会发现AI 编程从玩具到工具的台阶往往不是多了一个更聪明的模型而是多了一套靠谱的干活方式。