superpowers实战：用技能模块把AI编程助手调教成懂你的老同事

不绕弯子，直接说结论：superpowers不是某个炫酷的新编程语言，也不是某款灵异IDE插件，它是一套专门给 AI 编程工具（尤其是 Codex CLI 这类终端型助手）做“外挂式增强”的配置与技能集。说白了，它就是把你平时反复敲给 AI 的提示词、代码规范、工作流约定，打包成一堆能直接调用的“技能模块”，让 AI 从“一个啥都会但需要你不断叮嘱的实习生”，变成一个“懂你项目规矩、上手就按你习惯干活的老同事”。

这类东西目前在开发者圈子里讨论热度很高，尤其是当你发现 AI 写代码“第一版总是不尽如人意”、或者说“每次都要重复交代背景和规范”的时候，superpowers就是冲着解决这几个痛点来的。这篇文章我会从设计思路、安装配置、Java 实战、以及我实际踩过的坑这几个维度展开，尽量写得实操一些。无论你是刚接触 AI 编程辅助的开发者，还是已经在用 Codex、想进一步榨干它能力的进阶玩家，都值得往下看。

1. 它到底是什么：superpowers 的设计思路与核心价值

1.1 从“临时工 AI”到“老熟人 AI”的转变

先想一个问题：为什么很多人用 AI 写代码，感觉“也就那样”？我的体会是，问题往往出在上下文管理上。直接跟 Codex 说“帮我写个订单模块”，它当然能写，但写出来的东西大概率是泛泛的、不符合你项目现有风格的——因为你没有告诉它你的分层习惯、异常处理规范、命名风格、数据库表设计约定。

superpowers的思路很直接：既然 AI 记不住你的偏好（而且每次会话都要重新说一遍），那就把这些偏好、规范、常用任务的执行步骤，固化成一个个“技能文件”。你只需要在对话里说一句“用 Java 重构这个类，并生成单元测试”，AI 就会自动去加载对应的技能定义，按照里面写好的步骤和规则来执行。

所以它的核心价值有三点：

• 减少重复沟通：规范只写一次，之后每次调用都自动生效。
• 稳定输出质量：把“碰运气”式的 AI 生成，变成“走流程”式的标准作业。
• 沉淀团队经验：谁踩过的坑、总结出的最佳实践，都能写进技能文件里共享。

1.2 它是怎么组织“技能”的

我拿自己用的配置来举例。superpowers装完之后，通常会有一个固定的目录结构，每个子目录或者文件就代表一个技能。比如常见的技能有：

• code-review（代码审查）
• write-tests（编写测试）
• refactor（重构）
• explain-code（解释代码）
• implement-feature（按需求实现功能）

每个技能文件里面，写的不是代码，而是给 AI 看的指令模板。包括这个技能的目标、执行步骤、输入要求、输出格式、注意事项等。你可以把它理解为“给 AI 写的岗位说明书”。当你在对话里明确提到@code-review或者使用 code-review 技能时，Codex 就会把这个文件的内容注入到当前上下文中，AI 接下来的行为就会被这份说明书约束。

生活化类比：你第一次请人装修，要在现场反复说“瓷砖要工字铺、踢脚线要做暗藏式、开关插座要离地 30 公分”。但如果给装修队长一份写清楚的“工艺标准手册”，他看一眼就知道怎么干，你也不用每句话重复三遍。superpowers就是给 AI 的那本“工艺标准手册”。

1.3 为什么不是所有增强工具都叫 superpowers

跟一些单纯的提示词合集相比，superpowers这类工具更强调“结构化”和“可执行”。它不只是在.txt文件里堆一堆话术，而是把技能、规则、工作流分开管理，通过 CLI 的机制动态加载。

我之前也试过把一大段提示词直接粘到对话里，效果其实很不稳定。原因在于：提示词一长，AI 容易“抓不住重点”，而且每次都要粘贴，稍微改一下项目场景就得再编辑一遍。而superpowers的设计是把“技能描述”和“具体任务输入”分开。技能文件里越写越精炼，任务输入反而是临时的、动态的。这样逻辑清晰，迭代也方便。

另外，它跟 Codex 的配合尤其自然。Codex 本身是命令行工具，而superpowers正好也是面向命令行的配置体系，两者亲近感天然就强。不过要注意，它并不绑定某个特定工具，理论上凡是支持读取外部指令文件的 AI 编程助手，都能用上这一套思路。

2. 从零搭建：安装 superpowers 与初始配置

2.1 安装前需要确认的环境

别急着复制粘贴命令，先把基础环境检查一遍，不然容易卡在一些莫名其妙的报错上。我建议按这个清单核对：

• Node.js 版本：很多基于 CLI 的配置工具都依赖 Node 运行环境，superpowers也不例外。要求不高，但至少 Node 16 以上比较稳妥。我用的 18.x，没出过兼容问题。
• Git：装superpowers通常需要从远程仓库拉取配置模板，没有 Git 寸步难行。
• Codex CLI（或等效工具）：如果你还没装过任何 AI 编程 CLI，建议先装好 Codex，并完成至少一次成功的对话调用，确认 API Key 配置没问题。这一步不能省，因为很多人后面排查半天，最后发现是密钥没配好。
• 终端环境：在 Mac/Linux 下体验最好，Windows 的话建议用 WSL 或者 Git Bash，纯 PowerShell 有时候会遇到脚本执行权限问题。

