1. 先搞清楚 superpowers 是什么1.1 AI 编程助手为什么需要“技能”你有没有遇到过这种情况同一个 AI 编码助手在干净的“hello world”项目里表现得像个天才一旦扔进一个带历史包袱的企业级 Java 工程就开始一本正经地胡说八道。它不知道你们的 Maven 仓库有内网镜像不知道代码规范里禁止 Lombok 的Data用在 JPA 实体上更不知道测试运行前要先启动一个特定的 Docker Compose 服务。这些信息不在模型的训练数据里也不在仓库的代码里而是散落在团队成员的脑子里。这就是 AI coding agent 在实际工程环境里的核心痛点它很强但它“不熟”。代码模型背下了全世界的开源代码却背不下你公司内部的构建流程和踩坑记录。早期大家靠什么解决靠在CLAUDE.md、AGENTS.md里写长篇提示词把规则一条条喂给智能体。问题是提示词越写越臃肿而且智能体不是每次都会认真读完。你写了两千字规范它可能只看了前两百字。superpowers 这个项目就是冲这个问题来的。它不是又一个编码助手而是给 Codex、Claude Code、Gemini CLI 这类编码智能体统一提供“技能库”的管理工具。所谓技能就是一组结构化的 Markdown 指令文件里面写明“在什么情况下用什么方法做什么事”然后由 superpowers 帮你安装、更新、组织、注入到智能体的工作流程里。简单说它把“写在提示词里的项目知识”变成了“按需自动加载的即插即用技能”。1.2 项目核心思路与能解决的问题我第一次用 superpowers 的时候脑子里浮现的画面是一个老师傅的抽屉每个抽屉贴着标签里面有对应的操作手册、检查清单、常用脚本。智能体遇到问题打开对应抽屉而不是把所有手册都摆在桌面上读。这正是 superpowers 的设计哲学技能不是一股脑塞进上下文而是由智能体根据任务描述自主判断“我现在需要哪份技能”再按需读取。这样做有几个很实际的好处。第一上下文窗口被节省了智能体不用每次都在几万字的规范里翻找条款它只需要读取当前任务相关的技能文件。第二技能是可复用的同一个“后端代码审查”技能可以同时用于 A 项目和 B 项目不需要在每个仓库里复制粘贴。第三技能是可版本管理的它就是一个普通目录放进 Git团队里所有人都能同步。在这套体系里技能跟插件不是一个东西。插件是改写了工具本身行为的代码技能只是“更聪明的使用说明书”。所以它几乎没有侵入性卸载了 superpowers你的项目代码不会受到任何影响。这一点对很多核心系统特别友好——你不需要让 AI 拿到代码执行权限只需要让它更懂你的工程上下文。2. 安装与初始化从零接上 superpowers2.1 环境准备与安装在动手之前先确认你本地的环境。superpowers 是一个基于 Node.js 的命令行工具所以前提是机器上有 Node.js 环境建议版本在 18 以上。可以用node -v快速确认。没有 Node.js 的话先去官网装一个 LTS 版本这一步没有捷径。安装用的命令是 npm 全局安装以我写这篇博客时的常见发布方式来看入口是 npm 包superpowers。不同版本、不同仓库源的包名可能略有差异有的教程里会看到superpowers/cli这样的写法这属于正常的包名命名差异实际以官方文档为准。我自己执行的是npm install -g superpowers装完之后验证一下superpowers --version如果能看到版本号说明装好了。这里有一个新手很容易踩的坑如果你用 macOS 并且之前装过 Python、Ruby 之类的东西npm 全局目录的权限经常出问题。我在 Linux 服务器和 macOS 上都碰到过EACCES权限报错解决办法是用nvm管理 Node.js而不是用系统自带的 Node这样全局安装目录在你的用户目录下权限清爽很多。2.2 初始化并接入 Codex安装好命令行工具之后接着要在你的项目里初始化 superpowers。进入项目根目录执行cd your-project superpowers init初始化过程会做几件事创建一个.superpowers/目录用来存放技能文件扫描项目当前使用的编码智能体类型自动改写或生成AGENTS.mdCodex 使用的项目级指令文件或者CLAUDE.md在里面写入一段“调用技能”的指引。如果你是 Codex 用户这一步很关键。Codex 官方支持读取仓库根目录的AGENTS.md把它作为项目上下文的强制输入。superpowers init 做的事情本质上就是帮你把“技能库的索引”注入到 Codex 每次启动都会读的这份文件里。之后再运行codex它就已经知道自己旁边有技能库这个东西了。注意有些项目里已经手工维护了一份AGENTS.md初始化前最好先备份。superpowers 在改写文件时通常不会删除你原来的内容而是在末尾追加但我见过某些旧版本处理得比较粗暴所以有备无患。2.3 目录结构说明初始化完成之后你会看到类似这样的结构your-project/ ├── .superpowers/ │ ├── skills/ │ ├── templates/ │ └── config.json ├── AGENTS.md ├── package.json └── ....superpowers/skills/就是技能库的存放位置。每一个技能可以是一个 Markdown 文件也可以是一个目录目录里除了主文件还能附带脚本和资源。config.json记录当前项目的配置比如启用了哪些技能包、自动更新策略之类的。AGENTS.md是被注入的索引文件。我个人的习惯是把这个目录也提交进 Git。有人会觉得项目里的“AI 配置文件”不该进版本库但我的经验相反技能库本质上是团队知识的沉淀是文档的一部分不进 Git 的话每个人本地的技能版本会越来越不一致最后变成“在我机器上是好的”。3. 使用指南技能怎么写、怎么被调用3.1 技能文件的基本格式superpowers 的技能文件不是随便写写就行的它有固定的结构。一个标准的技能文件包含两部分YAML 格式的 frontmatter 元数据以及正文部分。frontmatter 里最重要的两个字段是name和description。--- name: java-build-debug description: 分析 Java Maven 项目构建失败的原因包括依赖冲突、编译器错误、测试失败三类常见场景。 when_to_use: 当 Maven 构建失败、编译报错、测试不过且需要诊断根因时使用。 ---重点说说description字段。这个字段是智能体判断“要不要使用该技能”的唯一依据写得好不好直接影响技能能不能被正确触发。你要是写成“这个技能用于 Java”那等于没写智能体在任何 Java 任务里都可能去加载它浪费 token 不说还可能因为内容不匹配而误判。我的建议是描述里至少包含三层信息适用场景、技术栈、具体触发条件。参考上面的例子“Maven 构建失败”是场景“依赖冲突、编译器错误、测试失败”是具体信号“诊断根因”是任务目标。正文部分就是技能的主体内容通常包括操作步骤、注意事项、检查清单。和普通文档不同技能文件更接近“标准操作流程”语言要指令化少废话。比如你可以写“先执行mvn dependency:tree -Dverbose检查依赖树再根据冲突报错定位 pom.xml 中的排除项”而不是写一大堆“依赖管理是 Maven 的核心功能之一”。3.2 写一个 Java 技能实例光说格式不够直观我这里给一个完整的、可以直接抄的 Java 技能示例。这个技能解决的是“Java 项目代码审查”问题——我实际在团队里就是靠它统一了 Codex 做 code review 时的关注点。--- name: java-code-review description: 对 Java 代码进行审查重点检查空指针风险、并发安全问题、资源泄漏、异常被吞、SQL 注入隐患。 when_to_use: 当用户要求审查 Java 代码、提交 merge request 前检查、或者询问某段代码是否存在隐患时使用。 --- # Java 代码审查技能 ## 审查范围 1. 空指针风险检查所有链式调用、Optional 的 orElseGet/orElse 使用、方法入参是否可能为 null。 2. 并发安全检查共享变量是否有 volatile 或 synchronized 保护线程池使用是否规范是否使用 ConcurrentHashMap 代替 HashMap。 3. 资源泄漏检查 InputStream、Connection、Statement 是否在 finally 或 try-with-resources 中关闭。 4. 异常处理检查 catch 块是否吞掉异常是否打印了足够上下文的日志是否抛出了可读性强的业务异常。 5. 安全性检查字符串拼接 SQL、反射调用、不安全的反序列化。 ## 审查输出格式 对每个问题按以下格式输出 - 文件位置 - 问题类型严重/建议 - 问题描述 - 修改建议 ## 禁止事项 不要为了建议而建议不要修改和当前任务无关的代码格式。你可能会问这跟手工在 Codex 的提示词里写一段“请按以下规范审查”有什么区别区别在于触发机制。提示词需要你每次重复技能是靠description自动匹配的。你只要说一句“帮我把改动 review 一下”Codex 读到任务描述里有 review、Java 这些词就会主动去加载这个技能文件不需要你再贴一遍规则。一次编写所有后续会话持续生效。3.3 技能调用机制剖析这背后究竟发生了什么我一开始也觉得神奇后来扒了一下实现思路才弄明白。superpowers 本质上是给编码智能体提供了一个“按需阅读索引”。它在AGENTS.md里写入的指引大致意思是当接收到任务时先检查.superpowers/skills/目录下有哪些技能文件。阅读技能文件 frontmatter 里的name和description判断是否与当前任务相关。如果相关读取该技能文件正文并严格按正文指示工作。如果多个技能都相关按任务的主次顺序加载。这个机制生效的前提是智能体本身具备“工具调用”或“迭代式阅读文件”的能力。Codex、Claude Code 这类智能体在执行任务时天然会去读项目里的说明文件superpowers 只是在说明文件里精确地埋了“钩子”告诉它往哪里翻。所以它不是一个后台守护进程也不是魔法。它的高明之处在于极其克制不抢智能体的执行权只负责把知识和规则整理到“伸手就能够到”的位置。实操心得技能文件不要让智能体一次性全读。我见过有人在一个技能文件里写了三千行结果智能体读取大量内容后反而忽略关键技术点。一个技能解决一件事每个文件控制在 100 行上下效果是最好的。复杂问题拆分技能包比如 Java 的审查、构建、测试分成三个独立技能。4. Java 项目实战用 superpowers 管好构建和测试4.1 实战前的 Java 项目准备前面讲了通用用法这一节我拿一个真实场景——Java 单体应用项目——来完整演示一遍。我手头有一个 Spring Boot 项目Maven 构建模块化结构测试分单元测试和集成测试两层。在这个项目里AI 编码助手以前的表现不太稳定主要是三个问题不知道集成测试需要先启动 Testcontainers遇到 Maven 依赖冲突时只会建议升级版本不会分析依赖树写单元测试时经常写出依赖 Spring 上下文的“伪单元测试”跑一次要十秒。接入 superpowers 之前我在AGENTS.md里写过一大段项目规范但效果一般。后来我把这些规范全部改成了技能文件每个问题一个独立技能。这里要说明一下改造不是把原来的文档拆开就算完而是要站在“智能体会怎么触发”的角度重新组织内容。4.2 设计一组 Java 技能包我最终给这个项目设计了四个技能放在.superpowers/skills/下技能文件用途触发标志maven-dependency-fix.md分析依赖冲突、版本仲裁问题“依赖冲突”“mvn 报错”“dependency”spring-test-guideline.md规范单元测试与集成测试的边界“写测试”“测试不过”“JUnit”testcontainers-setup.md启动和管理集成测试容器“集成测试”“Testcontainers”java-code-review.md代码审查“review”“审查”“检查代码”这里最值得聊的是spring-test-guideline.md里面的一条规则。之前智能体写测试经常直接SpringBootTest一把梭启动整个应用上下文慢得要命。我在技能文件里明确写了触发条件## 测试类型选择 - 如果测试只涉及一个 Service 类优先使用 Mockito 直接 mock 依赖不要启动 Spring 上下文。 - 如果必须校验 MyBatis 映射或 JPA 查询再使用 MybatisTest 或 DataJpaTest 切片测试。 - 只有完整的接口/集成测试才允许使用 SpringBootTest且必须配合 Testcontainers。这条规则写成技能之后Codex 写出的测试文件风格明显变了。倒不是它忽然变聪明了而是因为技能文件把“什么场景用什么策略”写成了明确的决策树智能体只需要照着选项走。Maven 依赖冲突那个技能我写得最简单核心就是先执行诊断命令再根据输出决定处理方式mvn dependency:tree -Dverbose mvn dependency:analyze这个动作本身不复杂但很能说明问题智能体在遇到依赖冲突时默认行为往往是去 Maven 中央仓库找“最新版本”然后升级。有了技能文件它才会意识到先看依赖树、确认冲突来源再用排除依赖或者调整 import 顺序来解决问题。行为路径变了结果完全不一样。4.3 实战效果与我的体感跑了两周之后这个项目里 Codex 的表现变化我觉得是质变。以前提交代码前让 AI 做一轮 review它的关注点经常漂移喜欢挑代码风格、变量命名的毛病对真正的风险点——比如一个catch (Exception e)把异常吞了的隐患——反而视而不见。有了java-code-review技能之后它的检查顺序稳定下来了先看空指针、再检查资源释放、最后才看安全漏洞确实像“见过世面的老手”。另一个体感是在上下文占用上。以前为了让 AI 遵守项目规范我在提示词里夹带各种约束一次会话要多花好几千 token。技能机制是“用到才读”大部分会话它根本不加载相关技能省下来的 token 很可观。当然这不是 superpowers 这个工具直接省出来的而是“按需加载”这个模式带来的效率红利。避坑提醒技能文件里写的命令一定是当前项目真正可用的命令。我同事曾经把mvn clean install -DskipTests写进技能结果团队的 CI 里必须跑测试这个技能反而干扰了 Agent 的判断。技能是给 Agent 用的“默认行为”里面的每条指令都要对当前环境负责。5. 常见问题与排查记录5.1 技能不被加载用这类工具最烦的一件事就是明明技能写得没问题智能体就是不理它。我排查过几次大部分情况下是description写得不够“可匹配”。智能体判断要不要读技能本质上是一个语义匹配过程描述里缺关键词或者描述得太大而空匹配率就会很低。比如有人把description写成“Java 相关”结果智能体在做一个 Spring Boot 接口开发任务时根本不会把这个技能跟眼前代码联系起来。改成“开发 Spring Boot RESTful 接口包括 Controller、Service、Mapper 三层结构与异常处理”之后匹配率瞬间提高。还有一种情况是AGENTS.md没有被正确读取。Codex 对AGENTS.md的读取位置有约定除了项目根目录还有用户目录下的全局配置。你的技能索引如果写错了位置智能体自然看不到。排查时先确认初始化指令生成的索引文件在哪个目录再确认里面有明确指向.superpowers/skills/的路径。5.2 命令找不到或版本不对有些朋友装完 superpowers 之后第一次执行就报command not found。这个事 90% 是因为 npm 全局安装目录不在系统的 PATH 里。用 nvm 安装 Node.js 的情况下全局二进制通常软链到了~/.nvm/versions/node/xxx/bin/正常来说不会被漏掉。如果是自己编译的 Node 或者用 apt 装的就可能踩这个坑。我的建议是装完立刻验证which superpowers superpowers --version如果which有结果但--version报错大概率是版本太旧或者包名搞混了。卸载重装时记得清一下 npm 缓存npm uninstall -g superpowers npm cache clean --force npm install -g superpowers这种基础问题看着简单实际在新环境里最容易卡住人。5.3 和团队协作时的细节最后说一个多人协作的细节。技能库进 Git 之后理论上全团队共享但实际运行的智能体类型可能不一样——有人用 Codex有人用 Claude Code还有人用 Gemini CLI。不同智能体对技能文件的读取方式有细微差异有些对 frontmatter 的字段要求更严格有些会自动把技能文件当成工具来调用。我在多智能体共存的团队里试过一段时间结论是技能文件尽量写得“口径统一”不要依赖某个特定智能体的私有特性只在技能正文里使用通用的 Markdown 结构。这样同一个技能目录三款智能体都能使用。至于 superpowers 的版本更新建议固定在一个经过验证的版本上不要逢更新就升等你确认新版本没有破坏技能索引结构再升级不迟。对于 Java 项目还有一个特殊建议技能文件里提到的包名、类名、模块路径如果经常变最好用相对路径而不是绝对路径不然项目重构一次技能文件里的命令就失效一次。我在一个多模块 Maven 项目里吃过这个亏后来统一约定技能里的命令都从仓库根目录执行并写明-pl参数指定模块再没报过路径错误。写在最后一点个人经验用 superpowers 这段时间我最深的感觉是这类工具真正解决的其实是“知识管理”的问题。AI 编码助手的能力上限不仅仅取决于模型本身还取决于我们有没有把工程知识用它看得懂的方式喂给它。技能文件就是一种让知识结构化、可复用、可检索的形式。我个人现在不管项目大小初始化之后的第一件事就是先给 AI 建两三个最核心的技能文件一个管构建一个管测试一个管代码审查。这三个跑顺了日常开发能省下大量沟通成本。最后再分享一个小技巧技能的编写不要追求“一劳永逸”。我的习惯是每次 AI 在项目里犯了明显的错误就把错误场景和正确做法补进对应技能文件里。这相当于让 AI 手里那本“操作手册”持续迭代越用越顺手。整个项目团队的工程经验也就这样一天天沉淀进了那个.superpowers/目录里。 
长河君 · 2026/10/3 6:02:10 · 阅读 1.2k superpowers：为AI编码助手打造按需加载的技能库
1. 先搞清楚 superpowers 是什么1.1 AI 编程助手为什么需要“技能”你有没有遇到过这种情况同一个 AI 编码助手在干净的“hello world”项目里表现得像个天才一旦扔进一个带历史包袱的企业级 Java 工程就开始一本正经地胡说八道。它不知道你们的 Maven 仓库有内网镜像不知道代码规范里禁止 Lombok 的Data用在 JPA 实体上更不知道测试运行前要先启动一个特定的 Docker Compose 服务。这些信息不在模型的训练数据里也不在仓库的代码里而是散落在团队成员的脑子里。这就是 AI coding agent 在实际工程环境里的核心痛点它很强但它“不熟”。代码模型背下了全世界的开源代码却背不下你公司内部的构建流程和踩坑记录。早期大家靠什么解决靠在CLAUDE.md、AGENTS.md里写长篇提示词把规则一条条喂给智能体。问题是提示词越写越臃肿而且智能体不是每次都会认真读完。你写了两千字规范它可能只看了前两百字。superpowers 这个项目就是冲这个问题来的。它不是又一个编码助手而是给 Codex、Claude Code、Gemini CLI 这类编码智能体统一提供“技能库”的管理工具。所谓技能就是一组结构化的 Markdown 指令文件里面写明“在什么情况下用什么方法做什么事”然后由 superpowers 帮你安装、更新、组织、注入到智能体的工作流程里。简单说它把“写在提示词里的项目知识”变成了“按需自动加载的即插即用技能”。1.2 项目核心思路与能解决的问题我第一次用 superpowers 的时候脑子里浮现的画面是一个老师傅的抽屉每个抽屉贴着标签里面有对应的操作手册、检查清单、常用脚本。智能体遇到问题打开对应抽屉而不是把所有手册都摆在桌面上读。这正是 superpowers 的设计哲学技能不是一股脑塞进上下文而是由智能体根据任务描述自主判断“我现在需要哪份技能”再按需读取。这样做有几个很实际的好处。第一上下文窗口被节省了智能体不用每次都在几万字的规范里翻找条款它只需要读取当前任务相关的技能文件。第二技能是可复用的同一个“后端代码审查”技能可以同时用于 A 项目和 B 项目不需要在每个仓库里复制粘贴。第三技能是可版本管理的它就是一个普通目录放进 Git团队里所有人都能同步。在这套体系里技能跟插件不是一个东西。插件是改写了工具本身行为的代码技能只是“更聪明的使用说明书”。所以它几乎没有侵入性卸载了 superpowers你的项目代码不会受到任何影响。这一点对很多核心系统特别友好——你不需要让 AI 拿到代码执行权限只需要让它更懂你的工程上下文。2. 安装与初始化从零接上 superpowers2.1 环境准备与安装在动手之前先确认你本地的环境。superpowers 是一个基于 Node.js 的命令行工具所以前提是机器上有 Node.js 环境建议版本在 18 以上。可以用node -v快速确认。没有 Node.js 的话先去官网装一个 LTS 版本这一步没有捷径。安装用的命令是 npm 全局安装以我写这篇博客时的常见发布方式来看入口是 npm 包superpowers。不同版本、不同仓库源的包名可能略有差异有的教程里会看到superpowers/cli这样的写法这属于正常的包名命名差异实际以官方文档为准。我自己执行的是npm install -g superpowers装完之后验证一下superpowers --version如果能看到版本号说明装好了。这里有一个新手很容易踩的坑如果你用 macOS 并且之前装过 Python、Ruby 之类的东西npm 全局目录的权限经常出问题。我在 Linux 服务器和 macOS 上都碰到过EACCES权限报错解决办法是用nvm管理 Node.js而不是用系统自带的 Node这样全局安装目录在你的用户目录下权限清爽很多。2.2 初始化并接入 Codex安装好命令行工具之后接着要在你的项目里初始化 superpowers。进入项目根目录执行cd your-project superpowers init初始化过程会做几件事创建一个.superpowers/目录用来存放技能文件扫描项目当前使用的编码智能体类型自动改写或生成AGENTS.mdCodex 使用的项目级指令文件或者CLAUDE.md在里面写入一段“调用技能”的指引。如果你是 Codex 用户这一步很关键。Codex 官方支持读取仓库根目录的AGENTS.md把它作为项目上下文的强制输入。superpowers init 做的事情本质上就是帮你把“技能库的索引”注入到 Codex 每次启动都会读的这份文件里。之后再运行codex它就已经知道自己旁边有技能库这个东西了。注意有些项目里已经手工维护了一份AGENTS.md初始化前最好先备份。superpowers 在改写文件时通常不会删除你原来的内容而是在末尾追加但我见过某些旧版本处理得比较粗暴所以有备无患。2.3 目录结构说明初始化完成之后你会看到类似这样的结构your-project/ ├── .superpowers/ │ ├── skills/ │ ├── templates/ │ └── config.json ├── AGENTS.md ├── package.json └── ....superpowers/skills/就是技能库的存放位置。每一个技能可以是一个 Markdown 文件也可以是一个目录目录里除了主文件还能附带脚本和资源。config.json记录当前项目的配置比如启用了哪些技能包、自动更新策略之类的。AGENTS.md是被注入的索引文件。我个人的习惯是把这个目录也提交进 Git。有人会觉得项目里的“AI 配置文件”不该进版本库但我的经验相反技能库本质上是团队知识的沉淀是文档的一部分不进 Git 的话每个人本地的技能版本会越来越不一致最后变成“在我机器上是好的”。3. 使用指南技能怎么写、怎么被调用3.1 技能文件的基本格式superpowers 的技能文件不是随便写写就行的它有固定的结构。一个标准的技能文件包含两部分YAML 格式的 frontmatter 元数据以及正文部分。frontmatter 里最重要的两个字段是name和description。--- name: java-build-debug description: 分析 Java Maven 项目构建失败的原因包括依赖冲突、编译器错误、测试失败三类常见场景。 when_to_use: 当 Maven 构建失败、编译报错、测试不过且需要诊断根因时使用。 ---重点说说description字段。这个字段是智能体判断“要不要使用该技能”的唯一依据写得好不好直接影响技能能不能被正确触发。你要是写成“这个技能用于 Java”那等于没写智能体在任何 Java 任务里都可能去加载它浪费 token 不说还可能因为内容不匹配而误判。我的建议是描述里至少包含三层信息适用场景、技术栈、具体触发条件。参考上面的例子“Maven 构建失败”是场景“依赖冲突、编译器错误、测试失败”是具体信号“诊断根因”是任务目标。正文部分就是技能的主体内容通常包括操作步骤、注意事项、检查清单。和普通文档不同技能文件更接近“标准操作流程”语言要指令化少废话。比如你可以写“先执行mvn dependency:tree -Dverbose检查依赖树再根据冲突报错定位 pom.xml 中的排除项”而不是写一大堆“依赖管理是 Maven 的核心功能之一”。3.2 写一个 Java 技能实例光说格式不够直观我这里给一个完整的、可以直接抄的 Java 技能示例。这个技能解决的是“Java 项目代码审查”问题——我实际在团队里就是靠它统一了 Codex 做 code review 时的关注点。--- name: java-code-review description: 对 Java 代码进行审查重点检查空指针风险、并发安全问题、资源泄漏、异常被吞、SQL 注入隐患。 when_to_use: 当用户要求审查 Java 代码、提交 merge request 前检查、或者询问某段代码是否存在隐患时使用。 --- # Java 代码审查技能 ## 审查范围 1. 空指针风险检查所有链式调用、Optional 的 orElseGet/orElse 使用、方法入参是否可能为 null。 2. 并发安全检查共享变量是否有 volatile 或 synchronized 保护线程池使用是否规范是否使用 ConcurrentHashMap 代替 HashMap。 3. 资源泄漏检查 InputStream、Connection、Statement 是否在 finally 或 try-with-resources 中关闭。 4. 异常处理检查 catch 块是否吞掉异常是否打印了足够上下文的日志是否抛出了可读性强的业务异常。 5. 安全性检查字符串拼接 SQL、反射调用、不安全的反序列化。 ## 审查输出格式 对每个问题按以下格式输出 - 文件位置 - 问题类型严重/建议 - 问题描述 - 修改建议 ## 禁止事项 不要为了建议而建议不要修改和当前任务无关的代码格式。你可能会问这跟手工在 Codex 的提示词里写一段“请按以下规范审查”有什么区别区别在于触发机制。提示词需要你每次重复技能是靠description自动匹配的。你只要说一句“帮我把改动 review 一下”Codex 读到任务描述里有 review、Java 这些词就会主动去加载这个技能文件不需要你再贴一遍规则。一次编写所有后续会话持续生效。3.3 技能调用机制剖析这背后究竟发生了什么我一开始也觉得神奇后来扒了一下实现思路才弄明白。superpowers 本质上是给编码智能体提供了一个“按需阅读索引”。它在AGENTS.md里写入的指引大致意思是当接收到任务时先检查.superpowers/skills/目录下有哪些技能文件。阅读技能文件 frontmatter 里的name和description判断是否与当前任务相关。如果相关读取该技能文件正文并严格按正文指示工作。如果多个技能都相关按任务的主次顺序加载。这个机制生效的前提是智能体本身具备“工具调用”或“迭代式阅读文件”的能力。Codex、Claude Code 这类智能体在执行任务时天然会去读项目里的说明文件superpowers 只是在说明文件里精确地埋了“钩子”告诉它往哪里翻。所以它不是一个后台守护进程也不是魔法。它的高明之处在于极其克制不抢智能体的执行权只负责把知识和规则整理到“伸手就能够到”的位置。实操心得技能文件不要让智能体一次性全读。我见过有人在一个技能文件里写了三千行结果智能体读取大量内容后反而忽略关键技术点。一个技能解决一件事每个文件控制在 100 行上下效果是最好的。复杂问题拆分技能包比如 Java 的审查、构建、测试分成三个独立技能。4. Java 项目实战用 superpowers 管好构建和测试4.1 实战前的 Java 项目准备前面讲了通用用法这一节我拿一个真实场景——Java 单体应用项目——来完整演示一遍。我手头有一个 Spring Boot 项目Maven 构建模块化结构测试分单元测试和集成测试两层。在这个项目里AI 编码助手以前的表现不太稳定主要是三个问题不知道集成测试需要先启动 Testcontainers遇到 Maven 依赖冲突时只会建议升级版本不会分析依赖树写单元测试时经常写出依赖 Spring 上下文的“伪单元测试”跑一次要十秒。接入 superpowers 之前我在AGENTS.md里写过一大段项目规范但效果一般。后来我把这些规范全部改成了技能文件每个问题一个独立技能。这里要说明一下改造不是把原来的文档拆开就算完而是要站在“智能体会怎么触发”的角度重新组织内容。4.2 设计一组 Java 技能包我最终给这个项目设计了四个技能放在.superpowers/skills/下技能文件用途触发标志maven-dependency-fix.md分析依赖冲突、版本仲裁问题“依赖冲突”“mvn 报错”“dependency”spring-test-guideline.md规范单元测试与集成测试的边界“写测试”“测试不过”“JUnit”testcontainers-setup.md启动和管理集成测试容器“集成测试”“Testcontainers”java-code-review.md代码审查“review”“审查”“检查代码”这里最值得聊的是spring-test-guideline.md里面的一条规则。之前智能体写测试经常直接SpringBootTest一把梭启动整个应用上下文慢得要命。我在技能文件里明确写了触发条件## 测试类型选择 - 如果测试只涉及一个 Service 类优先使用 Mockito 直接 mock 依赖不要启动 Spring 上下文。 - 如果必须校验 MyBatis 映射或 JPA 查询再使用 MybatisTest 或 DataJpaTest 切片测试。 - 只有完整的接口/集成测试才允许使用 SpringBootTest且必须配合 Testcontainers。这条规则写成技能之后Codex 写出的测试文件风格明显变了。倒不是它忽然变聪明了而是因为技能文件把“什么场景用什么策略”写成了明确的决策树智能体只需要照着选项走。Maven 依赖冲突那个技能我写得最简单核心就是先执行诊断命令再根据输出决定处理方式mvn dependency:tree -Dverbose mvn dependency:analyze这个动作本身不复杂但很能说明问题智能体在遇到依赖冲突时默认行为往往是去 Maven 中央仓库找“最新版本”然后升级。有了技能文件它才会意识到先看依赖树、确认冲突来源再用排除依赖或者调整 import 顺序来解决问题。行为路径变了结果完全不一样。4.3 实战效果与我的体感跑了两周之后这个项目里 Codex 的表现变化我觉得是质变。以前提交代码前让 AI 做一轮 review它的关注点经常漂移喜欢挑代码风格、变量命名的毛病对真正的风险点——比如一个catch (Exception e)把异常吞了的隐患——反而视而不见。有了java-code-review技能之后它的检查顺序稳定下来了先看空指针、再检查资源释放、最后才看安全漏洞确实像“见过世面的老手”。另一个体感是在上下文占用上。以前为了让 AI 遵守项目规范我在提示词里夹带各种约束一次会话要多花好几千 token。技能机制是“用到才读”大部分会话它根本不加载相关技能省下来的 token 很可观。当然这不是 superpowers 这个工具直接省出来的而是“按需加载”这个模式带来的效率红利。避坑提醒技能文件里写的命令一定是当前项目真正可用的命令。我同事曾经把mvn clean install -DskipTests写进技能结果团队的 CI 里必须跑测试这个技能反而干扰了 Agent 的判断。技能是给 Agent 用的“默认行为”里面的每条指令都要对当前环境负责。5. 常见问题与排查记录5.1 技能不被加载用这类工具最烦的一件事就是明明技能写得没问题智能体就是不理它。我排查过几次大部分情况下是description写得不够“可匹配”。智能体判断要不要读技能本质上是一个语义匹配过程描述里缺关键词或者描述得太大而空匹配率就会很低。比如有人把description写成“Java 相关”结果智能体在做一个 Spring Boot 接口开发任务时根本不会把这个技能跟眼前代码联系起来。改成“开发 Spring Boot RESTful 接口包括 Controller、Service、Mapper 三层结构与异常处理”之后匹配率瞬间提高。还有一种情况是AGENTS.md没有被正确读取。Codex 对AGENTS.md的读取位置有约定除了项目根目录还有用户目录下的全局配置。你的技能索引如果写错了位置智能体自然看不到。排查时先确认初始化指令生成的索引文件在哪个目录再确认里面有明确指向.superpowers/skills/的路径。5.2 命令找不到或版本不对有些朋友装完 superpowers 之后第一次执行就报command not found。这个事 90% 是因为 npm 全局安装目录不在系统的 PATH 里。用 nvm 安装 Node.js 的情况下全局二进制通常软链到了~/.nvm/versions/node/xxx/bin/正常来说不会被漏掉。如果是自己编译的 Node 或者用 apt 装的就可能踩这个坑。我的建议是装完立刻验证which superpowers superpowers --version如果which有结果但--version报错大概率是版本太旧或者包名搞混了。卸载重装时记得清一下 npm 缓存npm uninstall -g superpowers npm cache clean --force npm install -g superpowers这种基础问题看着简单实际在新环境里最容易卡住人。5.3 和团队协作时的细节最后说一个多人协作的细节。技能库进 Git 之后理论上全团队共享但实际运行的智能体类型可能不一样——有人用 Codex有人用 Claude Code还有人用 Gemini CLI。不同智能体对技能文件的读取方式有细微差异有些对 frontmatter 的字段要求更严格有些会自动把技能文件当成工具来调用。我在多智能体共存的团队里试过一段时间结论是技能文件尽量写得“口径统一”不要依赖某个特定智能体的私有特性只在技能正文里使用通用的 Markdown 结构。这样同一个技能目录三款智能体都能使用。至于 superpowers 的版本更新建议固定在一个经过验证的版本上不要逢更新就升等你确认新版本没有破坏技能索引结构再升级不迟。对于 Java 项目还有一个特殊建议技能文件里提到的包名、类名、模块路径如果经常变最好用相对路径而不是绝对路径不然项目重构一次技能文件里的命令就失效一次。我在一个多模块 Maven 项目里吃过这个亏后来统一约定技能里的命令都从仓库根目录执行并写明-pl参数指定模块再没报过路径错误。写在最后一点个人经验用 superpowers 这段时间我最深的感觉是这类工具真正解决的其实是“知识管理”的问题。AI 编码助手的能力上限不仅仅取决于模型本身还取决于我们有没有把工程知识用它看得懂的方式喂给它。技能文件就是一种让知识结构化、可复用、可检索的形式。我个人现在不管项目大小初始化之后的第一件事就是先给 AI 建两三个最核心的技能文件一个管构建一个管测试一个管代码审查。这三个跑顺了日常开发能省下大量沟通成本。最后再分享一个小技巧技能的编写不要追求“一劳永逸”。我的习惯是每次 AI 在项目里犯了明显的错误就把错误场景和正确做法补进对应技能文件里。这相当于让 AI 手里那本“操作手册”持续迭代越用越顺手。整个项目团队的工程经验也就这样一天天沉淀进了那个.superpowers/目录里。