最近一直在折腾 Codex CLI有个问题特别典型给它一个需求它马上就开写写到你面前的时候你才发现方向从一开始就偏了。后来我把一个叫 superpowers 的技能包装进 Codex整个协作节奏才终于靠谱起来——它不直接给 AI 塞提示词而是给 AI 一套“工作方法”。这篇文章就围绕 superpowers 的安装、使用、踩坑和 Java 场景下的实战做一份完整的使用笔记给同样被 AI“勤奋但跑偏”折磨的人参考。如果你是第一次听说这个项目本文也足够当一份 superpowers 使用教程来用。1. 先搞清楚superpowers 到底是个什么东西1.1 它不是插件而是一组“行为协议”superpowers 这个项目本身社区里也有人叫它 codex superpowers因为它和 OpenAI Codex CLI 配合得最多但它并不只是 Codex 专属。作者把一系列工程实践——头脑风暴、写实施计划、测试驱动开发、代码审查、调试复盘——写成了结构化的 Markdown 文件。这些文件不是给你读的而是给 AI 编程助手读的。AI 在开始干活之前会先去读对应技能文件然后按照文件里的流程来工作。这和我们习惯的“插件”完全是两码事。插件是在编辑器侧栏加按钮或者往终端面板里塞面板。superpowers 不碰你的编辑器 UI不注册任何快捷键也不依赖某个语言服务器。它做的事情更像是给 AI 装了一套“职业习惯”先问清楚需求边界再拆任务再写测试再实现最后自己审查一遍。用一个生活化类比普通 Prompt 是“今天帮我整理房间”AI 听完立刻把所有东西塞进柜子表面干净但下次找东西全乱superpowers 则是要求 AI 先问“哪些东西要保留、哪些要丢掉、柜子的分区规则是什么”然后按分区归置最后再检查一遍有没有放错位置。它改变的是做事的顺序不是做事的工具。这种做法对 AI 编程特别有效因为大模型写代码的能力其实不缺缺的是“什么时候该停、什么时候该验证、什么时候该回头改”的决策能力。上下文一长AI 很容易陷入局部最优盯着一个函数猛改忘了整个模块的契约。技能文件就是为了对抗这种“过拟合式写代码”。1.2 和普通提示词的区别其实在“流程可复用”很多人第一次看到 superpowers 的仓库会觉得“这不就是一堆提示词吗”是的它确实是 Markdown 写的但和提示词收藏夹有本质区别。普通提示词是“一次性指令”比如“请用 Java 写一个 RESTful 接口”AI 执行完就结束了技能文件则包含“分支流程”“验收标准”“失败回退机制”AI 会按里面的条件判断自己要做什么而不是只按一句话动作。我举个实际差别。普通提示词写“先写测试”AI 可能真的先写一个测试文件但测试写得稀烂只覆盖 happy path。superpowers 里的 TDD 技能会明确要求 AI 先列出行为清单把正常路径、异常路径、边界条件都列出来然后逐条转成测试再进入实现阶段。同样一个“先写测试”的要求有没有流程支撑效果天差地别。更关键的是普通提示词每次都要重新写一遍或者从收藏夹里复制粘贴而技能文件放在固定目录里AI 每次会话都能自动读到规则是稳定复用的。你不需要每次提醒它“按团队规范来”因为它自己会去查规范文件。维度普通提示词superpowers 技能文件作用范围单次回答整个任务周期流程一次性指令分支流程、验收、回退可复用性每次重写固定目录自动加载可解释性黑盒人可读的 Markdown依赖无需要 Codex/Claude Code 等底座1.3 它和“Agent 框架”也不是一回事现在各种 Agent 框架很多有带规划器的有带工具调用的有带记忆库的。superpowers 不造这些轮子它假设你本来就有 Codex CLI 或 Claude Code 这样的 Agent 底座它只负责把“工作方法”喂给底座。所以它的安装成本很低就是往技能目录里放文件不需要起服务不需要装 Python 依赖不需要配向量数据库。这一点特别重要。我见过不少团队一上来就上重型 Agent 框架最后发现大部分时间在调框架本身。superpowers 把复杂度降到最低所有技能都是人可读的 Markdown你能直接打开看 AI 将要遵守什么规则。这种透明性是黑盒框架给不了的也是我敢把它接进日常研发流程的最大原因。2. 安装从零到能跑通的最小路径2.1 前置环境缺一个都不行在动手之前先把基础环境捋清楚。我用的是 macOS但 Windows 和 Linux 过程类似关键是路径要对应上。Codex CLI 或者 Claude Code二选一建议版本保持更新老版本对技能目录的支持可能不完整Git用于克隆仓库Node.js 运行时因为 Codex CLI 本身依赖它。我踩过一个坑一开始用了一个很老的 Codex 版本技能目录一直加载不进去AI 完全无视技能文件。后来升级到新版本问题直接消失。所以如果你装完发现没效果第一反应应该是查 CLI 版本而不是怀疑装法。2.2 克隆项目先别急着复制最稳妥的办法是把 superpowers 仓库克隆到一个固定位置然后用软链接指向技能目录。这样以后仓库更新你只需要git pull所有技能同步更新不用反复复制。git clone https://github.com/obra/superpowers ~/.superpowers cd ~/.superpowers ls -la克隆完你会看到仓库里有skills目录。每个技能是一个子目录里面通常有SKILL.md作为入口文件。我现在用的版本里包含了 planning、brainstorming、TDD、debugging、code-review 这些核心技能每个文件都不长但流程写得很细。先别急着动手复制看一眼 README 里的安装说明因为项目的目录约定可能会随版本变化。我下面给的是社区里最常见的做法但如果你克隆下来的版本自带安装脚本优先用官方脚本。2.3 把技能放进 Codex 或 Claude Code 认得到的位置Codex CLI 的技能目录通常是~/.codex/skillsClaude Code 是~/.claude/skills。确认你的 CLI 实际使用的路径可以直接看文档也可以自己新建。mkdir -p ~/.codex/skills ln -s ~/.superpowers/skills/* ~/.codex/skills/如果你用的是 Claude Code把上面命令里的.codex换成.claude即可。建立软链接之后技能文件并没有被复制一份两边指向同一个地方更新仓库时自动生效。这里有个容易被忽略的细节很多 CLI 只会扫描技能目录的一级子目录也就是它希望skills/xxx/SKILL.md这样的结构如果你把技能文件直接平铺在skills目录下AI 很可能找不到。所以链接完以后一定要确认目录结构是“每个技能一个文件夹”。2.4 验证技能是否生效装完之后怎么确认 AI 真的读到了技能我的土办法是开一个新会话直接问“你会哪些技能列出名字和适用场景”。如果 AI 能报出 planning、TDD、debugging 这些名字说明目录没问题。另一个更真实的验证方式是给一个小需求并在需求里点名用某个技能。比如告诉 AI“用 TDD 技能实现一个 Java 的字符串反转函数先不要写实现代码先给我行为清单”。如果它真的先给行为清单说明技能已经生效。如果 AI 完全不理你优先检查三件事路径对不对、目录层级对不对、CLI 版本是否支持。不要一上来就怀疑技能文件本身有问题。3. 实战拆解superpowers 是怎么改变 Codex 工作流的3.1 先从“先规划再动手”说起我最直观的感受是装上 superpowers 以后Codex 不再急着写文件。我给它一个“给订单模块增加导出 Excel 功能”的需求它没有立刻打开代码而是先跑了一轮 brainstorming 流程问我几个问题导出范围是当前筛选结果还是全部订单大数量下是异步任务还是同步导出表头要不要按运营部门的口径字段里有没有敏感信息这些问题以前我是要自己在需求评审会上跟产品经理确认的现在 AI 先替我问了一遍。它这么做的原因是技能文件里明确写了“没有澄清需求之前不要开始设计”。这个约束不在模型本身而在技能流程里。把这种感觉翻译成技术语言AI 在生成代码前先把“需求规格”收敛成一个可验证的清单再基于清单去拆任务。这大大减少了“AI 写完了发现完全不是要的东西”的返工。3.2 测试驱动不再是口号第二点是 TDD 技能。以前我很难让 AI 真正 TDD因为模型训练数据里充斥着“先写代码再补测试”的模式你嘴上说 TDD它写代码的时候还是会先写实现。superpowers 的 TDD 技能把动作拆得非常死先列行为再写失败测试再跑测试确认失败再写最小实现再跑测试确认通过。我拿一个 Java 项目试了试。我先要求 AI 为PriceCalculator写一个打折计算功能并且点名要用 TDD 技能。它的反应是先把输入输出样例列出来比如“原价 100折扣率 0.8期望输出 80”“原价 100折扣率 1.2抛异常”然后才写测试。测试跑红它不慌只写最简实现让测试变绿接着主动提出要做边界补全。这种节奏在纯 Codex 默认行为里很难见到。默认行为更像是一个人在抢跑而 TDD 技能是在给它上发条每一步都留证据。3.3 收尾阶段的强制审查第三个变化是 code review 技能。以前 AI 生成完代码会说“我完成了”然后停下。装上 superpowers 之后它会在完成时主动开一个 review 环节重新读一遍自己写的 diff检查命名、异常处理、重复代码然后输出一份自审报告再问我要不要按报告修订。自审报告不是走过场。有一次它写完一个工具类自审时发现日志里打印了用户邮箱提示这可能涉及隐私合规问题建议脱敏。这个点如果靠我人肉 review不一定能发现因为代码本身能跑测试也过了但数据进日志这件事很隐蔽。superpowers 等于把“资深工程师 review”的清单变成了 AI 的固定动作。3.4 Java 项目里要注意的差异点先回应一下热词里的 superpowers java。superpowers 本身是语言无关的它管的不是语法是流程。但用在 Java 项目里有几个 Java 特有的地方需要你提前跟 AI 交代清楚。第一是构建工具。Java 项目有 Maven、Gradle 之分技能流程里凡是涉及“运行测试”的步骤AI 都需要知道该用mvn test还是./gradlew test。我建议在项目里放一个AGENTS.md之类的说明文件写清楚构建命令、测试命令、目录约定这样 AI 执行 TDD 流程时不会反复问。第二是 Java 的编译期检查比较严格。TDD 流程中先写测试再写实现意味着测试在编译阶段就可能失败——因为被测类还没存在。你要让 AI 明确区分“编译失败”和“测试断言失败”编译失败时它应该创建桩类而不是直接跳过测试。这个区分如果不说清楚AI 可能会为了“测试能编译”而先把实现写完流程就白搭了。第三是 Java 生态里框架魔法多比如 Spring 的依赖注入、MyBatis 的 Mapper 代理。代码审查技能如果在 Spring 项目里必须让它读pom.xml或build.gradle否则它会在 review 时提出一些“无中生有”的配置建议。我一般在会话开头加一句“请先阅读项目构建文件和启动类再进入流程”这句话值得固化进你的常用提示里。4. 调用 superpowers 的几个实用姿势4.1 显式点名比隐式触发更可靠虽然很多技能文件设计成让 AI 自动选择但我的经验是在关键节点上显式点名效率最高。比如“请使用 planning 技能先给我实施计划”“请使用 debugging 技能按它的排查流程走”。原因很简单自动选择依赖 AI 对技能文件的理解而理解就会有偏差。你显式点名相当于直接指定了工作协议AI 不会因为觉得“这个需求简单”就跳过流程。尤其是涉及多文件修改、重构、老代码迁移时显式点名能减少“AI 自由发挥”的空间。4.2 让 AI 先读技能文件再回答问题在会话开始阶段我会先发一条消息“请先阅读 superpowers 技能目录里的 planning 技能然后按该技能流程处理以下需求”。这一步相当于“热启动”。如果不主动提AI 虽然能看到技能目录但不一定会把技能文件完整读一遍它可能只凭文件名猜测内容。点名让它先读能确保后续行为严格跟随文件里的步骤。这个小动作对 Codex 尤其重要因为 Codex 的上下文窗口虽然大但“知道有这文件”和“真正读进去了”是两回事。4.3 会话中切换流程别怕打断使用过程中我发现 AI 会在某个流程里走得很深这时如果你意识到方向错了直接打断它明确说“停请切换到 debugging 技能重新审视当前实现”。不用不好意思AI 没有状态连贯性的心理负担打断它只会节省 token。有一次它按 TDD 流程写到一半测试总是红我立即叫停让它切换到 debugging 技能。它会先从“复现失败”开始而不是继续硬着头皮补测试。这种切换在传统人机协作里很自然但很多人跟 AI 协作时反而不敢打断结果让它在错误流程里跑完浪费大量时间。4.4 把自己团队的规范也写成技能superpowers 最被低估的能力是可扩展性。你完全可以在skills目录下新建一个team-rules技能把团队的编码规范、Git 提交信息格式、分支命名规则、Code Review 检查单放进去。AI 每次会话都能读到等于把团队规范从“文档库”搬到了“执行层”。我试过把“Java 项目必须使用 Lombok 的Slf4j而不是手写 Logger”“新增接口必须补充 OpenAPI 注解”这些规则写进自定义技能。效果非常明显Codex 生成的代码从“风格随机”变成“符合团队习惯”后面 review 的压力小了很多。5. 一个完整小案例从需求到合入的 superpowers 走法5.1 第一阶段用 brainstorming 收敛需求为了让你更直观地理解我拿一个真实的 Java 小需求过一遍。需求是“给用户模块增加一个查询用户最近订单的接口”。如果直接丢给 Codex它大概率会立刻生成一个 Controller、Service、Mapper性能、分页、权限全都不考虑。在 superpowers 的流程下我首先说“请使用 brainstorming 技能帮我澄清这个需求”。AI 没有写代码而是列出了一串问题最近订单的时间范围是什么最近一个月还是最近一单是否要分页默认页大小多少订单数据是否需要脱敏接口调用方是 App 端还是运营后台鉴权方式一样吗我逐一回答后它把需求整理成一份行为清单接口路径、请求参数、响应结构、异常场景。到这里我才允许它进入下一阶段。这一步看似多花了十分钟但之后写代码几乎没有返工。5.2 第二阶段planning 和 TDD 双线推进需求清单确认后我说“请使用 planning 技能给实施计划”。AI 给出的计划是先改 MySQL 查询语句再写 Mapper 接口然后写 Service 和 Controller最后补集成测试。它会按文件依赖关系排序而不是按心情乱写。接着点名 TDD 技能。它先为 Mapper 写了一个查询测试预期是按用户 ID 和时间范围查出最近订单。测试编译失败因为 Mapper 方法还不存在于是它创建方法签名再跑测试让红再写 XML 里的 SQL让测试变绿。整个过程每步都可见我可以随时介入。5.3 第三阶段自审和合入前检查代码写完后我让它“使用 code review 技能自审”。它自己发现了三个问题接口返回了订单内部的备注字段可能泄露信息Service 层没有处理用户不存在的情况SQL 的ORDER BY字段没有加索引数据量大时可能慢。这些问题如果靠我自己 review 也能发现但需要仔细读一遍。现在 AI 在合入前就主动提出来我只需要决定哪些当场改、哪些记到技术债里。这个流程走完之后我真正体会到 superpowers 的价值它不是让 AI 更聪明而是让 AI 更有章法。6. 踩坑记录装了 superpowers 以后反而更折腾的三种情况6.1 技能目录路径不匹配AI 根本不理你我最初在 Windows 上用 Git Bash 装软链接命令的写法跟 Linux 不一样结果技能目录没有真正建立。AI 表现得很正常但完全不知道有技能这回事。我排查了大半天最后才发现~/.codex/skills指向的是一个不存在的目标。这里有两条经验。一是安装完不要急着干活先花两分钟验证比如让 AI 列技能。二是如果你对 CLI 的配置目录不确定直接在命令行里执行codex --help或claude --help大部分新版本会显示配置路径。6.2 所有事情都走完整流程小改动反而变慢superpowers 的流程很适合中大型任务但如果每个小改动都要求它“brainstorming→plan→TDD→review”你会觉得 AI 极其啰嗦改个配置项都要先给你写两页计划。我的调整方法是在会话开头约定流程粒度比如“这是一个小改动不需要 planning直接实现但完成后必须自审”或者“这个涉及公共接口变更走完整流程”。把粒度选择权掌握在自己手里而不是让技能文件死板地适用于所有任务。6.3 多个技能文件互相冲突自定义技能多了以后会遇到文件互相打架的情况。比如团队规范里写着“优先使用 Stream API”而另一个重构技能里写着“如果循环可读性更好用循环”AI 可能会在两者之间摇摆。解决思路是给技能文件加优先级说明在自定义技能开头明确写“本规范优先级高于通用 superpowers 技能”。这样 AI 在冲突时知道以哪个为准。如果不加它通常会挑最后读到的那个文件遵循行为不稳定。6.4 关于 WorBuddy 及其他兼容客户端热词里还带了“worbuddy 怎么用 superpowers”。我没法替你确认 WorBuddy 的细节但可以给一个通用判断方法任何客户端只要支持“技能目录/技能系统”安装 superpowers 的思路都是一样的——先找到它读取技能的目录把skills目录链接过去然后在会话里显式要求它读技能文件。如果客户端不支持技能系统也没有关系你仍然可以把技能文件当作提示词模板使用需要哪个流程就把那个SKILL.md的关键段落复制进对话。效果会打折扣但至少能获得流程化的好处。最后分享一个我的个人习惯每次新开项目会话第一句话不是给需求而是“请先查阅技能目录和项目说明文件再开始处理需求”。这一句话多花不了几个 token但往往能避免后面几万 token 的跑偏成本。superpowers 这类技能包真正教会我的不是某个神奇 Prompt而是让 AI 先建立工作框架再开始动手——听起来简单做起来真的能少掉一半的返工。如果你也被“AI 勤快但方向感差”折磨试试把这套技能装进去大概率会打开新世界的大门。