咱们做开发的人应该都有过这种体验手头的 AI 编码助手单看聊天窗口里的表现像个顶级专家可真把任务交给它让它直接上手改代码它就开始放飞自我——改一个文件连带掀翻三个无关模块或者信誓旦旦说“已完成”实际连测试都没跑过。我在本地折腾 Codex CLI、把它接进 Java 项目日常维护时最烦的就是这种“高智商低配合”的状态。后来接触到一个叫 superpowers 的技能扩展体系整个思路一下就打开了与其每次重新组织提示词手把手教 AI 怎么做不如把一整套工作流程、操作规范和技能库直接丢给它让它像经过正规培训的实习生一样知道什么时候该问、什么时候该动手、动手之后怎么验收。这篇文章就把我对 superpowers 的理解、安装配置方法和实际使用心得完整记录下来。superpowers 这个名字很容易让人联想到超级英雄但在这套体系里它做的事其实非常朴素给 AI 编码代理加装“操作手册”。它不是某个编程语言框架也不是独立的 IDE 插件而是一套技能定义和工作流规范依附在主流的 CLI 编码代理之上通过预设的规则文件、技能模块和验收步骤把 AI 的“即兴发挥”变成“按流程办事”。说白了就是给 AI 一个企业级的入职培训包。这篇文章适合正在用或者在考虑用 Codex CLI、类似命令行编程代理的工程师也适合那些已经被“AI 改着改着就失控”折磨得没脾气的人。我会把概念拆透把安装、配置、实战流程都走一遍并且在最后如实告诉你哪些地方容易踩坑。1. 这到底是个什么东西给 AI 编码代理加装的“操作手册”1.1 从一场尴尬的对话说起上个季度我让某个知名编程代理帮我重构一个 Java 模块需求描述得很详细接口名甚至都写在提示词里了。结果它跑了四十分钟输出了一堆“小作文”然后告诉我“重构完成”。我切到终端一看它压根没有执行任何 build 命令所谓的新类连 import 都对不齐更别提测试了。那一刻我突然意识到AI 编码工具的问题不是“会不会写代码”而是“知不知道自己在干什么”。superpowers 体系针对的正是这个痛点。它默认改变代理的执行模式从“用户问一句、代理答一句”的对话模式切换成“接收任务、进入工作流、拆解子任务、执行并自检、最后汇报”的项目模式。你会发现当代理手头有一条清晰的工作流约束时它的行为像换了个人——会主动列出计划会停下来等待关键决策会在提交前执行测试而不是一股脑儿自嗨式输出。这类增强方案之所以叫“superpowers”是因为它把 AI 从“一个聪明的编辑器”提升为“一支遵守纪律的远程开发小队”。它所做的不是提高模型的智力而是压缩信息损耗。你不再需要把项目经理、架构评审、代码评审、测试工程师的职责用大白话翻译给 AI 听因为这些角色的操作规范都被固化成了技能文件和规则说明。1.2 为什么单纯靠“提示词”不够用了每个喊出“提示词工程已死”的工程师大概率都经历过提示词膨胀。我见过有人把系统提示写到几千字从“你是一个资深 Java 架构师”到“改完必须跑 mvn test”事无巨细。副作用很明显上下文窗口被占满、无关信息干扰判断而且每次新开会话这些“祖宗规制”还得重新灌一遍。这种做法的天然缺陷在于人与 AI 的交流通道是线性的。你一股脑告诉它 20 条规则它执行第 3 条任务时可能已经忘了第 14 条约束。superpowers 或者说整套技能体系的做法则是把规则分散到“按需加载”的技能文件里。代理看到任务里出现“单元测试”关键词就自动读取测试技能模块看到“重构”关键词就自动加载重构流程。就像你平时不会背着一整本词典吵架而是说话时只取当下需要的词句。更深一层看大多数 AI 编码事故都出在“角色模糊”上。同一个模型你让它做架构设计它能侃侃而谈你让它直接实现它也可能直接躺平。换句话说模型不知道自己在流程中的位置。工作流规范化之后代理在计划阶段就是架构师在编码阶段就是工程师在验收阶段就是测试人员——角色切换全部由流程控制不再依赖模型自觉。1.3 这套方案能解决什么问题适合谁如果你是个人开发者经常要用 AI 处理一些小而杂的任务比如“把这段日志格式统一”或者“给这个工具类补个单测”那 superpowers 对你是有意义的。因为在没有流程约束的情况下这类小任务反而最容易出大事故——AI 只改了你指定的两行却为了让自己舒服把周边一百行也一并重构了。如果你在团队里负责维护长期项目AI 代理的历史“恶行”不断——乱改公共模块、绕过 checkstyle、提交前不跑测试——那更值得试一试。你可以把团队的编码规范、提交规范、测试规范全部做成技能包任何新成员哪怕是 AI一旦加入就自动按规矩办事。这相当于给团队加了一层质控网。当然这套体系也有受众边界。如果你只是偶尔用 AI 闲聊代码问题从来不打算让它真正接管写代码的任务那 superpowers 对你来说就是杀鸡用牛刀如果你对命令行操作完全不熟连环境变量都还没有彻底搞明白也建议先把基础补一补因为这套方案从安装到日常使用基本上都发生在终端环境里。它适合的是“已经把 AI 编码代理用起来了、只是对结果不满意”的人而不是刚开始接触 AI 编程的新手。2. 整体设计思路拆解把“万能 AI”变成“懂规矩的实习生”2.1 核心套路技能库加规则文件加反馈回路这套体系里最核心的三个组件我按重要性排序技能库、规则文件、反馈回路。技能库是一组结构化的 Markdown 文件每个文件对应一种“能力”。比如write_code.md、run_tests.md、commit_changes.md。关键在命名和索引——代理通过关键词匹配来决定加载哪个技能所以技能文件名必须跟实际操作强相关。实际测试中fix_bug.md比solution_guide.md的触发率高出非常多因为后者这种宽泛命名AI 很难判断什么时候该用。规则文件是指定代理“元行为”的文档。常见的有CLAUDE.md或按所用代理类型命名的工作区说明文件。这里写的是全局约束哪些命令可以执行、哪些目录不能碰、每一步操作之前需要先确认什么、如果发生错误该如何报告。它的角色类似宪法技能文件则是具体法律。反馈回路是这套体系里最容易被人忽略的。定义完流程还不够得让代理在关键节点停下来找人确认。比如 Java 项目里涉及改pom.xml依赖版本的操作代理必须主动罗列版本变更前、变更后的坐标并拒绝执行单元测试集之外的全量集成测试。这种“暂停点”设计就是把 AI 当实习生用不懂就问而不是自作主张。2.2 为什么把技能拆成小文件而不是全塞进系统提示我在刚开始配置的时候犯过一个典型错误就是把所有规范都堆到一个巨大的CLAUDE.md里整整八百行满怀信心地启动了代理。结果任务执行到一半它突然开始主动修改公共工具类还声称这是“为了让代码更规范”。后来复盘发现它根本没有真正记住文件后半段的约束因为上下文被长文本干扰了。技能模块化则完全不同。代理每进入一个新阶段核心上下文只加载当前需要的技能文件。比如在“补全单元测试”这个阶段它只需要知道测试规范、mock 规则、覆盖率阈值至于提交规范、部署规范那些信息留到验收阶段再加载反而更准确。对模型来说是减负对使用者来说是提高可控性。另外拆成独立文件也方便团队协作。架构师可以单独维护“代码评审”技能运维可以单独维护“部署发布”技能互不干扰任何一个文件的修改都不需要触动全局规则。相比维护那个八百行的大文件模块化管理大步降低了对单一文档的依赖。2.3 方案背后的取舍什么场景会后悔用这个方案我一直强调superpowers 这种方案不是免费午餐它的代价是你的“初始配置成本”很高。你需要把团队里很多约定俗成的规则显式写出来变成结构化文件。这是一个痛苦的过程如果你所在团队根本没有文档文化很多规范就散落在几个老员工的脑子里你还得先花时间做访谈和梳理。另一个痛点是“流程过度约束”。一旦定义了严格的阶段代理的灵活性会下降。遇到那些根本不按常理出牌的问题比如线上故障排查需要跳过多层防线直击要害流程化方案就成了障碍。我建议日常把这类“探索任务”和“生产任务”分开配置探索任务里只保留最低限度的安全约束让代理自由发挥生产任务才启用完整工作流。你还需要考虑维护成本。技能文件一旦过期后果比没有技能文件更糟——代理会照着过时的规范执行然后产出一堆“符合规范但不符合现状”的代码。因此我把这套系统当成项目一样维护每次代码规范更新就要同步更新技能文件每次发现代理盲目照做某个过期步骤就要立刻修订对应的技能描述。3. 从零安装与初始化一份可以直接照抄的配置过程3.1 前置环境其实没有那么多玄学在正式安装 superpowers 相关的技能包之前我建议先把基础环境理一遍。这里说的是最常见的一套组合一个类 Unix 终端环境macOS 或 Linux、一个能跑起来的 CLI 编码代理以 Codex CLI 为例我当前用的版本是某个稳定的 0.x 系列、一个配置好的 Git 仓库。如果你用的 Windows那基本得靠 WSL否则很多 shell 脚本会跑得很别扭。我声明一下下面这些安装步骤是基于我本地环境的实际操作记录。不同版本的 CLI 代理可能路径不同但思路是通用的把技能文件和规则文件放进代理默认会读取的项目目录下让代理能够通过网络或 MCP 协议发现并使用这些能力。首先要确认代理的命令行入口。以 Codex CLI 为例安装后通常直接就有codex命令。接着可以在项目根目录下新建一个隐藏文件夹比如.superpowers/专门用来存放技能和配置。这个目录我建议加入.gitignore吗我不建议因为技能本身就是团队资产应该提交进仓库新成员克隆之后直接继承同一套“操作手册”。3.2 初始化“操作手册”与技能目录第一步是创建目录骨架。我通常会跑这样一串命令mkdir -p .superpowers/skills mkdir -p .superpowers/templates touch .superpowers/README.md touch CLAUDE.md这里的CLAUDE.md放在仓库根目录是所有规则的入口。里面写什么我放了一段短小但精确的话大意是你是一位严格遵循操作流程的编码代理。收到任务后必须先从.superpowers/skills/中查找匹配的技能文件并完整加载所有修改类操作执行前需要向用户展示计划每完成一个步骤必须运行对应的验证命令。第二步是创建第一个技能文件。我挑最常用的“修 Bug”场景来演示。在.superpowers/skills/bug_fixing.md里我写清楚触发条件当发现测试失败、异常堆栈或用户明确提到 bug执行步骤先构造最小复现、再定位根因、再修改代码以及验收标准相关测试全部通过且不得同时改动无关文件。这样代理在遇到 bug 类任务时就会按这套流程走。3.3 配置工作流让代理学会“先想再做”只给代理一堆技能文件还不够得把工作流串起来。设计时我把流程固定成四段理解任务、制定计划、分步执行、验收报告。在规则文件里我要求代理在开始任何代码变更前先输出一份“实施计划”列清楚涉及的文件、修改理由和测试方案计划未获确认前不允许进入编辑阶段。这套做法的好处肉眼可见绝大多数 AI 滥改代码的事故都发生在“想和做之间没有缓冲区”的时候。AI 一旦开始逐文件修改就会进入一种“路径依赖”状态发现小问题顺手改掉改完又引发新问题越陷越深。而现在计划阶段就锁定了变更范围后面的执行只能在“搭好的架子”里填充。实际执行中我还会在流程里插入“暂停点”。比如 Java 项目改完代码后代理必须暂停并显示测试结果摘要而不是急着提交。它需要等待我说“继续”或“修复”来推进。这个习惯看着有点啰嗦但长期看它帮我提前拦截了非常多的低质量提交。3.4 与 Codex CLI 等工具的联动配置技能体系要真正生效还得让代理能够在运行时主动读取这些文件。常见的做法有两种。一种是直接通过规则文件“引导”代理告诉它先去读.superpowers/skills/下的相关文件以指令的形式加载另一种是通过 MCP 服务器把技能库暴露给代理让代理可以使用工具调用方式按需获取技能内容。MCP 这套方案我推荐给团队使用因为配置好后技能文件能做到实时生效不必重启代理。但这里有个需要注意的坑MCP 服务器本身的启动和鉴权也可能成为新的故障点。如果代理连 MCP 服务器都连不上那一切等于零。我的建议是在个人项目中先走“规则文件加载”的路径体量小、调试直观团队级使用再上 MCP。以一个实际的 Codex CLI 配置为例我会在规则文件里写明加载策略“在尝试所有技能之前先检索.superpowers/skills/目录列出所有.md文件提取文件名与任务关键词的匹配项读取完整内容后再行动。” 这句指令不算复杂但实测下来代理确实会乖乖先看技能库而不是空着脑子上阵。4. Java 业务场景实战让代理真正帮你改代码4.1 针对 Java 项目的技能设计Java 项目跟脚本型项目不一样它的工程化链路长、构建工具重、模块边界严。给 Java 项目设计技能必须把构建和测试环节焊死在流程里。我单独建了一个java_build_manager.md的技能文件其中规定了识别项目类型是 Maven 还是 Gradle、定位构建命令是mvn test还是./gradlew test、以及编译失败时的标准响应动作。这个设计非常有必要。因为一个模型就算编码能力再强如果连构建命令都搞不对产出的代码只存在于“理论上”。把它写成技能文件的好处是所有 Java 任务进入执行阶段之前代理会先统一加载构建知识避开常识性错误。同时我还写了一个“代码影响范围分析”技能。拿来应对最头疼的场景——AI 改了一个小方法因为“看着别扭”顺手重构了整个类。这个技能会强制代理在每次修改前展示diff摘要并列出不可触碰的文件名单。比如API 接口层、数据库迁移脚本这类我锁进黑名单代理连改的念头都会被规则直接掐断。4.2 一个 Maven 项目的完整任务示例我拿自己维护的一个订单服务模块举例Maven 多模块结构核心业务在order-service子模块里。我给代理的任务是“RefundService类里有个退款幂等校验的 bug当同一退款请求并发提交时会出现重复退款记录请修复并补充测试。”按 superpowers 工作流代理先加载了bug_fixing.md和java_build_manager.md然后按流程输出了一份计划第一步阅读RefundService.java定位幂等校验逻辑第二部复现并发路径构造两个相同退款参数的请求第三步确定根因是校验和插入之间存在竞态窗口第四步建议加分布式锁或数据库唯一约束并向用户请求确认。计划到了这一步它就停下来等我了。我选择了数据库唯一约束的方案后代理才开始动代码。改完跳出暂停点显示mvn -pl order-service test的输出确认新增的并发测试通过后又跑了一遍全模块编译确认没有影响到其他模块。整个过程跟不带流程约束时的体验天差地别。它没有自作主张改别的接口也没有省略测试环节因为流程设定了“不跑测试不允许报告完成”。4.3 风险控制让代理只改它该改的话说回来即使有了技能体系和流程约束风险也不可能降为零。我在实际使用中总结出几条对 Java 项目特别重要的硬性规则。第一条pom.xml的任何修改都必须经过人工确认不允许代理因为“依赖版本过旧”就一股脑升级全家桶第二条禁止代理修改target/、build/这类产物目录下的任何文件这在技能里写得很清楚遇到直接忽略第三条涉及公共模块改动时代理必须先列清依赖这些模块的上游服务确认不会造成破坏性变更才允许动工。这几条规则写成文件不算难难的是维护。每次项目结构变化、模块职责调整我都会同步更新黑名单。有一次我忘了把新拆出来的common-utils模块加进公共模块保护名单代理就顺手改了里面的日期工具类因为它觉得“那个方法命名不太规范”。好在最终没有引发线上事故但吓得我后来每次重构模块前先检查保护名单。5. 常见问题与排查技巧实录5.1 代理死活不读取技能文件怎么办这是新手最容易碰到的问题。你辛辛苦苦写好了.superpowers/skills/下的技能但代理好像完全没看见依旧我行我素。原因多半出在规则文件里的表述太弱。如果你写的是“可以参考技能目录中的文档”代理大概率会忽略因为“可以”不是强制动作。我的解决方法是把命令改成祈使句“在与代码相关的任何操作之前必须检索.superpowers/skills/目录依据任务关键词匹配并加载技能文件输出加载结果。” 加了“必须”之后代理的配合度明显提高。另一个排查点是你用的 CLI 代理是否支持项目级规则文件的自动加载有些工具只加载用户目录下的全局配置不加载项目目录下那个CLAUDE.md那就要在启动代理时手动指定。5.2 工作流陷入“计划-确认-再计划”的死循环代理倒是变得小心了结果又走向了另一个极端——每一步都要确认一天下来AI 干的活没多少你按确认键按到手抽筋。这类问题本质是工作流里的“暂停点”设置太密。像“读取文件列表”这种操作根本不需要经过你确认直接执行即可只有“修改接口定义”“变更依赖”这种高风险动作才值得打断。我的优化思路是把确认级别分成两档。低风险操作读文件、跑测试、查日志放行为高风险操作改模块边界、升级依赖、重构公共代码才暂停确认。这个分级直接写进工作流规则文件里代理的自主性立刻恢复了正常不再是一个需要全程监护的“新手”。5.3 MCP 服务器连接失败导致技能加载不了MCP 连接失败的坑我自己栽过不止一次。症状就是代理开始正常执行一跑到技能加载那一步就报错接着整个任务全线崩溃。多数原因是 MCP 服务器地址配置错误或者技能库路径发生了移动。排查第一步在终端手动跑一遍 MCP 服务器命令看能否正常启动第二步检查代理配置里的 MCP 服务器 channel 是否正确指向本地服务地址第三步看目录权限如果.superpowers/目录对运行代理的系统用户没有读权限MCP 自然无法索引文件。为降低这个痛点我在本地会用“先文件后 MCP”的双通道模式。技能文件放在磁盘上规则文件也会提到按需读取路径MCP 只是加速和补充不是唯一入口。这样即使 MCP 挂了代理依然能通过普通文件的读取方式拿到技能内容任务不至于帅不过三秒就折戟。5.4 代理“装模作样”地完成任务比上面的故障更隐蔽的是代理假装做了验证。它会输出一排“测试通过”但你根本搜不到它运行测试的记录或者它说“已执行编译”实际上只是“看了一下”构建日志。出现这种现象根源在于规则文件只规定了“完成后要报告测试通过”却没有规定“必须实际运行测试命令”。我的补救方案是把验证步骤做成不可跳过的硬性流程“输出测试结论时必须同时附带对应测试命令的实际执行输出禁止对命令行为进行模拟。” 同时我也会在工作流里加入“随机抽查点”让代理在某个步骤之后贴出当前 Git 工作区的状态。如果它真的运行过命令工作区状态肯定是真实匹配的。技术配置与规则文件参考我把自己目前在用的主规则文件核心部分整理在下面给你一个直接参考的底子。注意这不是完整配置而是一个经过实践检验的“胚子”你可以在此基础上按团队需求修剪。# 代理运行规则 在执行任何代码修改任务之前必须阅读 .superpowers/skills/ 目录下的技能文件。 技能文件为 Markdown 格式文件名即为技能触发词。任务匹配方式为将任务描述拆分为关键词与技能文件名做语义匹配。 计划输出要求涉及代码变更的任务必须先输出实施计划包含文件清单、变更类型、测试方案。用户确认前不得执行写操作。 暂停点要求公共模块边界修改、依赖版本变更、接口签名调整每次必须输出变更预览并请求用户确认。 验证要求测试结论必须附带命令输出禁止以描述代替实际执行。 禁止操作不得修改 target/ 目录不得修改数据库迁移序列号不得改动用户明确指定的保护名单中的文件。这些规则我一开始工期也是东一榔头西一棒子后来渐渐收敛成了上面这几条删掉了很多“正确的废话”。规则文件的价值密度比长度重要得多一句“必须附带命令输出”比十句“请确保代码质量”强出百倍。我的经验是整套 superpowers 方案最怕的不是技术问题而是你不愿意维护它。技能文件和规则文件是活物项目在变、团队在变、甚至连 AI 模型版本都在变。一次模型升级后代理原来遵守的指令可能是另一个表现水平旧的技能文件写得再细也未必对新版本奏效。所以每当代理版本更新我都会把几个代表性任务重新跑一遍观察它的行为是否符合规则预期不对就微调措辞。最后再分享一个特别实际的小技巧给代理“留退路”。在技能文件里统一加上一条兜底规则——如果当前任务无法通过现有技能文件确定执行路径不要猜测立即停止并请求人工介入。这条规则曾帮我拦住了一次尴尬的“自动提交”。那次代理遇到一个从未见过的新型编译错误它原本想挠着头自作主张去改 gradle 脚本看到兜底规则后停了下来等我接手。这种确定性有时候比 AI 的“聪明”更值钱。