superpowers实战：为AI编程助手注入工程化协作能力

如果你最近在终端里用过 Codex CLI 这类 AI 编程助手大概率会有一种感觉它很强但更像一个“听话的实习生”。你每一步都要给它下指令稍不留神它就跑偏让它改个东西它可能把不相干的代码也顺手改了。superpowers 这个项目就是专门来改变这件事的。简单说superpowers 是一套开源的能力增强层目标是把终端里那个只会“一问一答”的 AI 助手变成一个具备职业习惯的协作者。它通过技能Skill、子代理Subagent和工作流Workflow三件套把“AI 编码”从一次性的对话聊天升级成一套可以复用的工程流程。你可以把它理解为给 AI 装上一本“团队规范手册”什么时候该先写计划、什么时候该写测试、什么时候该问你要上下文都由你预先定义好而不是让它自由发挥。这篇文章不是官方的文档翻译而是我实际折腾下来的使用总结。我会从它的设计思路讲起再到安装、配置最后用一个 Java 项目实战场景演示完整流程顺便把踩过的坑一并列出来。不管你之前用过 Codex、Claude Code 还是其他终端 AI 工具只要你受够了“重写对话”“反复纠偏”的体验这篇文章都值得你花十分钟看完。1. superpowers 到底是什么给 AI 编程助手装上“职业习惯”1.1 为什么普通对话式编程不够用先聊一个最底层的问题为什么默认状态下的 Codex CLI 这类工具用起来总觉得别扭因为它的默认行为是“单轮问答优先”。你让它写一个功能它会直接写你让它改 bug它也会直接改。这在简单需求下问题不大但一旦面对真实项目麻烦就来了。真实项目有约束有现有的代码风格、有需要兼容的老接口、有不能动的模块边界。默认模式的 AI 看不到这些它只会根据你当前这句话的上下文猜测然后给出一个“看起来合理”的方案。我举一个实际例子。有一次我让它帮我重构一个 Java 类的方法签名它确实改了但连带把三个调用点也改了。表面看没问题。可那三个调用点里有十个调用方其中两个是跨模块的它根本没搜到。结果编译过了运行时线上报错。这种“局部正确、整体失控”的问题就是对话式 AI 的典型短板。superpowers 想解决的就是这件事。它的核心主张是不要指望 AI 靠“智能”去猜而是给它一套明确的流程和角色分工。就像一个新员工入职你不能指望他看一眼代码库就懂公司规范你得给他培训手册、给他上级、给他标准作业流程。superpowers 就是那套培训手册。1.2 superpowers 解决的核心痛点具体来说这套增强层主要针对四个痛点上下文管理混乱默认情况下AI 能记住的对话内容有限项目稍微大一点它就“失忆”了。superpowers 通过技能文件把关键项目信息、编码规范、文件结构在你需要时显式加载到上下文里。缺少计划意识直接上手写代码不如先写方案。superpowers 内置了“先计划后执行”的工作流模板让 AI 在动手前先列出改动点让你确认后再干活。角色不清晰你希望 AI 有时像架构师、有时像测试工程师、有时像代码审查员。默认工具不区分角色。superpowers 的子代理机制允许你定义多个专业角色按需调用。复用性差你在项目 A 里总结出来的好 prompt项目 B 里没法直接用。superpowers 把这类经验固化成技能文件跨项目复用。这四个痛点说到底是一件事AI 工具缺少“工作方法论”。superpowers 的定位就是给 AI 补上这套方法论。1.3 它适合谁不是所有人都需要 superpowers。如果你只是拿 Codex CLI 写点脚本、做点一次性任务那这个项目对你来说反而增加了负担——你得先学会它的配置规则。但如果你是下面这类开发者我会强烈建议你试试主力用终端 AI 工具写业务代码项目规模在中等以上代码文件超过几十个。团队里多人共用 AI 编码工具希望大家的产出风格保持一致。你在重复性任务上花了很多时间想把“标准操作流程”交给 AI 执行。你曾经写过很长的 prompt但发现换个项目就失效想要一套可沉淀的模板机制。我自己属于第一类和第三类的混合体。用上之后最直观的感受是我不再需要每次对话把项目背景重新讲一遍了。技能文件一加载AI 自己知道这个项目用 Java 17、Spring Boot 3.2、不允许 Lombok、测试必须用 AssertJ。这些约束我之前每次都要打一遍现在它自己就清楚。2. 核心设计拆解技能、子代理与工作流2.1 技能SkillAI 的可复用操作手册superpowers 中最基础的概念是 Skill技能。一个技能本质上是一个 Markdown 文件通常叫SKILL.md放在约定好的目录结构里。技能文件的格式一般包含两部分开头是 YAML 格式的元信息包括技能的名称、描述、适用场景正文是具体的操作说明。当 AI 需要执行某个技能时它会读取这个文件把里面的步骤当成自己的行为准则。我打个比方。你想让 AI 帮你写 REST API规则是必须包含参数校验、错误码统一、日志埋点这三样。你当然可以在每次对话里手打这些要求但更好的方式是把这些要求写成一份“接口开发技能”告诉 AI 第一步做什么、第二步做什么、哪些是强制约束。之后你只要说“用接口开发技能生成用户模块的 CRUD”AI 就会严格按你定义的流程走。为什么这比普通 prompt 更可靠因为普通 prompt 是“对话内有效”你换一个新会话AI 的记忆就清零了。技能文件是“落盘存储”的它独立于对话存在可以被任何子代理、任何工作流反复调用。这就像你把自己的最佳实践沉淀成了一本书每次需要时直接翻到对应章节而不是凭记忆复述。2.2 子代理Subagent让 AI 学会分工如果说技能是“操作手册”那子代理就是“专业角色”。subagent 可以理解为一个带着特定身份、特定权限集合的 AI 实例。你定义一个“测试工程师”子代理它就专注于写测试、分析测试覆盖。你定义一个“代码审查员”子代理它就专门做 code review且只输出问题和修改建议不会直接改代码。子代理实现上有两种常见方式。一种是独立的 Agent 调用由主代理把任务委派给子代理子代理独立运行并返回结果。另一种是“伪子代理”本质上是切换 system prompt 和上下文工具集让同一个模型扮演不同角色。superpowers 的配置同时支持这两种思路你可以按自己的需要选择。子代理的配置通常也是一个 Markdown 文件里面有角色描述、擅长领域、允许使用的技能、回复风格等。我的经验是子代理设计的关键是“边界清晰”。一个子代理别指望它干所有事就像你不能让测试工程师去解决内存泄漏。把任务切细每个子代理只负责一个明确目标协作效率反而更高。2.3 工作流Workflow从“问答”到“项目执行”技能解决“怎么做一件事”子代理解决“谁来做事”工作流解决的是“事情按什么顺序做”。一个典型的工作流是分析需求 → 写实施计划 → 等我确认 → 拆解任务 → 分派给子代理 → 执行 → 验证测试 → 总结。这套流程看起来不复杂但它恰好是很多开发者日常开发的真实节奏。问题在于默认的 AI 助手不会主动按这个节奏走它更倾向于直接跳到最后一步“开写”。superpowers 里预设了几类工作流模板比如“先计划后执行”和“测试驱动开发”。当你启动一个工作流时AI 会严格按阶段推进每个阶段结束都会停下来向你汇报。这样带来的好处是你始终知道 AI 在干什么关键节点你都有机会干预而不是等它写完一堆代码后才发现方向错了。我用一个生活化的类比来解释工作流的意义。你去餐厅吃饭后厨如果只有一个厨子他既洗菜又切菜又炒菜速度慢且容易出错。但如果后厨有明确分工有人备菜、有人掌勺、有人摆盘那效率和品质都可控。工作流就是后厨的动线设计它规定了每个人什么时候出现、做什么事、把结果交接给谁。2.4 设计理念为什么“限制”反而带来“自由”很多第一次接触 superpowers 的人会有一个疑惑给 AI 加这么多规则和流程不会拖慢速度吗这里我想聊点更深的东西。AI 编程工具带给我们的价值并不仅仅是“生成代码的速度”而是“可预测性”。默认模式下AI 每次输出的质量波动很大——有时候惊艳有时候翻车。当你把技术栈、代码风格、流程节点都固化成技能和工作流之后它的输出质量会从“看运气”变成“看机制”。机制的作用不是限制 AI 的能力而是把不确定性降下来。这就像写字你给一支笔装上了笔套笔尖露出来的部分变少了但正因如此你才能写出更稳的线条。superpowers 是在给 AI 装笔套不是给它戴手铐。3. 安装与基础配置让 superpowers 跑起来3.1 环境准备在开始安装之前先确认你的环境。superpowers 本质上是依附于现有 AI 编程助手运行的能力包所以你必须先有一个可用的终端 AI 工具。目前社区用得比较多的是 Codex CLI 和 Claude Code 这类原理类似都是通过配置文件加载外部技能。我的建议是先把基础工具跑通再装 superpowers。你至少要满足这几个条件操作系统建议 macOS 或 LinuxWindows 用户最好是 WSL 环境因为后续很多路径、脚本操作在类 Unix 环境下更顺畅。Node.js 18 以上npm 可用。很多自动化子任务依赖 Node 脚本老版本会有兼容性问题。已有的 AI CLI 工具能正常独立工作也就是说你不装 superpowers 时它也能完成基础对话。Git 可用因为拉取项目、更新组件都需要它。我见过有人上来就装 superpowers结果发现自己的 Codex CLI 都没配好折腾半天全是环境问题。先把地基打牢再往上盖房子这个顺序别搞反。3.2 安装步骤安装方式通常是把开源仓库克隆到本地然后把核心目录链接到你的 AI 工具配置目录下。不同工具的路径略有差异但思路是一致的。我用一个通用流程演示克隆仓库到本地。我习惯放在~/tools/下面方便统一管理。mkdir -p ~/tools cd ~/tools git clone https://github.com/obra/superpowers.git进入仓库安装依赖并执行初始化脚本。这一步会在你的用户目录下创建技能目录、子代理目录和配置文件。cd superpowers npm install npm run setup根据你的 AI 工具类型把生成的配置目录软链到工具读取的位置。以配置目录下的.superpowers为例把它加到工具的 user snippets 或 skills 路径中。具体路径可以在你的 AI CLI 工具配置文档里找到。ln -s ~/tools/superpowers/.superpowers ~/.codex/superpowers到这里基础安装就完成了。但注意我对具体命令的细节描述基于常见实现不同版本的仓库可能会调整目录名或脚本名。你以 clone 下来的 README 为准核心就是“把项目里的技能和子代理目录让 AI 工具能扫到”。提示安装前先看一下仓库里的目录结构和说明文件。开源项目迭代快名称和路径变了是常有的事。不要死记我这里的路径理解“它需要把能力包放到 AI 工具的认知范围内”这个原理更重要。3.3 验证安装是否成功装完不能直接开用先做个快速验证确认 AI 确实能感知到 superpowers 的存在。验证方式很简单在你的 AI CLI 工具里输入一句类似“列出你能用的所有技能”的指令。如果安装成功AI 会回复你说它掌握了若干技能并说出技能名称和用途。如果它回复“我没有技能”或者表现得很茫然说明路径配置有问题AI 根本扫描不到你的技能文件。另外你也可以直接打开技能目录看看文件是否生成成功。通常你会看到skills/、subagents/、workflows/这几个目录里面有若干个 Markdown 文件。如果安装脚本正常执行这些文件应该已经存在。我第一次安装时就是在这个验证环节踩的坑。我误以为 clone 完仓库就结束了结果 AI 完全感知不到技能。后来发现是因为我的 AI 工具读取的是~/.codex/snippets目录而我软链到了错误的位置。所以说验证这一步千万别省它能在 30 秒内发现问题省得你真开始干活时才发现不对劲。4. 实操在 Java 项目中用 superpowers 落地一个自动化任务4.1 场景设计理论讲再多不如跑一个真实场景。我用最近实际做过的一个 Java 任务来演示。场景是这样的一个 Spring Boot 项目需要新增一个“用户积分”模块包含积分流水查询、积分增减接口、定时清零任务。需求看似简单但项目本身有严格的编码约束这些约束必须被遵守。在这个场景里我要让 superpowers 帮我完成三件事第一根据现有项目规范生成模块代码第二自动补充单元测试第三执行静态检查并汇总结果。整个过程中我不希望自己去手写每个文件也不希望 AI 无视项目规范乱写。在开始之前我先准备了一个项目级技能文件把约束写进去。这是整个实操里最核心的一步。4.2 定义项目级技能文件我在项目的.superpowers/skills/目录下新建了一个spring-boot-module.md文件内容大致如下--- name: spring-boot-module description: 生成 Spring Boot 业务模块代码严格遵循项目编码规范 --- # Spring Boot 模块生成规范 ## 项目技术栈 - Java 17 - Spring Boot 3.2.4 - MyBatis Plus 3.5.5 - 构建工具Maven ## 强制编码约束 1. Controller 层只做参数接收和路由禁止写业务逻辑。 2. Service 层统一使用接口加实现类的方式接口放 service 包实现放 service.impl 包。 3. 所有接口返回值必须使用统一响应体 ResultT禁止直接返回 Map 或裸对象。 4. DTO 命名以 Request 和 Response 结尾禁止直接使用实体类接收前端参数。 5. 时间字段统一使用 LocalDateTime禁止使用 Date。 6. 日志必须使用 Slf4j禁止 System.out.println。 7. 所有写操作必须添加事务注解Service 方法内不得出现嵌套事务调用。 8. 代码注释只保留必要部分拒绝无意义的块注释模板。这个技能文件的核心价值在于“把项目规范文本化”。以前 AI 不知道你的项目用什么框架、有什么编码红线。现在只要你在对话里说“使用 spring-boot-module 技能”它就会把这个文件内容加载进上下文并且当成最高优先级约束来遵守。实际测试下来效果非常明显。它在生成代码时确实没有出现直接返回实体类的问题也没用 Date 类型。而我以前用手打 prompt 的方式驱动它时几乎每次都要在第二三轮才会主动修正这些点。这就是“显式技能”和“隐式期望”的区别。4.3 子代理配置示例技能搞定之后我再配置两个子代理一个负责写代码一个负责审查代码。在.superpowers/subagents/下创建两个文件。第一个是backend-coder.md定位是业务代码实现者--- name: backend-coder description: Spring Boot 业务代码实现专家擅长按规范生成高质量模块代码 --- 你是资深 Java 后端工程师擅长 Spring Boot 项目开发。 ## 你的职责 - 按照指定技能文件中的规范生成代码 - 拆分合理的包结构 - 生成必要的 DTO、Service、Controller、Mapper ## 你的行为准则 - 动手前先列出你要创建的文件清单 - 每个文件完成后做一个简短说明 - 严格遵循项目技能文件中的强制约束 - 不修改与本次任务无关的文件第二个子代理是code-reviewer.md定位是代码审查者只发现问题、不改代码--- name: code-reviewer description: 严格的代码审查专家只分析问题不修改代码 --- 你是代码审查专家关注代码质量、安全性、可维护性。 ## 你的职责 - 审查代码是否遵守项目技能文件中的规范 - 找出潜在的 NPE、事务失效、并发问题 - 指出测试覆盖不足的地方 ## 你的行为准则 - 输出审查意见时按严重程度分组阻断、重要、建议 - 直接指出文件路径和行号 - 不修改任何代码只输出报告这两个子代理配合起来就从“一个 AI 自己写自己查”变成了“写的人写完审的人再审”。这看起来是小事但实际效果差别很大。因为同一个模型如果既是作者又是审查者很容易对自己的错误视而不见。切换一个独立的角色描述后它的“挑剔程度”会明显上升这算是大模型使用中的一个实用技巧。4.4 完整执行流程实录配置完成后我开始实际执行任务。我输入的第一条指令是“启动项目计划工作流。需求新增用户积分模块包含积分流水查询、积分增减接口、每日零点定时清零。使用 spring-boot-module 技能所有代码完成后交代码审查员审查。”这时 superpowers 进入计划模式。AI 没有立刻写代码而是先输出了一段实施计划包括要创建的包结构、实体类、接口设计、定时任务方案以及风险点。我检查了计划修改了两处一是积分增减接口需要支持幂等二是定时任务需要加分布式锁。这些点如果 AI 直接写代码我大概率事后才能发现但现在它在动手前列出来了我提前更正了方向。确认计划后我让它继续执行。AI 按计划先后完成了以下文件UserPointsController.java暴露积分流水查询和积分增减接口。UserPointsService.java和UserPointsServiceImpl.java核心业务逻辑。UserPointsMapper.javaMyBatis Plus 数据访问。PointsExpireScheduler.java定时清零任务并加了Scheduled(cron 0 0 0 * * ?)。对应的 DTO 和统一返回封装。然后它自动调用了测试工程师角色为积分增减服务生成了单元测试覆盖了正常增加、余额充足扣减、余额不足扣减、流水记录写入等主要路径。最后它把代码交给 code-reviewer 子代理进行审查。审查报告里指出了两个重要问题一处是积分扣减时查询余额和更新余额之间没有加锁存在并发超扣风险另一处是定时任务没有幂等保护如果上一个任务还没执行完下一个触发周期到来时会重复处理。这两个问题非常实际相当于帮我做了一次免费 code review。我把这些问题反馈给 coding 子代理修正后模块顺利完成。整个执行过程我不是全程盯着而是在关键节点计划确认、审查报告介入。这比我以前“逐文件手把手教 AI 怎么写”节省了大量精力和时间。5. 常见问题与排查技巧实录5.1 技能没有加载AI 完全感知不到 superpowers这是最常见的问题90% 的情况是路径配置问题。技能文件没被 AI 工具扫描到。排查思路很简单先手动检查你的 AI 工具实际读取的目录路径是什么然后确认 superpowers 的文件确实放在那个路径下。我在 3.3 已经提过一个判断方法直接问 AI 能不能列出技能清单。另一个容易忽略的点是修改配置后要重启 AI CLI 进程。很多工具是启动时加载配置文件运行中途改了不会热更新。我经常改完技能文件忘了重启然后在对话框里反复问“为什么你没反应”。不是 AI 笨是它压根不知道文件已经变了。5.2 上下文溢出技能文件太多AI 记不住技能是好事但物极必反。如果你把一堆技能文件都塞进上下文中AI 的注意力会被稀释反而记不住关键约束。我建议严格控制一次对话加载的技能数量一般不超过 3 个。项目级规范放一个任务级技能放一个最多再来一个通用的代码风格技能就够了。技能文件本身也要精简只保留“必须被遵守”的内容。那些“建议性”的、可有可无的规范就别写了写得越多核心约束反而越不被重视。5.3 子代理执行结果不稳定同样指令两次输出差异大子代理看起来是独立角色但它毕竟是同一个模型输出天然有随机性。这不完全是 bug但如果你希望结果更稳定可以从两个方向优化。一是把子代理的指令写得非常具体减少模糊语义。不要只说“审查代码质量”要说“检查是否有未处理的空指针风险、是否所有新增方法都有测试覆盖、是否有事务边界问题”。指令里包含的具体可验证项越多子代理的输出越可控。二是明确限制子代理的“输出边界”。比如审查类子代理明确说“只输出问题列表不输出解决方案”代码生成类子代理明确说“每个文件单独生成不合并成一个回答”。边界清晰结果就稳定。5.4 安全问题AI 自动执行命令的高风险点superpowers 的强大之处在于它可以调用工具、执行命令、读写文件。这同时也带来了安全风险。我的建议是初期使用时要限制 AI 能执行的命令范围。具体做法是在 AI 工具的系统配置里设置白名单只允许 Maven 和 Git 这些常用命令禁止它执行 curl 下载远程脚本、禁止用 sudo 权限操作系统级文件。这个限制不是不信任 AI而是不给恶意输入任何机会。毕竟 AI 可能会在读取某些外部文件时被注入恶意指令这一点你要有基本的安全意识。5.5 效率变低配置了流程后反而更慢有用户反馈用了 superpowers 后原本一句话能生成的代码现在要先走计划、再审查一整套跑下来觉得更慢了。我的看法是这不一定是坏事。要区分“流程变慢”和“交付变慢”。如果 AI 生成代码的速度是快了但因为方向错了反复返工那总时长反而更长。superpowers 牺牲了几分钟的前期计划时间换来了后期几小时的纠错时间怎么看都是划算的。当然如果你只想快速生成一个一次性脚本就别启动完整工作流直接关掉流程约束就当普通对话工具用即可。工具是死的用法是活的。6. 体验心得与进阶建议6.1 我踩过的坑从“不会用”到“离不开”我刚开始用 superpowers 的一周里因为急于看到成效不对项目做定制化配置直接把默认技能拿来就用。结果是 AI 的表现确实比裸奔好一些但远没有形成质变。直到第二次迭代时我才静下心来为专注的项目写了专属技能文件把项目中那些“血泪经验”类的规范全部文本化。那一刻开始才真正觉得它在帮我变成一个隐形的高级工程师。还有一个教训是技能文件要持续维护。项目规范一旦变更我要求所有子代理和技能文件同步更新这样才能保证 AI 的认知始终符合最新的项目状态。如果把技能文件当成一次性文档那它很快就会过时反而误导 AI。6.2 进阶玩法往“团队级 AI 协同”方向探索如果基础功能你已经玩熟了我建议往更深处探索。一个值得尝试的方向是让子代理之间形成多轮协作。比如先让架构师子代理输出接口设计文档再让编码子代理按文档实现然后让测试子代理补测试最后让审查子代理提出改进意见然后再回到编码子代理循环迭代。这种“多角色流水线”模式已经接近一个小型开发团队的运作方式了。另一个方向是沉淀“公共技能库”。个人维护的技能文件可以复制到团队共享的 Git 仓库里让整个团队通过拉取同一份配置来统一 AI 编码规范。这等于把团队的经验变成一份可版本化的资产新人入职后不再需要靠老人口述学规范AI 可以直接遵守团队统一的编码标准。6.3 一些补充建议如果你想在业务代码之外试试更多场景也可以用它来做更偏工具链的事情比如自动化生成项目文档、维护 CHANGELOG、批量处理代码格式化。无论哪个场景核心方法论都是一样的把你想要的行为模式流程化、文本化、可复用而不是依赖每次对话时临场发挥。我的经验是superpowers 这类能力增强层还有很大的想象空间。它本质上在做的一件事就是把“个人经验”转化为“AI 可执行的结构化资产”。谁沉淀得好谁就能让 AI 工具发挥出十倍以上的价值。工具本身不会让人变强但对工具背后方法论的重视会。