最近在折腾 Codex CLI 的时候，我挖到了一个叫 superpowers 的项目，最初以为只是又一个给 AI 编程工具打补丁的小插件，结果花了一晚上读完文档、配好环境、跑了两个真实项目之后，我发现它改变的是我使用 AI 编程代理的整套方式。如果你手里也在用 Codex 这类终端里的 AI 编程工具，并且经常觉得 AI 写出来的代码“单看没问题、放进项目就变味”，那这篇东西大概率能帮你把工具真正盘活。我会从 superpowers 是什么、为什么值得装、怎么装、怎么写自己的技能包、再到 Java 项目里的实战，一条线讲清楚，最后附上我踩过的坑和排查思路。

先说结论：superpowers 不是某个编程语言框架，也不是代码生成器，它是给 AI 编程代理（比如 Codex CLI）加装“可复用技能”的增强层。打个比方，原版 Codex 像一个专业扎实但没带项目经验的新人，你把需求丢给它，它能把代码写出来，但不知道你们组的代码规范、不知道测试怎么组织、遇到编译错误只会盯着日志发呆。而 superpowers 做的事情，就是把一个“资深工程师的干活习惯”沉淀成 Markdown 格式的技能手册，让 AI 按着手册走流程。这不是给它多装点上下文，而是给它一套完整的工作方法论。

如果你是 AI 编程工具的日常用户、团队的 AI 工程效率负责人，或者单纯对“怎么让 AI 写代码更可控”这件事感兴趣，这篇文章应该能给你一套可以直接抄作业的方案。下面我从设计原理开始拆。

1. 核心设计拆解：superpowers 解决的是“流程缺失”而非“能力缺失”

1.1 为什么 AI 编程代理总在“局部正确、全局翻车”

用 Codex CLI 写过几次真实需求的人应该都有同感：单看它生成的函数，命名规范、注释齐全、边界处理到位，但一旦把它放进整个项目里，问题就来了——它不知道你们的目录规范、不理解现有模块的依赖关系、也不会主动去跑测试给自己“验货”。这不是模型能力不够，而是交互方式有问题。你给它的是一次性提示词，它回你一段一次性代码，两个人之间根本没有“重复使用的合作流程”。

superpowers 的设计出发点就是补上这一环：把 AI 编程代理从一个“问答工具”改造成一个“按流程办事的执行者”。它的核心机制是技能包（Skills），每个技能包是一组 Markdown 文件，以SKILL.md为入口，里面写清楚“什么时候该用这个技能”“使用前要收集哪些信息”“处理流程分几步”“每一步的验收标准是什么”。AI 在运行时会读取这些文件，把自己“代入”到一套标准工作流里。

我在实际使用中的体会是：这相当于给 AI 配了一本“操作手册”。新人入职时你给他讲一遍业务、丢给他几个需求文档，他能干，但经常干得歪歪扭扭；可你要是把团队规范、典型任务的执行步骤都写成文档，他照着做，质量立刻稳定一个档次。superpowers 就是把这种“文档化团队经验”的做法搬到了 AI 代理身上。

1.2 为什么用 Markdown 而不是写死在代码里

我第一次看到技能包全是.md文件时也愣了一下：不该是 JSON 配置或者 Python 脚本吗？后来细想才发现这是最合理的设计。

第一，Markdown 是人类可读、AI 也读得最稳的格式。模型对自然语言的指令理解远好于对复杂 JSON 结构的关系推断，与其让 AI 去“解析配置”，不如直接让它“读手册”。第二，修改技能不需要改代码、不需要重新构建、更不需要升级主程序，编辑一个文本文件就能让 AI 的行为发生改变，迭代成本极低。第三，技能包天然适合 Git 管理，团队的技能沉淀可以像代码一样评审、分支、回滚，这点对企业落地太重要了。

另外，superpowers 把技能包组织成了三层结构：skills/存放通用小型技能（比如“写提交信息”“做代码审查”），agents/存放完整的代理角色定义（每个 agent 可以带一组技能，面向完整任务），commands/存放斜杠命令（Slash Commands），让你在 Codex CLI 里直接通过/skill-name触发特定流程。这个分层本质上是把“经验”按粒度拆开：小技能是积木，agent 是组装好的机器人，命令是遥控器。