确认没问题后，就可以开始了。

2.2 安装步骤实操

我用的是 npm 安装方式，整个过程其实不复杂，三步走：

# 1. 全局安装 superpowers 命令行工具 npm install -g superpowers # 2. 在你要应用的工作目录里初始化 cd your-project/ superpowers init # 3. 按照交互提示，选择你需要的技能包

第三步它通常会问你“要启用哪些技能”（比如 code-review、write-tests 等），选完之后会在项目根目录生成一个.superpowers/文件夹，里面就是技能定义和配置文件。

我实际安装时踩的第一个坑：初始化命令执行完，提示“No skills found”——我明明选了技能包，为什么还说没有？查了一会儿才发现，是因为当前项目目录名里带了中文，导致路径解析异常。这个概率其实不小，只能说很玄学。后面我会在排查部分细说。

初始化完成后，比较合理的习惯是先打开 .superpowers/ 目录看一眼，了解里面每个文件的作用。比如：

.superpowers/ ├── config.json # 全局配置，启用哪些技能、默认语言模型等 ├── skills/ │ ├── code-review.md │ ├── write-tests.md │ └── ... └── custom/ # 自定义技能的存放位置

把结构看清楚再动手，后面改起来心里才有底。

2.3 验证是否安装成功

一个简单的验证方法是：直接在项目目录开启 Codex，随便说一句“列出当前可用技能”。如果配置正常，它会返回一串技能名字列表。如果它回复“没有找到技能”或者显示一堆“无效指令”，那就是安装或者路径上有问题。

再更直接一点，你可以在 Codex 会话里引用某个技能，比如：

使用 write-tests 技能，为 utils/MathHelper.java 生成单元测试

看看它是不是会比平时更“懂规矩”地输出测试用例。如果它输出的测试结构、命名、覆盖方式明显比之前规范，说明技能已经注入成功。

2.4 初始配置里的几个关键参数

打开config.json，我建议重点关注这几个配置项：

• defaultSkill：默认注入到每次会话里的技能。比如你大部分时间都在做 Java 开发，可以把java-project这类技能设为默认，省得每次手动指定。
• maxContextTokens：技能文件占用的上下文窗口大小。不是越大越好，因为总上下文是有限的，留给实际代码对话的空间会被挤占。我个人的习惯是保持默认，最多微调。
• customSkillsPath：自定义技能目录路径。如果你打算把团队规范沉淀成技能，把这个路径指向团队共享目录就行。

提示：配置文件修改完，务必重启 Codex 会话再测试，否则修改不生效。这是很多人忽略的一点，我本人也在这上面白费过十分钟。

3. 真正发挥威力：Java 项目中的 superpowers 实战

3.1 为什么拿 Java 场景举例

superpowers这种工具其实不分语言，但我特意选 Java 来说，是因为 Java 项目的特点特别适合体现这类技能系统的价值：

• 工程结构严格（分包分层、接口与实现分离），技能文件可以很精准地规定“什么代码放哪层”。
• 测试文化重（JUnit、Mockito 是家常便饭），write-tests技能在这种场景下能发挥出极大的提效作用。
• 框架约定繁琐（Spring、MyBatis 等），把常用注解、配置规律写进技能，AI 生成的代码能少很多低级错误。

3.2 实战一：用技能包生成规范的单测

先说我以前不用superpowers时，让 Codex 给 Java 类写测试会遇到什么情况：它会生成一个测试类，但常常出现的问题包括——测试方法命名没有规律、用System.out.println做验证、没有覆盖边界条件、Mock 用法稀奇古怪。不能说它不会写，只能说写得不够“像我们团队的代码”。

用了write-tests技能之后，我在技能文件里定义了这样几类规则：

• 测试类与被测类位于相同包路径，放在src/test/java下。
• 测试方法命名统一为方法名_场景_预期结果，例如calculateTotal_whenEmptyList_returnsZero。
• 优先使用 Mockito 做依赖隔离，禁止在单测里启动 Spring Context。
• 要求覆盖正常路径、异常路径、边界条件。
• 断言必须使用 AssertJ 或 JUnit 的 Assertions，禁止使用 if 语句做验证。

在完成了这个技能文件的配置后，我可以直接在 Codex 里说：

使用 write-tests 技能，为 service/OrderService.java 生成单元测试

它生成的代码，基本能做到“拿过来就能提交”。甚至有好几次，它连 Mock 的when(...).thenReturn(...)都跟我自己手写的一模一样。这里面的区别就是技能文件里明确写了“依赖隔离优先用 Mockito，不要 mock 具体类，要 mock 接口”。

3.3 实战二：用 refactor 技能做安全重构

重构是一件很考验“纪律性”的事情。人都会偷懒：时间紧的时候直接大改，结果测试挂了都不知道是哪一步引起的。superpowers的refactor技能能帮我们约束 AI 按流程来。

