1. 什么是 superpowers它到底解决什么问题先说结论如果你在用 Codex CLI 这类终端里的 AI 编程 Agent发现它“能写代码但不会干活”——单文件补丁没问题跨模块改功能就手忙脚乱还总记不住项目里约定俗成的写法那 superpowers 大概率就是你缺的那一层。我最初接触 Codex CLI 的时候感受是“什么都能聊但什么都浅”。让它修个 bug 还能应付让它按团队规范走完整的 TDD 流程、同时维护设计文档、再跑回归测试它就完全没章法了。原因不难理解Codex 默认的工作模式偏“对话驱动的补丁生成”它对当前对话上下文敏感可对长期项目结构、行业惯例、工具链约定几乎没有记忆。每次开启新会话它都会退化成一个“懂很多但什么都不了解你的项目”的外来人员。superpowers 这类东西本质上是一套给 AI Agent 用的配置和技能框架。它不是模型不重新训练任何参数也不替代 Codex CLI 本身。它提供的是一组明确的行为指令、可复用的技能脚本、以及按项目或全局生效的上下文文件让同一个模型在你的终端里表现出完全不同的工作水准。说白了就是把“提示词工程”从对话里抽出来做成了工程化的、可版本管理的文件体系。这类框架在圈子里有各种名字有叫 skills 库的有叫 command 集合的有叫 agent rules 的。superpowers 的特点是把这套东西做得比较彻底它不只给你一两个命令示例而是搭了一套分层结构全局的基础能力、项目级的领域约束、语言级的语法规则全部拆开可以单独启用或覆盖。配合 Codex CLI 的 flexible mode 和自定义 slash command一套配置下来你会明显感觉到 Agent 变得像“一个熟悉这个仓库的老同事”而不是“一个每次都要重新认识项目的实习生”。这篇文章从我的实际使用经验出发讲清楚 superpowers 的安装、结构、定制方式、常见坑以及怎么让它服务于 Java 这类强规范的工程场景。后面的内容全部是可复现的操作不是概念介绍。2. 安装之前你需要明确的三个前提2.1 本机环境与前置工具superpowers 本身不复杂但它依赖的底座比较多前置装不对后面所有步骤都会连锁出问题。一个可以正常运行 AI Agent 的 CLI 工具我这边用的是 Codex CLI安装方式是用 npm 全局装。Node.js 版本建议 18 以上因为这堆配置脚本大多用 JavaScript 写而且新版 Codex CLI 对 Node 版本有明确要求。Git 必须可用因为技能库的版本管理和更新依赖 git。编辑器方面VS Code 或 JetBrains 系都可以看你日常习惯。但我建议至少在初始阶段让终端保持干净不要引入太多插件变量方便排查问题。这个组合不是我拍脑袋定的。Node.js 是 Codex CLI 的运行时基础Git 是做技能配置版本管理的唯一可靠方案编辑器的选择则决定了你在哪些环节能可视化地看到 Agent 的行为日志。三个前置都到位后面装什么东西都顺畅。2.2 为什么推荐先在全局层面安装而不是项目级很多教程一上来就让你往项目里塞 AGENTS.md 和 skills 目录我强烈不建议这么做。全局安装的逻辑和“先装操作系统再装软件”一样。superpowers 的基础技能里有很多是与具体项目无关的通用能力比如规范的 git commit 信息生成、自动化单元测试的骨架搭建、代码重构步骤的标准化流程。这些能力应该放在用户级别的作用域下让所有项目都能继承。项目级配置的职责是“覆盖”和“补充”而不是“从零搭建”。你总不想每拉一个新仓库就把整套技能复制一遍也不能接受不同项目里 Agent 的行为习惯五花八门。先全局安装项目内做的只是引用和微调这才是可维护的做法。2.3 说清楚它对 Codex CLI 做了什么、没做什么我得把边界讲清楚免得有人期望过高。superpowers 没有“增强模型智能”这种魔法。它做的三件事很朴素第一把任务拆解的思考过程固化在指令文件里让 Agent 每次动手前都按固定框架分析第二把高频操作的完整步骤做成可复用的命令比如“给这个模块补测试全覆盖”就是一条命令第三把项目上下文、技术栈约束、代码风格偏好集中管理让 Agent 在不同会话之间保持一致性。模型本身的逻辑推理能力不会因为装了这套东西就提升但你给它的“工作环境”变得更完整了它的输出下限会明显抬高。对我这种靠 Agent 处理大量重复模式的开发场景来说下限比上限重要得多。3. 完整安装步骤与初始化配置3.1 安装 Codex CLI 与准备目录结构如果你还没装 Codex CLI打开终端直接执行npm install -g openai/codex codex --version这一步正常的话你会看到版本号输出。然后确认配置文件目录存在ls ~/.codex默认情况下Codex CLI 的全局配置目录就在用户主目录下的 .codex 文件夹里。如果看不到这个目录就先执行一次codex login让它自动创建。接着把 superpowers 克隆到本地git clone https://github.com/your-source/superpowers.git ~/.superpowers这里的路径你可以自行调整但后面配置里会用到建议保持稳定。我见过有人把技能库放到项目目录内结果切项目就忘非常不建议。3.2 初始化核心配置文件superpowers 初始化最关键的一步是生成一份全局的 AGENTS.md 文件到 Codex CLI 的配置目录里。这个文件相当于 Agent 的“岗位说明书”它定义了基础工作准则比如“在不清楚需求时先提问不要猜”、“改完代码必须跑干净测试”、“提交说明按约定格式输出”。我在安装后的第一件事就是把这份全局 AGENTS.md 手工读一遍而不是直接信任模板。因为这份文件直接决定了 Agent 后续所有行为模板里的任何一条规则你不同意都要在初始化之后立刻改掉。否则你会在未来某一天发现 Agent 按照某个你并不认可的规范工作而这规范源头就是这份被忽略的文件。配置完成后验证一下codex --help如果你的版本支持 custom commandshelp 输出里会看到相关说明。然后随便跑一次codex exec 列出当前目录结构确认 Agent 能正常响应同时观察它是否加载了全局配置文件。这一步没有报错说明底座通了。3.3 在项目中启用 superpowers 的最小步骤项目级启用不需要复制整个技能库通常只需要两样东西。第一在项目根目录放一份精简的 AGENTS.md开头用引用句或明确声明导入全局技能规则。第二建立你自己的 skills 目录存放项目特有的技能文件。这个目录的结构我下一节展开讲这里先说明为什么需要它全局技能是“通识”项目技能才是“私教”。比如你在一个 Java Spring Boot 仓库里全局技能负责“怎么写规范的 commit message”项目技能负责“新增一个带完整测试的 REST 接口应该按什么步骤走”。后者在不同项目里差异极大没道理放在全局。我自己的做法是初始化之后先做一次“空跑验证”选一个很小的重构任务让 Agent 独立完成然后检查它的执行轨迹。如果它表现出的行为模式和你期望的一致说明配置生效了如果不一致优先检查 AGENTS.md 是否被正确加载而不是急着加更多指令。4. superpowers 的原理拆解AGENTS.md、技能文件与 slash command4.1 AGENTS.md 的分层设计与行为约束机制AGENTS.md 是一种事实上的 Agent 指令标准。它不是 superpowers 发明的但 superpowers 把它的用法推到了更细的粒度。在我的配置里全局 AGENTS.md 至少覆盖五类内容基础行为准则、代码风格偏好、工具使用约定、任务拆解框架、以及错误恢复策略。项目级 AGENTS.md 则更聚焦通常包含技术栈清单、目录结构说明、常用命令表、以及团队特有的代码规范。关键点是层级之间的覆盖关系。全局说“所有提交信息必须遵循 Conventional Commits”项目级如果没写就按全局规则执行项目级如果额外声明“commit 的 scope 必须包含模块名”那它会在全局规则之上叠加约束。这种精细的覆盖机制靠纯对话提示词是实现不了的因为提示词在每次会话里都会被遗忘而 AGENTS.md 是每次会话都被加载的固定上下文。4.2 技能文件的结构前置检查、执行步骤、后置验收superpowers 的核心资产是技能文件。一个技能文件不是简单的“指令提示词”它是一份结构化的操作流程通常包括三个部分。前置检查记录执行前必须确认的信息当前分支是否干净、相关测试基线是否通过、依赖是否安装完整。执行步骤定义按顺序要做的操作每步尽可能具体。后置验收则列出任务完成前必须满足的条件测试覆盖率数字是否达标、代码格式检查是否通过、有没有留下未清理的临时文件。这三个部分的价值在于它们把一个模糊的指令“帮忙加个配置项”变成了一条可执行的流水线。Agent 在动手之前先检查前置条件执行中按步骤推进完成后自我验收。这比单纯告诉它“好好干”靠谱得多因为“好好干”没有验收标准。我给这套结构做个类比普通提示词是请了个自由职业者你说了需求他自由发挥技能文件是给了这个自由职业者一份详细的项目章程、检查表、验收清单。同样的能力流程化管理之后产出稳定性天差地别。4.3 自定义命令的注册与调用如果你用过 Codex CLI 的 flexible mode你就知道 slash command 是它的核心交互方式。superpowers 的很多能力都封装成自定义命令注册方式是在配置目录里放置对应的命令描述文件。比如我注册过一条review命令效果是让 Agent 按我的代码审查清单逐项检查本次改动输出表格化的问题列表并对每个问题给出严重级别和建议修改方式。注册后在终端里敲/review就能触发不再需要输入任何复杂的提示词。slash command 的好处是“固定入口可变参数”。固定入口降低了记忆成本你不需要记住那条又长又绕的提示词可变参数则保留灵活性你可以让命令接收具体文件名、模块路径等参数。不过这里有个容易踩的坑如果你在多个项目之间切换项目级注册的命令不会自动出现在全局命令列表里。Codex CLI 的默认行为里项目级命令需要你在项目目录内才会被识别。这个问题排错了很久才搞清楚后面常见问题里会详细说。4.4 为什么说它是“给 Agent 建肌肉记忆”我用了大半年的心得就一句话superpowers 的本质是在给 Agent 建肌肉记忆。模型从训练角度讲是“无记忆”的每一次对话都是从零开始。但当你把高频操作固化成技能文件把项目规范沉淀在 AGENTS.md 里把常用工作流封装成 slash commandAgent 的每一次启动都不再是“重新认识世界”而是“加载好的一套工作习惯”。这套工作习惯就是它的肌肉记忆。肌肉记忆的建立是有成本的维护成本和收益。你写一个高质量技能文件花半小时未来每一次触发这个技能都省掉十五分钟重复引导的时间。技能库积累到一定数量后这种时间回报是指数级的。5. 让 superpowers 在 Java 工程里发挥价值5.1 先想清楚 Java 场景的特殊诉求如果你是 Java 开发者没有比这更吃上下文的技术栈了。Java 工程的痛点很集中模块边界清晰但依赖关系复杂、构建工具链相对固定但配置繁琐、测试框架统一但编写模板代码量大。通用技能当然能覆盖一部分场景比如“先生成测试再实现功能”的 TDD 流程但 Java 场景还需要更细颗粒度的支撑。比如 Spring Boot 项目里新加一个接口需要同步写 Controller、Service、Repository、DTO、异常处理、单元测试、集成测试哪个文件落到哪个包下都有强约定。这对 Agent 来说是巨大的上下文负担你不可能每次都在对话里把这些约定描述一遍。superpowers 的解法是把这些约定写在项目级技能文件里让 Agent 每次执行“新增接口”这类任务时自动加载。5.2 定制一个 Java 技能文件的完整示例以“新增 REST 接口”为例我写了一个名为add-rest-endpoint的技能文件内容包括以下步骤。第一步是确认当前模块的包路径读取现有 Controller 的代码风格确定返回类型是 ResponseEntity 还是自定义 Result 封装。第二步是列出这个接口需要触达的 Service 方法是否存在不存在就先定义接口和实现。第三步是补测试单元测试覆盖 Service 层的业务逻辑集成测试覆盖 Controller 层的路由和序列化。第四步是运行该模块的 Maven 测试命令确认全绿后给出提交说明模板。这个技能文件写完后我在对话里输入“给用户模块新增一个改昵称的接口”Agent 会自动触发这个流程完全不靠我额外解释任何项目约定。结果可能是它生成的代码并非完美无缺但结构和步骤永远是对的差别只在我做 review 时修多少细节。5.3 Java 项目里我实际用的三个高频命令除了上面的接口技能我还有三个高频命令。/run-mvn-tests它不只是执行测试命令而是先检查 maven wrapper 是否存在再用正确的方式触发指定模块的测试最后把失败用例按包名分组输出。/generate-repository是数据访问层的生成器它读取实体类定义按项目里的持久层框架生成对应 Repository 接口和基础查询方法。/refactor-module是用来处理重构任务的核心是让 Agent 先列出受影响的调用方、再逐层修改、最后跑全量回归。这三个命令解决的是 Java 开发里出现频率最高的三类需求。它们的共同特点是任务步骤明确、验收标准清晰、重复度高。正因如此它们才值得被固化成技能而不是每次重新向 Agent 解释一遍。5.4 多语言混用项目里的技能切换策略实际项目里很少是纯 Java。前端 TypeScript、基础设施的 shell 脚本、数据同步的 Python 任务各占一部分。如果全局技能只针对 Java 定制那 Agent 在处理前端代码时就会表现平庸。我的经验是在项目级 AGENTS.md 里明确声明“本仓库前端使用 TypeScript Vue后端使用 Java 17 Spring Boot脚本使用 Python 3.10”然后在 skills 目录下按技术栈分子目录。比如skills/java/下面放 Java 相关技能skills/ts/下面放前端技能。这样 Agent 在读取文件时能按目录结构快速定位适用规则不会出现用 Java 的规范去审查 TypeScript 代码这种错位。这个“按栈隔离”的策略在混合仓库里非常管用。它避免了全局技能文件越长越臃肿、最后失去约束力的窘境。6. 日常使用的工作流与配合技巧6.1 任务启动前的高效引导模板superpowers 不是万能的它给你提供了完整的能力框架但每次任务的第一步引导质量仍然决定后续走向。我存了一套自己打磨过的任务引导模板核心结构是任务目标一句话明确约束条件比如“不改动公共接口签名”“不引入新的第三方依赖”指定影响范围比如“只涉及 user 模块其他模块不允许修改”给出验收标准比如“所有测试必须通过且新增用例覆盖分支”。这套模板我在每个项目里都放了一份叫task-brief.md任务开始前把内容填充好丢给 Agent。这么做表面看多了几步实际上让后续交互时间直接砍半。你要理解一个原则Agent 在信息不足时的默认行为是猜测你给它的上下文越精确它的输出就越接近可交付状态。6.2 如何把 superpowers 和 WorBuddy 这类工具配合使用有人问过 WorBuddy 这类工具和 superpowers 是什么关系。我的理解是WorBuddy 这类偏任务编排的工管工具负责的是流程视图它管的是“我们要做哪些任务、任务的依赖关系是什么、谁负责什么”而 superpowers 解决的是“具体一个任务进来之后Agent 应该怎么高质量完成”。这两者天然互补。在我的工作流里WorBuddy 层面定义里程碑和任务看板每个任务分配到人或者分配到 Agent。当任务真正落到 Agent 执行时superpowers 的技能库和全局指令就发挥作用。你可以说 WorBuddy 是“调度层”superpowers 是“执行层”两者配合之后管理者和执行者都不迷茫。6.3 会话中途切换项目上下文的方法实际开发里经常遇到的情况是同一个终端会话里先改完 Java 后端马上又要处理前端问题。如果你不告诉 Agent 上下文已经切换它极大概率还在用后端的项目管理规范来写前端代码。我的做法是在项目根目录建一个.context文件里面只写三行当前项目名称、技术栈摘要、生效的规范文件路径。每次切换到当前目录时我会先让 Agent 读这个文件再开始新任务。这个小动作比在对话里反复解释“现在是前端项目”可靠得多因为文件是持久化的Agent 每次都读到同一份说明。6.4 团队协作时如何统一技能库版本如果你和团队一起用这套框架最大的问题一定是版本不统一。你更新了技能文件同事还在用老版Agent 在两个人手里表现完全不一样review 代码的时候冲突不断。解法不复杂技能库用 git 管理团队内部维护一个稳定的主分支每次改动走 merge request合并后所有人各自拉取。CI 环节加一个检查脚本跑一遍技能库里的语法校验和目录结构完整性检查避免有人把技能文件格式写错推上来影响所有人。我建议每个团队指定一个人当技能库的“维护者”专门负责合并请求、解决冲突、更新文档。不是技术难度大而是这件事需要持续的关注度分散给所有人最后就是没人管。7. 常见问题与排查技巧实录7.1 命令被识别但没有任何响应这是最常碰到的问题注册了/review命令输入之后 Agent 像没看到一样既不报错也不执行。排这个问题先确认命令文件的位置对不对。全局命令应该在~/.codex/commands目录项目级命令在.codex/commands目录。很多人直接写在项目根目录下Codex CLI 根本不去那里找。其次要看命令文件的前缀格式通常文件名就是命令名如果文件名带空格或者包含特殊字符解析器会忽略。最后检查命令描述里的触发器参数是否和调用方式匹配比如你定义的时候要求带参数调用时没带Agent 可能直接放弃执行。7.2 AGENTS.md 被修改后不生效还是旧行为这个坑很隐蔽。Codex CLI 对 AGENTS.md 的加载可能带有缓存它不会每次任务都去重新读取文件内容。你修改了规则但 Agent 表现的还是旧规则下的行为很容易让人误以为“改错文件了”。我的经验是修改后开一个新会话验证不要在当前会话里继续测试因为当前会话的上下文已经携带了旧指令。如果新会话里仍然不生效检查文件编码格式有 BOM 头或者非 UTF-8 编码的情况下解析器有可能读取失败但不报错。7.3 技能文件在不同项目间串用技能串用是另一个高频问题尤其在你有多个项目共用全局技能的前提下。你为 A 项目写的接口规范被 Agent 用到了 B 项目的接口评审里结果报告里全是无关建议。根源在于技能文件的匹配机制。Codex CLI 通常根据命令名或文件路径来调用技能但你在对话里描述任务时如果任务描述和多个技能文件都能语义匹配Agent 可能选错。解决办法是项目级命令命名时加上项目前缀比如user-module-add-endpoint同时在 AGENTS.md 里明确说明“当前项目只允许使用带 user 前缀的项目级命令”。7.4 参数传递中的引号与空格问题slash command 的参数解析对特殊字符的容忍度很低。我踩过最深的坑是传文件路径参数时路径里有空格命令被拆成了两段Agent 跑到一半找不到文件。处理方式很简单命令文件里定义参数接收逻辑时显式处理引号包裹。调用侧也养成习惯带空格的参数值一律用双引号包起来。如果你在命令文件里写的是 shell 脚本记得对$*做一层严格解析别直接拼接进后续命令。7.5 快速诊断清单最后给一张排查清单遇到问题时按顺序过一遍大部分问题都能解决。命令文件路径是否位于 Codex CLI 期望的目录下命令文件名是否符合命名规则无空格无特殊字符AGENTS.md 是否采用 UTF-8 无 BOM 编码是否在修改文件后开了一个全新会话命令行参数是否用双引号包裹完整全局技能和项目技能是否存在命名冲突Codex CLI 和 superpowers 版本是否匹配是否都升级到了最新。按这条清单走完还没解决的基本就是技能文件内部的逻辑问题需要你把文件内容逐段读一遍确认流程步骤里没有写死某条并不存在的本地路径。8. 写在最后的一些个人经验用了这么久 superpowers我最直观的感受是它把我从“反复向 Agent 解释我的项目”这件事里解放出来了。以前开个新会话要先花五分钟粘贴项目说明、技术栈、代码规范有时还要附带几条示例代码就为了让它写出风格一致的代码。现在这些信息全部沉淀在配置文件和技能库里一个会话打开Agent 自己就知道该按什么规矩干活。如果你刚开始接触这套东西我的建议很明确先不要贪多不要一次性把所有技能装满。从一条命令开始选择一个你每天都会做的重复任务把它的流程仔细写成一个技能文件用半个月然后评估收益。确认有价值再逐步加第二个、第三个。技能库的核心不是数量是每条技能都能稳定高质量地输出。我见过有人一次性导入了上百个技能结果 Agent 在任务选择上频繁混乱最后退回去只留了十几个精品的反而顺畅。还有一点要分享的这个框架的价值边界很清楚。它优化的是“工具使用方式”不是“决策能力”。当你在做一个业务解决方案的架构决策时superpowers 帮不了你那还是得靠你自己的判断。但当你确定了方案、明确了步骤它能让 Agent 以极高的稳定性和一致性把方案落地成代码这种“执行层面的确定性”对我来说已经值回所有安装成本。最后给个小技巧可以定期翻一下技能库把那些已经很久没被触发过的技能删掉。技能和代码一样不维护就会过期。仓库里的技术栈变了命令变了旧技能描述里的路径全是错的留在那里只会增加 Agent 选择时的噪音。精简过三轮技能库之后我明显感觉触发准确率上了一个台阶。