1.3 渐进式披露：避免“一口气碾压上下文”

superpowers 还有一个很关键的机制叫渐进式披露（Progressive Disclosure）。简单说，AI 一开始不会把整本手册全部塞进上下文，而是先读取SKILL.md这个入口文件，了解技能概览；需要执行具体步骤时，再去读对应章节的详细文件。这样做的好处有两个：一是节省 Token，二是不让 AI 被海量信息干扰，保持对核心任务的专注度。

这个设计思路我特别认可。在我的使用经验里，一次性给 Codex 几千行项目文档，它反而会“看花了眼”——重点信息被淹没，指令权重被稀释。渐进式披露相当于给 AI 一个“先看目录、再看正文”的阅读路径，信息是按需加载的，不是一锅端。

2. 安装与基础配置：从零把 superpowers 跑起来

2.1 环境准备：先确认你的底子

在动手安装之前，先确认你的机器满足这几个条件，缺一个后面都会卡住。

• 系统：macOS、Linux、Windows（通过 WSL）都行，我是在 macOS 13 上跑的，流程最顺。
• Codex CLI：superpowers 主要面向 Codex CLI 这类 AI 编程代理，确保你已经装好并能正常使用。安装命令一般是npm install -g @openai/codex，装完先跑一次codex确认能正常对话。
• Node.js 18+：Codex CLI 依赖 Node 环境，版本太低会被拒。
• Git：拉取技能包仓库要用到。

提示：如果你日常用的是其他支持技能包机制的 AI 编程工具（部分开源代理也兼容类似格式），思路完全一样，只是配置文件位置略有差异。本文以 Codex CLI 为主。

2.2 拉取技能包仓库

官方技能包集合是直接以 Git 仓库形式分发的。我用的典型流程是：

# 找个干净目录存放技能包 mkdir -p ~/.codex/skills cd ~/.codex/skills # 克隆官方技能包仓库 git clone https://github.com/worksolutions/superpowers.git

仓库克隆下来之后，你会看到里面有skills/、agents/、commands/三个主要目录。先别急着改东西，进去把结构浏览一遍，心里有个数。

装好之后还需要让 Codex CLI 知道“去哪里找技能包”。这一步以 Codex 的配置文件为准，通常是在~/.codex/config.toml里添加技能包路径，或者在 Codex CLI 的启动参数里指定。如果你用的是默认配置，可以在config.toml中加入：

[experimental] skills_path = "/Users/你的用户名/.codex/skills/superpowers"

注意这里的路径一定要写成绝对路径，用~有时候解析不到。配置完重启 Codex CLI，技能包机制就会加载。

2.3 验证是否生效

怎么确认技能包被成功加载了？最简单的方式是在 Codex CLI 里输入斜杠命令，比如：

/superpowers

如果能看到技能列表输出，就说明加载成功。此时让它做一个简单任务，比如用 /delegate 技能帮我列出当前目录的 git 状态，观察它是否先输出“正在读取技能包…”之类的中间过程，如果是，说明它已经进入“按技能干活”的模式。

我在这一步遇到过一个问题：技能列表能看到，但实际调用不生效。后来排查发现是路径写错了——我复制文档时带了一个尾随空格，解析直接失败。所以配置路径时务必检查空格和大小写。

3. 核心实操：编写你自己的技能包

3.1 SKILL.md 的结构：YAML 头 + Markdown 正文

学习 superpowers 的最好方式不是读教程，而是拆一个现成的技能包看结构。我拆解了仓库里的code-review技能，它的SKILL.md长这样：

--- name: code-review description: 对代码变更进行系统性审查，发现逻辑错误、安全隐患和风格问题。适用于 merge request 或 push 前。 --- # Code Review 技能 ## 触发场景 - 用户要求“审查代码”“看看这次改动有没有问题” - 提交前需要自我检查 ## 前置信息 - 需要审查的代码范围（diff 或文件列表） ## 执行步骤 1. 获取变更文件列表 2. 逐个文件阅读差异，记录疑点 3. 分类汇总：逻辑错误 / 安全隐患 / 风格问题 4. 输出结构化审查报告

