最近我开始把 Superpowers 引入到日常的编码 Agent 工作流里起因是一个很实际又很痛的问题用 Codex 这类命令行 Agent 做一次中大型重构看起来省了很多事实际上没少折腾。Agent 经常在上下文一大片之后就“跑偏”把一个简单改动想成复杂方案或者明明改完了却不跑测试直接告诉我“完成了”。后来我把 Superpowers 这套工作流加入到 Codex 的启动流程里才真正体会到它和普通 Prompt 插件的差别。它不是给模型加几个提示词而是给编码 Agent 配了一套完整的“工程师思维方式”先想清楚意图再画架构再拆任务再验证改动每一步都有明确的动作规范。这篇文章我就从一个实际使用者的角度把 Superpowers 是什么、怎么安装、怎么用、有哪些坑以及网上常问的“WorBuddy 怎么用 Superpowers”这类适配问题一次讲清楚。文章不是官方文档的翻译而是我个人用下来之后的方法论拆解和操作笔记适合那些已经在用 Codex、Claude Code、WorBuddy 等编码 Agent但总觉得它们不够“懂事”的人。1. Superpowers 是什么给编码代理装上“工程师人格”1.1 一个很真实的痛点命令少了出错多了先说一个我自己的经历。之前接手一个 Java 后端服务里面某个核心模块的 if-else 嵌套已经多到让人头皮发麻。我本来想用 Codex 帮我一次性把这段逻辑改造成策略模式省得自己一行行抠。结果前前后后花了大概一个下午来回调整 PromptCodex 给出的方案一会儿是改接口一会儿是引入状态机一会儿又想把整个类拆成四个新文件。没有一个方案是错的但也都没有真正贴合我最初“只是想降复杂度”的意图。问题出在哪儿很多编码 Agent 默认的工作方式是“你给一个模糊目标我立刻开始猜”。目标越模糊它越容易在巨大的搜索空间里东碰西撞。Superpowers 解决的恰恰就是这个“一开始不急着写代码”的问题。它把工程师写代码之前的脑暴、架构设计、任务拆分这些隐性动作显式地变成了 Agent 必须执行的工作流步骤。1.2 它不是另一个 Agent而是 Agent 的“工作方法包”Superpowers 并不是一个独立的编程助手它是一套可以被安装到各种编码 Agent 里的工作流增强方案。它的核心内容是一系列规则、动作模板和工作流文档Agent 在启动的时候会把这些内容加载成自己的“职业习惯”。我比较喜欢的一个类比是普通的 Agent 像一个刚入职的程序员能力很强但是没经验你一说什么它立刻去做做完也不知道检查。而 Superpowers 像是给这个新人配了一个资深导师制定的开发流程手册接到需求先不要动手先确认你的理解动手前先把接口边界和文件影响范围列出来改完代码之后必须跑最小验证如果发现路径不对允许回滚重来。这套东西落到实操层面通常由SUPERPOWERS.md、工作流指令目录、Agent 配置三部分组成。当 Agent 启动后它会依据这套规则决定自己每一步该做什么而不是单纯等着用户下一条指令。1.3 它的几个核心设计取向我自己总结下来Superpowers 有四个很值得关注的设计取向也是它区别于普通“提示词工程”的地方。意图优先于计划它不会让 Agent 一开始就生成一份庞大的实施计划而是通过一轮一轮的提问把“用户到底要什么”“哪里可以妥协”“哪里不能动”这些关键约束问清楚。架构先于编码涉及多文件改动时它倾向于先写一版架构说明把模块划分、依赖方向、风险点写清楚再进入编码。任务拆分和验证闭环一个复杂目标会被拆成可独立验证的小任务每个任务都有明确的完成定义而不是笼统的“实现完成”。显式支持回滚和重试Agent 如果发现自己走错路可以停下来说明原因而不是继续在错误的方案上硬改。这套东西说起来不复杂但一旦真正落地效果非常明显。我之前那种“一个下午浪费在来回试探”的情况后来基本没有再出现过因为 Agent 在第一步就会先追问我要的是什么。2. 安装与接入从 Codex CLI 到 WorBuddy 的适配路线2.1 先用一句话说清楚安装的本质很多第一次接触 Superpowers 的人看到网上说“安装 Superpowers”时会下意识以为要跑一个安装脚本然后就会多出一个可以启动的程序。其实不是。你的编码 Agent 还是原来那个 AgentSuperpowers 做的事情是把一套行为规则注入到 Agent 的上下文里或者放到 Agent 会自动读取的配置目录中。所以“安装”这个词更准确的理解是让 Agent 在每次启动的时候自动加载 Superpowers 工作流。基于这个理解安装方式就变得很清晰只要你的 Agent 支持自定义指令、自定义工具、或读取项目级配置文件就能接入 Superpowers。2.2 我推荐的接入步骤以我常用的 Codex CLI 环境为例接入过程大致是这样先下载或克隆 Superpowers 的规则包里面通常包含SUPERPOWERS.md、workflows/、以及若干工作流模板文件。把SUPERPOWERS.md放到项目根目录或者在全局 Agent 配置目录里设置成默认加载。这样 Agent 每次启动时都会先读到这套规则。确认你的 Agent 配置允许模型在工作流期间调用文件读写、命令执行、搜索等基础工具。Superpowers 的很多动作依赖这些工具如果 Agent 只有“对话”能力那这套流程发挥不出来。最后做一次简单验证。你可以故意提一个需要多文件协作的小需求看 Agent 是否会在动手编码前先给出意图澄清和架构说明。如果它直接开始改代码说明规则没有加载成功。提示安装过程中最容易犯的错是把SUPERPOWERS.md当普通项目文档放在仓库里但没有告诉 Agent 必须在启动时读取它。一定要确认好 Agent 的“系统提示”或者“自动上下文”部分确实包含了对该文件的引用。2.3 WorBuddy 怎么用 Superpowers最近经常有人在问“WorBuddy 怎么用 Superpowers”我猜这是因为很多国产编码 Agent 也开始支持自定义工作流了。这里我不打算去细抠某个产品某个版本的按钮位置而是说一个通用的适配思路适用于 WorBuddy 以及类似工具。WorBuddy 这类集成式编码工具通常有一个“自定义指令”或“项目技能”区域可以导入外部规则。具体做法分三步。第一把 Superpowers 仓库里的SUPERPOWERS.md主规则文件下载到本地。第二在 WorBuddy 的项目配置或全局配置里增加一条自定义指令让 Agent 在开始任何编码任务之前先读取这个文件并严格遵循其中的工作流顺序。第三如果你的 WorBuddy 支持子工作流或自定义 Action就把workflows/下那些阶段模板对应导入让“脑暴”“架构设计”“验证”变成可选的动作节点而不是一次性描述。用这种方式接完以后WorBuddy 的行为会发生一个很直观的变化它收到需求时会先反问“这个需求的成功标准是什么”然后进入设计而不是马上打开代码文件开始乱找。这个体验是我觉得最值得去适配的原因。2.4 安装后不生效的情况排查如果按上述步骤做了但 Agent 表现还是老样子通常原因有三个模型上下文里根本没读到规则文件需要检查是否把配置放到了全局目录而不是项目目录Agent 配置里把“工具调用”关掉了Superpowers 需要执行 shell 命令和读文件没有工具就没有工作流用的模型推理能力太弱理解不了多步骤规则。这个问题我在后面会单独展开。3. 核心工作流拆解意图澄清、架构拆分、任务执行与验证回路3.1 Brainstorm先让模型把“要什么”写清楚Superpowers 工作流的第一步通常不是写方案而是进入一个类似“脑暴”的阶段。在这个阶段Agent 会通过提问来收敛需求而不是立刻给出答案。它问的问题通常很刁钻比如这个改动的使用者是谁当前这个模块最让你痛苦的是什么你希望这次改动之后哪些行为绝对不能变有没有已经存在的测试可以佐证当前行为这些问题看着简单但非常有效。因为很多项目里用户自己都没想清楚优先级Agent 却把所有需求当成同等重要的目标去实现。我一开始觉得这个阶段浪费时间直接跳过了。后来才发现跳过脑暴等于让 Agent 自己脑补需求它脑补出来的那个需求永远比我实际想要的复杂。现在我会主动配合它完成这个阶段把回答写进一个简短的需求记录文件这样后面的架构阶段才有依据。3.2 Architecture用文档把“设计决策”固化下来脑暴结束以后Superpowers 会引导 Agent 进入架构阶段。它的做法是先查看项目结构、关键文件、现有模块边界然后产出一份简短的架构说明。这里有一个容易忽略的点架构说明不是为了写在文档里给别人看的而是为了让 Agent 自己在后续任务执行时能够“照着走”。当 Agent 改到一半忘记整体方向时它可以重新读回这份架构说明避免越改越偏。这就好比施工队手里有一份图纸而不是只靠开工前项目经理口头说一遍。我自己在实际使用中会让这份架构说明尽量短控制在几百字到一千字之间。它只需要说清楚改动涉及哪些文件、模块之间的依赖方向、哪里是风险点、哪些部分可以暂时不动。这样就足够了。有些项目的架构文档写到几千字Agent 反而抓不住重点因为它的注意力窗口有限塞太多资料只会挤压真正执行代码时的上下文。3.3 Implementation 和 Verification小步快跑加持续验证进入实现阶段后Superpowers 不会把一个大目标一次性丢给模型完成而是拆成若干个可以独立验证的子任务。每个子任务完成之后Agent 需要先做验证再继续下一步。它的验证动作包括但不限于运行相关单元测试、检查编译、用 git diff 审查变更范围、根据项目语言执行 linter。如果验证失败Agent 要停下并分析失败原因而不是重新生成一段不同的代码糊上去。这个“失败就停下而不是重试硬编”的习惯是它和普通 Completions 式开发最核心的区别。我记忆比较深的一次是用这套流程改造一个 Java 服务的日志模块。Agent 在完成一个子任务之后主动跑了编译和单测结果发现某个旧测试因为时间格式变化失败了。它没有直接修改旧测试去迎合新代码而是先把失败原因记录了下来回到实现阶段调整了序列化逻辑最终让旧测试通过的同时也保留了新格式的兼容。这个判断过程就完全体现了验证回路的价值。4. 让这套方法真正发挥效力的几个细节4.1 为什么它能处理回滚工程师在重构时会频繁回退但传统意义上的编码 Agent 很少主动回退因为它很难判断“当前路径是不是错了”。Superpowers 能处理回滚原因在于它引入了“状态记录”机制。Agent 在每个阶段结束时会把当前进展写成一个简短的状态文件。当后续执行发现矛盾或者验证失败时它可以参考这个状态文件找出是在哪个阶段发生了偏差然后选择回滚到那个阶段重新开始。这比它在残缺上下文里从头思考要可靠得多。4.2 搜索和浏览边界另一个我很欣赏的细节是它对“搜索动作”的约束。很多 Agent 接到需求后会疯狂搜索代码库把大量相关但不重要的文件扫一遍然后成功把自己的上下文撑爆。Superpowers 工作流则倾向于让搜索围绕特定问题边界展开比如只搜索指定函数的所有调用方或者只查询某个接口的返回类型。缩小搜索边界不是限制 Agent反而是让它的注意力更集中。你可以把这个想象成一个维修工进了机房。有经验的维修工不会把整个机房的设备都检查一遍而是先根据故障现象定位到某几个机柜再针对范围做细致排查。Superpowers 教 Agent 的就是这种定位式搜索。4.3 代码笔记的价值Superpowers 工作流里还会生成一些看起来像是“笔记”的文本片段。这些片段不是给人看的注释而是 Agent 自己的“内存外置”。因为 LLM 的上下文窗口再大也有限当一段会话执行了很久之后早期的信息会被从注意力中挤出去。Superpowers 通过把关键决策、已完成任务、待办事项写进笔记文件等于让 Agent 随时可以回去翻自己的“工作日志”而不是凭模糊记忆继续操作。这招在多文件、跨模块的任务里特别管用。我试过在一个改动量比较大的前端项目里整个会话持续了很久但 Agent 每一步都能从笔记文件里找到之前的设计约束几乎没有出现重复问我已经回答过的问题的情况。4.4 Java 项目有没有语言门槛不少人在热搜里找“superpowers java”我直接说结论Superpowers 本质上是语言无关的Java、Python、Go、前端项目都能用。但实际体感上Java 项目接入后获益更大原因是 Java 项目通常有更复杂的包结构、接口约定和依赖关系Agent 如果没有架构约束很容易在类之间乱拉依赖。Superpowers 强制先架构后实现正好抵消了 Java 项目里最容易出现的那种“改一个类连带五个类一起动”的问题。我用 Java 写完上面提到的日志模块之后最大的感受是它在动手之前对调用链的梳理非常准确准确到我在代码评审时都不太需要补充说明。这点在过去直接用 Agent 编码时是感受不到的。5. 接上这套工作流之后我踩过的三个坑5.1 坑一状态文件越攒越多上下文还是被撑爆Superpowers 鼓励 Agent 把阶段状态写进文件这本身很好但文件也是要占上下文的。有一段时间我在同一个项目里连续做了好几个重构Agent 每次都会把过去几天的状态文件全部加载进来导致上下文越来越重反应越来越慢。后来我改为按功能分支管理状态文件一个分支只保留当前任务对应的笔记和决策记录。跨分支的长期经验不该塞进工作上下文里而是应该沉淀成项目文档或者仓库 README。简单说就是状态文件要“用完即扔”别当长期记忆用。5.2 坑二低估了模型推理能力的要求Superpowers 本质上是在教模型“怎么思考”但前提是模型本身要有足够的推理能力去执行这套思考流程。我在一个低配模型上试过结果它连“脑暴阶段该问什么”都没搞清楚最后又回到老路子上乱猜代码。后来我固定使用推理能力较强的模型来跑这套工作流低配模型只用来做简单问答。这个取舍很重要如果你的模型本身推理水平不高装再多方法论包也没用就像给一个新手强行塞一本《系统架构设计指南》他能看懂字但做不了判断。5.3 坑三过度验证改个变量也要跑全套流程工作流刚接入的那段时间我甚至产生了一种“过拟合”的感觉让 Agent 把某个硬编码变量改成配置项它也给我来了一个脑暴加架构加验证的完整流程。这显然是不合理的。Superpowers 的判断应该是分级触发的单文件小改动可以直接进入实现多文件、跨模块、涉及公共接口的改动才需要走完整流程。如果你发现 Agent 对任何微小的改动都走全套可以在规则里加一条分级判定标准让它在开始前先评估改动影响面。影响面小的任务直接执行不需要启动完整工作流。6. 什么项目建议接入什么项目建议保持现状6.1 适合接入 Superpowers 的典型场景总结一下我自己的使用体会有这三类项目很适合接入 Superpowers历史代码复杂、模块间耦合严重的老项目这类项目最需要架构阶段来约束 Agent避免它乱拉依赖。多文件协同或有明确接口约定的后端项目Java、Go、大型 TypeScript 等项目验证回路能显著降低编译和测试层面的低级错误。需要一个持续运行、跨多会话完成的“长期施工”型任务状态记录机制让 Agent 的思维可以“续上”而不是每次重新开始都像第一次接触这个项目。6.2 不建议接入的情况反过来如果你是快速验证一个想法或者只是想让 Agent 帮你完成一次性脚本那 Superpowers 反而是负担。它那一轮一轮的意图澄清和架构说明会把你从“两分钟拿到结果”拖到“十分钟还没开始写代码”。还有一个场景要考虑如果你的团队没有一个固定的项目管理方式Agent 生成的架构文档没有地方沉淀那这套流程的价值会大打折扣。因为 Superpowers 非常依赖“设计决策可以被记录、被回读”如果记录完根本没人维护那就成了一次性文书工作。6.3 后续可以怎么扩展我最近在尝试的两个方向大家可以参考。一个是把 Superpowers 的分支级状态记录做成一个简单的项目复盘汇总每次迭代结束后从状态文件里提取“当初的设计假设”和“最终实际结果”对比慢慢形成一个团队自己的决策知识库。另一个方向是把它的工作流模板适配到更多工具上不只是 Codex CLI还有团队内部的私有化编码助手。只要工具支持注入自定义规则Superpowers 的骨架就能复用进去。最后分享一个小技巧不管你用的是 Codex、WorBuddy 还是别的编码 Agent在第一次接入 Superpowers 时不要直接拿核心项目试。先找一个不重要的测试模块故意提一个你自己已经知道答案的问题观察 Agent 的行为变化。确认它开始先问、再想、后动手了再放到重要项目里跑。这样你就能在低风险的环境下真正建立起对这套工作流的掌控感而不是被它牵着走。
Superpowers实战：为编码Agent装上工程师思维与工作流
最近我开始把 Superpowers 引入到日常的编码 Agent 工作流里起因是一个很实际又很痛的问题用 Codex 这类命令行 Agent 做一次中大型重构看起来省了很多事实际上没少折腾。Agent 经常在上下文一大片之后就“跑偏”把一个简单改动想成复杂方案或者明明改完了却不跑测试直接告诉我“完成了”。后来我把 Superpowers 这套工作流加入到 Codex 的启动流程里才真正体会到它和普通 Prompt 插件的差别。它不是给模型加几个提示词而是给编码 Agent 配了一套完整的“工程师思维方式”先想清楚意图再画架构再拆任务再验证改动每一步都有明确的动作规范。这篇文章我就从一个实际使用者的角度把 Superpowers 是什么、怎么安装、怎么用、有哪些坑以及网上常问的“WorBuddy 怎么用 Superpowers”这类适配问题一次讲清楚。文章不是官方文档的翻译而是我个人用下来之后的方法论拆解和操作笔记适合那些已经在用 Codex、Claude Code、WorBuddy 等编码 Agent但总觉得它们不够“懂事”的人。1. Superpowers 是什么给编码代理装上“工程师人格”1.1 一个很真实的痛点命令少了出错多了先说一个我自己的经历。之前接手一个 Java 后端服务里面某个核心模块的 if-else 嵌套已经多到让人头皮发麻。我本来想用 Codex 帮我一次性把这段逻辑改造成策略模式省得自己一行行抠。结果前前后后花了大概一个下午来回调整 PromptCodex 给出的方案一会儿是改接口一会儿是引入状态机一会儿又想把整个类拆成四个新文件。没有一个方案是错的但也都没有真正贴合我最初“只是想降复杂度”的意图。问题出在哪儿很多编码 Agent 默认的工作方式是“你给一个模糊目标我立刻开始猜”。目标越模糊它越容易在巨大的搜索空间里东碰西撞。Superpowers 解决的恰恰就是这个“一开始不急着写代码”的问题。它把工程师写代码之前的脑暴、架构设计、任务拆分这些隐性动作显式地变成了 Agent 必须执行的工作流步骤。1.2 它不是另一个 Agent而是 Agent 的“工作方法包”Superpowers 并不是一个独立的编程助手它是一套可以被安装到各种编码 Agent 里的工作流增强方案。它的核心内容是一系列规则、动作模板和工作流文档Agent 在启动的时候会把这些内容加载成自己的“职业习惯”。我比较喜欢的一个类比是普通的 Agent 像一个刚入职的程序员能力很强但是没经验你一说什么它立刻去做做完也不知道检查。而 Superpowers 像是给这个新人配了一个资深导师制定的开发流程手册接到需求先不要动手先确认你的理解动手前先把接口边界和文件影响范围列出来改完代码之后必须跑最小验证如果发现路径不对允许回滚重来。这套东西落到实操层面通常由SUPERPOWERS.md、工作流指令目录、Agent 配置三部分组成。当 Agent 启动后它会依据这套规则决定自己每一步该做什么而不是单纯等着用户下一条指令。1.3 它的几个核心设计取向我自己总结下来Superpowers 有四个很值得关注的设计取向也是它区别于普通“提示词工程”的地方。意图优先于计划它不会让 Agent 一开始就生成一份庞大的实施计划而是通过一轮一轮的提问把“用户到底要什么”“哪里可以妥协”“哪里不能动”这些关键约束问清楚。架构先于编码涉及多文件改动时它倾向于先写一版架构说明把模块划分、依赖方向、风险点写清楚再进入编码。任务拆分和验证闭环一个复杂目标会被拆成可独立验证的小任务每个任务都有明确的完成定义而不是笼统的“实现完成”。显式支持回滚和重试Agent 如果发现自己走错路可以停下来说明原因而不是继续在错误的方案上硬改。这套东西说起来不复杂但一旦真正落地效果非常明显。我之前那种“一个下午浪费在来回试探”的情况后来基本没有再出现过因为 Agent 在第一步就会先追问我要的是什么。2. 安装与接入从 Codex CLI 到 WorBuddy 的适配路线2.1 先用一句话说清楚安装的本质很多第一次接触 Superpowers 的人看到网上说“安装 Superpowers”时会下意识以为要跑一个安装脚本然后就会多出一个可以启动的程序。其实不是。你的编码 Agent 还是原来那个 AgentSuperpowers 做的事情是把一套行为规则注入到 Agent 的上下文里或者放到 Agent 会自动读取的配置目录中。所以“安装”这个词更准确的理解是让 Agent 在每次启动的时候自动加载 Superpowers 工作流。基于这个理解安装方式就变得很清晰只要你的 Agent 支持自定义指令、自定义工具、或读取项目级配置文件就能接入 Superpowers。2.2 我推荐的接入步骤以我常用的 Codex CLI 环境为例接入过程大致是这样先下载或克隆 Superpowers 的规则包里面通常包含SUPERPOWERS.md、workflows/、以及若干工作流模板文件。把SUPERPOWERS.md放到项目根目录或者在全局 Agent 配置目录里设置成默认加载。这样 Agent 每次启动时都会先读到这套规则。确认你的 Agent 配置允许模型在工作流期间调用文件读写、命令执行、搜索等基础工具。Superpowers 的很多动作依赖这些工具如果 Agent 只有“对话”能力那这套流程发挥不出来。最后做一次简单验证。你可以故意提一个需要多文件协作的小需求看 Agent 是否会在动手编码前先给出意图澄清和架构说明。如果它直接开始改代码说明规则没有加载成功。提示安装过程中最容易犯的错是把SUPERPOWERS.md当普通项目文档放在仓库里但没有告诉 Agent 必须在启动时读取它。一定要确认好 Agent 的“系统提示”或者“自动上下文”部分确实包含了对该文件的引用。2.3 WorBuddy 怎么用 Superpowers最近经常有人在问“WorBuddy 怎么用 Superpowers”我猜这是因为很多国产编码 Agent 也开始支持自定义工作流了。这里我不打算去细抠某个产品某个版本的按钮位置而是说一个通用的适配思路适用于 WorBuddy 以及类似工具。WorBuddy 这类集成式编码工具通常有一个“自定义指令”或“项目技能”区域可以导入外部规则。具体做法分三步。第一把 Superpowers 仓库里的SUPERPOWERS.md主规则文件下载到本地。第二在 WorBuddy 的项目配置或全局配置里增加一条自定义指令让 Agent 在开始任何编码任务之前先读取这个文件并严格遵循其中的工作流顺序。第三如果你的 WorBuddy 支持子工作流或自定义 Action就把workflows/下那些阶段模板对应导入让“脑暴”“架构设计”“验证”变成可选的动作节点而不是一次性描述。用这种方式接完以后WorBuddy 的行为会发生一个很直观的变化它收到需求时会先反问“这个需求的成功标准是什么”然后进入设计而不是马上打开代码文件开始乱找。这个体验是我觉得最值得去适配的原因。2.4 安装后不生效的情况排查如果按上述步骤做了但 Agent 表现还是老样子通常原因有三个模型上下文里根本没读到规则文件需要检查是否把配置放到了全局目录而不是项目目录Agent 配置里把“工具调用”关掉了Superpowers 需要执行 shell 命令和读文件没有工具就没有工作流用的模型推理能力太弱理解不了多步骤规则。这个问题我在后面会单独展开。3. 核心工作流拆解意图澄清、架构拆分、任务执行与验证回路3.1 Brainstorm先让模型把“要什么”写清楚Superpowers 工作流的第一步通常不是写方案而是进入一个类似“脑暴”的阶段。在这个阶段Agent 会通过提问来收敛需求而不是立刻给出答案。它问的问题通常很刁钻比如这个改动的使用者是谁当前这个模块最让你痛苦的是什么你希望这次改动之后哪些行为绝对不能变有没有已经存在的测试可以佐证当前行为这些问题看着简单但非常有效。因为很多项目里用户自己都没想清楚优先级Agent 却把所有需求当成同等重要的目标去实现。我一开始觉得这个阶段浪费时间直接跳过了。后来才发现跳过脑暴等于让 Agent 自己脑补需求它脑补出来的那个需求永远比我实际想要的复杂。现在我会主动配合它完成这个阶段把回答写进一个简短的需求记录文件这样后面的架构阶段才有依据。3.2 Architecture用文档把“设计决策”固化下来脑暴结束以后Superpowers 会引导 Agent 进入架构阶段。它的做法是先查看项目结构、关键文件、现有模块边界然后产出一份简短的架构说明。这里有一个容易忽略的点架构说明不是为了写在文档里给别人看的而是为了让 Agent 自己在后续任务执行时能够“照着走”。当 Agent 改到一半忘记整体方向时它可以重新读回这份架构说明避免越改越偏。这就好比施工队手里有一份图纸而不是只靠开工前项目经理口头说一遍。我自己在实际使用中会让这份架构说明尽量短控制在几百字到一千字之间。它只需要说清楚改动涉及哪些文件、模块之间的依赖方向、哪里是风险点、哪些部分可以暂时不动。这样就足够了。有些项目的架构文档写到几千字Agent 反而抓不住重点因为它的注意力窗口有限塞太多资料只会挤压真正执行代码时的上下文。3.3 Implementation 和 Verification小步快跑加持续验证进入实现阶段后Superpowers 不会把一个大目标一次性丢给模型完成而是拆成若干个可以独立验证的子任务。每个子任务完成之后Agent 需要先做验证再继续下一步。它的验证动作包括但不限于运行相关单元测试、检查编译、用 git diff 审查变更范围、根据项目语言执行 linter。如果验证失败Agent 要停下并分析失败原因而不是重新生成一段不同的代码糊上去。这个“失败就停下而不是重试硬编”的习惯是它和普通 Completions 式开发最核心的区别。我记忆比较深的一次是用这套流程改造一个 Java 服务的日志模块。Agent 在完成一个子任务之后主动跑了编译和单测结果发现某个旧测试因为时间格式变化失败了。它没有直接修改旧测试去迎合新代码而是先把失败原因记录了下来回到实现阶段调整了序列化逻辑最终让旧测试通过的同时也保留了新格式的兼容。这个判断过程就完全体现了验证回路的价值。4. 让这套方法真正发挥效力的几个细节4.1 为什么它能处理回滚工程师在重构时会频繁回退但传统意义上的编码 Agent 很少主动回退因为它很难判断“当前路径是不是错了”。Superpowers 能处理回滚原因在于它引入了“状态记录”机制。Agent 在每个阶段结束时会把当前进展写成一个简短的状态文件。当后续执行发现矛盾或者验证失败时它可以参考这个状态文件找出是在哪个阶段发生了偏差然后选择回滚到那个阶段重新开始。这比它在残缺上下文里从头思考要可靠得多。4.2 搜索和浏览边界另一个我很欣赏的细节是它对“搜索动作”的约束。很多 Agent 接到需求后会疯狂搜索代码库把大量相关但不重要的文件扫一遍然后成功把自己的上下文撑爆。Superpowers 工作流则倾向于让搜索围绕特定问题边界展开比如只搜索指定函数的所有调用方或者只查询某个接口的返回类型。缩小搜索边界不是限制 Agent反而是让它的注意力更集中。你可以把这个想象成一个维修工进了机房。有经验的维修工不会把整个机房的设备都检查一遍而是先根据故障现象定位到某几个机柜再针对范围做细致排查。Superpowers 教 Agent 的就是这种定位式搜索。4.3 代码笔记的价值Superpowers 工作流里还会生成一些看起来像是“笔记”的文本片段。这些片段不是给人看的注释而是 Agent 自己的“内存外置”。因为 LLM 的上下文窗口再大也有限当一段会话执行了很久之后早期的信息会被从注意力中挤出去。Superpowers 通过把关键决策、已完成任务、待办事项写进笔记文件等于让 Agent 随时可以回去翻自己的“工作日志”而不是凭模糊记忆继续操作。这招在多文件、跨模块的任务里特别管用。我试过在一个改动量比较大的前端项目里整个会话持续了很久但 Agent 每一步都能从笔记文件里找到之前的设计约束几乎没有出现重复问我已经回答过的问题的情况。4.4 Java 项目有没有语言门槛不少人在热搜里找“superpowers java”我直接说结论Superpowers 本质上是语言无关的Java、Python、Go、前端项目都能用。但实际体感上Java 项目接入后获益更大原因是 Java 项目通常有更复杂的包结构、接口约定和依赖关系Agent 如果没有架构约束很容易在类之间乱拉依赖。Superpowers 强制先架构后实现正好抵消了 Java 项目里最容易出现的那种“改一个类连带五个类一起动”的问题。我用 Java 写完上面提到的日志模块之后最大的感受是它在动手之前对调用链的梳理非常准确准确到我在代码评审时都不太需要补充说明。这点在过去直接用 Agent 编码时是感受不到的。5. 接上这套工作流之后我踩过的三个坑5.1 坑一状态文件越攒越多上下文还是被撑爆Superpowers 鼓励 Agent 把阶段状态写进文件这本身很好但文件也是要占上下文的。有一段时间我在同一个项目里连续做了好几个重构Agent 每次都会把过去几天的状态文件全部加载进来导致上下文越来越重反应越来越慢。后来我改为按功能分支管理状态文件一个分支只保留当前任务对应的笔记和决策记录。跨分支的长期经验不该塞进工作上下文里而是应该沉淀成项目文档或者仓库 README。简单说就是状态文件要“用完即扔”别当长期记忆用。5.2 坑二低估了模型推理能力的要求Superpowers 本质上是在教模型“怎么思考”但前提是模型本身要有足够的推理能力去执行这套思考流程。我在一个低配模型上试过结果它连“脑暴阶段该问什么”都没搞清楚最后又回到老路子上乱猜代码。后来我固定使用推理能力较强的模型来跑这套工作流低配模型只用来做简单问答。这个取舍很重要如果你的模型本身推理水平不高装再多方法论包也没用就像给一个新手强行塞一本《系统架构设计指南》他能看懂字但做不了判断。5.3 坑三过度验证改个变量也要跑全套流程工作流刚接入的那段时间我甚至产生了一种“过拟合”的感觉让 Agent 把某个硬编码变量改成配置项它也给我来了一个脑暴加架构加验证的完整流程。这显然是不合理的。Superpowers 的判断应该是分级触发的单文件小改动可以直接进入实现多文件、跨模块、涉及公共接口的改动才需要走完整流程。如果你发现 Agent 对任何微小的改动都走全套可以在规则里加一条分级判定标准让它在开始前先评估改动影响面。影响面小的任务直接执行不需要启动完整工作流。6. 什么项目建议接入什么项目建议保持现状6.1 适合接入 Superpowers 的典型场景总结一下我自己的使用体会有这三类项目很适合接入 Superpowers历史代码复杂、模块间耦合严重的老项目这类项目最需要架构阶段来约束 Agent避免它乱拉依赖。多文件协同或有明确接口约定的后端项目Java、Go、大型 TypeScript 等项目验证回路能显著降低编译和测试层面的低级错误。需要一个持续运行、跨多会话完成的“长期施工”型任务状态记录机制让 Agent 的思维可以“续上”而不是每次重新开始都像第一次接触这个项目。6.2 不建议接入的情况反过来如果你是快速验证一个想法或者只是想让 Agent 帮你完成一次性脚本那 Superpowers 反而是负担。它那一轮一轮的意图澄清和架构说明会把你从“两分钟拿到结果”拖到“十分钟还没开始写代码”。还有一个场景要考虑如果你的团队没有一个固定的项目管理方式Agent 生成的架构文档没有地方沉淀那这套流程的价值会大打折扣。因为 Superpowers 非常依赖“设计决策可以被记录、被回读”如果记录完根本没人维护那就成了一次性文书工作。6.3 后续可以怎么扩展我最近在尝试的两个方向大家可以参考。一个是把 Superpowers 的分支级状态记录做成一个简单的项目复盘汇总每次迭代结束后从状态文件里提取“当初的设计假设”和“最终实际结果”对比慢慢形成一个团队自己的决策知识库。另一个方向是把它的工作流模板适配到更多工具上不只是 Codex CLI还有团队内部的私有化编码助手。只要工具支持注入自定义规则Superpowers 的骨架就能复用进去。最后分享一个小技巧不管你用的是 Codex、WorBuddy 还是别的编码 Agent在第一次接入 Superpowers 时不要直接拿核心项目试。先找一个不重要的测试模块故意提一个你自己已经知道答案的问题观察 Agent 的行为变化。确认它开始先问、再想、后动手了再放到重要项目里跑。这样你就能在低风险的环境下真正建立起对这套工作流的掌控感而不是被它牵着走。
