superpowers：给 AI 编程代理装上可执行的技能系统

最近在折腾 Codex CLI 和 Claude Code 这类 AI 编程代理的时候我频繁听圈子里的人提到一个名字superpowers。一开始我以为是某个“一键让 AI 变聪明”的玄学工具直到自己手动装了一遍、跑了几个真实项目之后才意识到superpowers 本质上是一套以“技能skills”为核心的 AI 代理增强框架。它不改变底层模型却能让模型按照预设的工作流程去思考、拆解任务、执行检查甚至自动遵循 TDD、代码评审、安全扫描这些本该由人工反复强调的工程规范。这篇文章我打算把自己从安装、初始化、日常使用到和 Codex CLI 配合调教的全过程写出来包括那些文档里没有写的坑。适合刚听说 superpowers 想入门的同学也适合已经在用但总觉得“AI 还是不够听话”的开发者。我会尽量用白话来解释它到底解决了什么问题并给出一套可以直接抄的 Java 项目实操路线。1. Superpowers 到底是什么不是超能力是给 AI 编程助手的“技能系统”1.1 一个被严重低估的 AI 辅助层很多人会把 superpowers 和普通的“提示词模板”混为一谈这是最大的误解。提示词模板只是给模型一段固定的上下文提示而 superpowers 做的是更底层的“行为约束”。安装之后它会在你的项目里生成一个专用的技能目录每个技能对应一份 Markdown 格式的流程文档。当你在对话中明确请求某个技能比如“用 brainstorming 技能帮我梳理需求”AI 就会去读取这份文档并且严格按文档里定义的阶段、输入输出格式、甚至检查清单来执行。换句话说superpowers 提供的是“过程管理”而不是“答案生成”。它让 AI 编程代理从一次性问答机器变成了一个会走流程、会自我检查、会在关键节点停下来等你确认的执行者。这种设计思路在工程上非常重要因为大模型最难控制的就是“发散”——它可能三秒钟就给你一个看似完整其实漏洞百出的方案。而技能系统本质上是给模型套上了一根“流程轨道”让它只能沿着轨道走。1.2 它解决的核心痛点AI 不会“主动干活”用过 Codex CLI 或者 Claude Code 的人应该都有体会你问一句它答一句你不要求的它绝对不会多做。比如你让它“修复这个 bug”它很可能直接改完代码就结束不会主动跑测试、不会检查是否引入了回归问题、也不会更新相关文档。这不是模型笨而是缺少“任务拆解和完成度定义”。superpowers 的核心价值就在于把这套工程习惯固化成技能文件让 AI 每接到一个任务就自动套用相应的工作流。举个例子我用它内置的 debugging 技能处理一个 Java 空指针异常时AI 会先要求我描述复现路径再让我提供堆栈日志然后它才会开始分析可能原因。分析完之后它还会按照技能要求补上“根因说明”、“修复方案对比”、“验证步骤”三个小节。整个过程像极了一个高级工程师在带新人而不是一个只知道给代码的工具。2. 安装与初始化三分钟跑通基础环境2.1 安装前的环境检查superpowers 本身是一个 Node.js 命令行工具所以第一前提是机器上有 Node.js 环境。我建议使用 Node 18 以上版本因为底层需要比较新的fs和pathAPI。如果是 Windows 用户建议用 WSL 2 或者 Git Bash否则在接下来的技能文件路径解析上可能遇到盘符和反斜杠的问题别问我怎么知道的都是泪。需要确认的还有你的 AI 编程代理版本。如果你打算配合 Codex CLI 使用请确保 codex 在 0.4 及以上版本因为早期的版本对自定义指令的加载机制不完善。如果是 Claude Code则建议 1.0.20 以上。检查方式很简单直接在终端跑对应命令的--version就行。2.2 安装步骤与命令推荐使用 npm 全局安装这样之后在任何项目目录下都能直接调用。安装命令如下npm install -g superpowers/core装完以后进入你的项目目录执行初始化superpowers init这一步会在当前目录生成.superpowers/文件夹里面包括skills/、templates/、config.json三个部分。skills/是存放技能 Markdown 文件的地方templates/放着技能文件的模板config.json则是控制技能加载行为和模型适配的配置文件。初始化完成后可以用superpowers list查看当前可用的技能列表。正常情况能看到 brainstorming、planning、debugging、code-review、security-audit、test-driven-development 这一批内置技能。如果你的列表为空大概率是安装路径的权限问题把.superpowers文件夹改成用户可读写即可。superpowers list2.3 初始化配置的注意事项这里有个关键点superpowers init只会创建配置目录它不会自动修改你的 Codex CLI 或 Claude Code 的配置文件。你需要手动把.superpowers/skills/路径加入你的 AI 代理的指令加载目录。以 Codex CLI 为例编辑~/.codex/config.toml添加如下内容[instructions] files [.superpowers/skills]改完之后重启 codex让配置生效。很多同学在这里栽跟头以为装上 superpowers 就能用结果 AI 完全不理它就是因为没有做这一步。我建议初始化后立刻检查一下 AI 代理能否读取技能文件方法是直接在对话里问一句“你知道 superpowers 的 brainstorming 技能吗请用一句话概括它的流程”。如果 AI 能准确说出来说明加载成功如果答非所问就去检查路径配置。3. 核心用法技能清单、模式匹配与 Java 项目实操3.1 内置技能清单解读我把最常用的几个技能做了一个表格方便你快速理解每个技能是干什么的、适合什么场景技能名触发方式核心流程适合场景brainstorming我说“用 brainstorm 技能”背景收集 → 问题重述 → 多方案生成 → 优劣对比需求方案设计、架构选型planning“按 planning 技能拆分任务”目标定义 → 任务拆解 → 依赖分析 → 里程碑划分复杂功能落地前debugging“用 debugging 技能排查问题”复现路径确认 → 日志分析 → 根因假设 → 验证计划线上 bug、疑难杂症tdd“按 tdd 技能开发”红 → 绿 → 重构先写失败测试再写实现新功能开发、单元测试code-review“帮我 code review用技能”逐文件检查 → 按规范打分 → 给出修改建议合并请求自查security-audit“执行安全审计技能”依赖扫描 → 边界输入检查 → 越权路径审查上线前的安全检查这六个技能基本覆盖了日常开发的高频场景。但要注意superpowers 的技能不是“魔法指令”不是说你说一句“用 brainstorming 技能”它就自动开始群聊式发散。它还是会希望你先提供必要的背景信息。技能文档里其实定义了 AI 需要向用户提问的清单所以很多时候你会发现 AI 反而会“反问”你更多问题这是正常的。3.2 在 Codex CLI 中启用 superpowers要在 Codex CLI 里真正用上 superpowers除了前面说的配置config.toml之外还有一件事值得做自定义启动提示词。我习惯在 Codex 的AGENTS.md文件末尾追加一段当你需要执行复杂任务时请先查看 .superpowers/skills 目录下的技能文档并遵循其中定义的流程。 如果用户提到某个技能请使用该技能对应的完整流程而不是仅凭常识泛泛响应。这样做的原因是虽然技能文件已经加入指令目录但模型在普通对话中未必会主动去翻技能文档。加上这段提示词相当于给模型一个“路由开关”让它遇到任务时先判断该调哪个技能。我实测下来加了这段之后AI 调用技能的频率明显提高回答质量也更稳定。另外Codex CLI 的非交互模式即通过-p传递一次性任务同样支持技能调用。比如我可以直接在终端里跑codex -p 用 tdd 技能为这个项目新增一个登录接口它会先读取 tdd 技能文档然后输出一个包含测试代码、实现代码、运行说明的完整方案。这个能力在写自动化脚本时特别有用。3.3 Java 项目里怎么用一个 Maven 工程示例不少人问 superpowers 是不是只能配合 JS/TS 项目其实完全不是。它和语言无关因为技能文件里写的是“流程要求”不是具体的代码规则。我拿手上的一个 Spring Boot 3 Maven 项目做了实验效果很理想。先看项目结构我提前建好了标准的 Maven 目录my-app/ ├── pom.xml ├── src/main/java/com/example/ ├── src/test/java/com/example/ └── .superpowers/我在pom.xml里只引入了 Web 和 Test 两个 starter。然后打开 Codex CLI输入codex -p 用 tdd 技能实现一个简单的用户注册接口要求用户名和密码不能为空使用 Maven 项目结构接下来有意思的事情发生了。AI 没有直接给我Controller代码而是先在src/test/java/com/example/下生成了UserControllerTest.java内容是一个针对空参数返回 400 的测试。测试跑当然会失败因为这时候还没有 Controller。然后它又生成了UserController.java实现了一个PostMapping(/api/users)接口用Valid配合NotBlank完成了参数校验。最后它输出了运行指令mvn test我按照这个流程跑了一遍测试确实从红变绿。这个例子虽然简单但很能说明问题superpowers 的 tdd 技能不是嘴上说说它会强制 AI 按照“先测试后实现”的顺序来并且生成的代码会严格匹配你项目的构建体系。这就是流程约束的价值。4. 常见问题与排查技巧实录4.1 命令找不到 / 安装失败最常见的问题是superpowers: command not found。原因通常有两个npm 全局安装的 bin 目录没有加入 PATH或者安装过程中权限不足导致命令没写到 bin。排查步骤我建议这样走先执行npm ls -g superpowers/core看包是否装上了再执行which superpowers看命令位置。如果包在但命令不在就用npm config get prefix把返回的路径加入环境变量 PATH 即可。如果是 EACCES 权限报错多半是 npm 全局目录的写权限问题别直接改权限最好用nvm管理 Node把全局包装到用户目录下。4.2 技能不生效 / 上下文被覆盖技能文件加载了但 AI 就是不用大概率是上下文窗口被其他指令占满了。Codex CLI 会先加载AGENTS.md再加载config.toml里指定的指令文件。如果AGENTS.md很长技能文件的描述可能被模型忽略。我遇到过一种情况项目根目录有一个巨大的AGENTS.md描述了一堆业务规则superpowers 技能文件放在后面结果模型完全“看不见”。解决方案是把技能加载路径尽量前置。在config.toml的[instructions]中可以在files列表里把.superpowers/skills放在最前面只留AGENTS.md在后续。另一方面也可以在对话中用更明确的指令比如请严格参考 .superpowers/skills/debugging.md 文件里的流程执行。这样模型会强制去读指定文件绕过上下文干扰。4.3 模型版本兼容性superpowers 对模型版本其实有一定要求。在 Codex CLI 里如果你使用的是比较老的gpt-4系列模型对长文档的遵循能力偏弱技能流程经常执行到一半就“跑飞”。我实测下来gpt-4o和o3系列表现稳定尤其是o3几乎每次都会严格按技能文档的检查清单走。如果是 Claude Code我建议至少用 Claude 3.5 Sonnet 以上。掉到 3.0 Opus 时技能中的多阶段任务拆分经常会出现遗漏比如跳过了“失败测试”直接写实现。这不是 superpowers 的问题而是模型指令遵循能力的差异。遇到这种情况最简单的解决办法是在技能文档的首行加一句强约束 你必须在完成阶段1并得到用户确认后才能进入阶段2。任何情况下都不允许跳步。亲测有效能够明显减少流程跳变。5. 进阶技巧与个人心得5.1 自定义技能把团队规范变成 AI 的肌肉记忆内置技能覆盖面有限真正好用的是自定义技能。superpowers 的项目模板给了非常清晰的结构我建议直接在.superpowers/templates/custom-skill.md基础上改。一个技能文件通常包含以下几个部分技能描述、触发条件、执行流程、输入要求、输出格式、检查清单。我举个例子最近我们团队要求每次合并请求前必须补充接口压测报告。我就写了一个perf-check技能流程是这样的询问用户当前接口的 QPS 预期和延迟要求生成 JMeter 脚本或一个简单的压测类执行压测并收集结果输出一份包含吞吐量、P99 延迟、结论建议的报告写好后放到.superpowers/skills/perf-check.md然后在 Codex 里说“用 perf-check 技能检查这个接口”AI 就会严格执行这四步。团队规范再也不会靠人肉提醒了。5.2 与团队共享配置把技能文件纳入版本管理因为.superpowers/就是一个普通目录完全可以提交到 Git。我建议直接把整个.superpowers/目录纳入版本管理这样新同事拉下代码后只需要运行superpowers init --use-existing或者直接让 AI 代理读取已有技能文件就能保持一致的行为标准。注意config.json里的模型适配参数可能因人而异建议把公共技能文件提交但把config.json加入.gitignore。如果你所在团队同时用 Codex CLI 和 Claude Code技能文件完全可以共用因为它们都是 Markdown 格式只是加载方式不同。这比分别维护两套提示词要高效得多。5.3 一些避免翻车的忠告我用了几个星期之后最大的感受是superpowers 不是“自动驾驶”而是“副驾驶的检查单”。它能把 AI 的行为拉回正轨但不能替你做技术判断。比如 debugging 技能可能会引导你分析日志和堆栈但最终的根因确认还是需要你拍板。该review的代码还是得review该跑的性能测试还是得跑。还有一点。不要过度依赖内置流程。我见过有人给所有任务都用 planning 技能结果一个两小时的活拆出了十几个阶段AI 每走一步都在问“是否需要继续”效率反而低了。我的经验是小型改动直接用普通对话就行只有多文件、跨模块、需要回归验证的任务才值得上技能。学会判断什么时候用、什么时候不用才是真正把 superpowers 用出“超能力”味道的关键。最后分享一个小技巧如果你发现某个技能在一次任务中跑得特别漂亮可以把这一次的完整对话记录保存到.superpowers/examples/目录下并在技能文档底部加一个“参考案例”链接。下一次 AI 执行同一技能时它会多一个高质量范例可以模仿输出质量会肉眼可见地提升不少。这个习惯让我在复用自己项目里的各种技能时省了大量时间希望对你也有帮助。