让AI Agent按章办事：Superpowers纪律引擎实战指南

1. 先聊聊 AI 编程“失控”的那一刻为什么无数 Agent 都败给了“自由发挥”说个我印象很深的场景。那次我用 Claude Code 让 Agent 帮我改一个支付模块需求就一句话“把超时重试的逻辑加上”。结果它特别兴奋地给我加了三层重试、一个指数退避算法还顺手改了我另一个文件的函数签名——因为它觉得那样“更优雅”。业务逻辑没坏但我的 review 成本比我自己写一遍还高更不用说它中途还自作主张引入了一个新的依赖库。这件事让我意识到一个核心问题AI 编程最大的瓶颈早就不是“模型能不能写代码”而是“Agent 靠不靠谱、守不守规矩”。你给它一个模糊目标它能在几分钟内产出结果但产出的过程完全没有工程纪律可言——不写测试、不按已有架构来、不遵循项目规范甚至会把需求理解成它自己脑补的“升级版”。Superpowers 这个技能框架解决的就是后面这件事。它是一套跑在 Claude Code 这类 AI Agent 上的“纪律引擎”通过结构化的 Skill技能和流程约束强制 Agent 从接到需求开始到写代码、跑测试、做评审每一步都按工程规范来而不是想到哪儿写到哪儿。坦白说我第一次接触它的时候也没太当回事毕竟“给 AI 加提示词约束”这事儿我干过太多次效果都不持久。但用了几周之后我是真的把工作流全面切过来了。这篇文章就把我对 Superpowers 整个机制的理解、实际配置过程、踩过的坑以及它和 OpenSpec、CLAUDE.md 配合起来形成完整闭环的用法一次性讲清楚。如果你也是那个在 AI 编程里反复“救火”的人这篇文章应该能帮你省下不少力气。1.1 一个典型的“AI 自由发挥”事故现场要理解 Superpowers 的价值得先从反面看。拿我自己一个外包项目举例。当时我让 Agent 实现一个用户积分过期提醒的功能。需求其实很简单每天扫描一次积分表把过期前 7 天的用户筛出来给推送通知。我给了它项目路径顺便说了一句“按项目现有风格写就行”。结果呢Agent 直接创建了一个scheduler.py自己引入了一个定时任务库还给整个项目的配置改成了支持多环境变量。我 review 的时候人都傻了。测试呢没写。日志规范它自己定了一套。数据库连接方式它觉得原来的db.py写得不好给绕过去了。功能确实实现了但整个代码和项目的其余部分完全是两个世界的人写的。后来我复盘问题不在于模型能力而在于 Agent 的“价值取向”。它天然倾向于把任务完成得“漂亮”而不是“合规”。没有外部强约束时它会默认自己那套优雅方案就是最好的根本不会先去看项目已有的模式。工程规范里所谓的“一致性”“最小变更”“测试先行”对 Agent 来说是隐形的空气。这就是自由发挥的本质不是恶意是无序。1.2 为什么你写一百遍“请遵守规范”都没用很多人面对这个问题第一反应是加强提示词比如在系统提示里写“你是一个资深工程师请务必遵循 TDD写干净整洁的代码”。我也这么干过。刚开始有点用但效果衰减得特别快。原因有三个。第一是上下文衰减。Claude 这类模型的注意力是有限的你塞给它的指令越多它在具体任务执行时就越容易“忘记”那些优先级没那么高的约束。尤其当一个会话拉到几万 token早期提到的“规范”早就被淹没在海量上下文里了。第二是隐式约束没法落地。你跟它说“按工程规范来”但工程规范是几十条不同粒度的规则文件命名用小写加横线、单元测试文件要靠近源码、不要修改与你无关的模块……这种隐式知识你得拆成显式步骤它才知道从哪个动作开始执行。第三是缺少流程闸门。提示词只能影响 Agent 的“意愿”影响不了它的“流程”。你想要的是它先写计划、你审批、再写测试、看测试失败、再写实现。但模型不会自动这么跑它倾向于一口气把活干完——因为这样最符合它的训练习惯也最省事。这三座大山决定了光靠“说话”管不住 Agent。只有把规则变成程序上的步骤把约束变成触发执行的条件Autonomy 才会被关进笼子里。Superpowers 的核心思路正是把“工程规范”翻译成一连串 Agent 无法跳过的操作节点。2. Superpowers 的底层逻辑Skills 不是提示词是一套可强制执行的工程流程Superpowers 最容易被误解的点是大家觉得它就是一个“更高级的提示词集合”。不是的。它的本质是把“做事方法”封装成了结构化的工作流再让 Agent 按工作流一步步执行。提示词只是它用来沟通的最小单位真正的约束力来自流程本身。你可以把它想成给 Agent 装了一套“施工手册”不是告诉它“你要盖好楼”而是告诉它“先勘察地基、再支模板、再浇筑混凝土、再养护”每一步都有产出物和验收标准。只要流程被严格执行结果自然就不会跑偏到哪儿去。2.1 它到底往 Claude Code 里塞了什么Superpowers 的项目本体是一个 GitHub 仓库你 clone 下来之后里面是一堆按功能划分的 Skill 文件和配套的说明文档。它的核心组成部分是以 CLAUDE.md 为入口把skills/目录下各个 skill 的能力暴露给 Agent。举个例子它里面我会用到的主要 skill 有这几个brainstorming头脑风暴用来澄清需求、writing-plans把需求拆成可执行的计划、executing-plans按计划实施、TDD测试驱动开发、code-review代码评审”。每个 skill 里都有一个 SKILL.md 文件里面详细描述了“这个技能用来干什么、在什么情况下触发、执行时需要遵循哪些步骤、产出物是什么”。这跟普通提示词的关键区别在于Skill 是带“触发条件”和“完成检查”的。如果某个 Skill 要求 Agent 先输出计划再动手那它就不会在没写计划的情况下直接跳去写代码——因为这套流程已经把“输出计划”设置成了它继续执行的前提条件。换句话说这种约束不再是语言层面的“请求”而是执行层面的“门槛”。2.2 从 brainstorming 到 plan 到 execute一次规范的“思考漏斗”Superpowers 的整个流程可以看作一个漏斗从抽象需求开始逐步收敛到具体任务再进入执行。这个漏斗的第一层是 brainstorming。它的作用是逼 Agent 在动手前先确认需求。你在 Claude Code 里敲#调用 brainstorming skillAgent 不会立刻给方案而是反过来问你一系列问题你到底要解决什么问题现有的系统边界在哪你期待的结果是什么状态这块体验非常像跟一个较真的同事过需求而不是面对一个急于交作业的执行者。需求澄清之后进入第二层 writing-plans。这个 skill 会把目标拆成一份 Markdown 格式的计划文档里面有步骤、有依赖关系、有验收标准。我在实际用的时候它生成的计划往往会分阶段并且会在计划里标记哪些地方需要我人工确认。这个文档不是摆设后续的 executing-plans 会严格按照这份计划来执行Agent 每做完一步都会检查自己“是不是还在计划轨道上”。最后才是真正写代码的阶段。这个阶段也会套上 TDD skill先让它根据计划写测试再跑测试看到失败然后写实现代码让它通过最后做重构。整套漏斗走下来Agent 每一步都有明确的上下文和目标而不是握着整个代码库自由发挥。2.3 TDD 为什么是 Superpowers 的“纪律核心”前面说的计划流程负责管方向TDD 这个 skill 负责管质量。技术上TDD 本身只是“红-绿-重构”三个循环先写一个会失败的测试再写让测试通过的最简实现最后在安全网的保护下重构。听起来很简单但让 Agent 执行起来却非常难。难在哪因为模型本质上是“结果导向”的。你让它实现一个功能它的本能是先写实现测试只是附带品。但 TDD skill 会把顺序彻底倒过来在 Agent 看到任何实现代码之前它必须先根据需求写出一批测试用例。这些测试的内容实际上就是把需求文本翻译成了可验证的行为契约。这一步的价值体现在两个地方。一方面它逼 Agent 在写码之前想清楚“这个功能的行为边界到底是什么”很多需求歧义在这一步就会暴露而不是等到功能上线才发现理解错了。另一方面测试代码是天然的“质量标准”Agent 后续的实现有没有跑偏跑一下测试就知道了不用靠人肉 review 猜。我在实际项目中感受最深的是有了 TDD 约束之后Agent 的“自作聪明”行为大幅减少。因为它一旦开始重构别人的函数或者改接口测试会直接报警。纪律不是靠自觉是靠“违规就会被抓住”的机制。3. 从安装到跑通我把 Superpowers 接进工作流的关键细节概念说完了进入实操环节。Superpowers 的安装本身不复杂但有几个坑要提前避不然会被各种“目录找不到”“Agent 不识别 skill”的问题卡半天。以我目前使用的方式为例我的目标环境是macOS 本机 Claude Code 已安装 Node.js 环境可用。Superpowers 本质上依赖 Node.js 来跑一些辅助脚本所以 Node 版本不能太低建议 18 以上。3.1 克隆仓库前先想清楚三件事第一件事是“装到哪里”。Superpowers 官方推荐的做法是 clone 到~/.claude/skills/里这样对当前用户下所有项目生效。但我个人的建议是如果你在多个项目里实验先放进全局目录感受一下一旦决定在某个正式项目里固化使用就复制到项目自身的.claude/skills/里。理由很简单全局生效意味着 Agent 在每一个会话里都会把这一堆技能加载进来上下文被占用的代价是你想象不到的。第二件事是“版本锁定”。Superpowers 目前迭代特别快master 分支随时可能变。第一次 clone 成功之后建议记录一下 commit hash后续更新时做一次对比再升。我之前有一次直接git pull结果某个 skill 的目录结构变了旧项目的 CLAUDE.md 引用路径全部失效Agent 完全找不到技能折腾了一天。第三件事是“盘点你要哪些 skill”。不是仓库里所有 skill 都适合你的项目。如果项目本身没有测试体系硬上 TDD 会让你先补一大堆测试基建。我现在的用法是核心的 brainstorming、writing-plans、executing-plans 一定保留TDD 和 code-review 看项目成熟度决定要不要启用。3.2 一步步配置让 Claude Code 主动认识这些技能整个配置我给你拆成几个动作你跟着做就行。第一步clone 仓库。我把指令放在下面如果你已经有~/.claude目录就直接用没有就先建一个。mkdir -p ~/.claude git clone https://github.com/obra/superpowers.git ~/.claude/skills/superpowers注意这里有个最容易踩的坑很多教程会让你 clone 到~/.claude/skills根目录下直接把一堆 skill 文件散在skills/里。这会导致 Claude Code 在扫描技能时目录结构对不上加载失败。正确做法是 clone 成一个子目录superpowers让它的内部结构和仓库保持一致。第二步告诉 Claude Code 去读技能说明。你需要在项目根目录或全局的 CLAUDE.md 里加上一段引用我习惯这样写在开始任何复杂任务前先阅读 ~/.claude/skills/superpowers/SKILL.md 了解可用技能并按其中描述的流程执行。这一步的作用是给 Agent 一个“入口索引”。因为 Agent 不会自己去翻你的文件系统你得明确告诉它技能说明书在哪儿。如果你把 Superpowers 装到了项目目录那路径就改成.claude/skills/superpowers/SKILL.md这种项目相对路径。第三步重启会话。CLAUDE.md 的改动只在新的会话里生效。改完配置之后一定要/clear开一个新会话然后随便敲一句“你有哪些技能”看它能不能正确罗列出来。如果这一步失败了优先检查路径和目录层级。3.3 第一次触发 Skill 时的交互体验配置完成之后你不需要做什么特别的操作。正常描述你的需求比如“我想给订单模块加一个取消功能”Superpowers 的入口会判断这个问题是否足够复杂、是否需要启动 brainstorming。如果它判定需要就会在回复里引导你进入技能流程。实际操作中我会看到类似这样的交互Agent 先回复一段“这个问题有几个关键点需要先确认”然后列出三四个问题等我的反馈。这种“不急着干活”的状态就是 skill 被触发的信号。这里我要特别说一点你会觉得 Agent 变“啰嗦”了。以前你一个需求丢过去它闷头写半天给你一坨代码现在它会先问需求、再给计划、再等审批节奏明显变慢。但你要理解这个“慢”本身就是纪律的一部分。它把大量返工成本提前到了计划和设计阶段实际上总耗时往往是下降的。第一周你会不习惯但坚持下来你会发现这种“慢”才是真的快。4. 实测两周后Agent 的行为发生了哪些肉眼可见的变化光讲理论没意思我直接说实测结果。我把 Superpowers 接入到一个真实的中型项目里跑了大概两周这个项目是 Vue 3 FastAPI 的全栈应用有测试基线但覆盖不全团队成员对代码规范有要求但没有自动化检查。以下是几个让我印象深刻的实际变化。4.1 同一个任务的前后对比从“直接开写”到“先出计划”我特意做了一个对照实验。同一个需求“把用户列表接口加上分页参数”我分别用普通 Claude Code 会话和接入了 Superpowers 的会话来处理。普通会话的行为直接搜索用户列表接口的位置然后改代码返回一段修改摘要告诉我“已经加上了 page 和 page_size 参数”没有任何测试和计划。Superpowers 会话的行为先触发 brainstorming问了我“分页默认值是什么前端传参格式是 page1size20 还是 limit20接口返回格式要不要包一层 metadata”等问题。确认之后生成了一份计划明确写着“在现有 ListUsers API 上增加 query 参数同时保证原有调用不受影响新增 2 个测试用例验证分页边界”。最后才进入 TDD 流程先写测试跑红再改实现跑绿。我把两份产出都提交到分支里差异是巨大的。前者代码能用但没有任何安全保障后者从一开始就有测试兜底后续重构也不心虚。这就是工程规范和自由发挥最直观的区别。4.2 测试先行真能压住“无意义返工”吗我本来有点怀疑 TDD 在 AI 编程里是不是形式主义但两周里发生的两次事情说服了我。一次是 Agent 在实现“优惠券叠加”功能时TDD 流程让它先写了“同一订单不能叠加两张同类优惠券”的测试。写实现的时候它试图直接修改优惠券计算的公共函数结果跑测试立刻失败因为公共函数变更影响到了其他已经通过的用例。于是它被强制停下来重新评估最小变更方案最后选择在调用层做判断而不是大改底层。另一次是“积分过期提醒”那个任务。因为测试先定义了“只在过期前 7 天发送提醒”的边界Agent 实现时想改成“10 天内都提醒”测试直接红迫使它重新读需求确认。如果按自由发挥模式它可能就自作主张改了业务规则我们 review 时还不一定看得出来。这个机制的厉害之处在于它不是靠 prompt 求 Agent 别乱来而是用测试结果作为“行为是否符合预期”的裁判。一旦越界立刻暴露返工成本被压到最低。这种效果是任何文字约束都达不到的。4.3 code-review 模式揪出的典型问题Superpowers 的 code-review skill 我一开始以为就是拿来看一遍代码有没有 bug用了几次发现它的价值远不止此。它会在审查时按几个维度检查变更是否超出任务范围是否有重复造轮子是否有明显的安全或性能隐患是否遵循了项目现有的命名和分层最让我吃惊的是它能在 diff 里识别出“Agent 顺手做的无关改动”类似之前那样改掉函数签名这种——它会明确标记“此变更与当前任务无关建议撤销”。我特意统计了一下两周内 review 报告里频率最高的三类问题排名第一是“改变了现有 API 的响应格式但未更新调用方”第二是“在公共模块添加了只为一个调用点服务的参数”第三是“新增了不必要的依赖”。这些问题放在人工 review 里要花不少时间才能发现而 skill 基本能在几分钟内列出来。作为人在环路的最终把关者我只需要确认这些告警是不是真的需要修省掉大量从 diff 里找问题的精力。5. 和 OpenSpec、CLAUDE.md 配合把“纪律”从代码层面扩展到项目层面Superpowers 管的是“Agent 接到任务之后怎么执行”但落到真实项目里光有执行纪律还不够。需求本身是模糊的项目约束是散落的这两块如果不兜住Superpowers 在中间环节再怎么规范源头一个错误理解也会传递到最终代码。这也是圈子里经常把 Claude Code OpenSpec Superpowers 称为“三件套”的原因。5.1 OpenSpec把需求从“一句话”变成“可验证规范”OpenSpec 是一个规范驱动开发的开源工具它解决的是“需求到底说了什么”的问题。它用结构化的 Markdown 文件来描述系统行为每个功能点对应一个spec.md里面写清楚背景、需求细节、验收标准。我现在的流程是接到需求后先让 Agent 用 OpenSpec 生成一份规范草案我审核并修订后才进入正式开发。这样做有一个非常大的好处需求和实现之间不再是“一连串聊天消息”而是一份可持续追踪的文档。后续如果 Agent 对某些行为不确定它可以回去翻 spec而不是靠猜。举个例子有一次客户提了个需求“用户可以在会员中心看到积分明细”。这听起来足够清晰了吧但 OpenSpec 的流程会让 Agent 细化出“积分明细包含哪些字段”“排序规则是什么”“是否分页”“统计口径是入账时间还是出账时间”。这些细节全都沉淀进 spec 文档写代码时 Agent 只需要翻译文档不需要二创。5.2 CLAUDE.md项目级规则应该写什么CLAUDE.md 是 Claude Code 的项目记忆文件它就是 Agent 每次进入项目时必读的“员工手册”。Superpowers 的 Skill 说明书放在这但项目自身的约束也放在这。我建议 CLAUDE.md 至少包含这几块项目技术栈和技术选型理由、目录结构说明、代码风格约定命名、注释语言、接口设计风格、测试要求哪些目录必须有单测、怎么跑测试、禁止事项比如不允许修改哪些目录、不允许引入哪些依赖。你写得越具体Agent 的自由发挥空间就越小。这里我说一个实战体会。以前我总想写“代码要高质量”这句空话对 Agent 一点用没有。后来我改成“所有 API 层的输入必须用 Pydantic 做校验不允许在 View 函数里直接操作原始 request 对象”。这种规则是 Agent 能直接执行的而且它一旦违反你在 review 时一眼就能看出来。规范的价值不在于写得漂亮在于能够被执行和验证。5.3 三件套怎么分工才不会功能重叠很多人觉得 OpenSpec、CLAUDE.md、Superpowers 都在“约束 Agent”会不会功能重复我一开始也迷糊用了一段时间才理清楚它们的分工。合理的分工是OpenSpec 管“做什么What”负责从模糊需求里提炼出可验证的行为规范CLAUDE.md 管“在什么约束下做Constraints”描述项目固有的技术栈和规则Superpowers 管“一步步怎么做How”定义任务从接单到交付的方法流程。这三者的配合可以画成一条流水线需求进来OpenSpec 把它变成规范文档规范确定后Superpowers 的 brainstorming/writing-plans 把文档变成可执行计划Agent 写代码的过程中CLAUDE.md 里的项目规则兜底写完代码再通过 TDD 验证和 code-review skill 收尾。每层各管一段既有独立性又能串成闭环。我从接入这套体系之后AI 产出的代码基本只需要做业务确认不用再为“代码规范”给他返工。6. 绕不开的边界哪些场景下 Superpowers 反而会帮倒忙任何工具都有局限Superpowers 也不是银弹。我用了这段时间踩了一些坑有些场景下这套“纪律引擎”不但没提效反而让简单事变得复杂。这些边界如果你不提前知道很容易被劝退。6.1 Skill 目录塞太满Agent 会“选择困难”Superpowers 的技能体系本身就不少再加上社区里还有一堆第三方 skill。如果你一股脑全装进去Agent 每次任务前都要在几十个技能里做选择反而容易选错。有一次我装了一个“图片优化”的 skill结果在我做前端页面调整时Agent 自己触发了一次图片压缩流程等了几分钟其实我根本不需要这个操作。所以我的建议是“最小化技能集”只保留你项目真正高频使用的技能其他的一律不装。少即是多。6.2 计划写得再细也要留人工审批闸门Superpowers 的 plan 流程确实能把需求拆得很细但它生成的计划不等于你确认过的事实。有一次它针对“导出数据”的功能写了八步计划里面有一步是“新增一个后台任务队列来异步处理导出”。这个方案在技术上没错但对我们那个小项目来说纯属过度设计。好在整套流程里计划会等我来确认我直接删掉那一步调整了思路Agent 就沿着修正后的计划执行下去了。这个教训是不要让“它的计划”成为“你的计划”。你得把它生成的计划当作一份草案保持否决权。人工闸门一旦放开前面所有纪律都会失去意义。6.3 资源消耗和时间成本比想象中大这一点很多人不会跟你说TDD 和严格的流程会让单次任务耗时明显变长同时 token 消耗也会上升。毕竟它要先写测试、跑测试、看失败、写实现、再跑测试每一步都要读文件和上下文这比直接生成一段代码贵得多。在我们团队一个中型需求的 token 消耗大概比普通会话高出 40% 到 60%。如果项目本身预算敏感或者你只是做一次性脚本那这套重流程就没必要上。按需启用才是理性的做法像我自己的小项目就没有全程开 TDD只开 brainstorming 和 writing-plans。6.4 不适合的场景原型探索和一次性任务最后说说场景边界。Superpowers 适合的是“要长期维护、多人协作、对稳定性有要求”的工程化项目。但如果你是在快速验证一个方案、做一个 hackathon demo、或者临时写个脚本处理数据那这套纪律引擎反而会拖你后腿。我上次想快速实验一个数据清洗思路Agent 还在那按流程跟我确认需求和写测试我直接把它打断了。这种场景需要的是“自由发挥”的模糊探索让模型快速给出各种可能性而不是一板一眼地按工程规范交付。判断标准其实就一句话这件事做完之后还要不要长期维护要就上纪律不要就让它随便跑。7. 我最后想说的是关于“可控性”的一点个人体会用 Superpowers 这段时间让我重新想明白了一个问题AI 编程的未来方向不在于把模型变得更强而在于让模型在既定规则内稳定发挥。能力强但没有纪律的 Agent相当于一个技术很牛但完全不听指挥的同事——你宁可不要他。而 Superpowers 的意义就是给 Agent 建立了一套可执行、可验证、可干预的行为规范让它从“自由发挥”变成“按章办事”。当然它不是万能的。它不能代替架构师不能代替产品经理把需求想清楚更不能取代你作为工程师的判断力。它真正的价值是把那些繁琐但必须遵守的工程规范从你的口头叮嘱变成 Agent 的执行本能。如果你现在也被 AI 的“自由发挥”折磨得头疼我的建议是别一上来就全套照搬。先只装 brainstorming 和 writing-plans跑一个迭代感受一下流程变化觉得能接受再逐步加上 TDD 和 code-review。让 Agent 从一个“莽撞的实习生”变成一个“有章法的高级工程师”这中间需要的不是更强的模型而是一套你真正愿意坚持的纪律。