如果你最近搜过“superpowers 使用教程”“codex superpowers”这组关键词八成已经跟我一样开始把 Claude Code 或 Codex CLI 当成日常写代码的搭档了。我最初接触 superpowers就是因为被 AI 助手“写一半就跑偏”的尴尬折磨到不行吩咐它改个订单模块它能把购物车、优惠券、积分三个模块齐刷刷改一遍最后还自信满满地说“已全部完成”。后来我才搞清楚这其实不是模型变笨了而是我把它放养了——没有流程约束没有计划意识没有测试兜底再聪明的模型也只会给你一个“看起来合理但经不起推敲”的结果。superpowers 这个名字很唬人实际它也不是什么黑魔法而是一套面向 AI 编程代理的工作流与技能包。它把“先规划、再测试、后实现、最后反思”这套工程师习惯翻译成一个 Agent 能按步骤执行的技能集。这篇文章我会从它解决什么问题讲起把安装、核心机制、实际跑一个 Java 重构案例、常见坑都过一遍希望能帮你少走弯路。1. 它到底解决的是 AI 写代码的什么问题1.1 我最早用 Claude Code 写代码的挫败感先说一次真实经历。我在一个 Spring Boot 项目里让 Claude Code 给订单金额计算加上“优惠券分摊”的逻辑。当时我是直接丢给它一句话“帮我把优惠券分摊到订单明细里注意别弄坏积分抵扣。”它答得很快不到两分钟就输出了一版“改动”看起来沾沾自喜。结果代码评审的时候发现了问题它把积分抵扣的顺序调换了导致组合支付场景下用户多付了 4 分钱。更离谱的是它还顺手把另一个无关的 DTO 字段命名改了改得毫无必要。为什么会出现这种问题因为模型在长对话里很容易丢失最初的目标边界。它以为自己在“帮用户改完整模块”而不是“只改优惠券分摊这一处最小逻辑”。上下文越长它就越是哪个文件都看一眼哪个文件都想动一动最终把一次本来很小的改动变成了“伪重构”。当时我还没意识到问题不在模型本身而在工作流我没有给它一个清晰的“影响面清单”没有让它先写测试也没有要求它最后自查 diff 是不是最小集合。这一切恰好就是 superpowers 这类技能集想补上的。1.2 superpowers 的设计理念让助手像成熟工程师一样工作superpowers 不是一个单独的“开挂命令”它的核心是一组可以被 Agent 按需加载的技能文件外加一套拆分任务、保存计划、调用子代理的框架。你可以把它的工作方式理解成把一名 AI 助手从“愣头青实习生”培养成“按规范走流程的工程师”。具体拆开讲它强迫 Agent 在动手前回答几个问题这次改动的目标是什么判断成功的标准是什么涉及哪些文件哪些边界绝对不能碰是否可以先写一个会失败的测试把“预期行为”锁定下来实现跑通之后是否有回顾/反思步骤用来检查自己是否改多了听起来很基础对吧但恰恰是这些基础步骤我们人类通常下意识会做而 AI 不会。你把它们写成技能文件等于把“做事的规矩”固化成了提示词。这就是 superpowers 最核心的理念不要指望模型自动具备工程素养而是把工程素养写进流程里。1.3 适合什么人用我实际体验下来下面几类人用它会比较赚已经在用 Claude Code / Codex CLI但觉得对话式编码不可控、经常改一半跑偏的人。团队想统一 AI 编码规范的人比如强制所有 AI 改动必须有测试、必须有计划文档。想让 AI 跑长任务的人比如“把支付模块整体重构一遍”但又不敢完全放手需要中间产物可追踪。反过来说如果你的工作只是“问几个语法问题”“写几个一次性脚本”那 superpowers 对你可能偏重杀鸡用牛刀了。2. 安装与前置环境从零到第一次召唤2.1 环境准备中最容易忽略的细节先说说环境。superpowers 的底层是跑在终端里的所以不是所有设备都体验一致。我的建议顺序是已经有 Node.js 18 或更高版本最好 20。很多安装脚本和技能本身依赖 npm/npx。已经装好 Claude Code 或 OpenAI Codex CLI并完成登录。也就是说你自己至少已经能在这个终端里跟 AI 对话。有 Git且当前项目已经是一个 Git 仓库。因为 superpowers 的计划恢复、diff 自检都严重依赖 Git 状态。操作系统优先 macOS 或 Linux。Windows 用户我建议用 WSL纯 Windows PowerShell 下会遇到路径分隔符和权限模型的额外麻烦不是不能用是坑更多。2.2 安装命令到底怎么敲我在不同版本里见过的安装入口不完全一样这里给你两种最常见的# 方式一npm 全局安装会提供一个 superpowers 命令 npm install -g superpowers# 方式二在 Claude Code 会话里直接装插件 /plugin install superpowerslatest如果你不想全局安装也可以在某些版本里用 npx 方式直接执行例如npx superpowers init。命令在不同小版本之间漂移得很厉害所以我不建议你死记某一条命令而是安装前先看一眼你拿到的仓库 README以它写的为准。装完之后进入你的项目目录执行初始化cd your-project superpowers init执行完你会发现目录下多了一些东西最常见的包括.superpowers/skills/技能目录以及一个被追加了“superpowers 技能索引”的CLAUDE.md或AGENTS.md。如果你看到这些说明安装成功了一半。2.3 验证安装让 Agent 自己说出会哪些技能初始化只是把文件放好真正要验证的是模型能不能感知到这些技能。我会先把当前终端关掉重开然后进入项目目录打开 Claude Code第一句话不问业务问题而是问“这个项目启用了哪些技能列出名称和触发条件。”如果 superpowers 生效了它会按照 CLAUDE.md 里的技能索引给你列出一串技能名比如 test-driven-development、design-doc、refactor-workflow 等。如果它回答“我没有看到任何技能”大概率是CLAUDE.md没被正确加载或者技能索引没有写到这份文件里。这时候别急着怀疑模型先去文件里看一眼如果没有“superpowers 技能集”相关的章节手动把技能索引文本追加进去即可。很多安装失败其实只是“文件生成了一堆但模型没读到入口索引”。3. 核心运行机制技能、记忆与子代理如何配合3.1 技能是怎么被“按需加载”的superpowers 里的“技能”本质上是一个个带元信息的 Markdown 文件。每个技能文件头部有一段 YAML frontmatter里面写了 name 和 description正文就是让 Agent 照做的具体步骤、检查清单和输出模板。举个例子一个“设计文档”技能的头部大概长这样--- name: design-doc description: 在涉及多文件改动前生成设计文档适合重构、新增模块、架构调整等任务 ---当你在对话里说“我要把支付模块重构一遍”Agent 会先读到技能索引再根据描述词“多文件改动、重构”命中 design-doc 这个技能然后把整个文件的正文加载进上下文开始按里面的模板生成设计文档。这里的设计很巧妙它不是把几十个技能一次性塞进上下文而是靠描述匹配、按需加载。技能文件写得再多也不会让每轮对话都变重。这就像你书架上放了一堆工具手册需要拧水管时只抽水管那本而不是背着整座图书馆去修水管。3.2 记忆与计划文件会话断了也能接上我最开始用的时候对“计划写进文件”这件事并不敏感总觉得对话就是最好的状态。直到有一次重构到一半终端崩溃重开会话后 AI 完全不记得之前的上下文我差点原地自闭。superpowers 的思路不一样它鼓励 Agent 把关键中间产物落盘比如把设计文档、影响面清单、测试清单写进.superpowers/plans/目录。这样即使会话断了重新打开后只要说一句“读取最新的计划文件继续任务”Agent 就能通过文件 Git 状态恢复工作。我自己实操下来会在任务开头额外叮嘱一句“每一阶段结束后把结论写进.superpowers/plans/下带时间戳的文件。”这句话看着多余实际救了我很多次。AI 的工作记忆是极不可靠的但文件是可靠的。长任务能不能跑完往往就取决于你是不是把该保存的都保存了。3.3 子代理调用链把大任务切成多人协作superpowers 里还有一个我很喜欢的设计子代理调用。面对“重构支付模块”这种大任务主线程不会自己吭哧吭哧干而是像项目经理一样拆分子代理 A扫描现有代码输出“涉及文件清单 影响面分析”子代理 B基于新契约写测试故意跑出红牌子代理 C实现逻辑把红牌变绿主线程收拢结果做最后 diff 自检。每个子代理都带着明确目标启动互不干扰。这比单线程对话强在两点一是不会聊着聊着目标漂移二是能并行处理耗时操作比如在跑测试的同时另一个子代理已经在分析下一个受影响模块。3.4 权限分级什么能自动跑什么必须人确认我见过太多“AI 把项目搞乱”的事故说到底是权限放太宽。superpowers 的技能文档里虽然会约束 Agent 的行为但工具调用权限还是握在你手里。我的习惯是分三档采集类命令ls、grep、cat、git diff、git log直接放行。修改类命令npm install、sed -i、rm、mv先看计划里有没有列出来再放行。破坏性命令git push --force、全局格式化、批量重命名文件必须人工确认。不要嫌确认麻烦。真等到它把 lock 文件、无关配置文件改得面目全非的时候你才知道什么叫真正的麻烦。4. 用真实项目过一遍主流程TDD 与重构4.1 让 AI 先写测试再写实现Java 订单模块案例结合“superpowers java”这个高频搜索词我用一个 Java 场景完整走一遍 superpowers 的 TDD 流程。项目背景Spring Boot 订单模块金额计算逻辑散在三个 Service 里。需求是把优惠券分摊和积分抵扣统一成一条计算链路。我没有直接让它“开始改”而是说“我要重构订单金额计算请先用测试驱动的方式输出计划并先写红牌测试。”它会先生成一个计划文档里面可能包含圈定涉及文件OrderService、CouponService、PointsService、几个 DTO。定义输入输出契约入参是什么零头怎么处理优惠券与积分谁先谁后。写第一份 JUnit 测试声明目标行为但不实现。预计算的用例大致长这样public class OrderAmountCalculatorTest { Test void should_apply_coupon_then_points_on_order_amount() { OrderAmountInput input new OrderAmountInput(100.00, 15.00, 2_000); OrderAmount result new OrderAmountCalculator().calculate(input); // 100 - 15 852000 积分按规则抵扣 20 元 65 assertThat(result.finalAmount()).isEqualTo(65.00); assertThat(result.couponPart()).isEqualTo(15.00); assertThat(result.pointsPart()).isEqualTo(20.00); } }注意这里测试不是“写完功能后再补”的测试而是先写红、再写绿。superpowers 的 TDD 技能会要求 Agent 先让测试失败然后才去实现。这一步对于老代码尤其有用它会逼你把“到底期望什么行为”说清楚。我记得当时跑完红牌测试后发现旧代码里有一条“金额 0.001 防浮点误差”的玄学逻辑之前根本没人敢动新测试直接把它暴露了。这就是契约的力量。4.2 策略先行codex superpowers 怎么接有人会问既然 superpowers 最初更多被 Claude Code 的用户使用那 Codex CLI 里能不能用答案是能但接入方式稍微绕一点。Claude Code 靠CLAUDE.md作为全局指令文件Codex CLI 则读AGENTS.md。思路是一样的把技能索引放到模型每轮会话必然能看到的地方然后让它“遇到多文件改动先读技能文件再动代码”。我自己的轻量接入方式是在项目根目录放一份AGENTS.md里面写明“遇到多文件任务先阅读.superpowers/skills/design-doc.md并按流程执行”。把需要的技能文件放到.superpowers/skills/目录。在对话里显式说“使用 design-doc 技能先设计方案再实施。”Codex 的版本迭代也会变有些版本支持自定义命令有人会把技能调用封装成命令别名用起来更顺。但核心永远是那句只要能读文件、能执行命令、能注入系统提示的代理工具都可以承载这套技能目录只是触发方式不同。我曾经整理过一份极简对照遇事不决就看这张表对比维度Claude CodeCodex CLI全局指令文件CLAUDE.mdAGENTS.md技能索引写入位置CLAUDE.md 开头AGENTS.md 开头技能触发方式对话自然语义命中需要显式告诉它去读技能文件长任务拆分能力原生 subagent 较成熟需要脚本封装或依赖外部工具适合人群习惯交互式协作习惯命令式、批处理式这张表不一定永远精确因为两边都在快速迭代但思路是对的Claude Code 更“自动”Codex CLI 更“显式”。4.3 重构与自检让 AI 先提交方案再改代码很多人以为让 AI 重构就是一句“帮我把 X 模块重构掉”然后等结果。我用 superpowers 的习惯是走四步生成影响面清单。明确列出“会改哪些文件哪些文件只读不改”。对每处改动写理由。不允许出现“因为你说改”这种话。跑完测试后进入评审模式让 Agent 用挑剔的眼光看一遍自己的 diff。确认改动是最小集合后才允许提交。最后这一步很容易被忽略。AI 写代码时经常“顺手”把格式化、重命名、注释调整混进来让 diff 变得又大又难评审。superpowers 的反思技能会把“我是否是这次改动的最小集合”变成一个强制检查项。我在实际项目里用过这招后评审 AI 生成的 PR平均要看的文件数少了差不多一半。5. 日常使用踩坑与解决从配置冲突到长任务恢复5.1 配置冲突多个工具抢着写 CLAUDE.md这是我在启用 superpowers 后碰到最早的坑。项目里同时有.cursor/rules、手写的CLAUDE.md、AGENTS.md而 superpowers 初始化时会往CLAUDE.md里写技能索引。如果你原本的CLAUDE.md是一份精心维护的项目规范它很可能被覆盖或干扰。解决思路很简单但很多人不知道初始化之前先备份初始化之后手动合并。不要把整份文件交给工具重写而是只追加一个“superpowers 技能集”小节。如果你的项目同时给多个 Agent 工具用我甚至建议把公共技能放到一个shared/目录然后让各工具各自的索引文件都指向这个目录避免“一份技能放三份副本”的同步噩梦。5.2 权限提示全放行 vs 步步确认第一次跑 superpowers 的时候你可能会被一连串工具调用提示吓到。这里我有一个经验值读操作全放写操作先审破坏性操作必停。如果项目只有你一个人且是实验性代码权限可适度放宽但至少保留“命令执行前只确认一次”模式。子代理的工具调用比单线程多得多日志会看起来很乱。我习惯把子代理内部的读写折叠成摘要只看主线程的关键行动否则看日志会看到头大。记住一个原则不是所有工具调用都值得批准也不是所有批准都需要人工点一次。关键是让“危险动作”永远留在你手里。5.3 长任务中断与恢复文件就是救命稻草前面说过superpowers 把计划写进文件的思路我要再强调一遍。具体到恢复场景如果会话崩了重新开一个窗口。输入“我们之前在做订单模块重构读取最新的计划文件并继续”。Agent 读到计划文件 当前 Git 状态就能无缝接着跑。这里的隐藏要求是在任务进行过程中每一步都要保存。模型不会主动保存所以我会在任务开始时明确加一句“每阶段结束把产出物写入 .superpowers/plans/”。没有落盘的步骤恢复时就是一场空。我自己试过几次之后已经把这句固化成了固定开场白。5.4 关于“WorkBuddy 怎么用 superpowers”之类的疑惑偶尔会看到有人问类似“WorkBuddy 怎么用 superpowers”这样的问题。其实答案不在某个具体工具里而在“这个工具能不能读技能文件”。如果你的工具支持自定义命令、技能文件或至少能执行 bash就能把这套技能目录挂进去如果它既不能读文件也没有自定义命令入口那就没法用。不要把 superpowers 想成某个 GUI 工具里的一颗按钮。它的本质是一套流程 提示词资产可以在 Claude Code 里用也可以部分迁移到 Codex CLI 以及其它支持自定义技能与权限模型的 AI 编码工具里。工具间的差别主要在于触发与注入方式而不是“能不能”。5.5 别迷信最新版我踩过的另一个坑是为了追新功能频繁升级 superpowers 技能包版本。结果就是某个技能的元信息字段格式变了Agent 突然匹配不到技能文件或者初始化脚本把目录结构重排了一遍旧项目里引用的路径全部失效。我的建议是稳定使用你验证过的版本升级前先在一个临时目录试跑。等到新版本在社区里讨论一段时间后再跟上也不迟。工具链这种东西稳定压倒一切。6. 实际体验层面的一些感受这套工具用了大半年我的结论是它不会让你的代码库一夜之间变干净但它能把失控的 AI 编码过程拽回正轨。最直接的变化是AI 在动手前会先给我一份计划在写实现之前会先有测试。即使它最后写出来的代码还是有小问题流程也能把问题框在一个可控范围内而不是让它顺着上下文一路跑偏。如果让我只留一条使用建议我会说养成“先要点计划再放权执行”的习惯。哪怕你暂时没装 superpowers也先在对话里逼自己多问 AI 一句“你打算怎么改涉及哪些文件怎么验证”。你会发现就这么一句AI 写出来的代码质量就能上一个台阶。而 superpowers 的功劳就是把这句“多问一句”变成了默认流程还顺便把计划、测试、反思这些好习惯都固化到了技能文件里。工具始终会迭代命令名会变目录结构会调但“先规划、再测试、后实现、最后反思”这条主线我认为在很长一段时间里都成立。