最近我在带团队用 Codex 和 Claude Code 跑一个中型的业务系统重构发现了一个很现实的问题AI 编程代理写代码确实猛但一旦离开局部上下文整个流程就容易乱套。你让它写一个接口它能马上给你一套完整的 API可你让它从需求梳理开始、自己拆任务、自己写测试、自己重构最后再产出一份像样的变更文档它十有八九会在中途跑偏。直到试了 Superpowers情况才明显好转。Superpowers 不是一个新的语言模型也不是某个 IDE 插件而是一套围绕 AI 编程代理设计的完整软件开发工作流。它把“技能”skills这件事做成了体系从需求分析、任务拆解、TDD 实践、代码审查到文档沉淀每个环节都有对应的技能包引导代理像一位真正的软件开发工程师那样思考和工作。这篇文章就是我的使用记录和踩坑总结适合那些已经在用 Codex、Claude Code、Cursor 等 AI 编程代理、但总感觉效果不稳定的团队和个人开发者。1. Superpowers 到底在解决什么问题1.1 AI 编程代理的“偏科”困境过去我们使用 AI 编程代理的方式基本等于“提示词—代码”的直给模式我提一个需求它给一段代码。这个模式在处理局部函数、单个接口、单元测试时效率确实很高但把它放到一个完整项目或者一个跨模块的需求里问题就来了——它往往只能看到眼前的一小段代码缺少全局视角更不会主动分解任务。就像一个只会写一行行代码的工程师却没有人告诉他整个模块要完成什么也不知道下一步该做什么。我在实际项目里最大的感受是模型本身的能力已经够了缺的是“流程约束”。让它写一个函数它很出色让它管理一组任务列表它却会飘。Superpowers 的做法就是把“怎么做一个软件项目”的隐性经验显式化写成一组可加载的 skill 文件让代理在切换任务时按照这些流程走而不是每次从零开始自由发挥。这相当于给 AI 装了一套“工作方法”而不是简单增加代码量。1.2 从“代码助手”到“软件开发工程师”的转变所谓“软件开发工作流”并不仅仅指写代码的顺序还包括需求澄清、任务规划、测试先行、重构、代码审查、文档同步等等。Superpowers 把这些环节抽象为一个个独立的“技能”每个技能里既包含提示词模板也包含操作规则和决策树。当代理拿到一个任务时它会先加载对应的技能包然后按照技能包定义的工作流去执行。这带来的直接变化是代理不再是一个单点工具而是可以被“编排”的执行者。你可以告诉它“使用 TDD 技能完成登录功能”它会先写失败测试、然后实现、再重构你也可以告诉它“使用计划技能梳理这个迭代”它会主动列出任务、识别风险、给出时间估算。对团队来说AI 编程代理从“快速补代码”变成了“可预期的开发成员”而不是一个随缘出结果的暗盒。1.3 技能驱动的核心设计思路Superpowers 的设计思路本质上是在模型能力之上加了一层“工作流抽象层”。它把项目开发中反复用到的最佳实践比如测试驱动开发、重复代码消除、文档即代码编码成结构化的技能描述。这些描述通常包含适用场景、执行步骤、产物要求、以及常见的“不要做什么”。我觉得这个思路很高明的一点是它没有试图用一套固定的流程把代理限制死而是把技能拆成可以被选择和组合的模块。有些技能是分析类的比如需求澄清有些是实践类的比如 TDD有些是治理类的比如代码审查。代理在特定阶段加载特定技能就像我们人类工程师在不同阶段切换思维模式一样。这种做法既保留了模型的灵活性又给它提供了明确的操作路径比单纯丢给代理一个巨大的 system prompt 要可控得多。2. 核心技能拆解一套完整的工作流2.1 需求澄清与目标设定一个靠谱的开发工作流起点绝不是动手写代码而是需求澄清。Superpowers 的“需求澄清”技能会引导代理向用户提问这个功能要解决什么核心问题目标用户是谁有哪些边界条件验收标准是什么这些问题不是一次问完而是根据上下文逐步追问直到能生成一份可执行的需求说明。我在使用中特别感受到这一步能帮我挡住很多“伪需求”。以前我给代理一个很含糊的描述它往往会先假设一个解决方案然后埋头实现最后发现根本不是我要的东西。现在让代理先加载需求澄清技能它会在设计前先输出假设再让我确认。这种“先确认再动手”的机制能省下大量返工时间。尤其是涉及多方协作的项目需求澄清技能产出的“问题清单”可以直接作为需求评审的输入帮助团队把遗漏点提前暴露出来。2.2 测试驱动开发TDD流程TDD 是 Superpowers 最核心的技能之一。技能包会规定严格的执行顺序先写测试运行测试确认它失败然后写最小实现让测试通过最后重构代码并保证测试仍然是绿的。代理在执行时会把测试结果作为强反馈而不是仅凭“感觉”认为代码没问题。以 Java 项目为例代理会根据需求先写出 JUnit 测试用例再运行 Maven 或 Gradle 命令等测试失败后补上实现再次运行测试直到全绿。这个过程听起来机械但实际使用中它带来的收益非常明显代码覆盖率会显著提高重构时也不容易破坏已有功能。最值得一提的是Superpowers 的 TDD 技能还包含一个很实用的细节——如果实现过程中出现意外失败它会建议回退到最近一次全绿状态而不是强行“修修补补”。这个习惯对保持代码库稳定非常关键尤其适合多人同时修改同一代码库的团队。2.3 任务拆解与进度管理除了写代码Superpowers 的“任务拆解”技能可以把一个大需求拆成可执行的小任务列表并标注依赖关系和验收标准。这样代理在执行过程中可以自己决定先做什么、后做什么同时把进度记录在工作目录里的一个 Markdown 文件里。这个功能在多人协作或长期迭代中格外有用。因为代理的上下文窗口有限它不可能一直记住所有任务通过把任务列表外置到文件中每次重新加载上下文时代理只需要读取进度文件就能快速“回忆”起当前状态。我在实践中经常把它当作 AI 代理的“备份记忆”即使会话意外中断恢复后也能无缝接续。如果你正在负责一个跨月的迭代建议每天让代理更新这个进度文件长期下来它就成了一份非常自然的项目周报素材。2.4 重构与代码审查重构技能的目标是减少重复代码、改善类设计、优化 API 边界。它不会大刀阔斧地改动而是遵循小步重构的原则每次只改一小块跑测试确认没有破坏再继续下一步。配合 TDD 流程重构会变得非常安全。我在一个老项目里试过让代理对一张大而全的 Service 做拆分它通过一次只提取一个方法的方式用了大约十轮小步重构最后把原本 800 行的类拆成了四个职责清晰的类期间所有测试一路绿灯。代码审查技能则像一位资深工程师在做 Code Review。它会从代码可读性、测试缺失、潜在 Bug、性能隐患等角度给出评论并给出修改建议。最让我惊喜的是审查技能输出的是人类可读的评论而不是那种“代码有 bug请修改”的笼统提示。它会明确指出具体文件和行号并附带修改前后的对比示例直接发给团队成员使用也完全没有问题。这比很多商业代码扫描工具更贴近工程师的交流习惯。2.5 文档与知识管理Superpowers 的文档技能分成两部分一部分是生成项目级文档比如 README、架构说明另一部分是把开发过程中的决策记录下来比如 ADR架构决策记录。它甚至会要求代理同步更新任务进度和变更日志形成一种“开发与文档同步演进”的节奏。以前我不太喜欢让 AI 写文档因为写出来的东西经常太“浮”说了半天没有具体的操作说明读完还是不知道怎么做。但 Superpowers 的文档技能通过结构化管理要求每个文档里必须有“示例”“执行步骤”“注意事项”这些章节所以产出的文档更接近“操作手册”而不是“宣传稿”。如果你维护的是一个对外使用的开源项目这个能力会特别有价值。我的习惯是每次完成一个模块就让代理顺手生成一份简短的决策记录解释为什么选择这个方案对后续接手的人帮助很大。3. 安装与配置实操以 Codex / Claude Code 为例3.1 环境准备Superpowers 本身不是一个独立运行的进程而是运行在 AI 编程代理之上的技能管理方案所以第一步是保证你有一个可用的代理环境。我自己实测过 Codex 和 Claude Code两者都能正常工作。如果你是命令行重度用户推荐优先用 Claude Code因为它的 CLI 交互更成熟如果团队统一用 OpenAICodex 也完全没问题。需要准备的东西包括一个可用的 AI 编程代理命令行工具、Git用来拉取和更新技能库、Node.js部分脚本依赖以及基本的开发环境比如 Java 项目就需要 JDK 和 Maven/Gradle。我踩过的一个坑是刚开始没装 Node.js结果技能包里的“脚本执行器”一直报错所以建议提前装好 Node.js版本最好在 18 以上。如果是在 Docker 环境里使用也不要忘记把代理可执行文件的路径和 Node 路径都映射进去否则启动时容易相互找不到。3.2 安装 Superpowers安装分两步第一步是把项目克隆到本地第二步是让代理加载初始化配置。常见的安装方式如下git clone https://github.com/your-scene/superpowers.git ~/.superpowers cd ~/.superpowers ./install.shinstall 脚本会做两件事把技能库索引写入代理的配置目录并在当前用户目录生成一个.superpowersrc配置文件。如果你的技能库目录不在默认位置可以通过环境变量SUPERPOWERS_HOME来指定。需要说明的是不同版本的项目安装细节可能有差异以上是基于我使用时的安装过程作为一个常见实践的参考。安装完成后进入代理交互界面输入/skills如果能列出技能列表就说明安装成功。如果列表为空多半是脚本没有正确找到代理的配置目录可以检查一下.superpowersrc里的路径是否真实存在。3.3 配置你的第一套技能技能有两种使用方式一种是在对话中直接调用比如/skill tdd start另一种是在项目根目录放一个superpowers.yml通过这个文件指定当前项目要启用的技能集。我建议团队项目优先用配置文件因为这样可以统一成员之间的工作流减少同一代码库内出现“每个开发者一种做法”的混乱。下面是一个简化版的示例project: user-service skills: - requirement-clarify - tdd - task-split - code-review - docs-generate这样设置后代理每次在项目中启动时都会自动加载这些技能。如果某个需求不需要某一技能也可以在对话中临时关闭非常灵活。你也可以通过skill-order字段指定加载顺序比如先加载需求澄清再加载任务拆解最后加载 TDD这样代理的思考路径会更符合人类工程师的习惯。3.4 让 Superpowers 接管一个真实项目Java 示例为了演示我用一个真实的 Java 业务模块来说明假设需求是“添加一个用户注册接口包含邮箱唯一性校验”。传统 AI 代理很可能直接生成 Controller、Service、Repository 代码就完事了而 Superpowers 驱动的代理会按照技能流程执行。先加载需求澄清技能它会追问注册是否需要邮箱验证码密码规则是什么是否需要手机号确认后生成任务清单。接着加载 TDD 技能代理会在src/test/java下生成失败测试运行mvn test确认失败然后补全实现代码再运行测试最后进行重构并更新任务列表。整个过程下来最终产出不仅有代码还包括测试报告、任务进度和变更说明。我可以随时在对话中查看中间产物发现问题就及时叫停而不是等它全部跑完才发现方向错了。如果你实际使用后发现生成的任务清单只存在于对话里没有写到本地文件多半是任务拆解技能没有正确加载可以检查superpowers.yml里是否包含了task-split技能。这里有一个我强烈建议的小技巧把进度文件也纳入版本控制每天提交一次这样即使模型重写对话项目的“记忆”也不会丢相当于把 AI 代理的短时记忆变成了项目级的持久记忆。4. 常见问题与排查技巧实录4.1 代理“失控”技能执行偏离轨道我遇到最多的现象是代理加载了技能包但执行到一半开始“自由发挥”。比如 TDD 顺序变成了先写实现再补测试或者任务清单越列越乱甚至开始改无关代码。大部分时候原因不是模型能力不够也不是 Superpowers 框架失效而是技能上下文不够强。常见解决方案是在项目根目录放一个superpowers.yml把要遵循的技能明确列出来并在对话开始时点名当前阶段比如“现在进入 TDD 阶段请先写测试不要先写实现”。如果还是跑偏就用/skill reset重置技能状态再重新加载对应技能包。我在实践中发现只要在关键节点上多“点名”几次代理的纪律性会明显提高。4.2 环境变量与依赖缺失运行 Java 项目时Superpowers 调用 Maven 或 Gradle 需要正确的环境变量。最常见的问题是JAVA_HOME没设置或者代理运行时的 PATH 和你的 shell 环境不一致导致它执行mvn test时提示命令找不到。我建议把所有环境变量写入代理的启动脚本或者在superpowers.yml里声明env字段。另外如果某个技能依赖命令比如tree、jq在安装时最好把这些基础工具先装好避免执行到一半才发现工具缺失。踩过几次坑后我的做法是在安装完 Superpowers 后先跑一次/skill doctor它会帮你检查常见依赖是否齐全能省掉很多后续排查时间。4.3 模型上下文窗口不够用Superpowers 的技能文件较多如果项目很大技能描述加进度文件很容易把上下文撑满。我的经验是不要在同一会话里启动全部技能。比如把项目分为“开发阶段”和“审查阶段”在superpowers.yml中用注释临时关掉不需要的技能让代理聚焦在当前阶段。另外任务进度文件要写得精简只保留待办、完成状态和关键决策不要把大段讨论记录全部塞进去。模型把宝贵上下文窗口用在读代码和写代码上效果会远远好于去读一堆历史聊天记录。我甚至会给进度文件设置一个最大行数一旦超过就让代理归类压缩一次保持文件始终“小而可读”。4.4 与现有 CI/CD 的衔接如果你的代码库已经接入了 GitHub Actions 或 GitLab CI最理想的情况是让 Superpowers 的技能复用现有 CI 命令。比如 TDD 技能的测试命令不要在技能里写死成mvn test而是建议从项目配置中读取。我的做法是在superpowers.yml里设置test-command字段让代理使用的命令和 CI 里的命令保持一致。否则很容易出现本地测试通过、CI 却失败的情况往往就是因为两边调用的测试命令不一致。例如 CI 里用的是mvn verify但本地代理用的是mvn test后者不会运行集成测试等推到远程才发现问题返工成本会高很多。这是一个很隐秘但影响很大的配置项值得在项目初始化时就设定好。4.5 避坑清单与经验整理一个我在真实项目里反复用到的速查表方便对照排查问题可能原因解决办法代理未按技能顺序执行缺配置或上下文被稀释用superpowers.yml固定技能对话中频繁点名当前阶段测试命令在代理中失败PATH / JAVA_HOME 不一致将所有环境变量写入启动脚本统一配置进度文件越来越膨胀日志记录太多未精简只保留待办、完成、关键决策定期压缩安装脚本执行报错缺少 Node.js 18升级 Node.js并重跑安装脚本技能列表为空SUPERPOWERS_HOME环境变量错误使用/skill debug查看技能加载路径这里最想强调的一点是Superpowers 并不是银弹它不会让 AI 编程代理瞬间变成 100 分的工程师但它确实能降低很多不确定性。我个人的体会是与其纠结模型的能力边界不如先给代理搭好一个稳定的工作流骨架。只要“发现目标—拆解任务—执行测试—审查重构—沉淀文档”这个闭环能稳定跑起来开发效率的提升是肉眼可见的。尤其对团队来说统一的工作流意味着每个人从代理身上得到的结果质量更接近Code Review 的标准也更容易对齐。最后再分享一个我一直坚持的小技巧每次让 Superpowers 完成一个里程碑我都会让它用“变更日志”技能把这段经历总结成一篇简短的 Markdown 文档提交到仓库里。几个月下来这些文档就成了团队最宝贵的知识库新成员接手项目时只要翻一遍记录就能少走很多弯路。如果你的团队也在用 AI 编程代理不妨从今天开始给它们配上一套完整的工作流Superpowers 是一个相当合适的起点。