1. superpowers 到底是什么最近一个月我基本上所有能挤出的大块时间都花在研究 superpowers 上了。说实话这几年代码辅助工具层出不穷我一开始听到这个项目名字第一反应是又一波营销噱头毕竟敢拿 superpowers 当名字的要么真有两把刷子要么就是敢吹。实际用下来之后我得说它属于前者而且属于那种被严重低估的前者。先给不太清楚的读者同步一下背景superpowers 本质上是给 Codex CLI 这类 AI 编码代理做增强的开放式框架。更直白一点说它是一套安装在本地、通过精心设计的提示词模板和自动化流程来大幅提升 AI 编码代理在真实工程中表现的基础设施。你不用把它理解成一个传统意义的编辑器插件它更像一套军规加工具箱的组合——让原本你说一句、它写一句的 AI 编程工具变成一个会主动规划、分步执行、自我检查的编程搭档。它适合谁如果你日常已经在用 Codex CLI 或者类似的命令行 AI 编程助手写代码但总觉得 AI 生成的代码有点飘、让它改老项目时它总把上下文忘光、遇到编译错误就原地绕圈那这套东西就是冲着你来的。如果你还没用过任何命令行 AI 编程工具也能从文章里看到这类工具的运行逻辑以及什么叫给 AI 立规矩。这篇文章我会按照自己的真实上手路径来写先讲它的设计思路再讲安装配置然后拿一个真实的 Java 小项目完整跑一遍最后把使用过程中踩过的坑和排查经验整理成表。全程没有照本宣科按着我这条路走你大概率能比瞎试少花一半时间。1.1 为什么我盯上了这个项目先说我自己动手之前的处境。我主力用的工具是 Codex CLI在文本生成、单文件改写这类任务上它的表现相当能打。可一旦放到真实项目里问题就很明显AI 经常不知道当前项目的代码结构需要我把关键文件一份份手动粘进会话里改完代码之后不做编译检查直接把带着语法错误的代码丢给我碰到跨多文件的改动时它会按自己的脑补乱改一通有时候把毫不相关的模块也顺手优化了。这些问题不是模型能力的问题而是工作流的问题。模型本身像一个天赋很高但缺乏纪律的新人程序员你给它一个模糊任务它容易自由发挥你给它一套明确的流程、标准和检查清单它的输出质量会稳定很多。superpowers 做的就是把流程、标准、检查清单固化下来在每次会话开始的时候注入给模型。所以我当时的目标很简单能不能让 Codex CLI 在我熟悉的工程流程里稳定地输出像样的代码。superpowers 就是冲着这个目标来的工具。1.2 它的核心概念给 AI 编码代理立规矩superpowers 的名字虽然张扬但骨架非常朴素。我理解下来它由三层东西组成一套模块化的提示词库。不同任务写单元测试、重构、修 bug、写文档对应不同的提示词路径AI 在动手前会加载相应的规则和范例。一套任务定义与路由机制。你告诉它任务类型和目标仓库位置它自动决定该注入哪些上下文、按什么顺序执行。一套技能包Skills系统。技能包可以理解为针对特定场景的增强插件比如 Java 项目特有的编译检查规则、Spring Boot 项目的分层约定等。这三层组合起来的效果是每次会话不再是一场毫无准备的自由聊天而是一次带着作战手册的定向任务。后面我会逐个拆开讲。2. 设计思路为什么我们需要一个增强层2.1 模型不会主动遵守工程纪律这几年我用过不少 AI 编程工具一个特别深的感触是模型的能力上限和它实际表现出来的水平之间差距大得惊人。同样的模型在正确的提示框架下能写出结构清晰、考虑边界条件的代码在糟糕的提示下它只会机械地堆功能完全不管项目里的既有约定。举个例子。我接手过一个内部工具项目代码风格是老派的 Java 8 加大量 Lombok异常处理用自定义的 BizException全局有统一的 Result wrapper。直接让 Codex CLI 改里面的一个接口它第一版就给我返回了 Java 17 的 record 语法还自作主张把 Result 结构改成了它觉得更合理的样子。这种问题的根源不在于模型笨而在于它不知道你的项目规则。它默认按训练数据里最常见的风格输出而训练数据里的风格是模糊的大杂烩。你如果不把规则显式喂给它它就只能在通用风格上瞎猜。superpowers 的解决思路就是从根本上改变信息注入的方式。它不再是你在对话框里临时粘贴几段规则而是在任务开始前通过一套固定的加载流程把项目上下文、编码规范、任务类型对应的操作步骤全部注入到会话里。模型的角色从一个接收零散指令的生成器变成了按照既定 SOP 执行的工程师。2.2 增强层到底在增强什么我用了一段时间后把 superpowers 的价值总结成三个词一致性、可迁移性、可审计性。一致性指的是输出风格。同一套提示词模板意味着同一个项目、同一类任务无论你什么时候发起AI 的执行路径都是接近的。这在工作交接或者隔几天继续旧任务时特别重要不会出现上周写的代码和这周写的代码像两个人写的这种状况。可迁移性是指当你把一套技能包从 A 项目带到 B 项目时只要 B 项目的技术栈和工程约定与技能包匹配AI 的表现就能快速复制。我不需要为每个新项目重新手写一大堆提示词。可审计性则体现在执行过程上。因为 AI 的行为被模板约束了它会按步骤输出——比如先分析改动影响面再列修改清单再逐文件实施最后给出验证方案。每一步都有迹可循出问题时你能定位是哪个环节丢了信息而不是对着一段莫名其妙的代码发呆。3. 安装与初始化从零开始跑起来3.1 环境准备先装好这三样在动 superpowers 之前先把基础工具备齐。我用的环境是 macOSLinux 和 WSL 下的操作基本一致Windows 原生终端理论上也能跑但建议还是用 WSL省得碰路径和权限问题。Git这个不用说clone 项目、管理技能包更新都需要。Node.js 和一个包管理器我本机是 Node 20 LTSnpm 或 pnpm 都行。superpowers 这类工具大多用 Node 生态做脚手架先备好不会错。Codex CLI 或你打算让它增强的目标 AI 编码工具我以 Codex CLI 为例因为它和 superpowers 的配合度最高。如果你用的是其他工具确认它支持外部提示词注入和命令行调用即可。这些我都提前弄好了所以安装过程没花多少时间。3.2 具体安装步骤我的实际操作路径分三步。第一步把仓库拉到本地。我不喜欢全局散落各种文件所以把它放在了一个专门的工具目录下方便统一管理版本git clone superpowers仓库地址 ~/tools/superpowers cd ~/tools/superpowers第二步安装依赖并初始化。不同版本可能略有差异这一步的核心是让工具自己把依赖装好、把默认配置生成到位npm install npm run init第三步也是最关键的一步把 superpowers 接入 Codex CLI 的配置。我这边是编辑 Codex CLI 的配置文件在启动时让它加载 superpowers 提供的提示词目录和技能包路径。具体文件名和格式因版本而异我实际操作时是直接参考工具初始化后输出的提示把一段加载配置加进去。提示初次安装时建议先跑一遍自带的示例任务确认链路通了再往自己的项目里接。我一开始跳过这步直接上真实项目结果排查了半天还以为是配置问题后来发现只是基础链路没打通。3.3 初始化后的目录结构安装完你会看到一个清晰的目录结构。我当时的目录长这样superpowers/ ├── config/ │ ├── default.toml # 全局默认配置 │ └── projects/ # 按项目保存的覆盖配置 ├── prompts/ │ ├── plan.md # 任务规划阶段提示词 │ ├── implement.md # 实施阶段提示词 │ ├── review.md # 自查阶段提示词 │ └── skills/ # 各技能包目录 │ ├── java/ │ │ ├── rules.md │ │ └── templates/ │ └── cleanup/ │ └── rules.md └── skills/ ├── registry.json # 技能包注册表 └── java-compile-check/ # 示例技能包prompts 目录那一堆 markdown 文件就是给 AI 读的军规。config 目录则是给工具本身读的参数。我后来做自定义时80% 的时间都在改 prompts 和 skills 里面 md 文件的内容。这种用文本承载规则的设计我很喜欢因为它不需要你理解什么编译原理写 markdown 就行所见即所得。4. 核心能力与模块拆解4.1 提示词模板体系AI 的执行剧本提示词模板是 superpowers 最核心的资产。它的逻辑不是简单的一句请帮我写好代码而是一整套按阶段划分的执行剧本。拿 implement.md 来说它规定了 AI 在写代码阶段必须经历的步骤先复述理解到的需求再列出涉及的文件清单然后逐个文件给出修改方案实施完以后要做一次自检。每一步的指令都是明确的、可执行的不是尽力而为那种空话。我自己用下来感觉这套模板最有价值的地方在于强制了先规划后动手。以前我直接问 Codex CLI 一个功能改法它经常直接甩出代码思路是什么、改哪些文件、影响谁全靠我事后从代码里反推。有了模板之后AI 会先输出一段规划说明我能在它动手之前就判断思路对不对。如果方向偏了直接在规划阶段打断远比等它写完再返工省事。如果你需要对模板做定制我建议先从最简单的地方入手——改项目描述。在配置里把项目简介、技术栈、目录说明写清楚AI 对项目的理解立刻不一样。这个前置投入非常值。4.2 技能包与任务路由技能包这个概念我理解成特定场景下的 SOP 集合。每个技能包里有一套规则说明和若干可复用的代码片段模板AI 在任务开始时根据任务描述自动匹配并加载对应技能包。举个例子java-compile-check 这个技能包关注的是编译期问题。它会要求 AI 在生成代码后主动检查 import 是否缺失、泛型是否正确、有没有使用项目未引入的依赖坐标。对我来说这相当于给 AI 配了一个专职的编译前置检查员。任务路由机制也很有意思。你发起会话时描述了任务类型superpowers 会根据关键词和项目配置选择优先级最高的技能包。修 bug 的任务会加载调试相关的排查清单新写功能的任务会加载代码规范和结构要求写测试的任务会加载测试框架的规则。它有点像一个分诊台先判断你挂哪个科再让对应科室的医生接手。我个人建议刚上手时不要贪多先装两个跟当前项目最相关的技能包用熟。技能包装多了AI 在匹配路由上会多出一些选择成本有些任务的反应速度反而变慢。4.3 多语言场景Java 项目里的表现这次分享我特意选了 Java 项目做实操因为 Java 项目对 AI 来说其实是相对难处理的类型类型系统严格、框架约定多、旧项目技术栈往往偏老。如果 superpowers 能在 Java 老项目上立住那它在别的语言上的表现基本不用担心。我在 Java 项目里主要依赖了两类能力。第一类是静态结构感知superpowers 的技能包会引导 AI 先读取 pom.xml 或 build.gradle确认项目实际依赖了哪些库再结合源码里的包结构判断代码风格。第二类是构建反馈闭环它把执行 mvn compile 来验证写进了规则AI 改完代码后会主动提议或直接执行编译命令而不是把验证交给用户。这两类能力叠加的效果非常明显。以前用 Codex CLI 改 Java 代码十个改动里总有六七个存在编译层面的小问题需要我来回贴错误信息。引入后AI 自我纠正的比例大幅上升我可以把精力留给真正的设计决策。5. 实操记录让 superpowers 改造一个 Java 仓库5.1 任务背景与目标我拿一个手头的小 Java 服务做实验。这个服务是老代码了Spring Boot 2.xJava 8依赖管理用的是 Maven。模块结构是常见的 controller-service-mapper 三层但历史包袱不小有些 service 类超过八百行异常处理不一致部分接口没有事务边界。我设定的任务是重构其中一个订单查询接口要求保留对外参数和返回结构不变把业务逻辑拆分到独立的 service 方法中并补充基础的异常处理。这个任务跨两三个文件涉及对既有逻辑的理解挺适合用来观察 AI 的表现。5.2 完整操作流程我按 superpowers 推荐的使用方式先建立一个任务目录或直接在一个干净的会话里描述任务。我的输入大致是这样任务类型重构 目标仓库~/projects/order-service 模块范围OrderController / OrderServiceImpl 任务说明 重构订单详情查询接口。要求保持对外参数和响应结构不变。 将 OrderServiceImpl 中查询详情的长方法拆分至少拆出参数校验、数据组装、结果转换三个子方法。 统一使用 BizException 和 Result 包装返回不再直接返回 null。 验证方式mvn -q compile然后观察 AI 的执行过程。按照我加载的 implement.md 模板它先是复述了一遍任务理解列出了涉及文件和当前方法的调用关系然后输出拆解方案还标出了拆出来的三个子方法大致放哪些逻辑。这一步大概花了不到一分钟输出比我想象中完整。我确认思路没问题之后它开始动手改代码。印象比较深的是它在改造 OrderServiceImpl 的时候保留了原有方法上的注释没有像以前那样把注释和代码一起重写说明技能包里的最小改动原则确实起了作用。改完后它没有直接说搞定而是真的执行了 mvn -q compile。第一次编译报了三个错误都是它新增的子方法里引用了未声明的方法参数它自己读取错误信息后修正了再次编译通过。整个过程我没贴一次编译报错这在以前不太敢想。5.3 输出结果与前后对比我特意把这次的输出和之前手动用 Codex CLI 改同类代码的情况做了个对比差距非常直观。对比维度无 superpowers 时有 superpowers 时是否先列改动方案偶尔且经常不完整固定先输出规划和影响面分析是否保持既有代码风格不稳定容易引入新语法严格按项目技术栈约束输出编译验证基本靠用户手动执行AI 主动执行并自主修复多文件改动相关性容易改动无关模块严格限定在任务清单内任务完成后的总结简单一句已完成输出改动清单和验证结果这个对比不是说 superpowers 用了什么魔法它只是把以前需要我反复叮嘱、反复纠正的隐性知识变成了 AI 每次都遵守的显式规则。模型还是那个模型但输出质量上了两个台阶。6. 踩坑指南与常见问题速查6.1 环境与安装类问题我在这阶段踩的坑不算少整理成一张速查表都是实际遇到过的情况。现象可能原因解决办法安装后运行报找不到命令Node 版本过低或未将 bin 目录加入 PATH升级 Node 到 18用绝对路径或重新配置 PATHCodex CLI 会话里加载不到规则配置文件路径写错或模板目录被移动检查配置文件是否存在确认相对路径还是绝对路径技能包不生效技能包未注册到 registry.json或项目配置没写对打开 registry.json 检查注册项确认项目配置关联了对应技能包初始化命令执行中断网络原因或权限不足确认能正常拉取依赖避免放在系统目录下安装安装阶段我最大的教训是不要抄网上旧版本教程里的路径配置。这个项目更新节奏不算慢目录结构和配置项时不时会变照着老博客写路径很坑。最靠谱的方法是让初始化命令自动生成配置然后在默认配置基础上做小幅修改。6.2 使用过程中的问题与调整心得用了一两周之后我遇到了几类使用层面的问题比环境问题更值得一提。一个典型问题是技能包打架。我最早一次同时加载了代码规范、单元测试和性能优化三个技能包结果 AI 在改一个普通接口时既想补测试又想做性能优化最后方案变得很臃肿。后来我的做法是日常开发只加载职责匹配度最高的一个主技能包加一个辅助技能包其他按需在任务描述里手动指定。另一个问题是模板过于死板。默认模板对小型改动来说显得有些重改一个变量名也要输出规划、清单、验证。我后来调整了模板的触发条件在任务配置里定义小改动类型走简化流程。这个自己改一下 md 里的条件判断就行不难。还有一点是关于模型的选择。旧模型或者参数较小的模型在执行复杂技能包时容易顾此失彼记住编码规范但忘了执行编译验证。有条件的话尽量用当前主流的旗舰模型来跑差距不是一点半点。6.3 几条反复验证过的独家心得最后分享几条我踩过多次坑之后总结出来的心得算是给后来者的小礼物。第一项目描述写得越具体效果越好。我第一次只写了订单服务AI 对项目的理解相当模糊。后来我把技术栈、包结构、关键约定、模块职责全部写进去输出质量立刻提升。这个过程很像带新人你把背景交代得越清楚他干活的偏差就越小。第二不要跳过验证环节。superpowers 执行完任务后我会习惯性扫一眼改动清单和编译结果但不会像以前那样从头到尾查一遍逻辑。把精力留给真正需要人判断的点这是引入这类工具最大的收益之一。第三模板和技能包要持续迭代。没有一套通用配置能适配所有项目我的做法是每完成一个任务如果发现 AI 在某类错误上重复踩坑就往对应的规则文件里补一条注意事项。一个月下来规则文件从最初的默认状态被我养成了适合自己团队习惯的版本。这个积累过程很有价值因为它沉淀下来的是团队知识不是模型自己的偏见。我个人的使用体会是superpowers 这类工具最大的意义不是让 AI 一步到位写出完美代码而是把让 AI 干活从一次性的偶然成功变成稳定持续的可复用能力。它不会替你做架构决策也不会突然理解你的业务但它能确保 AI 每次都按你们团队认同的方式做事。这个过程需要一点点调教但调教出来的东西是真正能跟着你换项目的。
