如果你每天也在用 Codex 这类命令行 AI 编程代理干活大概也经历过这种崩溃让 AI 改一个模块它顺手把不相关的测试删了让它重构它上来就铺开十几个文件改到一半上下文失控跟它反复强调“先读文件再动手”结果它还是按照自己的理解一通乱写。我最近手上的项目正好进入密集重构期为了治这些毛病把 codex superpowers 这套技能增强框架从头到尾试了一遍。试完之后我得说它没有换更大的模型也没有改 Codex 的底层推理逻辑但它确实改变了 AI 的工作方式——从“你问一句它答一句”的临时工模式变成了一套有流程、有纪律、可追溯的协作流程。这篇不打算写成官方 README 的翻译而是我实际安装、配置、用 Java 项目压测之后的操作记录和踩坑总结。如果你是第一次听说 superpowers看完应该知道它到底解决什么问题、值不值得装如果你已经在用但总感觉不太顺手后面几节专门写了排错和自定义技能的思路。1. superpowers 的核心机制它真正改变的不是模型而是工作流1.1 为什么叫“superpowers”从一次性问答到流程化协作先说一个很容易误解的点。很多人看到“superpowers”这个项目名以为是给 Codex 灌了一堆魔法提示词让模型突然变聪明。实际上它的切入角度完全不同它默认“模型的能力就是那样不会因为你多写两句话就陡然提升”但模型的行为方式是可以被流程约束的。换句话说它管的是 AI 拿到任务之后怎么做而不是负责把你的需求变成结果。日常用 Codex 的时候用户的每次提问基本都是一次独立的小任务。你问“这个函数哪里有问题”它就去看那个函数你问“帮我重构这个 service”它可能唰地一下展开十个文件改到一半发现依赖关系没理清又回头改前面的代码。这种模式最大的问题是没有中间确认点AI 一旦开始生成容易沿着自己的理解一路走到黑。superpowers 的做法是把开发协作中的常见动作拆成一个个“技能skills”。每个技能是一份结构化的行为指南包括这个技能什么时候触发、执行前要看哪些资料、输出时要遵守什么格式、做完之后要做什么检查。比如“defensive coding”这个技能会要求 AI 在修改代码前先列出受影响的范围、写清楚为什么这么改、改动后必须检查哪些边界条件。再比如“code review”技能不是简单地让 AI 看代码而是规定它按优先级检查逻辑正确性、并发安全、异常处理、可测试性每一类都要给出明确的结论不能模棱两可说“看起来没问题”。所以它叫 superpowers本质上是给 AI 增加了一套可复用的行为模板。你不需要每次都在提示词里重复“你要分析影响范围、要写注释、要跑测试”这些已经被写进技能文件里AI 发现任务匹配某个技能时就会自动按那套流程走。1.2 技能的加载与激活方式superpowers 里的技能不是魔法本质就是 Markdown 文件。每个技能文件通常有固定的头部结构比如技能名称、触发条件、使用说明、行为步骤。当你在对话中提到某个关键词或者要求“activate skills”时Codex 会去读对应的技能文件把这些规则注入到当前上下文里。我实际用下来的感受是它对“触发条件”的描述很关键。写得太宽泛AI 会在不该用的时候强行套技能写得太窄该触发的时候又触发不了。比如“planner”技能触发条件适合写成“当用户提出一个复杂的、涉及多文件变更的任务且需要分步骤实施时”这样 Codex 在面对大型重构时就会先启用规划流程而不是一上来就写代码。加载方式上也花了我一点时间才搞明白。它有一个比较舒服的设计可以在会话开始时就声明“请按 superpowers 的技能体系处理这个任务”也可以让 AI 根据任务内容自动判断。我倾向于前者——先显式启用相关技能再下达具体任务这样行为的可预期性会高很多。还有一种方式是做“技能链”比如“planner”拆解完任务后自动把“code reviewer”和“defensive coding”串起来形成一套完整的执行流水线。1.3 和普通 prompt 的区别可复用、可审计、可版本管理我知道有人会想这跟我在提示词里写“请你先制定计划再逐步实施最后自查”有什么区别区别在于普通提示词是一次性的、不可靠的。你今天写了“先计划后实施”明天写“先做影响面分析”可能就漏了“计划”这步换一个会话模型对“计划”的理解又可能漂移。而技能文件是固定的、被反复加载的行为规范同一套技能在不同项目里表现基本一致。另一个容易被忽略的价值是可审计性。技能文件里写的每一步AI 执行的时候通常会展示“它正在按流程做什么”比如先列出影响面再写测试再改代码。出了问题时你可以回头检查是哪一步没遵守而不是像以前那样对着一段混乱的代码猜它当初为什么那么改。再加上技能文件本身是文本可以被 Git 管理——我们团队现在把技能文件放在项目仓库里新成员 clone 下来就能用同一套规范这比口头对齐高效得多。2. 安装与初始化从 clone 到首次对话的完整记录2.1 环境准备与仓库放置位置先说我当时的环境一台 macOS 笔记本Codex CLI 已经装好并且能正常跑通对话。如果你 Codex 本身还没调通建议先把它搞利索再碰 superpowers否则排查问题的时候会把两套东西混在一起非常难受。我拿到 superpowers 之后做的第一件事是把它 clone 到~/.codex/superpowers这个目录下。注意这个位置有两个好处一是 Codex 的全局配置目录通常就在~/.codex下两者放一起好找二是很多技能文件里会引用相对路径或者全局的辅助脚本放在这个固定位置可以少配一堆环境变量。理论上你 clone 到任何位置都行但我强烈建议别放项目目录里——它会混进你的 Git 仓库还会被 Codex 误读项目上下文。clone 完成后仓库里通常有一个安装脚本比如install.sh或者setup.sh。执行之前我习惯先快速扫一眼脚本内容确认它到底往哪里写配置。我当时的安装脚本做的事情大致是在~/.codex下创建或更新配置文件把 superpowers 的技能目录注册进去然后启动一个交互式引导。跑完脚本之后我额外手写确认了一下配置文件里的路径是否真的指向 superpowers 目录防止出现“脚本执行成功但读的是旧配置”的情况。2.2 初始化交互选项怎么选安装脚本跑起来后会有几个交互问题我当时凭感觉选完后来又回去改了一次所以这里把我的实际选择写出来供参考。第一类问题是“是否启用全部 skills”。我建议如果你刚上手就直接选启用全部先在一堆技能里跑几天看看哪些对你有用哪些是噪音。比对着清单逐个勾选要省事得多也更容易建立起对这套系统全局的体感。等用熟了再关掉不常用的技能即可。第二类问题是“是否生成 working agreements”。这个词直译是“工作协议”我理解成一组你和 AI 之间默认的行为约定比如“修改代码前先说明改动理由”“测试失败时优先排查而不是改写测试”“遇到破坏性命令必须停下来确认”。我选了生成而且后来自己往里加了不少条款。因为这个机制非常实用相当于给 Codex 立了一套通用的交互规则就算某个技能没有被触发工作协议里的约束也会先约束住 AI 的大方向。第三类问题通常和“示例项目”有关它会问你需不需要生成一个 demo 项目用来验证安装。我没有选后面验证是否成功也有更直接的方式。但如果完全没接触过命令行 AI 代理的新手生成一个 demo 项目跑一遍其实更好能快速看到技能文件被加载后的行为差异。2.3 最容易翻车的三个安装细节我在安装过程中踩了几个坑第一个是 shell 集成问题。安装脚本可能会往~/.bashrc或~/.zshrc里追加环境变量但如果你的 shell 是 fish或者你自己管理 dotfiles 文件追加的内容很可能不生效。最典型的表现是重启终端后在 Codex 对话里怎么都读不到 superpowers 的技能但检查配置文件却又一切正常。解决办法很简单手动在正确的 shell 配置文件里补上export PATH之类的变量或者干脆启动 Codex 前source一下对应文件。第二个坑是目录权限。有一次我把 superpowers clone 到了公司的统一工具目录下结果那个目录对当前用户只有读权限安装脚本创建缓存或技能索引时直接报错。当时报错信息很不直观我排查了半天才发现是权限问题。所以如果你碰到类似的奇怪错误先看目录写权限别急着改配置。第三个坑和版本兼容有关。superpowers 的发展节奏相当快有些技能文件的写法依赖 Codex 的新版本特性如果 Codex 版本太老技能加载时可能出现解析失败。我建议安装前先看一下项目文档里标注的 Codex 最低版本要求不满足的话先升级 Codex否则技能文件不一定能解析成功。装完之后怎么确认成功我的方法是开一个新会话直接问一句“你现在能用哪些 superpowers 技能”如果它能把技能清单列出来就说明技能目录已经被正确加载。不要一上来就丢个大任务——万一环境没通你看到的“AI 行为怪异”其实和环境有关容易得出错误的结论。3. 融入日常开发把 superpowers 嵌入 Codex 工作流的正确姿势3.1 对话前先定“工作协议”安装好只是第一步真正想让它改变日常开发效率关键在怎么用。我自己摸索出来的流程是开始一个任务之前先在工作协议层面把规则定清楚再谈具体需求。一个典型的开场长这样请按我们的工作协议处理这个任务 1. 动手改代码前先列出你理解的业务目标和潜在的边界条件 2. 如果任务涉及多文件修改先给出改动清单让用户确认 3. 修改完必须运行相关测试没有测试的代码要说明原因 4. 涉及删除文件或者重置操作前必须先停下询问。 现在请完成以下需求把订单服务中的拆单逻辑拆成独立模块。你可能觉得这很啰嗦但它带来的好处是巨大的。没有这套协议时Codex 拿到“拆单逻辑独立模块”这种需求会默认你已经想清楚了直接开写。而实际上“拆单逻辑”涉及哪些边界、调用方有多少、有没有隐藏依赖AI 并不知道。协议里逼着它先列理解和影响面就是给你一个纠偏的机会能在它写代码之前就把方向校准。我的经验是这套“先协议后任务”的开场在工程量超过 30 分钟的任务里特别值钱。小任务如“帮我看这个函数的空指针 bug”直接问就行不需要走完整流程。但对大需求协议带来的首次纠偏收益极高。3.2 典型任务分发Plan → Code → Review我对 superpowers 用得最重的两个技能分别是 planning 和 code review。当任务足够复杂时我会显式要求 AI 按“规划器 → 编码者 → 评审者”的流程走一遍。第一步我用一句话描述业务目标然后让 planner 技能接管。它会输出一份计划内容包括问题定义、涉及文件、改动步骤、验证方式。我可以在这个阶段直接修改计划比如砍掉某个不必要的步骤或者把某个改动拆分得更细。这一步等于在真正动代码之前先做了一次低成本的沙盘推演。第二步把计划确认完之后我让 AI 以编码者的身份按计划实施。这里我很少再重复业务逻辑直接引用计划文件或者把计划贴在上下文里即可。AI 会按计划逐项完成每完成一项就停下来汇报而不是一口气改完十几个文件。这个“分步实施逐步汇报”的粒子度对保持上下文质量很有用——你可以在中途发现问题而不是等它全部改完再面对一个巨大的 diff。第三步是让 code review 技能对改动做一次审查。它会按照技能文件里的优先级检查代码通常包括逻辑正确性、潜在异常、并发问题、测试充分性等等。有时候它能挑出一些 AI 生成代码时常见的低级错误比如没有判空就使用返回值、异步回调里改了共享变量之类的。更重要的是review 流程会催着 AI 给每个问题标注严重程度方便我判断哪些必须立刻处理哪些可以留到后面优化。3.3 与 Codex 原生功能的分工用了一段时间之后我慢慢理清了一个边界**superpowers 管行为纪律Codex 原生能力管代码生成。**它俩不是竞争关系而是分工不同的两层。Codex 原生那一层负责具体执行它能够读懂文件、生成修改、跑 shell 命令、定位错误堆栈。这些都是它的强项superpowers 并没有试图替代这些能力。superpowers 做的事情更像是在上层加了一个“流程调度器”——先帮 AI 判断该不该做规划、什么时候该停下来确认、输出结果时该遵守什么格式。这个分工对我最直接的影响是权限管理。Codex 执行 shell 命令时本来就有授权机制但光靠那个只能控制“能不能执行”管不了“该不该执行”。superpowers 在工作协议里补充了行为层面的约束比如“测试失败时优先分析失败原因禁止直接修改测试让用例通过”“删除代码前必须给出影响面说明”。前者解决能不能的问题后者解决该不该的问题两者配合之后才真正把 AI 限制在可控范围里。还有一点是多文件修改的节奏问题。Codex 原生支持一次读取和修改多个文件这本来是效率优势但没有约束时它容易变成灾难——改到第三个文件发现自己一开始的设计有问题回头把前两个文件又改一遍一来一回上下文窗口就被消耗掉了。superpowers 的分步实施机制实质上是在用“小步快跑”替代“大步流星”文件数越多这种节奏的价值越明显。4. Java 项目实战配置、磨合与效果4.1 我为什么拿 Java 项目来压测很多人用 Codex 都是写 Python、JavaScript 这类动态语言代码改了立刻可以看到效果反馈循环短AI 即使写错一点也容易被运行时错误暴露出来。Java 就不一样——它有严格的静态类型检查有繁琐的构建工具链还有各种框架级别的上下文依赖。这个特性对 AI 编程代理来说其实是“地狱难度”因为一点点类型不匹配、依赖没引入、注解写错都会让整个构建失败。我选它来测 superpowers就是想看这套行为约束能不能在“反馈延迟高、错误类型多、上下文依赖深”的环境里真正撑住。如果它连 Java 都能hold住放到其他语言上的可信度就高很多。4.2 Java 专属技能与配置superpowers 本身是语言无关的但技能里可以针对特定语言做约束。我在项目里额外建了几个 Java 相关的技能文件并配置它们只在检测到 Java 文件时触发。第一个是“compile-first”技能。以前 AI 改完代码后有时候直接用“看起来没问题”收尾在 Java 项目里这显然不够。我给这个技能定的规则是任何代码修改完成后必须运行mvn -q compile或mvn -q test-compile如果编译失败必须优先修正编译错误而不是继续改动。第二个和构建输出有关。Maven 的编译错误信息很长AI 经常被一长串堆栈淹没找不到重点。我规定遇到构建失败时必须先截取[ERROR]行的核心错误码和对应文件位置按照“错误码 → 所在文件 → 可能原因”的结构分析再让我确认修复方案。实践下来这个约束非常有用AI 不会再犯“拿着整段日志问我怎么看”的低级错误。第三个是测试策略。Java 项目里 JUnit 测试的粒度很细AI 常常因为改了一个方法连带破坏了几个旧测试。工作协议里我加了规则修改有测试覆盖的代码后必须运行相关测试类如果测试失败禁止直接删测试或弱化断言必须先检查是不是业务逻辑被改变了。这条规则堵住了一个很常见的作弊行为——AI 为了让测试通过而反向修改测试代码。4.3 一次具体的重构会话复盘说一个我实际跑过的案例把一个OrderService类里的拆单逻辑抽成独立的OrderSplitter组件。这个类大概有 800 行里面混合了数据库访问、库存校验、优惠券计算和拆单逻辑。如果用传统方式让 Codex 直接做它大概率会创建一个新类然后把订单服务里的相关方法原样搬过去再手忙脚乱地补依赖。用了 superpowers 之后整场对话的结构完全变了。第一步planner 技能先产出了一份计划大致是梳理OrderService中所有和拆单相关的方法 → 确认哪些私有字段会被新组件依赖 → 设计OrderSplitter的接口 → 迁移代码并保持原逻辑不变 → 编译和跑相关测试 → 检查调用方是否需要调整。这份计划里最值钱的是第二点——AI 没有急着写代码而是先确认了OrderDetailRepository、CouponCalculator这些依赖和拆单逻辑的耦合关系。第二步才是具体编码。AI 创建了OrderSplitter类把拆单逻辑迁移过去同时保留了原有OrderService中的调用入口。这一阶段我没有被它的每个修改细节打扰因为计划已经替我控制住了方向。第三步是 code review它发现了两个问题一个是拆分后的新类缺少Transactional事务注解导致拆单过程中如果中途失败库存回滚会不一致另一个是原来某段代码直接访问了OrderService的私有成员变量迁移后变成了通过 getter 调用多了一次不必要的 NPE 风险点。这两个问题它都在 review 阶段主动标注出来而不是等测试跑挂了再发现。对比一下用和不用的差异大概是这样对比项无 superpowers使用 superpowers首轮改动文件数8 个4 个中途需求纠偏次数我需要主动打断 3 次计划阶段已纠正 2 次编译失败后重新修改轮次3 轮1 轮最终 diff 中无效改动约占 30%约占 5%这不是严格的对照实验但它反映的趋势我很确定流程上的前置梳理能大幅减少无效代码生成而 review 环节能补上很多 AI 编码时容易忽视的边界问题。对 Java 这种编译成本高、测试运行慢的语言来说提前把方向弄清楚比事后反复修 bug 省太多时间。5. 调优与排错运行过程中最常见的坑和我现在的处理方式5.1 权限和命令执行问题Codex 本身会在执行 shell 命令时请求授权但 superpowers 引入后你会有更多“AI 因为技能要求而尝试执行命令”的场景。比如我在技能里写了“修改后必须运行mvn test”结果 AI 拿到任务后没改几行代码就急着跑全量测试跑一次五分钟很容易把人搞毛。我在工作协议里加了一条只有确认代码改动已经完成或被指定要定位特定测试失败时才能运行全量测试其余情况只运行相关测试类。另一个坑是破坏性命令。AI 在某些技能指引下可能会执行类似git reset --hard、rm -rf的操作这种命令一旦跑错后果很严重。我的处理方式是在工作协议里明确禁止 AI 未经确认执行任何与 Git 回滚、文件删除相关的命令还需要在技能文件里重复写一遍这条底线。好在这套系统支持在工作协议层面做强制约束不然每个技能文件里都写一遍太容易漏。5.2 上下文失控与针对性学习上下文窗口是这类工具最大的天花板。superpowers 在一定程度上解决了“AI 不知道边界在哪里”的问题但它没法解决“AI 需要读多少文件才知道项目结构”的问题。尤其是在大型 Java 项目里随便一个 service 类都可能牵扯几十个依赖类让 AI 全部读一遍显然不现实。我的做法是给 AI 加了一个“针对性学习”的约束只允许它在动手前按依赖关系逐级读关键文件最多探索两层超过层数必须停下来向我确认。比如处理OrderSplitter这个任务时它只读了OrderService、OrderSplitter相关接口和调用方的少量代码并没有把整个项目结构都拉进来。这个限制的好处是让上下文保持精简长会话不容易走到一半输出质量滑落坏处是某些隐藏依赖可能没被它看到需要靠编译器和测试来暴露。我的心理预期是用编译错误和测试结果来兜底隐藏依赖问题而不是指望 AI 一次读完整个项目。5.3 技能文件的自定义一个最小例子很多人装上 superpowers 之后最想问的是它提供的那一堆技能不够我用怎么办答案是自己写。技能文件本质就是带结构的 Markdown我把一个最精简的自定义技能模板贴出来--- name: concise-commit description: 当用户要求生成提交信息时触发。适用场景包括 git commit、git log 风格摘要。 --- ## 目标 生成一个结构清晰、不超过 50 字的提交标题以及按改动类型分组的提交正文。 ## 步骤 1. 先通过 git diff --stat 查看本次改动涉及的文件和大致行数。 2. 提取每个文件的改动主题归入 feat/fix/refactor/test/chore 等类型。 3. 标题用祈使句正文按类型分组一行一个要点。 4. 如果改动涉及多个不相关的功能提示用户考虑拆分成多个提交。 ## 检查 - 标题是否在 50 字以内 - 正文是否避免了“修改了某些文件”这类模糊表达 - 是否遗漏了用户明确要求的 breaking change 提示建好之后把它放到 superpowers 的技能目录下再确认技能索引能读到然后就可以在会话里触发了。我在自定义技能时踩过一个小坑技能的description字段如果写得和项目自带技能重叠AI 就会在两个技能之间犹豫不知道按谁的规则来。所以自定义技能尽量选那些项目没覆盖到的场景或者把触发条件写得足够特定这样激活时就不会打架。5.4 升级与版本兼容superpowers 迭代速度确实快我之前因为用过时的技能文件吃过亏。那次升级 Codex 之后原技能目录里几个文件的加载方式变了AI 经常出现“技能已加载但行为规则没生效”的诡异情况。排查了很久才发现是新版本不再支持旧技能文件里的一种写法。现在我的升级流程是固定的先把正在用的超级目录整个备份改名成superpowers.bak然后重新 clone 一份新的跑一遍安装脚本再手动对比新版技能文件是否有明显的结构改动。如果新版改动了工作协议相关的文件我会先用自定义的不变协议替换掉而不是盲目采用新版默认。这样既不会错过新功能也不会因为默认协议变化导致行为习惯断裂。另外一个让我很受用的是项目自带了测试机制。我是在跑完安装之后才发现的——仓库里有测试脚本可以用真实任务来验证核心技能是否能正常触发。升级之后先跑一遍这个内置测试能很快暴露环境问题而不是等到实际干活时才发现 AI 行为异常。6. 我的长期使用体会用了大半个月之后我对 superpowers 的态度经历了从“这东西是不是过度设计”到“回不去了”的转变。现在每天最常规的使用方式就是先在会话里声明工作协议然后让 AI 按 planner → coder → reviewer 的流程处理复杂任务。团队里有人问过我它能不能让 Codex 变得更聪明我会回答它不会让模型变聪明但它会防止模型犯蠢。真正懂开发的人都明白在 AI 编程代理这件事上“少犯蠢”比“偶尔惊艳”重要得多。如果你刚接触 superpowers第一周我不建议上手就去写自定义技能。先把它自带的技能清单全部过一遍挑三个最常用的planning、code review、defensive coding把这些技能配合工作协议用熟你会很快感受到“有纪律的 AI”和“没纪律的 AI”之间的差别。第二周再去试着改技能文件里让你不舒服的规则你会发现这套系统的可塑性才是它最大的价值——它不会强制你适应一种工作方式而是允许你把 AI 调教成符合你自己风格的工具。最后分享一个小技巧把工作协议文件文本同步到你项目的 README 或者 CONTRIBUTING 文档里当你不带 superpowers 用手动对话或者换一个工具的时候依然可以照着这套规则约束 AI。流程化的思路一旦建立起来迁移到任何工具上都成立。