我配置的refactor技能里写明了以下步骤：

1. 先分析目标类的当前结构和调用关系。
2. 列出潜在风险点，如公共方法签名变更的影响范围。
3. 建议拆分成多个小步，每一小步保持可编译、可测试。
4. 每完成一步，执行一次项目构建命令（比如mvn compile）。
5. 最后运行相关测试用例，确认无回归。

实际用下来最爽的一次，是让它帮我将一个几百行的老式 Service 类按业务域拆分成三个新类。我给它下达指令：

使用 refactor 技能，将 OrderService 按照职责拆分成 OrderQueryService、OrderCommandService、OrderValidateService

它真的就一步一步来：先分析原类方法，再建议如何分配，然后逐个类生成代码，每生成一个类就提醒我跑编译。虽然最终我还是人工 review 了一遍，但整体心理负担小了很多，因为每一步都验证过，不像以前那样“一夜回到解放前”。

3.4 自定义、可复用的团队技能

这里我想特别强调一下自定义技能的思维。由于superpowers本质上是“规则文件”，你可以把团队里很多约定都写进去。比如：

• 不允许在 Controller 层直接操作数据库。
• 所有接口返回统一使用Result<T>包装。
• 异常必须抛出业务异常类型，不允许裸抛RuntimeException。
• 数据库时间字段一律使用LocalDateTime，禁止使用字符串时间。

把这些约定写入自定义技能之后，每次让 AI 写接口、写分层代码，它都会自动遵守。这就相当于把代码规范 review 这个环节前置了，AI 生成时就把规范考虑了进去，评审压力会小很多。

一个团队往往只需要集中精力维护好那几个自定义技能文件，收益是全方位的。不过话说回来，技能文件也不是越多越好。文件太多、内容太长，反而会让 AI 的上下文窗口被占满，影响生成质量。我个人的建议是：单个技能文件控制在 50 行以内，求精不求多。

4. 踩坑记录：常见问题与排查技巧实录

4.1 症状与原因速查表

我在使用superpowers的过程中，确实遇到了不少奇奇怪怪的问题。这里总结成一张速查表，方便大家对照排查：

4.2 排查思路才是最重要的

很多朋友一遇到问题就搜报错，其实效率不高。我的习惯是先按下面的顺序排查：

• 第一步，确认技能文件本身能被读取。直接打开文件看格式对不对，有没有语法错误——是的，Markdown 也有“语法错误”，比如代码块没闭合、列表符号混用，这些都会影响 AI 解析。
• 第二步，确认当前会话确实加载了技能。在 Codex 里问一句“你现在加载了什么技能”，比啥都直观。
• 第三步，确认技能内容跟任务匹配。经常有人让 AI “用 write-tests 技能给 Python 模块写测试”，但技能文件里写满了 Java/JUnit 的内容，那结果当然不对劲。
• 第四步，确认是不是 prompt 的锅。有一阵子我明明调用了 code-review 技能，却发现它还在写代码而不是给建议，最后发现是我自己的 prompt 表述成“用 code-review 技能改进这个类”……这语义是模糊的。把它改成“用 code-review 技能审查这个类，只提建议不直接改代码”后，一切正常。

4.3 关于性能与体验的优化心得

最后再分享几个提升长期使用体验的建议，这些都是我实际测下来比较有用的：

• 不要把技能当成万能的：AI 的上下文窗口有限，技能文件太多太长一定会稀释注意力。宁可把大而全的技能文件拆成多个小技能，按需调用。
• 技能文件也要“版本管理”：我是直接把.superpowers/目录纳入 Git 管理的。这样每次对技能定义的改动都有历史记录，哪天改坏了，git diff一下马上知道哪里出了问题，回滚也方便。
• 定期审视技能文件里每条规则的实际价值：我每过一段时间就会删掉一些“理想主义”的规则。比如我之前写过“所有方法长度不得超过 10 行”，听起来很美，但在很多业务场景下就是不现实，最后 AI 反而为了凑 10 行以内写出了一堆难读的代码。这种规则留着就是坑。
• 跟团队的协作工具搭配使用：如果你们团队有用 Worbuddy 这类交互协作工具做任务同步或工作流管理，可以把技能文件里的关键步骤也同步到工作流中，AI 生成完代码后进行人工 review，再进入自动化测试，整个链路配合起来会比较顺。

我自己用下来最深的感受是，superpowers这类工具真正改变的不是 AI 本身的能力，而是你在使用 AI 前“有没有把自己的标准梳理清楚”。你先想明白什么是对的代码、什么是好的流程，然后才能把它们固化成技能文件，让 AI 稳定执行。如果没有这一层思考，装再多工具也只会得到一堆概率性的、时好时坏的代码。先把自己的标准定下来，这个工具才真正值回票价。

最后再补充一个小技巧：如果你发现某个技能的使用频率特别高，不妨把它设为默认技能，但内容里只保留最核心的约束，其他细节拆成“按需加载”的补充技能文件。这样既保证了基本行为符合预期，又不至于一次性占用太多上下文。我自己就是因为“把大招全默认开着”吃过亏，精简之后效果反而稳定得多。