1. 这个东西到底是干什么的superpowers 与 Codex CLI 的定位1.1 不装 superpowers 的 Codex CLI最容易踩的三道坎先聊 Codex CLI 本身。它把大模型能力搬进终端让你在项目目录下发指令AI 能读文件、改文件、执行命令。听起来很全能但实际用上一段时间你会遇到几个很具体的坎不是模型不行而是缺一层“操作规范”。第一对话感太重。你让它修一个 bug它第一轮往往只给一个修复方案或者改了文件但没跑测试等你追问一句才继续验证。在长任务里这种“挤牙膏式协作”特别累。你既要盯代码又要盯它有没有漏步骤基本等于自己重新做了一遍项目管理。第二缺少自我纠错循环。AI 改完代码后编译报错它不一定会自己看到错误并继续修。很多时候报错信息就在终端里它却已经回复“修改完成”等你手动跑起来才发现问题。一次两次还能忍任务一多这个“假完成”会浪费大量时间。第三上下文里的约定容易丢。你希望它遵守一套固定的工程纪律比如“每次改完必须跑测试”“遇到配置变更先检查引用方”但这些规则每次都要重新交代。一旦会话变长它就忘了前面的约定你会发现自己越来越频繁地重复同样的话。superpowers 瞄准的正是这个空间在 Codex CLI 上叠一套技能包把项目计划、实现、验证、修复变成一套让 AI 自主执行的循环而不是靠你一句一句喂。所以网上搜“superpowers使用指南”时你要先明白这不是换一个模型而是换一套工作方式。1.2 superpowers 不是一套代码库而是一个“工作方法外挂”我最早以为 superpowers 是一个独立程序后来才发现它本质上是给 Codex 准备的一批技能提示词、辅助脚本和配置模板。你可以把它理解成“给 AI 助手写好的岗位说明书”。它没有替代 Codex而是让 Codex 在启动时加载这些技能知道遇到什么场景应该走哪种工作流程。装上之后最直观的变化是你提一个任务AI 会先列计划、确认预期再开始改代码改完会主动跑构建或测试看结果如果失败它会把报错带回上下文继续改直到通过或明确告诉你卡在哪。这个体验跟裸 Codex 完全不一样更像带一个能自己交代进度的新人。用生活类比来解释给新人一台电脑不意味着他会干活你得先告诉他团队怎么分工、遇到报错找谁、提交代码前要跑什么检查。superpowers 就是把这些规则打包成机器可加载的文本。所以理解这个项目的关键是先抛开“代码库”思维把它当成一套“操作手册 自动化钩子”的组合。后面所有配置项、路径、技能清单都是在服务这件事。2. 安装前的脑子要清楚版本、目录、配置三条主线2.1 你需要的最小环境缺一不可在安装 superpowers 之前先说清楚我实践的基线环境操作系统macOS 或 Linux路径规则一致Windows 建议走 WSL。Codex CLI已安装且能正常启动命令行可以敲codex进入会话。Git用来把 superpowers 仓库拉到本地。一个测试项目最好是 Git 仓库改动前能提交方便对比 AI 到底做了什么。这三样缺一会让后面的排查变得混乱尤其是 Git。superpowers 的工作流里有个重要习惯动手前先让 AI 确认工作区状态至少保证改动前能回滚。没有 Git 这个动作就会退化成“直接改改坏了也没办法恢复”。安装前还要检查 Codex CLI 版本。最早版本的配置结构比较旧新版本对技能和插件支持不一样。我踩过最大的坑就是拿旧版 Codex 加载新格式配置启动后提示未知字段技能静默失效。建议先跑codex --version把版本号记下来后面所有配置格式都以它为准。2.2 拉取 superpowers 到本地目录选择有讲究项目本身不复杂一条git clone命令就能拿到。真正有讲究的是放哪个目录。网上流传比较广的做法是放在用户目录的.codex子目录里比如~/.codex/superpowers或~/dev/superpowers。如果你同时在多台机器同步配置我建议固定一个位置并在配置里写绝对路径避免“这台机器能加载另一台加载不上”的诡异现象。git clone --depth 1 superpowers仓库地址 ~/.codex/superpowers命令里的superpowers仓库地址换成你从项目主页复制的真实地址。--depth 1只拉最新版本技能包这类项目的历史提交对日常使用没意义能省时间和磁盘。拉下来之后别急着配置先花十分钟看目录结构。通常会有几个明显的部分skills目录存放各类技能提示词scripts目录放辅助脚本还有 README 和示例配置。先读 README 和示例配置它会告诉你哪些字段是必需项哪些是可选增强。这里额外提醒一句不要盲目把示例配置整体复制。如果你已经有自己的 Codex 配置文件直接合并很容易出现重复字段后面我会专门讲怎么合才干净。2.3 最简配置先让 superpowers 被 Codex 看见配置入口是 Codex CLI 的 config 文件路径通常在~/.codex/config.toml。新版本也可能用目录式配置取决于你的版本。最简做法是在 config 里把技能目录指过去让 Codex 启动时能发现它们。以我用的版本为例config.toml里需要有一段类似这样的内容具体字段以你本地 README 为准[profiles] [profiles.superpowers] skills [/Users/你的名字/.codex/superpowers/skills]配置完并不代表马上生效。Codex CLI 一般启动时才读取配置所以你要退出当前会话再重新进入。验证方法很直接在会话里问它“你有没有加载 superpowers 相关技能”或者换个更可靠的方式让它描述当前可用的工作流程。如果它讲得出“计划-实现-验证-修复”这个循环说明加载成功。这里有个通用经验不要一上来就追求完整配置。先让技能被看到再逐步加命令执行权限、Java 参数这些增强项。分步配置会让你知道到底是哪一步出了问题而不是整份配置黑盒式地失效到时候想排查都无从下手。3. 核心机制拆解技能会话来龙去脉3.1 技能包不是插件加载与执行的边界很多文章把 superpowers 称为插件其实不准确。Codex 的插件机制更偏程序化扩展而 superpowers 主要靠“技能注入”也就是把一批精心写的提示词放到 AI 的上下文里让它按照方法论行动。插件是代码逻辑技能是行为规范。这个区别决定了排查方向技能没生效查路径、文件名、加载顺序插件出问题查版本兼容和 API 调用。那为什么技能这种方式有效因为大模型在对话里即兴发挥时很容易遵循明确写出来的工作流。就像你给新员工一份 SOP他照着执行一定比靠猜稳定。superpowers 干的事就是把项目计划、测试先行、错误修复流程写成极为具体的文本并设计触发条件当任务匹配某种场景时让 AI 优先使用对应技能。但技能也有边界。它不改变模型本身的推理能力也不能让 Codex 获得它本来没有的工具权限。比如AI 能不能执行 git 命令取决于 Codex 的执行环境和审批配置而不是技能包里写了“你可以执行 git”。这个误区非常常见很多人装完发现 AI 还是不能自动跑命令就开始怀疑技能有问题其实应该先检查执行权限配置。3.2 关键配置项解读照着抄也要知道在改什么下面这张表整理了我实际用到的几个核心配置维度不是让你盲目填空而是理解每一项在干什么配置块典型字段作用注意事项skillsskills [路径]让技能包目录被识别路径尽量用绝对路径执行边界文件读写、命令范围控制命令执行的安全边界想验证 Git 操作要给对应目录放行审批策略auto / on-request决定命令执行前是否询问全自动风险高建议先 on-request模型设置model决定推理质量与成本按任务复杂度切换别一个模型走天下举一个实际例子审批策略设成auto后AI 确实能自主跑命令但代价是它可能在错误方向执行一堆操作。我的实践是先on-request跑几天观察 AI 的意图是否靠谱再决定对哪些命令放开自动执行。一上来就全自动等于把方向盘完全交给一个还不熟悉你项目的实习生胆子可以大但不能这么玩。配置还有一个容易忽略的点技能加载顺序会影响 AI 的决策优先级。如果你有多个技能目录注意看项目文档里有没有排序规则。我自己就经历过两个技能相互冲突AI 在“先写测试”和“先重构接口”之间摇摆最后是调整目录命名优先级才解决。3.3 Java 场景的额外配置maven/gradle 与 JVM 参数热词里专门有“superpowers java”这个组合很常见因为 Java 项目的编译、测试、依赖管理链路比脚本语言长AI 更容易在中间断掉。用 superpowers 跑 Java 任务我建议额外关注三件事第一构建工具选择要明确。项目里同时存在 Maven 和 Gradle 时AI 不知道该用哪个。你最好在项目说明里写清楚“构建命令是./mvnw test或./gradlew test”否则它可能随机选一个然后因为版本差异报一堆莫名其妙的错。第二JVM 环境要正确。Codex 执行子进程时JAVA_HOME和PATH必须可用。常见坑是你在当前 shell 里能跑java但 Codex 启动的子进程找不到 JDK报command not found: java。解决办法是把环境变量显式写进启动方式或者确保 Codex 由同一个配置好的 shell 拉起。export JAVA_HOME/path/to/your/jdk export PATH$JAVA_HOME/bin:$PATH codex第三测试日志要控制长度。Java 测试失败时的堆栈很长AI 上下文有限最好让技能引导它先抓核心异常而不是把整段日志贴回去。我见过 AI 因为上下文被撑爆在同一个错误里反复绕圈效率极低。Java 项目还有个特点改完后的验证时间明显长于脚本语言。如果技能里没有“先跑受影响模块的测试而不是全量测试”的约束AI 每轮都全量编译一个任务能跑十几分钟。我自己在技能描述里加了这条规则后效率提升非常明显。4. 实操实录从计划到自测的一整轮4.1 一个典型的 superpowers 工作流长什么样下面是我在一个真实项目里跑过的流程。项目是一个简单的 Java 命令行工具任务描述只有一句话“给现有命令增加一个--dry-run参数并补充测试。”进入 Codex 会话加载 superpowers 技能后AI 的表现和裸 Codex 有明显不同。它没有立刻改代码而是先输出一段计划先读入口类确认参数解析逻辑再查配置文件了解现有结构然后设计 dry-run 模式下的输出格式最后补测试并运行。这一步就是技能里“计划先行”规则在起作用。计划确认后AI 开始改动。因为我在配置里设置了on-request审批它每次执行命令前都会征求我的同意我能看到完整命令再决定是否放行。这个过程虽然多几次确认但让我对 AI 的操作有掌控感。你: 给现有命令增加一个 --dry-run 参数并补充测试。 AI: 计划如下 1. 读取入口类确认参数解析逻辑。 2. 查找现有测试结构。 3. 实现 dry-run 模式不执行实际写入。 4. 添加测试用例并运行 ./mvnw test。 5. 如果测试失败根据报错继续修复。 是否开始 你: 开始。跑完测试后如果有一个用例挂了它不会像裸 Codex 那样停在“已修改完成”而是把测试输出带回来定位到具体断言继续修改并再次运行。这一轮下来我的体感是它更像一个会主动汇报进度的远程实习生而不是一个聊完就走的顾问。4.2 命令自动执行的授权策略怎么配很多人装完 superpowers 后最想开的是“全自动”。配置里对应的是审批策略调整允许 Codex 自动执行命令。但我强烈建议分三档走。第一档完全手动。所有命令都要你确认适合第一次体验安全但效率一般。你会在确认过程中逐渐了解 AI 习惯执行哪些命令这本身就是一种学习。第二档白名单自动。只允许自动执行低风险命令比如git status、git diff、测试命令。不同版本的 Codex 对白名单字段写法不同核心思路是把“只读操作”和“验证操作”放进自动列表把“写操作”“网络操作”留给人审。第三档特定项目全自动。在一个你信任、改动可回滚的仓库里打开 auto。我的建议是作为兜底仍在每次会话开始前用git status确认工作区干净或让 AI 先建一个分支。下面是一个示意性的白名单写法不要照抄要根据你的 Codex 版本调整字段名[sandbox] auto_approve_commands [git status, git diff, ./mvnw test, ./gradlew test]让我印象很深的一次教训是我曾在全自动模式下让 AI 重构一个模块它每完成一步就自动格式化和提交其中一次提交信息写得莫名其妙。代码虽然没坏但提交历史很脏回滚时增加了认知负担。所以我现在坚持全自动模式也必须在技能里明确要求“每个逻辑变更独立提交提交信息写清楚”而不是放任 AI 用fix stuff这类消息。4.3 多轮自愈循环遇到失败怎么让它接着修superpowers 给我的最大价值是把“失败后继续修”变成了标准流程而不是靠碰运气。有一次我让它修改一个 JSON 配置它在循环里连续改了三轮。原因不是模型笨而是第一轮改完后关联检查工具报了一处命名不规范第二轮修好这个另一个文件的引用又没同步直到第三轮才真正全绿。裸 Codex 很可能会在第一轮后就草率给出“完成”结论。这个自愈循环能跑通依赖两个前提。一是上下文里保留报错信息二是技能里明确写了“未通过验证不得宣称完成”。如果你发现自己用的 superpowers 没有这种坚持先检查技能描述里有没有类似的强制条款。很多第三方改版为了“听话”会把这种刚性要求去掉结果 AI 变得很顺从但完成质量大幅下降。真正用起来之后你会慢慢学会怎么给 AI 留出足够的信息。我发现任务描述里写“如果测试失败把失败用例和堆栈贴回来再改”比“请修复问题”有效得多。机制一样但提示词的质量决定了这个循环能转多快。5. 常见问题与排查技巧实录5.1 技能加载不上目录、版本、字段三大元凶我见过最多的报障是“我配置了但 AI 完全没变化”。按优先级排查三个地方。首先是 skills 路径检查绝对路径是否真实存在目录名不能带空格其次是 Codex CLI 版本太老或太新的版本对技能配置的读取规则可能有差异结合项目文档确定版本支持区间最后是配置格式TOML 只要缩进或引号错一点整个配置就会跳过而 CLI 不一定报错这一点最阴。这里有个实用排查技巧用 Codex 的能力询问功能直接问它“你有哪些可用技能”。如果它答不出来问题基本在加载层如果它能说出来但行为没变化问题一般在触发条件也就是实际任务没有命中技能描述。5.2 审批设了全自动却还是追问安全策略覆盖问题另一个常见困惑是我明明设置了自动审批为什么执行构建命令时 Codex 还是要问原因是新版 Codex 的审批策略不止一层会话内还有附加确认策略可能限制某些危险命令必须经过人类确认。解决方式不是硬改成 auto而是先看命令分类给相关命令追加允许自动执行的规则。我后来意识到一个更稳的思路与其追求“所有命令自动”不如拆分。只读、测试、lint 这类验证命令放自动文件删除、依赖安装、大规模重构保留确认。这个折中方案既保留效率又留了一道安全闸。毕竟 AI 自动执行 100 次只要搞坏一次成本可能超过之前省下的全部时间。5.3 自定义技能文件不生效命名与优先级当你开始自己写技能文件时会遇到一个隐藏规则文件名的前缀会影响优先级或加载顺序。有些实现里数字或字母前缀控制顺序有的按目录层级决定。你必须严格按示例来否则技能文件存在但永远不会被 AI 选中。我写过一支“提交信息规范”技能文件名起得很随意结果 AI 一直没表现出遵守的迹象。后来对照项目示例改成约定前缀才生效。这里也想提醒喜欢深度定制的人改技能内容前先跑通一个自带技能确认基础链路没问题再加自己的规则。这能大大降低定位成本不然你会陷入“到底是配置问题还是技能内容问题”的泥潭。5.4 升级 Codex 后技能失效接口惯性最后提醒一个跟使用习惯有关的问题。Codex CLI 自身更新很频繁某次升级后可能改变技能读取约定导致以前配置好的环境突然失效。遇到这类情况不要急着重装先看项目主页有没有兼容性说明再查升级日志里涉及技能的部分。我自己处理过一次更新 Codex 后技能在会话里时有时无最后发现新版要求技能目录里必须有一个索引文件旧的布局不再被扫描。解决方案不是回滚而是按新版规范补一个索引文件。玩这类增强项目这种跟随社区节奏的维护成本是省不掉的也是和其他普通工具最大的区别。6. 最后分享一点个人体会玩 superpowers 这段时间我最大的体会不是写代码变快了而是它改变了我和 AI 协作的方式。以前我把 Codex 当成高级搜索引擎问一句答一句装上 superpowers 之后我开始把一整块任务交给它然后像带新人一样检查它的计划和结果。这种转变带来的效率提升远超过“改代码速度”本身。如果让我给刚接触的人一个建议我会说第一次配置千万别追求完美。先把技能加载起来用一个小任务跑通“计划-实现-验证”循环再逐步开命令自动执行、增加 Java 或其他语言专用配置。很多人在第一步就卡在完美配置上反而错过了这个工具真正好用的地方。还有一个小技巧是我后来才养成的每次任务开始前让 AI 先读一遍当前加载的技能清单。这个动作看起来多花几秒但能有效防止会话中途技能失忆尤其是切换项目类型时非常管用。我目前把这件事当成了使用 superpowers 的标准开场动作也推荐你试试看。