这个结构是最小可用的模板。YAML 头里的name是技能的唯一标识，description是给 AI 看的“何时该用这个技能”的说明——description 写得好不好，直接决定 AI 会不会在恰当的时候主动调用它。我后来在写技能时常犯的毛病是 description 写得太泛，比如“这个技能用于代码审查”，AI 判断不了什么场景该触发，使用率就很低。改成“适用于 merge request 前或 push 前”之后，调用率明显提升。

3.2 技能的设计原则：小而专、可验证

我自己写技能包踩过几个坑，总结出三条经验。

第一，技能粒度要小。一个技能只做一件事。比如“生成提交信息”是一个技能，“完成整个功能开发”就不应该是一个技能，而应该是一个 agent 编排多个技能。技能太大，AI 的注意力会被拆散，执行效果反而差。

第二，步骤必须可验证。每步最好都有明确的产出或检查动作，比如“运行构建命令并确认返回码为 0”“查看日志确认无 ERROR 级别输出”。AI 代理和真人一样，没有验收标准的步骤它会敷衍过去。

第三，使用前置信息显式列出。在 SKILL.md 里写清楚“开始前需要知道什么”，这能避免 AI 在信息不足时强行开干。比如写“升级依赖”技能，前置信息必须包括“当前依赖版本”“目标版本”“是否有锁文件”，AI 就会先去收集齐这些再动手。

3.3 用 Agents 组合多技能，完成复杂任务

单个技能解决的是单点问题，真实开发里你需要的往往是“一个完整功能的交付”：设计技术方案、写代码、补测试、跑构建、写提交信息、更新文档。superpowers 的 agent 机制就是干这个的。

我自建了一个feature-developeragent，它绑定了 6 个技能：analyze-existing-code（理解现有代码）、design-approach（设计方案）、implement-changes（实现）、run-tests（跑测试）、write-commit-message（生成提交信息）、update-docs（更新文档）。我还给它配了一个专门的AGENTS.md，里面写了这个 agent 的“人设”：比如“每一步必须跑测试，不通过不能进行下一步”“变更范围超过 5 个文件时必须先跟你确认”。

在我实际跑一个“给项目加缓存层”的任务时，这个 agent 的行为和默认 Codex 完全不同：它先分析了现有数据访问层，然后主动给出了缓存方案让我确认，确认后才动代码，写完自动跑了原有测试来验证不破坏功能，最后生成的提交信息把改动原因写得清清楚楚。整个过程我只参与了三次确认，这在以前不可能——默认的 Codex 会直接上手改代码，改完也不测试，等你自己发现。

注意：agent 不是用得越多越好。任务简单时，直接交互反而更快。agent 适合那些流程固定、需要多步骤协作的重复性任务。判断标准很简单：如果一件事你每次都要跟 AI 说同样的步骤，那就应该做成 agent。

4. Java 项目实战：用 superpowers 做“分析—改进—验证”闭环

4.1 定义目标：让 AI 对遗留代码做结构性改进

看到热搜里有人问 superpowers 在 Java 场景怎么用，我专门拿一个遗留 Spring Boot 项目试了一轮。场景是这样：项目里有一个老旧的OrderService，核心业务逻辑全堆在一个 800 行的方法里，测试覆盖几乎没有。我的目标是让 AI 帮我梳理逻辑、拆出独立方法并提出改进建议——注意，我没让它直接改，先让它分析和建议。

我预先准备了一个java-refactor技能包，包含三类技能：analyze-java-structure、design-refactor-plan、apply-refactor。每个技能的SKILL.md都写了详细的执行步骤和验收标准。

实际操作时，我在 Codex CLI 里启动该 agent，让它执行analyze-java-structure，它先是读取了pom.xml确认项目依赖，然后用find定位相关源码，再用grep找出方法内的关键业务分支。最让我意外的是，它不止分析了单个类，还自动追踪了调用方和依赖服务，输出的分析报告里画出了方法调用的依赖链（用文字描述），这比我手动梳理还仔细。

4.2 Java 技能包的编写要点：编译器和测试就是最好的验收标准

