先把话撂这儿给 Codex 配 Superpowers不是装一个 VS Code 插件那种“装法”。它本质上是一份写得极其啰嗦、但又极其有用的 AGENTS.md 规则集合外加一小撮配套脚本。最近社区里讨论度很高的“codex superpowers”指的就是 GitHub 上 obra/superpowers 这个开源项目。作者 Jesse Vincent大家一般叫他 obra把它定位成“TypeScript 3x faster”的工作流配置我自己的实测虽然没有跑到 3 倍那么夸张但“代码质量维度上的提速”是真的明显。如果你试过裸 Codex 那种“问一句答一句、改完代码不跑测试”的体验那 Superpowers 给你的就是另一个极端把 AI 程序员当成一个必须遵守 SOP 的新人实习生来管。这篇东西我会从安装、核心机制、实测效果讲到 Java 适配和排坑适合所有已经在用、或者正准备用 Codex CLI 的开发者。1. Superpowers 是什么它不是插件而是一套“AI 工程纪律”1.1 一个比喻它不是工具是入职第一天发给 AI 的 SOP 手册想象一下公司来了个能力很强但毫无行业常识的实习生。你给他一个任务他要么闷头写一坨跑不通的代码要么写完了也不告诉你有没有测试。你需要做的不是给他买更贵的电脑而是给他一份操作手册先看需求文档再列实施计划写完代码必须跑测试自测通过才能提 MR。Superpowers 干的就是这件事。GitHub 上 obra/superpowers 这个仓库本身核心资产就是一个巨大的 AGENTS.md 文件以及配套的脚本和规则文档。当你把它引用到自己的 Codex 项目里Codex 在每次会话启动时都会把这份规则加载进上下文。也就是说不管你下一条 prompt 是什么Codex 都会先“想起”这一整套工作纪律再开始回答你。很多人误解“装了 Superpowers”就是多了一个可以调用的函数或面板其实不是。它没有改变 Codex 的底层模型能力也没有引入什么黑科技推理内核。它改变的是行为约束让模型从“怎么方便怎么来”变成“按固定流程走”。1.2 它和普通提示词Prompt的区别你完全可以用一段提示词让 Codex“先写计划再写代码”但效果通常很差。原因很现实提示词是一次性指令模型可能在这轮遵守下一轮新会话就忘得一干二净提示词没有强制力。模型在生成长代码时上下文注意力会被任务细节挤占早期指令很容易被“遗忘”提示词不能跨项目复用你每个项目都得重新复制粘贴还容易写得不一致。而 AGENTS.md 是 Codex CLI 体系里内置的“常驻记忆”。它会在每次会话开始时自动加载并且支持分层项目根目录放一份子目录还能放更细化的规则模型在处理不同目录的文件时会自动套用对应约束。Superpowers 等于帮你把资深工程师的管理经验沉淀成了一份标准文件再通过 Codex 的机制“焊死”在每次会话里。1.3 官方宣称与实际口碑项目主页上写的是“TypeScript 3x faster”。这个数字不用太较真它更像是作者在自己熟悉的项目类型上做的基准测试结论。社区里更普遍的声音是速度不一定翻倍但返工率确实下降了。因为 Superpowers 强制“先规划、后编码、带测试、再提交”很多裸 Codex 下常见的“写出来但跑不通”“跑通了但破坏了其他功能”被提前过滤掉了。对团队协作来说返工减少比单纯生成速度快更有价值。2. 环境准备与安装从 Node 到 Codex CLI 再到 Superpowers2.1 前置条件清单在动手之前先确认环境里有没有这些东西依赖项要求用途Node.js建议 20 或更高运行 Codex CLI 和各类 MCP 服务Git任意较新版本拉取 Superpowers 仓库Codex CLI最新版本npm 包名openai/codexAI 编码代理本体OpenAI 账号ChatGPT 登录或 API Key鉴权与调用模型一个真实项目不要拿 hello world 试规则的工作流需要项目上下文才有意义Node.js 版本很容易被忽略。Codex CLI 本身对 Node 版本不挑但它调用的很多 MCP 服务、还有 Superpowers 配套脚本可能依赖新版特性。如果你 Node 还在 16建议先升级。2.2 安装 Codex CLI 并完成登录这一步不复杂但很多人卡在“不知道现在 npm 包叫什么名字”。早期 Codex CLI 的包名是codex后面官方调整过多次现在统一为openai/codex。安装命令npm install -g openai/codex codex --version接着登录账号codex login如果你用的是 API Key也可以走环境变量方式export OPENAI_API_KEYsk-你的key登录成功后建议随便找个目录跑一句codex exec hi确认端到端链路是通的再做下一步。注意网上很多旧教程还在用npm install -g codex或者codex install这些大多是 2025 年之前的命令。装完之后先看codex --version如果提示找不到命令多半是 npm 全局路径没配把 npm 的 bin 目录加到 PATH 里即可。2.3 拉取 Superpowers 并接入项目Superpowers 的推荐用法是把它放在项目目录之外作为一个公共资产多个项目共用。我自己习惯放在~/tools/superpowersgit clone https://github.com/obra/superpowers.git ~/tools/superpowers然后在你的项目根目录创建AGENTS.md如果已经存在就打开编辑在里面加上一行引用/Users/你的用户名/tools/superpowers/AGENTS.md这就是整个“安装”过程。Codex CLI 在读取 AGENTS.md 时支持语法导入另一个文件Superpowers 的规则文件会被展开进你项目的规则上下文中。如果你的项目已经有公司强制要求的AGENTS.md不用合并直接在文件末尾追加这行引用即可。两者互不覆盖Codex 会按顺序全部加载。2.4 怎么确认规则真的生效了接入之后先别急着丢大任务。打开 Codex 交互模式随口问一句你加载了哪些 AGENTS.md 文件请复述其中关于工作流的核心要求。如果模型能说出类似“我需要先写计划、再编码、然后运行测试验证”的内容说明 Superpowers 已经被正确加载。注意它会比较啰嗦因为规则文件本身就长。也可以直接在实际小任务上验证让它“给这个项目加一个简单的工具函数并完成提交”。看它的行为是不是变成了“先查看项目结构 → 写 PLAN → 写测试 → 实现 → 跑测试 → 提交”。如果它还是闷头直接改代码说明引用路径有问题检查一下AGENTS.md里的路径是否绝对路径、文件是否存在、Codex 版本是否过老。3. 核心机制拆解AGENTS.md 和“协议文件”是怎么把 AI 拽进工程模式的3.1 AGENTS.md 为什么能改变模型行为Codex CLI 会在每次会话启动时把当前目录下的AGENTS.md文件内容自动注入系统提示system prompt。这意味着这些规则不是“建议”而是模型说话做事之前就已经存在的背景约束。对大语言模型来说系统提示里的指令优先级远比用户后输入的话要高因为它在每一步生成时都在影响注意力分配。这也是为什么同样的模型裸 Codex 和加 Superpowers 的表现会像两个不同的生产力工具。模型的能力没有变变的是约束空间它知道“如果我不先写计划就直接写代码就会违反规则”于是选择了符合规则的路径。3.2 Superpowers 里的几条核心“军规”我读了一遍规则文件整理出几条对产出质量影响最大的约定规划先行Plan First任何非琐碎任务第一步不是打开编辑器而是先写一份plan.md。计划里必须包含变更目标、影响范围、实施步骤、验证方式。Codex 需要在计划得到确认后才开始写代码。单任务切片一次只处理一个“关注点”concern。不允许在一个提交里同时改业务逻辑、顺手重构、还更新了文档。这样做的好处是后续 review 和回滚都会很轻松。测试优先新功能必须配套测试。不是“写了最好”而是“没有测试就不算完成”。对于 bug 修复更是要求先写出能复现问题的失败测试再让代码通过。提交信息结构化提交信息需要清楚说明变更原因和影响不允许出现“fix stuff”这类无意义描述。这本质上是在强制 AI 保留决策上下文。验证环节不可跳过代码写完不算完必须在本地或沙箱里运行测试、lint、类型检查。只有全部通过才允许进入下一步。这些规则单看每一条都不新鲜任何一个成熟团队都会这么做。关键区别在于Superpowers 把它变成了 AI 每次行动前必须遵守的协议而不是写在 wiki 里没人看的文档。3.3 强制验证是怎么落地的脚本与 MCP光靠文本规则约束模型模型还是可能“假装”自己跑过测试。Superpowers 的应对方式是把验证动作绑定到真实工具调用上而不是让 AI 自我报告。它依赖 Codex 的 MCPModel Context Protocol能力把外部命令变成可调用的工具。规则文件里约定了涉及浏览器验证的任务必须调用 Playwright MCP涉及类型检查的任务必须调用对应的编译命令涉及依赖变更的必须更新 lockfile。模型在流程上只是“发起方”真正执行的是本地工具结果也是真实返回的。这就像给实习生配了一个必须插电才能用的电动螺丝刀——不是他不想偷懒是工具设计上让他偷不了懒。3.4 技术本质把概率模型变成流程机器大模型本质是概率生成器同一个问题每次生成的路径可能都不一样。工程化使用 AI 的核心难题就是如何降低这种不确定性。Superpowers 的做法是压缩输出空间的自由度虽然代码内容仍然是概率生成的但“步骤顺序”“验证动作”“提交规范”这些流程层面的东西变成了确定性约束。你可以不太严谨地理解成裸 Codex 是一个“随叫随到的程序员”Superpowers 是他桌上的那本《工程红线手册》。红线划得越清楚越少出现“我觉得没问题”这种不可控判断。4. 实测观察Superpowers 加持后的 Codex 和裸 Codex 有什么区别4.1 实验设计同一个任务两套跑法为了不被主观感受带偏我拿一个中小型 TypeScript 项目做了对照测试。任务是“给订单模块增加一个支持多种优惠券叠加计算的服务并接入现有接口”。同一份代码库我开了两个分支一个用裸 Codex CLI一个用接入 Superpowers 的 Codex CLI分别执行同一个自然语言任务描述观察两类表现。4.2 场景一新功能开发裸 Codex 的行为很典型我正好在聊天里描述完需求它就直接开始创建文件和改接口。生成的代码能跑通主流程但存在几个问题没有测试文件优惠金额计算规则写死了后续扩展其他券类型要改核心逻辑提交信息写的是“add coupon service”。Superpowers 版本则完全不一样。它先是阅读项目里已有的订单模块代码然后生成了一份plan.md列出了“优惠券叠加规则的数据模型变动”“服务层接口设计”“涉及哪些既有单测”“验证清单”。我确认计划后它开始按步骤实现先写测试再写实现跑完vitest再跑tsc --noEmit最后给出的提交信息是“feat(order): support stacked coupon calculation with rule extension points”。对比下来裸 Codex 花了更短时间生成了代码但我后续需要手动补测试、修扩展性、改写提交信息。总耗时反而更久。4.3 场景二跨文件 Bug 修复第二个任务是修一个跨模块的状态同步 Bug购物车数量变化后结算页的合计金额没有及时刷新。裸 Codex 的做法是直接把结算页的金额计算位置加了一次手动刷新确实解决了表面问题但引入了另一个问题——购物车里加商品时如果组件还没挂载会出现空指针。因为它是“哪里症状明显就改哪里”缺乏对状态链路的整体分析。Superpowers 版本在计划阶段就画出了数据流购物车状态变更 → 触发事件 → 结算页订阅 → 金额计算 → 渲染。它把根因定位到“状态变更事件在某个分支条件下被吞掉”然后先写了一个能复现该 Bug 的失败单测再修复事件分发逻辑。最终修复不仅解决了问题还给这个数据流补齐了此前缺失的测试覆盖。4.4 对照结果与我的判断维度裸 Codex接入 Superpowers首次生成速度快慢因为要先写计划测试覆盖基本没有强制配套跨文件问题定位容易表面修复会做链路分析提交信息随意结构化后续返工常见明显减少对上下文消耗少多规则文件本身占一部分我的个人结论是如果只是写一次性脚本、做草稿探索Superpowers 反而是一种负担。它会让流程变得啰嗦生成一段一次性代码也要先列计划写测试纯属浪费。但如果你是做正经项目、要提交到团队仓库、代码要长期维护那它带来的约束价值远超那点流程开销。项目越大、涉及文件越多、协作人员越广收益越明显。5. “Superpowers Java”是怎么回事给 AI 协议做语言适配5.1 为什么原版直接跑 Java 项目会水土不服很多人在搜“superpowers java”以为这是个单独的 Java 版项目但搜来搜去发现不太对劲。实际上更常见的情况是把原版 Superpowers 引入到一个 Java/Maven 项目里然后发现规则文件里全是 TypeScript 生态的命令。它会默认你存在package.json让你跑npm test、tsc --noEmit、biome check在 Java 项目里这些命令全部不存在。模型并不会因为命令不存在就停下来它可能自己猜一个mvn test也可能直接说“我无法运行”。整个工作流断在验证环节。Superpowers 原版的规则深度绑定了一套 TypeScript/Node 工具链vitest、tsc、eslint、biome、npm scripts。这些在它的视角下就是项目的“标准验证手段”。要让规则适配 Java不是简单改两个命令名而是要把整套验证协议的语言生态底座换掉。5.2 Java 适配版做了些什么社区里维护 Java 适配版的人思路基本是把规则里的“语言无关层”和“语言特定层”拆开再做替换。常见的替换矩阵是这样的原版TS/Node 生态Java/JVM 适配版package.json npm scriptspom.xmlMaven或build.gradleGradlevitest/jestJUnit 5 AssertJtsc --noEmitmvn -q compile或./gradlew compileJavaeslint/biomecheckstyle或spotlessPlaywright MCP浏览器验证Selenium MCP 或结合 Testcontainers 做集成测试nvm/ Node 版本管理JDK 版本管理sdkman 或 jenv除了命令替换规则里关于“测试优先”“单任务切片”“提交信息规范”的部分其实是可以原样保留的。这也是为什么有人能快速把一个 TS 定制版本改造成 Java 可用版——因为工作流骨架是语言无关的真正要动的只是验证工具链。5.3 自己做一个最小 Java 适配的思路如果你不想等社区现成版本自己做一个最小可用适配其实不难。步骤大致如下把规则文件按层级拆开保留语言无关的部分任务规划流程、提交规范、单任务原则、review 要求单独复制到一个AGENTS-java.md。替换验证命令在 Java 项目里把测试、编译、格式检查命令分别写成可复用的短语比如“运行测试请使用./mvnw test”“编译请使用./mvnw -q compile”。规则文件不需要写复杂脚本关键是让模型始终用同一套命令。调整 MCP 工具绑定如果原版规则里绑定的是 Playwright MCPJava Web 项目可以换成 Selenium 类 MCP或者干脆禁掉浏览器验证环节改用 Testcontainers 跑集成测试。实测迭代拿一个小型 Spring Boot 项目跑一轮“加新接口 写测试 提交”。规则文件太长时模型也会“顾此失彼”建议分阶段补先加测试优先稳定后再加计划流程。我自己试下来的经验是不要一次性把所有规则都塞进去。第一版只要保住“先写计划、后写代码、必须跑mvn test”这三条产出的代码质量就已经比裸 Codex 高一个档次。后面再逐步加提交规范、代码格式检查等细粒度约束。5.4 语言中立才是长期方向搜“superpowers java”时还能看到一个热点社区正在讨论能不能把规则文件里所有语言特定部分外置成配置文件让同一套 Superpowers 规则像插件一样适配任意语言。这个方向比单独维护一个 Java 版要可持续得多。如果规则文件里写的是“运行项目的测试命令”“编译命令”“Lint 命令”这些抽象概念再由语言配置文件映射到具体工具链那 Superpowers 就从一个 TS 专用工具变成了一个真正通用的“AI 工程纪律层”。现在很多做 Transformer 适配的人已经在按这个思路改等成熟之后Java 开发者接入成本会低很多。6. 排坑记录与调参建议我踩过的和网上高频踩的坑6.1 坑一AGENTS.md 引用路径和嵌套 Git 仓库第一次接入时我图省事直接把 Superpowers clone 到了项目目录里结果项目里多了一个嵌套 Git 仓库Codex 扫描文件时还把它的目录也当作项目源码的一部分频繁读入无关文件上下文浪费严重。正确做法是放在项目外的公共目录用绝对路径引用。例如git clone https://github.com/obra/superpowers.git ~/tools/superpowers然后项目AGENTS.md里写/Users/你的用户名/tools/superpowers/AGENTS.md这样多个项目都能共用一份规则更新也方便cd ~/tools/superpowers git pull。6.2 坑二MCP 工具没配齐流程走到一半卡死Superpowers 规则文件里约定了很多验证动作要通过 MCP 调用真实工具。如果你的 Codex CLI 根本没配对应的 MCP server模型就会卡在“我想调用浏览器验证但是我没有这个工具”这一步然后反复向你解释没法继续。解决办法是接入 Superpowers 之前先按它的 README 把依赖的 MCP server 装好。Codex CLI 的 MCP 配置一般写在~/.codex/config.toml典型片段长这样# ~/.codex/config.toml示例片段 [mcp_servers.playwright] command npx args [-y, playwright/mcplatest]具体要配哪些服务以你 clone 下来的规则文件里实际提到的为准。不要凭感觉瞎配一堆只配规则里要求的最小集合就够了。注意MCP 服务装多了也会有问题。每多一个 serverCodex 在每次工具调用时都要带一部分描述信息上下文消耗会变大。保持“够用就好”的原则。6.3 坑三规则太长上下文被撑爆Superpowers 的 AGENTS.md 相当长再加上你要求它先写计划一个会话还没开始写代码上下文就已经吃掉不少。在代码库很大、早期 context 窗口有限的情况下任务进行到一半可能就会丢弃早期信息。应对方法有几个用支持更大上下文窗口的模型版本把任务拆小一次会话只完成一个切片不要指望一个会话做完整个功能精简规则文件副本如果团队内已经约定了一些纪律可以把 Superpowers 里重复的部分删掉只保留增量约束让 Codex 自动把任务进度写在plan.md里这样即使上下文被压缩关键决策还能从文件里恢复。我踩过一次比较大的教训让 Codex 在一个会话里“实现整个模块并完成所有测试”结果跑到一半它忘记了项目早期的结构约定重新生成了风格不一致的代码。拆成两次会话、每次基于plan.md继续之后稳定了很多。6.4 调参建议规则不是越全越好Superpowers 默认规则是给大型 TypeScript 项目设计的如果你的项目是小型工具、内部服务、或者还在原型阶段全量接入会觉得“窒息”。建议按需裁剪保留规划先行、单任务切片、提交信息结构化、测试优先。这四条是对项目质量影响最大的通用性也最强。可删复杂的验证脚本、浏览器自动化要求、细粒度的代码风格检查环节。这些在简单项目里反而是负担。可调测试命令和编译命令改成你项目实际使用的工具链。规则裁剪不是删掉文件里的内容就算完最好在AGENTS.md里覆盖掉默认规则。例如你希望 Codex 不强制使用 Playwright可以在自己的 AGENTS.md 末尾追加一句“本项目的 UI 验证以现有集成测试为准不要求 Playwright”。后加载的规则会在指令优先级上覆盖前面的约定。6.5 一个大原则把 AI 当“实习生”而不是“背锅侠”最后说一个心态上的建议。用 Superpowers 这类工作流约束工具时很多人容易走极端要么彻底放任 AI 自由发挥要么把所有责任都推给规则文件以为配好了就不会出错。我在实际用下来的体会是规则文件只是把“发生低级错误的概率”压低并不能把 AI 变成免检产品。你仍然需要在它做完计划后看一眼方向在它提交代码后抽查关键逻辑。Superpowers 的价值在于把 AI 的错误从“渗透在代码细节里”变成“集中在上游计划里”——这恰好是人工 review 成本最低的位置。如果你刚开始接触我建议先在一个非核心项目上完整跑一周原始配置亲身体验一下“先写计划再写代码”到底有多啰嗦、又能省多少返工然后再按自己的项目节奏裁剪。这种对比带来的体感比看任何教程都更准。
