如果你用 Claude Code 或者同类 AI 编程工具写过真实项目大概率经历过这种场面让它改一个 Bug它顺手把整个模块重写了让它加一个功能它跳过需求确认直接开干等代码写完才发现方向完全跑偏你明明在提示词里写了“先写测试”它答应得好好的转头就把测试文件丢在一边。AI 编程 Agent 的能力确实强但越强的 Agent 越容易“自由发挥”。自由发挥对原型阶段是好事对工程阶段就是灾难。Superpowers 就是冲着这个问题来的。它不是某个具体的编程框架也不是提示词模板而是一套给 AI Agent 用的“纪律引擎”——它的核心作用是约束 Agent 的行为方式强制它按照 brainstorm、plan、checklist 这类的工程流程干活让 Agent 从“想到哪写到哪”变成“计划、评审、小步执行、自检、交付”的规范化作业。这篇文章我想结合自己这段时间的实操经验把这套东西的原理、装法、用法和坑都聊透希望能帮到在 AI 编程路上同样被“失控 Agent”折磨过的人。1. AI 编程的“失控现场”Agent 到底做错了什么1.1 Agent 不是不好用是太“自由”先梳理一下现状。AI 编程大体上经历了两个阶段第一阶段是自动补全GitHub Copilot 这种模型只负责在你敲代码的时候猜下一个 token第二阶段是 Agent 时代Claude Code、opencode、Codex 这类工具不只是补全而是能自主读写文件、执行命令、跑测试、改代码一次任务能完成“需求 → 实现 → 验证”的闭环。听起来很美好对吧但真正用起来你会发现一个问题Agent 实现目标的方式往往极其粗暴。我举几个自己真实踩过的场景第一个场景我让它修一个数据格式转换的 bug。它定位到源头之后没有只修转换逻辑而是把整个工具类重写了导致所有依赖旧 API 的地方全部报错。第二个场景我让它给现有的支付流程加一个折扣逻辑。它直接在我没有要求的情况下改了数据库字段还顺手迁移了一张完全无关的表。第三个场景我让它写一个单元测试。它写了但是测试逻辑和实现逻辑几乎一模一样属于典型的“测试给实现背书”随便改个 Bug 测试就跟着一起绿了。这些问题不是模型能力不够而是 Agent 的优化目标有问题。大模型本质上是一个“文本续写器”它优化的是“生成的代码像不像正确的代码”而不是“生成的代码是否经过验证、是否符合项目规范、是否最小化变更”。在缺乏外部约束的情况下Agent 天然倾向于写出一个“看起来能用”的大一统方案而工程规范恰恰是要求它克制、渐进、可验证。1.2 自由发挥和工程规范之间的鸿沟我们把自由发挥和工程规范做个对比你就能看到差距在哪。AI Agent 的典型行为模式是高产出、低审查一次性生成大量代码平均下来单行代码的质量不错但整体结构混乱它不会主动在改代码前梳理影响面也容易忽略“是否有测试覆盖”这个问题。工程规范对应的则是另一套行为模式先确认需求再拆解设计再小步实现。每步改动尽量控制在可 review 的粒度测试先行或至少同步补测试代码风格统一文档和注释跟着变更同步更新。这些规则单独拎出来任何一条都不难难的是让 Agent 每一步都自觉遵守。为什么难因为工程规范本质上是对“短期效率”的抑制换取“长期质量”。Agent 被设计成“越快完成越好”而规范要求它“绕一段远路”。如果没有外部机制强制Agent 几乎一定会选择那条捷径。这就像一个有天赋但刚入行的程序员你口头告诉他要写设计文档、要补测试、要控制 diff 大小他一听就懂一写就忘。1.3 为什么提示词约束解决不了根本问题很多人会尝试在提示词里约束 Agent比如在系统提示词里写“请先输出计划再开始写代码”“所有改动必须附带测试”“遵守项目的代码规范”。我第一次也是这么干的。第一轮任务确实有效Agent 规规矩矩地输出了计划然后才开始写代码。但多轮对话之后问题就来了。原因在于上下文窗口。Agent 在执行子任务时原始提示词中的规范会被不断压缩、摘要甚至被后续内容挤出上下文窗口。你在第 1 轮对话里定下的约定到第 15 轮子任务时早就成了一行模糊的摘要。提示词只是“口头约定”Agent 在长流程中非常容易遗忘。还有一个更隐蔽的问题即使你每次都强调规则Agent 也没有一个“自我检查”的触发机制。它不会主动去想“现在这个场景是不是应该停下来做个设计评审”。规范如果只存在于人嘴里就永远只是“建议”而不是“流程”。正是这些原因让我开始寻找一种能把工程规范“固化”进 Agent 运行机制里的方案而不是靠每次对话重新叮嘱一遍。这也是我第一次接触 Superpowers 时最兴奋的地方——它把规范做成了 Agent 可以调用、也必须调用的外部流程模块。2. Superpowers 是什么用 Skill 给 Agent 立规矩2.1 先把概念理清Agent、Skill、Superpowers 三者的关系先解释几个词方便后面展开。Agent 是指由大模型驱动、能自主决策并执行操作的智能体在编程场景里就是 Claude Code、opencode 这类能读写文件、跑命令的 AI 工具。Skill 是给 Agent 预装的一种“技能包”或“流程包”本质是一组指令文件和说明文档告诉 Agent 在某种场景下应该按照什么流程做事。Superpowers 的定位就是一个面向 AI 编程场景的 skill 集合专门用于解决“Agent 缺乏工程纪律”的问题。它里面包含若干个子技能每个子技能都定义了一套强制性的工作流。Agent 在执行任务时如果触发或者被要求调用这些 skill就必须按技能里定义的步骤来。可以这样类比Agent 是一个刚入职、能力很强但没有工作习惯的程序员skill 是公司发给他的《研发流程手册》。手册里写清楚了接到需求先干吗设计文档怎么写代码规范是什么提交前要跑哪些检查。程序员可以不看手册直接写代码但公司流程要求每一步必须走完手册上的流程Superpowers 做的事情就是让 Agent 在每次干活前“强制翻开手册”。2.2 Superpowers 的核心模块拆解Superpowers 不是单一技能而是一套技能的组合。我实际用下来最核心的几个模块是Brainstorm头脑风暴技能。这是整个流程的第一环。它强制 Agent 在动手写代码之前先和用户进行多轮需求对焦把目标、边界、约束条件、验收标准全部问清楚。很多 Agent 失控的根源就是没有这一步——用户说“加个标签功能”Agent 已经自作主张地把标签表结构、路由、UI 全设计完了。Brainstorm 的目的就是把这个过程拉回到对话里让用户在动手前先确认方向。Plan计划技能。在需求明确之后Plan 技能要求 Agent 输出一份详细的实施方案包括技术选型、文件改动清单、数据库变更、风险点、测试方案。它不只是一个“计划”那么简单它会强制 Agent 把大任务拆成小步骤并且预估每一步的变更范围。这一步对工程规范至关重要因为它让 Agent 在写代码前先建立起“影响面”的概念。Debug调试技能。这是一个结构化的排错流程。传统 Agent 遇到 bug 时的行为是“猜一个原因 → 改一下 → 跑一下 → 没解决再猜”Debug 技能会强制 Agent 先复现问题、再建立假设、再通过日志或者断点验证假设、最后才动手改代码改完还会要求你确认修复有效。这套流程本身就是工程师平常排错的标准做法只是很多人没想到可以把它沉淀成 skill。Checklist检查清单机制。Superpowers 鼓励在关键节点生成 checklist比如代码提交前要检查的事项、测试覆盖要求、文档同步要求。Agent 会被要求依照 checklist 逐项自检每完成一项就标记一下。这个机制看起来简单实际效果非常好——它把“抽象的质量要求”变成了“可勾选的具体动作”。TDD测试驱动开发支持。Superpowers 内部集成了 TDD 流程的 skill要求 Agent 先写失败的单测再写实现代码最后跑测试确认通过。这个流程对 Agent 的约束力很强因为测试先行意味着 Agent 必须先把“正确性的验证标准”定义清楚而不是写完代码再随便补一个测试。2.3 设计哲学把“工程规范”从口头约定变成代码流程理解 Superpowers关键是理解它的设计思路它不是靠提示词“说服” Agent 遵循工程规范而是靠流程“强制” Agent 遵循工程规范。为什么要这样做我们可以类比前端工程化的演进。早期的前端项目靠人自觉约定变量命名、文件结构结果就是代码风格五花八门。后来引入了 ESLint 和 Prettier 这类工具规则不再是“建议”而是“代码必须通过检查才能提交”。一旦规范变成了工具和流程的一部分它的执行率就完全不一样了。Superpowers 对 Agent 做的事情本质上就是 ESLint 对程序员做的事情。它把“先计划再执行”“改动前先确认影响面”“提交前跑测试”这些工程规范从人的提醒变成了 Agent 运行流程中绕不开的节点。如果 Agent 想跳过这些节点它有对应的机制进行提醒让它回到规范路径上。这套设计的另一个好处是可插拔、可扩展。Superpowers 本身是开源的你可以直接使用它预置的技能也可以根据自己的项目特点写新的 skill。团队可以把自己的工程规范沉淀成 skill统一所有人的 Agent 行为——这相当于把团队的研发规范从文档制升级成了“可执行代码制”价值非常大。3. 实操把 Superpowers 装进你的 Agent3.1 环境准备需要什么工具Superpowers 本身不直接运行它是给支持 skill 机制的 Agent 工具用的。目前比较主流的选择是 Claude Code 和 opencode 这类支持自定义 skill 的编程 Agent。我自己的主力环境是 Claude Code后面的步骤以它为例opencode 的安装路径类似只是命令和目录结构略有差异。需要的基础环境大概是这样一个能正常运行 Agent 工具的操作系统我主要在 macOS 和 Linux 上测试过Windows 需要额外注意路径和权限问题已经安装好的 Node.js 运行环境因为 Agent 工具本身依赖它已经配置好的 Claude Code 或同类工具并且确认它能正常读写项目目录、能正常调用模型接口。3.2 安装步骤详解安装 Superpowers 本身并不复杂核心步骤可以概括为四步第一步拉取仓库。由于它是个开源项目最常见的方式是直接从 GitHub 克隆到本地某个固定目录。我习惯把它放在~/.claude/skills或者其他 Agent 工具约定的技能目录下方便统一管理。第二步配置技能目录。Claude Code 支持在项目根目录放.claude/skills文件夹也支持全局配置。我的做法是把 Superpowers 的技能目录软链接到全局配置里这样所有项目都能共用不用每个项目重复装。第三步验证加载。启动 Agent 工具后直接问它“你有哪些 skills 可用”看输出里是否包含 brainstorm、plan、debug 等 Superpowers 预置技能。如果能看到说明安装成功如果看不到大概率是目录配置不对或者权限有问题。第四步权限设置。Agent 工具在调用 skill 时可能需要执行某些文件操作或者是读取特定目录需要确保对应路径有正确的读写权限。这里要提醒一个比较隐蔽的坑如果你在 Windows 环境下用路径分隔符和权限模型和 macOS/Linux 不一样软链接的方式经常不生效。我建议 Windows 用户直接把技能目录复制到项目目录下别折腾全局配置。还有一种常见情况是装了新版 Agent 工具之后自定义 skill 目录的约定发生了变化旧教程里的路径不适用了。遇到这种情况最好的办法是去官方文档里查当前版本支持的技能目录规则别凭老经验硬猜。3.3 从需求到交付的完整工作流安装只是开始真正有价值的是跑通一条“有纪律”的完整工作流。我用一个实际例子来演示给博客系统加一个标签筛选功能。没有 Superpowers 时我让 Agent 做这个需求它的典型路径是直接创建标签表、加路由、写查询逻辑、改前端模板、跑一下看能不能启动然后在没有确认的情况下把所有改动混在一起提交了。整个过程可能十分钟就结束了但 review 的时候我要花半小时拆解它的改动还得担心数据库变更有没有兼容旧数据。有 Superpowers 之后同样的需求流程变成这样先进入 Brainstorm 阶段。我调用 brainstorm 技能Agent 不会立刻写代码而是问我一系列问题这个标签筛选是文章列表页的筛选还是后台管理的筛选标签和文章是多对多关系吗筛选后是跳转独立页面还是当前页动态刷新有没有现成的标签数据还是需要新建我把这些问题回答完之后Agent 会输出一份“需求确认书”上面写了它对这个功能的理解、边界假设和验收标准。我确认无误才能进入下一步。然后是 Plan 阶段。Agent 会基于确认好的需求输出实施计划标签表结构设计包含迁移脚本、文章表是否需要加索引、路由设计和 API 设计、前端模板改动范围、需要新增的测试用例、风险点比如现有文章没有标签时怎么处理。输出计划之后Agent 会自己要求我先 review 这个计划而不是立刻动手。这一步帮我拦住了一个潜在问题——我原本需求里没要求加索引Agent 在计划里主动提出来了我觉得有道理补上了。接下来才进入执行阶段。最明显的变化是 Agent 开始“小步走”了。它不会一次性创建十几个文件而是先加数据库迁移跑通迁移再写数据模型和查询接口每完成一个步骤会主动汇报进度。所有改动都跟着测试一起提交而不是写完实现再补测试。最后它会生成一份 checklist包括“数据库迁移已验证”“标签页筛选接口返回数据正常”“无标签文章不报错”“测试全部通过”等若干项逐项自检。这次实操之后我最大的感受是代码本身没有比以前写得更好但整个过程的安全性提高了一个量级。Agent 不再是一个随时可能跑偏的“黑盒”而是一台按流程办事的“可控执行器”。我能清楚地知道它下一步要干什么也能量出每个阶段的风险。3.4 进阶玩法自定义 Skill 和团队规范化如果光是使用预置的技能Superpowers 的价值就已经不小了。但它的真正上限在于自定义 skill 的能力——你可以把你所在团队特有的规范、工具链、检查流程全部封装成 skill。举例说明。我所在的团队有个约定所有接口改动必须同步更新 OpenAPI 文档。这个规则写在团队 wiki 里但每次 Agent 在改完接口代码之后几乎不会记得去更新文档。后来我把这条规则写进了一个自定义 skill名字叫“api-change-checklist”内容是如果在改动中检测到接口定义文件发生了变化Agent 必须同步更新对应的文档并且要在 checklist 里勾选“文档已同步”。实现自定义 skill 并不复杂。核心就是创建目录结构写一个SKILL.md文件里面用自然语言描述这个技能的适用场景、触发条件和执行步骤。Agent 工具会读取这个文件把它当成能力清单的一部分。Skill 本身是一个 Markdown 文件不需要写复杂的插件代码门槛其实很低。团队层面还可以做更进一步的事把整个研发规范沉淀成一套 skill 集合新人入职后直接把这些 skill 装进自己的 Agent 工具里那么 Agent 的行为在团队内就是高度一致的。以前团队的规范靠人监督现在变成了 Agent 内置的默认行为。这对于小团队来说尤其实用相当于你花一份力气装了一个自动执行规范检查的“虚拟质量经理”。4. 踩坑实录常见问题与排查技巧4.1 问题速查表实操过程中总会遇到各种问题我把最常见的几类整理成了速查表方便你对照排错。问题常见原因解决方法安装后 Agent 不识别任何 skill技能目录路径配置错误检查当前 Agent 工具版本支持的技能目录规则确认路径精确无误skill 能识别但不主动触发提示词里没有明确要求调用Agent 默认按指令执行需要你明确要求“使用 brainstorm 技能开始这个任务”上下文过长导致技能流程中断多轮对话过长流程信息被压缩适时开启新会话把上一阶段的结论作为新任务背景Debug 流程反复循环不收敛问题场景描述不够具体先把“期望行为”和“实际行为”写清楚再让 Agent 按 Debug 技能走自定义 skill 不生效SKILL.md 格式或触发条件描述不清晰检查 Markdown 格式和 frontmatter参考官方 skill 的写法对照修正这张表里的问题我自己至少经历过三四个。最典型的是第一项——技能目录问题我在 opencode 上踩过一次路径差一个层级Agent 死活识别不了。后来查了当前版本的官方文档才发现新版换了目录结构约定按新规则调整后就正常了。经验就是一旦技能不生效先别折腾 skill 的内容优先检查路径和加载规则这个排查方向最快。4.2 三个实战心得除了上面的问题排查我还想分享三条自己的心得都是文档里不会写的东西。心得一不要把 Agent 当“甩手掌柜”brainstorm 阶段一定要亲自参与。很多人用 AI 编程工具用着用着就想当纯甲方提一句需求就等着拿结果。但 Superpowers 的流程里brainstorm 阶段用户是要“在线”的——Agent 会向你提问你需要回答。不要嫌烦这个环节是唯一能纠正方向的机会。你如果跳过这个阶段后面 Agent 的所有“规范操作”都是建立在错误假设上的越规范越麻烦。心得二小步提交是 Agent 最容易接受、也最容易在后期出问题的一环。Superpowers 会推动 Agent 分步执行但分步粒度取决于你的项目场景。建议你在 plan 阶段就明确跟 Agent 约定每个提交只包含一个逻辑单元不要多个功能搅在一起。我踩过的坑是Agent 把“数据库变更”和“前端页面改动”合在同一个 commit 里导致后期回滚时非常头疼。在计划阶段提前约束能省掉后面大量 review 时间。心得三自定义 skill 的触发条件一定要写得足够精确。我刚开始写自定义 skill 时语法描述是“当接口发生变更时需要同步更新文档”这个描述太模糊了Agent 经常不识别什么叫“接口变更”。后来我改成“如果检测到src/api/*.ts目录下的文件内容有修改则必须执行 npm run docs:gen 命令并更新对应的 API 文档文件同时在 checklist 中标注”。精确到文件路径和具体命令之后执行率几乎到了 100%。写 skill 就像写需求文档模糊描述带来模糊执行精确描述带来精确执行。4.3 Superpowers 与现有工程链路的配合最后聊一下 Superpowers 和其他工具链的配合问题。很多人会问我项目里已经有 ESLint、Prettier、CI/CD 了Superpowers 会不会和它们冲突我的实际体验是不会冲突反而能形成互补。ESLint 和 Prettier 这些工具检查的是代码的“静态质量”比如语法、风格、格式CI/CD 检查的是“集成的正确性”比如构建是否通过、测试是否通过。Superpowers 这种 skill 体系约束的是 Agent 在“开发过程”中的行为方式比如是否先做了设计、是否同步更新文档、是否遵循了小步提交原则。它和前面那套工具链是不同层面的东西。一个典型的工作流是Superpowers 在开发环节约束过程ESLint 和 CI 在集成环节约束结果相当于给项目加上了双重保险。如果你在团队里推广这套方案我建议不要一上来就全面铺开而是先挑一个小项目试点让 Agent 按 Superpowers 的流程跑几个迭代团队成员习惯了这种“有节奏感的交互方式”之后再逐步扩大范围。很多人第一次用 Superpowers 会觉得流程太啰嗦——以前一句话就开写现在要先问一堆问题。但这种“啰嗦”恰恰是它最值钱的部分每一次提问都是在帮你避开一个隐藏在需求背后的坑。最后再分享一个我自己用下来的小技巧不要只把 Superpowers 当成“装好就不管”的工具你可以定期翻一翻它的 skill 文件看看它定义了哪些新的流程。我就是在一次翻代码的时候发现它的 debug 流程里加入了“假设验证”这一步才意识到我之前手动排查问题时的思路有问题。这个开源项目本身也在迭代当你的使用习惯跟上它的最佳实践你对于“Agent 应该怎么管”的理解也会上一个台阶。在我个人的实际使用体验里Superpowers 最让我满意的不是某个单一功能而是它带来的整体心态变化——从“忐忑地把任务丢给 Agent祈祷它别跑偏”到“清楚地知道它在什么时候做什么、下一步要什么、在哪里可能出问题”。这种可控感才是 AI 编程工具走向工程化交付的关键一步。