Java 项目相比前端项目有个天然优势：有编译器兜底、有成熟的测试框架。所以在编写 Java 相关技能时，我把“跑编译”和“跑测试”作为硬性验收门槛。比如apply-refactor技能的执行步骤里，我明确要求每完成一步重构，必须立刻运行mvn -q compile，有编译错误就必须回退到上一个状态重新思考；所有重构结束后，必须跑一遍完整的mvn test，保证原有功能不回退。

这里有个值得分享的细节：让 AI 分步执行编译验证，而不是全部改完再编译。AI 改完一个方法后立刻编译，错误定位准确、修复成本低；如果让它一口气重构五个方法再编译，报错时它要面对的是“哪个改动引入了问题”的定位难题，很容易陷入反复试错。

实际效果如何？AI 最后把那个 800 行的方法拆成了 7 个私有方法，每个都有清晰的单一职责，并且生成了 4 个针对核心分支的单元测试。中间我唯一一次人工介入，是它设计的分拆方案里把两个原本共享局部变量的逻辑段拆得太碎，破坏了原有的事务边界——这种业务语义层面的判断，AI 在没有充分领域知识时确实容易想当然。所以 Java 场景里尤其建议：先让它出方案，你确认边界，再放它改。

4.3 复合技能：把常规流程固化成可复用资产

做完这次实战之后，我把整套流程固化成了一个java-feature-deliveryagent：分析现有代码 → 输出设计方案 → 确认 → 实现 → 编译 → 补测试 → 全量验证 → 生成提交信息。现在但凡要在这个项目里加新功能，我直接调用它，它自己就按这个流程走，不需要我重复交代。

这里建议你把团队常用的开发流程也做成技能包沉淀到 Git 仓库里。比如“接入新的第三方 API”的流程、“修复线上 Bug”的排查路径、“数据库迁移脚本的编写规范”——每一类重复劳动都值得固化成技能。技能不是一次性的提示词模板，它是会随着项目经验迭代的资产，越用越值钱。

5. 常见问题与排查技巧实录

5.1 常见问题速查表

5.2 我认为最值得记住的排查思路

遇到 AI 行为不符合预期时，先别急着改代码或者重装工具，第一件事是打开它实际读到的技能内容看一眼——你可以让它直接输出“你当前的技能包内容是什么”，通常能立刻发现它读错文件、路径拼接错误、或者读到了缓存的旧版本技能。

另外，我给所有技能目录都加了CHANGELOG.md，每次修改技能都会记录日期和改动原因。听起来麻烦，但对排查特别有用——当项目行为突然变化时，回看技能变更记录，经常能一秒定位问题。如果你和团队成员共享技能包仓库，这个习惯还能避免“有人偷偷改了技能导致全员行为变化”的混乱。

提示：技能包是活的，随项目演进要持续维护。一个半年没更新过的技能包，很可能已经在拖 AI 的后腿了。每个迭代周期花一点时间审查技能是否还符合当前项目状态，收益远超成本。

6. 从工具到方法论：让 AI 编程代理真正“懂规矩”

我在实际使用 superpowers 这段时间，最大的感触是：它没有给 AI 增加任何“新能力”，但让 AI 的每一次输出都变得更可控、更可预期。技术原理拆开讲并不复杂——把人的经验结构化、文档化，然后让模型像读操作手册一样去执行。这套思路价值很大，因为技能包一旦沉淀下来，就是团队集体智慧的结晶，不依赖某一个工程师的记忆，也不会在人员流动时流失。

如果你现在正用着 Codex CLI 或者类似的 AI 编程代理，我强烈建议你从克隆官方技能包开始，先跑通一遍，然后试着把你自己最常做的一件事写成技能。不用一开始就搞复杂的 agent，一个简单的SKILL.md就能让你体会到“AI 按规矩办事”和“AI 自由发挥”之间的区别。

最后再分享一个小技巧：给你的技能包写README.md，里面记录这个技能包解决的问题、使用场景和常见误区。这不是写给别人看的，是写给三个月后的自己看的。技能包数量一多，没有导航文档的情况下，连你自己都会忘记里面装了些什么。