最近一段时间我身边不少搞开发的朋友都在讨论 AI 编程代理日常写代码、赶需求、补测试的效率确实提上来了不少。但用一阵子你会发现这些工具用起来总是差一点顺手的感觉同样一个问题别人能用它半小时搞定一整套需求闭环你却在反复改提示词、调上下文、等它理解我的项目结构。这就是我写这篇 superpowers 使用指南的原因——我在实际项目中把它接入 Codex 的日常流程跑通了包括 Java 项目在内的好几套工作场景这套组合拳解决了我最头疼的AI 不懂上下文和重复劳动还得自己做的问题。如果你也是重度使用 AI 辅助编程的开发者想省下那些来回纠错的无效时间这篇东西应该能帮你把工具真正用到点子上。1. 整体设计与思路拆解1.1 为什么会出现 superpowers 这类增强工具先聊聊背景。AI 编码代理像 Codex CLI 这类工具本质上是一个能调用命令行、能读写文件、能尝试自己解决报错的智能体。它很强但在真实项目里有两个明显短板。第一个短板是上下文饥饿。AI 代理拿到的是一个自然语言指令但你的项目可能有一百个文件、三套依赖、一堆历史约定它只能通过有限的文件搜索和代码浏览来猜测你想要的方案。结果就是它在小任务上表现惊艳一旦涉及跨模块改造、多阶段流程就容易答非所问或者给你生成一套看起来很对但编译不过的代码。第二个短板是流程弱。它擅长单点执行但不擅长按你的工程规范一步一步来——比如你要求它先写设计文档再生成接口再补测试最后跑一遍构建它往往只做最后一步前面全跳过了。superpowers 这类项目就是冲着这两个痛点来的。它的核心思路非常务实在 AI 编码代理外面加一层工程化外壳。这层外壳替你完成了三件事——把项目上下文结构化地喂给 AI、把常用工作流固化成可复用的任务模板、按语言和框架预置好一套该做的事和该避的坑。我最初接触它时以为又是个提示词合集实际用了才发现它做的是更像装配线的事你只需要说一句按规范落地这个登录模块它会自动把需求拆解、文件定位、实现步骤、自测清单全部准备好再让底层的编码代理去执行。换句话说superpowers 管的是怎么干活的事编码代理管的是动手的事两者一配合整个开发节奏就顺了。1.2 它和 AI 编码代理的分工逻辑要理解 superpowers得先接受一个前提它不是一个独立的 AI 模型也不是替代品而是一个协调者和增强层。打个生活化的比方。AI 编码代理像一个刚入职、聪明但缺乏经验的实习生。你直接给它任务它能干但不一定干得规范——可能漏掉单元测试可能不遵循你们项目的分层结构可能做到一半发现方向错了。superpowers 则像你提前给这位实习生准备的一套工作手册标准作业流程SOP 检查表。它不亲自写代码而是确保实习生每一次动手都有清晰的依据、路径和质量标准。具体到实现上superpowers 通过几层机制发挥作用指令注入在每次会话开始时把项目的结构、语言偏好、框架规范、常用命令注入到上下文中让 AI 代理开局就懂规矩。工作流编排定义一套从需求到实现的流水线比如需求分析 → 技术方案 → 编码 → 自测 → 交付说明每个环节定义好输入输出和检查点。技能库内置一批针对不同场景的技能比如 Java Spring Boot 项目的脚手架生成、JUnit 测试补齐、MyBatis 映射排查、REST 接口规范自检等。你跟它说用 superpowers 生成个 Spring Boot 模块它就知道该往哪些文件里放什么。这套设计带来的直接收益是你不再需要当提示词工程师。过去你要花很多精力告诉 AI项目用什么框架、目录在哪、编码风格是什么现在这些信息被 superpowers 通过配置和工作流自动补全你的指令从几段长文本变成一句话意图剩下的交给工具链。1.3 多语言支持的设计考量很多类似的工具做出来只适合 Python 或 Node 项目superpowers 让人眼前一亮的是它对Java 这类传统企业级语言也做了完整支持。这里面的难点在于Java 项目的上下文复杂度比脚本语言高很多有 Maven 或 Gradle 的多模块结构有 Spring 容器带来的隐式依赖有各种注解和配置文件的联动。如果增强层只是简单地把项目目录文本塞给 AIAI 根本看不出这个类是 Controller、那个类是 Service、注入关系在哪定义。superpowers 的做法是为 Java 单独设计了一套结构和语义提取规则它能识别 Maven 工程的坐标、识别 Spring Bean 的装配方式、定位资源目录与配置文件把这些信息整理成 AI 更容易理解的结构化项目简报。这就是为什么很多 Java 开发者也在用——因为它是真的站在你的项目结构上思考而不是空谈代码生成。2. 安装与环境准备2.1 环境要求先确认你的底座在动手装 superpowers 之前我建议你先确认一下本机环境避免装到一半踩坑。结合我自己的体验和团队同事遇到的问题整理了一份启动检查清单检查项最低要求我的建议操作系统macOS / Linux / WindowsWSL 或 Git Bash日常开发用 macOS 或 Linux 最省心Node.js18.0 以上建议用 20 LTS 或更高版本版本太低会有兼容问题AI 编码代理已安装并登录 Codex CLI或其他兼容代理确认能在终端里正常发起会话Git2.30 以上部分工作流会用到 git 操作网络可正常访问 AI 模型 API这一步卡住的人最多后面会细说这里特别提醒一下 Node.js 的版本。我第一次装就是在一个比较老的 Node 16 环境里结果安装成功但运行起来一直报语法错误。后来查了文档才发现它用到了一些新版语法Node 16 根本不吃这一套。所以如果你还没升级 Node先花十分钟升级别在这儿浪费时间。2.2 安装步骤与验证superpowers 的安装方式非常常规走 npm 全局安装就行。完整步骤如下升级 Node.js如果你本机版本偏低 我建议直接用 nvm 管理避免系统级权限问题。安装好后执行node -v确认版本在 20 以上。全局安装 superpowers 在终端执行npm install -g superpowers如果你的目录权限不足可能需要加上sudo但我个人更推荐用 nvm 或 n 这类版本管理器安装 Node这样就不存在权限问题了。验证安装 安装完成后执行superpowers --version能看到版本号就说明 shell 层没问题。接着执行superpowers --help这时候会列出可用命令比如 init、list、agent、skill 等说明主程序已经跑起来了。初始化工作区 进入你的项目目录执行superpowers init这会在项目下生成一个.superpowers/目录里面是配置文件和技能定义。这一步非常关键它会把你的项目注册给 superpowers之后所有工作流才知道往哪里使劲。做完这四步环境就位。我第一次跑通整个流程只花了几分钟比起自己去写一整套提示词和上下文模板效率高得多。2.3 安装后的目录结构说明不少朋友装完就急着用从来没看过生成的.superpowers/里到底放了什么。我建议你花一分钟看一下这个理解能帮你排掉后续一多半的问题。典型的目录结构是这样的.superpowers/ ├── config.json ├── skills/ │ ├── java-spring-boot/ │ │ ├── skill.md │ │ └── templates/ │ ├── code-review/ │ │ └── skill.md │ └── ... └── workflows/ ├── feature-complete/ │ └── workflow.md └── ...config.json项目级配置包括语言框架偏好、AI 代理类型、自定义指令等。skills/技能目录每类技能是一个子目录skill.md里写的是这个技能能干什么、触发条件、执行步骤、输出要求。workflows/工作流目录定义的是从需求到交付的整套流程编排。理解这个结构之后你会发现它其实没有魔法就是把有经验的工程师脑子里装的那些干活套路完完整整地形态化了。你完全可以按自己的习惯去改它、加它。3. 核心功能与实操要点3.1 基本命令与高频操作superpowers 的命令集并不复杂日常用到的主要集中在下面这几类superpowers init初始化项目工作区生成配置目录。superpowers list列出当前项目可用的所有技能和工作流方便你看看自己手里有什么牌。superpowers run skill-name 你的需求描述直接执行某个具体技能。比如你想让 AI 补一批 Java 单元测试就执行superpowers run junit-tests 给 service 层所有 public 方法补单元测试。superpowers agent 任务描述以增强模式启动一次 AI 代理会话先自动加载项目上下文再进入交互模式。后续你所有指令都在项目结构加持下执行。superpowers plan 任务描述这是我最常用的功能之一。它会先让 AI 代理输出一份实施计划包含步骤拆解、涉及文件、风险点你确认后它再开始动手。这个环节极大降低了AI 自作主张瞎改代码的风险。具体到一次实操我举一个相对典型的例子我需要给一个旧的 Java 服务加上新的 REST 接口。直接用 Codex 的话它可能只会创建一个 Controller 类然后丢下一句请自行补充 Service 层。但用 superpowers 的流程就不一样了。我是这样操作的superpowers run java-api-builder 为用户模块新增接口根据 userId 查询用户详情返回统一响应格式执行以后superpowers 会自动加载项目上下文梳理出Controller、Service、Mapper、DTO、统一返回类它们分别在哪个包下面然后按工程规范生成一套完整的代码改动新建接口、实现类、DTO、异常处理、单元测试最后还会跑一遍 Maven 编译验证。这些步骤不是 AI 临时发挥而是技能模板里定义好的标准流程。整个过程中我几乎不需要额外补充提示词只需要在它完成后做一个 review。3.2 Java 项目的落地实践既然热词里出现了superpowers java我重点展开 Java 这一块因为我实际用的主要是 Java 技术栈踩过的坑和沉淀的经验也更具体。先说结论superpowers 对 Java 项目最大的价值不是能生成代码而是它能自动理解 Maven/Gradle 工程、Spring 容器、分包规范这几座大山。这一点对 AI 编程代理来说是质的提升。我第一次在 Spring Boot 项目里跑它时观察到一个细节它生成的代码里Autowired的注入是放在构造器里的而不是直接往字段上怼Autowired这个习惯一看就是懂工程规范的人写出来的。后来我去翻了技能模板发现里面确实有优先构造器注入 final的约束。这种代码风格层面的控制靠你自己每次写提示词去约束 AI 是很费口舌的而 superpowers 通过技能定义把它固化了。Java 场景里几个我特别推荐使用的技能Spring Boot 脚手架生成你跟它说生成一个用户管理模块包含基础 CRUD 接口它会按 controller-service-mapper 三层结构创建并生成配套的 DTO、VO、统一异常处理。JUnit 测试补齐它会扫描现有代码把没有覆盖的 public 方法找出来生成规范的单元测试。关键是它生成的测试不是空跑一团糊弄而是会 mock 依赖、构造边界数据、断言业务逻辑。Maven 构建问题排查当你把 Maven 编译报错抛给它时它不只是看错误信息本身还会检查pom.xml的依赖树、模块间的引用关系给出真正能落地执行的修复建议。有一个经验我觉得值得单独拎出来说让 superpowers 干活前最好先确认项目里执行mvn compile是能通过的。如果项目本身处于编译失败状态AI 代理会被一堆报错带偏技能再强也白搭。我在一个大接口改造中踩过这个坑后来养成了改造前先跑一遍全量编译的习惯问题少了很多。3.3 工作流编排与一键干活体验workflow是 superpowers 里比较进阶的能力也是它拉开与其他工具差距的地方。简单说工作流把多个技能串成一条流水线你只要说一次需求它就会按流水线推进。我举一个实际用过的场景新需求交付规范。我给它初步定义了一个流程口令是superpowers run workflow:feature-complete 为新用户模块实现注册登录功能。然后它按流程依次执行需求解析把注册登录拆成注册、登录、鉴权、校验等子任务。技术方案结合项目现有架构Spring Security JWT生成方案说明并列出影响到的文件清单。实施编码按依赖顺序依次实现实体、接口、服务、安全配置。测试自检生成或补全 JUnit 测试并执行mvn test验证。交付说明整理变更摘要、依赖变更、接口文档、注意事项。这套流程跑完一遍之后我再也不用在提示 AI 写代码和检查每步结果之间反复横跳。它本质上把不少团队要求的开发工序变成了可重复执行的自动化环节。对我这种既要写代码又要兼顾项目推进的人来说省下的精力相当可观。当然工作流不是定义一次就万事大吉的。你需要在实践中不断调整每个环节的检查项比如你们团队有额外的代码风格规范那就往对应的 workflow 配置里加一步执行 SpotBugs 规则扫描。这个过程很像调教一个不断变好的自动化同事值得投入。4. 配置详解与扩展技巧4.1 配置文件核心项解读前面提到的config.json是 superpowers 的大脑配置中心。下面是一个简化版的配置示例我标了注释方便你理解每项的作用{ agent: { type: codex-cli, modelPriority: [gpt-4o, o4-mini] }, language: java, framework: { branch: spring-boot-3, build: maven }, injection: { projectBrief: true, directoryTree: true, recentChanges: true }, workflow: { default: feature-complete }, customInstructions: [ 所有 API 返回统一使用 ResultT 包装, Controller 层不允许出现业务逻辑, 数据库访问层必须使用 MyBatis 的 Mapper 接口 ] }这里有几个关键点值得展开。agent.type决定了 superpowers 底下挂载的是哪款 AI 编码代理目前兼容性最稳的还是 Codex CLI。framework.branch区分 Spring Boot 2 和 3 很重要因为两代的依赖和写法差异不小配置错了我遇到过AI 用 jakarta 命名空间生成代码、项目还在用 javax的情况。injection控制的是每次会话要往上下文里注入什么。默认开启projectBrief和directoryTree没问题但recentChanges在超大项目里会消耗不少 token如果你用的大仓库动辄几千文件建议按需关闭。customInstructions是项目规范的一锤定音之处。不要小看这几行字它比你在对话里重复一百遍注意统一返回格式都管用因为它是每次会话都会自动加载的项目级约束。我强烈建议你把团队编码规范里最容易被 AI 违反的几条写在这里比如禁止空指针裸奔、禁止在循环里查库等长期下来效果非常明显。4.2 如何自定义一个技能如果内置技能满足不了你superpowers 允许你写自定义技能。这个能力的本质是把你觉得 AI 该按什么流程做事固化成一个可复用模板。我以新增一个导出 Excel 功能为例给你展示一下技能的基本写法。在.superpowers/skills/excel-export/下创建skill.md--- name: excel-export description: 为 Spring Boot 项目生成 Excel 导出功能基于 EasyExcel包含 DTO、Service、Controller 三层实现。 trigger: 用户要求导出 Excel 或生成导出功能 inputs: - entityName: 要导出的实体类名称 - fileName: 导出文件名 --- # 执行步骤 1. 定位实体类 {entityName}分析其字段和关联关系。 2. 创建导出 DTO继承指定的基础 DTO字段加上 EasyExcel 注解 ExcelProperty。 3. 在 Service 层新增导出方法采用分批查询避免大批量数据内存溢出方法返回 ListExportDTO。 4. 新增 Controller 端点 /export/excel使用 HttpServletResponse 输出流设置好 Content-Type 和文件头。 5. 生成或更新单元测试覆盖空数据与正常数据两种情况。 6. 最后执行 mvn compile 确认编译通过。 # 约束 - 禁止在 Controller 中直接写业务逻辑导出数据的组装必须在 Service 完成。 - 文件流用完必须关闭使用 try-with-resources。 - 日期字段统一按 yyyy-MM-dd HH:mm:ss 格式导出。写完这个文件你执行superpowers list就能看到新增技能。以后只要输入superpowers run excel-export 把订单表做成导出功能它就会按这份标准流程干活。这个扩展机制是我觉得 superpowers 最值得投入学习的地方。它的学习成本并不高——本质上就是把你自己平时做某类任务的 check-list 用 markdown 写下来但收益是长期稳定的工程质量一致性。如果你在一个团队里你甚至可以把你们组内的各类开发规范都沉淀成一套技能库新成员入职直接复用这套团队经验包。4.3 多项目与团队协作配置如果你是个人使用单项目配置就够了但如果你跟我一样要维护多个项目建议把通用规范抽出来避免每个项目重复劳动。superpowers 支持在用户主目录下放一个全局配置比如~/.superpowers/config.json里面放你对所有项目通用的规则比如所有代码必须包含中文注释、提交信息必须带模块前缀等。而项目级的.superpowers/config.json用来放这个项目特有的规则优先级更高。这样项目特性和个人习惯就分层管理了。团队协作时我建议把.superpowers/目录提交到 Git 仓库。技能和工作流本来就是团队规范的一部分放到代码库里大家拉下来就能直接用同一套流程。唯一的注意点是不要把你本机的 API 密钥、私人路径写进任何配置文件凡是涉及私密信息的内容用环境变量或单独的本地文件去传别污染团队仓库。5. 常见问题与排查技巧实录5.1 安装或启动报错安装这块的问题相对集中我按频率排列一下我遇到和听说的superpowers: command not found一般是 npm 全局 bin 目录没有加到 PATH。用 nvm 的情况下检查一下 Node 安装路径如果是从官网装的确认全局安装前缀把$(npm prefix -g)/bin加进 PATH。运行时报Unexpected token ?之类的语法错误基本可以断定是 Node 版本太低。superpowers 用到了较新的语法Node 18 以下会有问题。升级到 Node 20 LTS 基本解决。Windows 环境下命令无法直接执行我最早在 Windows 上原生跑遇到 shell 脚本兼容性的问题。后面改用 WSL 或者 Git Bash 就顺畅了。如果你也是 Windows 用户强烈建议直接上 WSL 开发环境别在 PowerShell 上死磕。权限不足导致安装失败报 EACCES 错。优先方案是用 nvm 重装 Node实在不行再用 sudo 安装但注意后续全局模块的权限问题会一直伴随你。5.2 与 AI 代理连接失败这一步是工具没问题但跑不起来的重灾区。现象通常是启动 superpowers 后它尝试调底层 AI 代理但长时间无响应或者直接报连接错误。排查顺序我建议如下确认底层的 Codex CLI 本身能独立工作直接在终端里跑一次codex或者发起一个简单会话看它是否能正常返回。如果它本就调不通问题不在 superpowers。确认 API 认证和配额看看密钥是否过期、余额是否不足、当前组织有没有访问权限。这一步很容易被忽略——很多时候不是技术问题是没钱了。检查模型参数配置如果你在配置里把某些参数调得过小比如最大 token 数太低复杂任务的上下文可能被截断表现成执行到一半莫名其妙停下。适当调高maxTokens或者换更长的上下文模型。看日志superpowers 一般会在.superpowers/logs/下输出运行日志。卡住的时候打开最新日志能直接看到它卡在哪一步、底层返回了什么错误信息。5.3 Java 项目使用中的典型问题Java 场景的问题往往比安装问题更隐蔽这里分享几个高频的生成的包名和路径对不上多发生在模块化工程里。项目实际路径可能包含一层模块目录但 AI 只看文本结构时容易忽略。解决办法是在配置里把sourceDirectories明确写出来或者在 customInstructions 里补充一句所有新文件必须放在 xxx-module 模块下。Spring Boot 2 和 3 的 javax/jakarta 混乱现象很典型——生成的代码用了javax.persistence但项目实际是 Spring Boot 3 Jakarta 规范。这个要靠framework.branch配置去约束别指望 AI 自己猜。测试代码生成后无法通过编译常见原因是 mock 依赖没配全。运行测试时报空指针或者找不到 Bean。我建议在执行测试生成后紧接着让 superpowers 连续跑一遍mvn test把报错回传给它迭代修复通常一两轮就稳定了。Lombok 相关代码看起来对但编译不过AI 生成的实体类使用了 Lombok 注解但可能引入了不存在的依赖或版本冲突。遇到这种情况直接把pom.xml的依赖片段和报错信息一起贴给 superpowers让它基于当前依赖上下文去改而不是让它从零猜。5.4 一个真实的排查现场最后分享一个我从一脸懵到找到规律的真实案例。有一次我在一个老项目中执行任务superpowers 一直报project info incomplete导致所有流程停摆。我起初以为是项目太大导致目录扫描超时后来手动检查才发现项目根目录下的.gitignore竟然把.superpowers/目录给忽略了生成的配置和中间文件根本没被正常追踪部分工具内部依赖文件缺失了。解决起来很简单把.superpowers/从.gitignore里移除或者把这个目录放到用户全局目录而不是项目里。这件事给我的教训是——使用增强工具时先检查它会不会被现有的忽略规则误伤。很多不起眼的小问题根源都在环境对工具视而不见。写在最后的一点实战体会连续用 superpowers 跑了这段时间我最明显的感受是它没有改变AI 写代码这个底层事实但显著改变了我和 AI 协作的方式——我从一个不断解释规则的人变成了设定规则的人把大量项目规范、流程、踩坑经验沉淀成技能模板后每一次新需求都像是在流水线上完成而不是每次从零闯关。这种积累感是我最看重它的地方。最后再分享一个小技巧不要一上来就配一堆自定义技能。先用默认技能把一两个真实需求跑熟确认工具链全通顺之后再逐步把你手头重复率最高的任务逐个固化成技能。用一段时间后你会积累出自己真正顺手的技能库那才是这个工具对你来说性价比最高的时候。工具说到底只是抓手真正发挥作用的是你沉淀下来的那套工程方法。
)
)