最早我是被这个关键词的中文搜索结果气到的搜 superpowers出来的全是游戏攻略和营销号软文真正想找的那个给 Codex CLI 加技能的开源项目反而要翻好几页。obra 在 GitHub 上开源的 superpowers 已经火了有一阵子但对中文开发者来说还是个相对陌生的名字。简单说它是给 Codex CLI 用的一套技能skills框架作用是让 AI 编码助手从会写代码变成会做工程。我重度用了大概一个月最大的感受是它没有让 Codex 变聪明但让它变得有纪律了。这篇文章把我从安装、自举、工作流拆解到 Java 项目实战的完整经验写下来适合正在用 Codex 但觉得结果不受控的人也适合想给团队 AI 编码流程立规矩的人。1. 先搞清楚 superpowers 是什么它不是插件是一套技能操作系统1.1 一个 skill 文件到底长什么样很多人第一次听说 superpowers第一反应是又一个 AI 插件。其实它和插件完全是两个物种。插件的核心是给编辑器加功能、加界面superpowers 的核心是给模型加行为约束。它把软件工程里那些被验证了几十年的好习惯——先规划再动手、测试驱动开发、根因分析式调试——写成一篇篇结构化的 Markdown 文件这些文件就是 skill。一个 skill 文件通常长这样--- name: write-a-plan description: 在动手写代码之前为当前任务产出一份可执行的分步计划 when_to_use: 当任务涉及多个文件、多个步骤或需求还不完全清晰时 version: 1.0.0 --- # Write a Plan 1. 先阅读项目现有结构和 PLANS.md如果存在 2. 将任务拆解为不超过 15 分钟的小步骤 3. 每个步骤写清楚意图、涉及文件、验证方式 4. 计划完成前不要动手写任何实现代码前面的 YAML frontmatter 是元信息其中 description 和 when_to_use 这两项最关键——它们是 Codex 判断当前这个任务该调用哪个技能的依据。正文才是真正的执行指令。这种判断条件 执行步骤的结构本质上就是给模型用的决策树让它不再靠猜来选工作方式。1.2 自举机制为什么安装过程需要 Codex 自己参与superpowers 的安装流程里有一个非常特别的环节它不只是把文件复制到某个目录而是要启动一次 Codex 会话让 Codex 自己把这些技能全部读一遍并把何时调用哪个技能的规则固化到它的指令体系里。这个过程在项目里叫 bootstrap中文社区习惯叫自举。我一开始觉得这步很玄学后来理解了技能要生效前提是模型真的知道这些技能的存在和使用时机。如果只是把 Markdown 文件丢在硬盘里Codex 根本不会主动去翻。自举的本质是让 Codex 在初始化阶段把这些技能的摘要信息加载进它的上下文——相当于入职第一天先读员工手册而不是边干活边翻书。技能文件有一个很好的特性格式对人类和模型完全透明没有任何黑盒。你可以随时打开技能库逐字阅读每个文件的每一条规则改成符合自己团队习惯的版本。这一点对技术团队非常重要意味着这套框架可以被审查、被定制、被沉淀成团队资产。1.3 和普通 prompt、插件、MCP server 的区别到底在哪我见过不少人把 superpowers 和 MCPModel Context Protocol搞混这里把几个概念一次说清概念本质举例普通 prompt一次性指令用完即弃帮我把这个模块重构一下插件给编辑器和工具链加功能VS Code 扩展、构建插件MCP server暴露工具给模型调用的协议数据库查询工具、文件系统工具superpowers 的 skill可复用的流程规范和决策规则写代码前必须先产出一份计划一句话总结MCP 解决的是模型能调用什么工具superpowers 解决的是模型应该以什么流程做事。两者可以共存superpowers 自己也支持通过 MCP 服务把技能和记忆暴露给 Codex 动态管理后面讲 Java 实战时我会具体说。1.4 它到底解决了我哪三个痛点第一是任务边界失控。我之前直接让 Codex 修一个方法它顺手重构了整整一个类diff 大得没法 review。superpowers 的规划技能会强制先产出 PLANS.md明确改动范围动代码之前就能拦住这种自由发挥。第二是跳过验证。裸用 Codex 时它经常写完代码就宣布完成不跑测试也不给验证命令。TDD 技能会强制它先写失败测试、再写实现、然后自己执行测试命令。这个改变是革命性的——AI 终于开始对自己的代码跑测试了。第三是上下文丢失。上一步刚说过的项目约束下一步就忘了。superpowers 的项目记忆机制会把这些约束持久化每次新会话重新加载。说白了就是给 AI 配了一个长期记忆盘。2. 安装与自举让 Codex 学会使用技能库的完整过程2.1 前置条件先检查一遍在动手之前确保三件事没问题Codex CLI 已经安装并且能正常对话系统是 macOS 或 LinuxWindows 用户建议开 WSL本机有可用的包管理工具比如 Homebrew 或 npm。如果你平时用科学的方式管理 Node 版本注意一下 npm 全局安装的权限别装完发现命令找不到。另外提醒一句网上搜 superpowers 会搜到一堆同名项目有游戏、有前端库别搞混了。本文说的是 GitHub 上 obra/superpowers 这个仓库针对的是 Codex CLI 的技能框架。装之前最好先去仓库 README 确认一下项目全名和当前推荐安装方式工具迭代很快以官方文档为准最稳。2.2 三种安装方式任选其一我自己用的是 Homebrew 方式brew install obra/superpowers/superpowers没有 Homebrew 的话官方也提供 npm 方式npm install -g obra/superpowers第三种方式是从 GitHub Releases 页面下载对应平台的预编译二进制解压后放进 PATH 目录。这种方式最适合 CI 环境或者不方便装包管理器的服务器。装完先验证一下superpowers --version能正常输出版本号说明 CLI 本身没问题了。2.3 自举让 Codex 把技能库读进脑子接下来是最关键的步骤。运行superpowers bootstrap codex严格来说具体子命令名在不同版本里可能略有差异装完后先跑superpowers --help看一眼官方提示。这个命令会输出一段引导说明大意是新建一个 Codex 会话然后在会话里粘贴一段特定的激活提示让 Codex 自己去下载、解压、安装技能库并把技能接入它的指令体系。我第一遍卡在这里了以为运行完 bootstrap 就完事了直接回原来的 Codex 会话继续聊天结果技能完全没生效。后来才发现技能是在新会话启动时加载的老会话里 Codex 根本不知道你装了新东西。所以自举完成后一定要关掉旧会话重新开一个。2.4 验证技能库是否加载成功重开会话后直接问 Codex你现在有哪些技能正常情况它会列出一串技能名比如 brainstorm、plan、TDD、debugging、commit-message 这类每个还带一句话说明。能列出这串名字说明技能库已经进入了它的上下文。还可以直接检查文件系统。技能库默认放在~/.codex/skills/目录下进去看一眼就能发现每个技能对应一个文件全是纯文本 Markdown没有加密也没有二进制格式。这一点我特别喜欢——你完全可以把整个技能库通读一遍搞清楚 Codex 到底被灌输了哪些行为准则而不是把它当黑盒用。提示如果你在这个目录里看到的技能文件很少或者 Codex 回复我不确定你有技能大概率是自举那一步没走完或者会话没重启。重跑一遍 bootstrap 流程然后再开新会话。3. 核心工作流拆解从需求澄清到提交信息的每一步3.1 需求澄清brainstorm 技能先拦住想当然superpowers 的第一个环节不是写代码而是 brainstorming。这个设计非常反直觉却是我觉得最值钱的部分。以前我扔给 Codex 一个需求它默认我的需求是完整的、清晰的直接闷头就开干。结果经常出现我要的是 A它做出来的是 B。superpowers 的 brainstorm 技能要求它在动手前先和我确认关键问题比如边界条件、异常路径、兼容性要求——这些恰恰是我之前懒得写清楚、又最容易出问题的地方。一开始我会嫌烦我只是让你加个导出按钮你问这么多干嘛后来被坑过几次就老实了需求澄清省掉的每一分钟都会在后面用十倍的返工时间还回来。现在我会主动配合这个环节把模糊的地方在会话里聊清楚再放它去干活。3.2 计划产出PLANS.md 为什么能改变 review 体验需求澄清之后进入 plan 环节。Codex 会产出一份 PLANS.md结构大致是本次任务的目标和验收标准涉及的文件清单标注新增/修改/删除分步实施顺序每一步都有明确产出物每步的验证方式测试命令、人工检查点这份文件的出现把AI 改代码从事后审查变成了事前审查。以前 Codex 直接提交一堆 diff我只能看到结果看不到它为什么这么设计、为什么选这条路径。现在计划先落地方向不对可以在零代码成本的时候纠正。而且 PLANS.md 本身就是项目资产新人接手时看一眼就能理解设计意图比读代码快得多。3.3 TDD 技能让 AI 先写失败测试而不是先写实现superpowers 对 TDD 的贯彻比我预想的要严格。执行计划时Codex 不是直接写实现而是严格走红灯—绿灯—重构三步先写一个会失败的测试跑一遍确认失败再写恰好让测试通过的最小实现跑测试确认通过最后重构代码并再次验证。我以前也试过在 prompt 里要求 Codex先写测试再写代码但它总是阳奉阴违写着写着就跳到实现了。原因很简单口头指令没有流程约束力。superpowers 的 TDD 技能把它变成了分步执行的规则加上技能描述里明确写了这是所有编码任务的默认路径Codex 几乎没有偷懒的空间。我实测下来它对 JUnit 这类测试框架的调用频率明显变高了不是嘴上说说是真跑。3.4 调试技能从随机改代码到根因分析另一个直接改善体验的是 debugging 技能。裸用 Codex 时它遇到 bug 的第一反应是猜一个可能的原因然后改掉经常把相关代码全动一遍最后 bug 还在还引入新问题。superpowers 的调试技能则给出一套标准排错路径先复现问题写清楚复现步骤和预期行为用日志、断点或二分法定位根因而不是靠猜测针对根因提出修复方案评估影响面修复后补充回归测试防止复发。这套流程本质上就是人类资深工程师的排查套路被固化成了模型可以照做的 checklist。我印象最深的一次Codex 定位到一个并发问题通过分析线程日志找到了真正的竞态条件修完之后还补了一个压力测试。那个瞬间我真的有种这才是队友的感觉。3.5 提交信息与自查把流程的最后一公里走完代码改完不等于任务结束。superpowers 的 commit-message 技能会要求 Codex 根据实际改动生成符合 Conventional Commits 规范的提交信息比如 feat、fix、refactor 这种前缀并把它在 PLANS.md 中完成的任务勾掉。更有意思的是自查环节Codex 会把最终改动范围和计划做对比如果超出计划必须说明理由——是需求变了还是发现了计划外问题。这个自觉汇报偏差的机制让我在 code review 时省了大量时间diff 范围基本都在预期内偶尔有偏差也带着解释不需要我再满屏找为什么这里动了。4. Java 项目落地把技能链跑进 JVM 生态4.1 为什么 Java 开发者尤其需要这套流程Java 项目可能是最让 AI 编码助手露怯的场景之一。构建链路长Maven 和 Gradle 版本复杂测试框架多JUnit 4 和 JUnit 5 写法差异大代码规范重Checkstyle、Spotless 稍不注意就挂 CI。裸用 Codex 时我踩过的坑包括用 JUnit 4 的语法写 JUnit 5 的测试、不知道项目用的是 Maven wrapper 还是全局 mvn、改完代码格式化不符合规范导致流水线红灯。superpowers 的价值在于它允许你把这些项目特有的约束写成技能或项目记忆让 Codex 每次开工前自动加载。语言无关的通用技能管住流程项目定制的规则管住细节两者配合Java 项目才能让 AI 真正放手干活。4.2 我在 Java 项目里做的三件配置第一件把构建命令写进项目记忆。很多 Java 仓库用 Maven wrapper./mvnw如果 Codex 直接跑系统 mvn很可能因为版本不一致翻车。我在项目记忆里明确写了一句本仓库统一使用 ./mvnw 执行构建禁止直接调用系统 mvn——从那以后它再没跑错过。第二件补齐测试技能。默认的 TDD 技能是语言无关的对 Java 缺一些约定。我新增了几条规则Java 测试统一使用 JUnit 5包结构遵循 src/main/java 和 src/test/java测试类命名以 Test 结尾。这几条看起来简单实际效果立竿见影生成的测试代码风格和团队惯例完全对齐。第三件把格式化纳入完成定义。我不希望 Codex 只是功能跑通就交差所以在技能里加了硬性要求提交前必须执行 Spotless 格式化并跑完本地全量测试。一开始它偶尔会漏现在基本养成习惯CI 红灯率大幅下降。4.3 一个真实场景给订单服务加取消订单并退回库存把流程串起来看假设需求是取消订单并退回库存。第一步brainstorm 技能会追问我库存退回是同步还是异步取消后是否允许重新下单如果取消失败该如何回滚需求聊清楚后进入计划环节PLANS.md 列出要修改的 OrderService、库存客户端、新增的 OrderCancelTest 等文件清单。第二步进入 TDD 执行Codex 先写 OrderCancelTest预期订单状态变更和库存回滚跑一遍确认失败然后写取消逻辑再跑./mvnw test直到绿灯最后做重构把取消逻辑中重复的库存调用抽成公共方法。第三步提交commit-message 技能生成了feat(order): add cancel order with stock rollback这样的提交信息并把 PLANS.md 里的对应项勾掉。整个链路走完我最省心的不是 Codex 写得多好而是每一步它都自己验证而不是拍胸脯说应该没问题。4.4 MCP 集成让技能和记忆可以被动态管理如果你在用 Claude Code、Cursor 这类支持 MCP 的客户端superpowers 还有一个可选的 MCP server 模式可以把它注册进客户端的 MCP 配置里。注册之后客户端就能通过工具调用动态查询技能列表、读取项目记忆、甚至创建新技能不需要手动改文件。我在 Codex 的 config.toml 里配置过一次好处是可以在对话中直接说把之前那条构建规范写进项目记忆它真会自己动手写文件。对团队协作来说这降低了维护成本——不用每个人手动同步技能文件MCP 拉取即可。5. 三十天实测踩过的坑、总结的技巧和它改变我的三个瞬间5.1 坑一技能不是越多越好约束越少越好我刚上手时陷入过一个误区觉得技能库机制这么灵活应该把自己能想到的规范全塞进去。结果 Codex 每次开工前要读一大堆技能反而不知道该优先执行哪个经常出现计划说做 A最后交付了 B的错乱。后来我把技能按场景重新梳理核心流程技能保留默认项目特有规则只放记忆文件不再单独建技能效果立刻变好。技能库是给模型减熵的不是增熵的越聚焦越有效。5.2 坑二计划质量直接取决于需求质量superpowers 的 code review 环节确实能拦住大部分偏差但有一个环节它拦不住需求本身模糊时计划也会模糊甚至错误。有一次我图省事把需求描述得含糊计划阶段它产出了一份看起来完整、实则方向跑偏的方案我偷懒没仔细审结果后面返工了整整一天。现在我的经验是brainstorm 阶段多花十分钟把边界条件和异常路径聊透后面能省一小时。这个环节千万别跳。5.3 坑三验证命令要按项目实际改不能照搬默认TDD 技能默认会跑一些通用测试命令但 Java 项目差异很大有 Maven 也有 Gradle有 JUnit 4 也有 JUnit 5还有 Lombok、Mockito 这些依赖。如果技能里的验证命令和项目实际不符Codex 就会跑错命令然后得出测试挂了的错误结论。解决办法就是我在 4.2 里说的把项目真实的测试命令和构建方式写进项目记忆确保它每一步都能验证在正确的环境里。5.4 三个让我回不去的瞬间第一个瞬间是它在 Java 项目里主动跑完./mvnw test告诉我绿灯的那一刻。过去一年我习惯了 AI 写完代码丢给我验证那是我第一次感觉到工作流闭环了。第二个瞬间是它修完一个并发 bug 后补了一个压力测试。那不是我会要求它做的事但它是技能里修复后补回归测试这条规则驱动出来的。规则和纪律真的能让 AI 多走一步。第三个瞬间是看到技能文件被团队成员 review、修改、扩展。我意识到这套东西已经超越了工具成了团队工程文化的载体。那些文件里写的每一条规则都是从我们的真实教训中沉淀出来的这比任何文档都鲜活。用一句话总结我的体会superpowers 并没有让 Codex 变得更聪明它只是让 Codex 变得有纪律。而纪律恰恰是 AI 辅助编程时代最稀缺的东西。如果你现在用 Codex 还处于让它干啥它也干但总让你提心吊胆的状态我强烈建议花一个下午把它装上然后耐着性子陪它完整走一遍规划—TDD—调试—提交的流程。你可能会和当初的我一样第一次觉得 AI 队友终于可以放心把后背交给它了。最后分享一个小技巧第一次跑完整流程时把 Codex 的每一步输出都保存下来。后面再和它合作当你觉得它不对劲时翻一翻这些早期输出你会更清楚地看到它是从哪一步开始偏离流程的。这比任何使用说明都更能教会你如何控制和引导 AI 协作也是把 superpowers 从工具变成习惯的关键一步。