说实话用 AI 编程最怕的不是代码写得烂而是它写着写着就开始“自由发挥”。我前阵子带一个项目Claude Code 帮我们写一个带筛选排序的中后台列表页功能本身不复杂可它干到一半“顺手”把我整个数据请求层重写了——结果就是全局白屏几个同事盯着 git diff 看了半天才定位到它改的那个 service 文件。这种失控感我相信用过 Agent 的人多多少少都经历过。后来我认真研究了一圈发现问题其实不在模型能力而在我们对 Agent 的“管理方式”上。直到我接触了 Superpowers 这套基于 Agent Skills 标准的 skill 集合才第一次感觉到AI 编程终于可以不只是“自由发挥”而是真的套上了一套“工程规范”。Superpowers 不是一个 IDE 插件也不是一个闭源平台它就是一堆 SKILL.md 文件装到 Claude Code、Codex 这类编程 Agent 里之后等于给你的 Agent 配了一套“纪律引擎”先问清楚、再写计划、逐步实现、每步验证、最后复盘。这篇我就从原理讲到实战把我踩过的坑和总结的经验一次说清楚。1. 为什么 Agent 需要“纪律引擎”先看一次真实的失控1.1 Agent 自由发挥代价远比你想的大先还原一下那次事故。需求是订单管理页加筛选就 3 个字段订单状态、支付方式、下单时间范围。正常人工排期半天Agent 干了一个小时确实把页面写完了但它发现原 service 的请求参数是写死的于是顺手把 service 改成了动态拼接 URLSearchParams。改完之后它自己跑了两个测试都过了看起来甚至很完美——它给 service 也补了测试。问题在于service 层被十几个页面共用其他页面的请求参数格式跟它猜的完全不一样而且它把原本的响应拦截逻辑也动了结果就是全站接口报错。这种“局部正确、全局翻车”的 bug恰恰是 Agent 自由发挥的最典型特征。为什么模型会这样大模型本质是在做“下一个 token 的预测”它在一个很长的多步任务里每一步都会基于最新上下文重新决策。任务一旦超过五六步前期的约束条件在注意力里会越来越弱Agent 很容易被“当前这一步怎么更好看”带着走最后变成它自己以为的“正确”。用生活化的类比来说它就像一个热情很高但没有团队纪律的新人第一天上班就“优化”了部门的目录结构。能力没问题问题是没有人给它在动手之前立一套规矩。能力越强、手脚越快失控之后造成的破坏也就越大。1.2 长提示词和规范文档为什么都压不住它正常人遇到这个问题的第一反应是那就把规范写详细点。我也这么干过在 CLAUDE.md 里写了几百行项目规范从命名到目录到接口风格事无巨细。结果呢改善了但没根治。原因有两层。第一上下文稀释。大模型的注意力窗口是固定的你塞越多背景和规则后面的规则被“稀释”得越厉害。尤其当对话拉长规范文档在上下文里的位置越来越靠后Agent 对它的“记忆”越来越模糊。到了第 30 轮对话它可能连 CLAUDE.md 里“禁止修改 service 层”这句话都想不起来了。第二规范是“知识”不是“动作”。告诉一个 Agent“应该遵守 TDD”它不会真的去先写测试告诉它“要写计划”它可能写两段话就继续写代码了。因为模型不具备人的“流程意识”它只会按输入输出模式去回应。想让 Agent 守纪律不能光靠“写出来”得靠“步骤化”——就是把它应该执行的流程切成一连串可调用的、有明确输入输出的小技能。1.3 关键转变Agent Skills 让规范变成可调用动作这里就要说到 Agent Skills 机制了。一个 skill 就是一个目录里面有一个 SKILL.md 文件文件头是 YAML 格式的 name 和 description正文是具体的操作指导。Agent 在运行时会根据用户当前需求和已有上下文去读这个 description决定要不要调用这个 skill。调用之后SKILL.md 正文里的指令就等于暂时成为它的“主线任务”。这意味着什么意味着我们不再依赖“把规范写进大脑”而是把工程规范拆成一个个“动作包”。当 Agent 开始干活时它会先搜索匹配的 skill——比如你让它改一个多文件的前端功能它会读到 writing-plans 这个 skill 的 description然后按照里面写的流程先出计划而不是凭它的直觉直接开写。这就是 Superpowers 能当“纪律引擎”的根本原因它不试图教育模型而是给模型设计了一套操作手册让规范变成每一步的具体动作。与其说是给 AI 装“超能力”不如说是给 AI 装了一套刹车和方向盘。2. Superpowers 的核心设计从自由发挥到工程流水线2.1 工作流总览brainstorm、plan、execute、reviewSuperpowers 这个项目是社区开发者 obra 发起的一个开源 skill 集合GitHub 仓库叫 obra/superpowers。它把 Agent 开发一个功能的全过程拆成了几个标准阶段。我以我实际在用的版本为例列一下我平时感知最强的几个 skill 和它们的协作关系Skill触发时机核心作用关键输出brainstorming新需求、方案不明确反向提问、列出方案、权衡取舍需求澄清记录、方案对比writing-plans已经明确要开发的功能把需求拆成子任务写计划文件plan 文件executing-plans计划文件就绪后按计划一步步实现、逐项验证每步提交的 git committest-driven-development开始写代码时先写失败测试再实现再重构可运行的测试用例reviewing-work一个功能完成时对照需求自查代码质量、覆盖率review 记录debugging测试失败或报错时定位根因避免瞎改修复后的验证git-workflow / commit每个子任务完成生成规范 commit message干净简洁的 git 历史整个流程的思路其实很像软件团队里的 TDD Code Review 流水线也像 OODA 循环它让 Agent 从“接到需求直接撸码”变成“先定向再计划再小步快跑每步反馈”。这些阶段并不是给你画流程图的而是真正写进 SKILL.md让 Agent 在对应场景自动去执行的。2.2 最关键的三个“纪律”设计我拆过这几个 skill 的源码之后发现它的约束设计核心有三条。理解了这三条你自己也能 DIY 类似的技能。纪律一先有书面计划才允许动代码。writing-plans 这个 skill会强制 Agent 把目标、范围、子任务、验收标准写进一个 plan 文件而且要求它把文件保存到项目里。为什么要落盘因为对话里的计划容易在后续步骤里被遗忘而文件是持久化的——Agent 在执行到第 7 步时可以重新去读第 1 步写下的目标人在 review 时也能对着文件逐条核对。相当于给 Agent 立了一份“合同”。纪律二TDD 是硬约束不是软建议。test-driven-development skill 写得非常强硬先写一个会失败的测试再写实现让测试通过然后重构不允许跳过任何一步。我以前总觉得让 AI 写测试是浪费时间后来发现正好相反——测试是 Agent 自己的“刹车系统”。没有测试的 Agent 改代码只能靠它自己“觉得没问题”有了测试它能立刻看到自己的改动有没有破坏什么。AI 写代码最大的风险不是写不出来而是“以为写对了”测试就是用来打破这个“以为”的。纪律三每一个子任务完成就提交一次。executing-plans 在执行计划时要求每完成一个子任务就 git commitcommit message 还要按 conventional commits 规范生成。好处有三层第一出错可以随时回退不会“一改改一片”第二git log 会成为可审计的过程记录你可以看到 Agent 每一步到底干了什么第三强制提交也在心理上给 Agent 一个“阶段终点”降低它自由发挥的概率。2.3 组合拳Claude Code OpenSpec Superpowers 三件套社区里现在很流行一个组合叫“Claude Code OpenSpec Superpowers 三件套”我在实际项目里也基本这么用。它们的分工特别清晰OpenSpec 负责回答“做什么”Superpowers 负责回答“怎么做”Claude Code 负责“真的去执行”。OpenSpec 是一个开放式的技术规范和需求管理格式类似于把产品需求、技术方案写成结构化的 spec 文件存进仓库。Superpowers 的 plan 阶段会和 spec 呼应先有 spec再有 plan实现时严格按照这两层文档推进。这样需求变更、方案决策都有据可查Agent 不会因为对话历史被压缩就忘掉最初的目标。为什么要强调这个组合因为我测试下来只装 Superpowers 能解决“过程规范”但解决不了“需求烂”的问题——需求本身就模棱两可时Agent 按流程走完也可能交付一个没人要的东西。OpenSpec 把需求先钉死Superpowers 再把实现流程钉死Claude Code 提供文件读写、命令执行和沙箱三层各管一段才是完整闭环。当然小项目可以不上一整套但如果你要“让 AI 稳定交付全栈项目”这套组合确实是当前最靠谱的路径之一。3. 安装与初始化给 Agent 装上 Superpowers3.1 环境准备先有一个能跑 Agent 的底座Superpowers 不是一个独立程序它是一堆 skill 文件所以你需要一个支持 Agent Skills 的编程 Agent 作为宿主。目前最主流的是 Claude Code我自己主要在它上面跑。准备过程三步走。安装 Node.js。Claude Code 是 npm 包Node 18 以上基本没问题。全局安装 Claude Codenpm install -g anthropic-ai/claude-code在项目根目录执行claude启动交互式终端第一次会走登录授权流程按提示操作就好。装完可以用/status或直接在对话里问它版本确认环境正常。除了 Claude Code现在也有一些支持 Agent Skills 的替代品比如 opencode、codex 等。它们的 skill 目录路径可能不一样但原理大同小异。我这篇以 Claude Code 为例写其他环境按各自文档把 skills 放到对应目录即可。3.2 安装 Superpowers 的两种方式方式 A官方的一键安装。克隆仓库后运行安装脚本脚本会把这些 skills 软链到~/.claude/skills目录这是单机用户最常见的方式。git clone https://github.com/obra/superpowers.git cd superpowers ./install.sh装完之后在 Claude Code 里输入/skills就能看到已安装的 skill 列表。如果你看到 brainstorming、writing-plans、executing-plans、test-driven-development 这些名字就说明装成功了。如果仓库里没有 install.sh那就手动把 skills 目录里的内容复制到~/.claude/skills效果一样。方式 B项目级 skills适合团队共享。如果想让整个项目组统一行为可以在项目根目录建一个.claude/skills目录把 superpowers 里的 skill 文件夹复制过去。这样团队里每个用 Claude Code 的人在这个仓库里都会自动加载同一套 skills。项目级的好处是不会污染个人环境坏处是每个仓库都要维护一份建议配合 git submodule 或脚本化更新。3.3 在 CLAUDE.md 里绑定“本地纪律”只装 skills 还不够我强烈建议你在项目根目录维护一份 CLAUDE.md。Claude Code 每次启动都会自动读这个文件它相当于项目的“宪法”。把工程规范、技术栈、AI 助手工作约定写进去Superpowers 才知道该在哪里发力。这里给一份可以直接抄的前端项目 CLAUDE.md 骨架# 项目规范 ## 技术栈 - React 18 TypeScript strict 模式 - 样式方案CSS Modules - 状态管理Zustand ## 代码风格 - ESLint Prettier提交前必须通过 lint - 组件文件命名PascalCase - 函数组件 hooks不使用 class component - 接口请求统一走 src/api禁止在其他层直接拼接 URL ## 提交流程 - commit message 遵循 conventional commitsfeat/fix/refactor/docs/test - 单个 commit 只做一件事 ## AI 助手工作约定 - 涉及多文件的改动先调用 brainstorming 澄清需求 - 动手前必须使用 writing-plans 写计划文件 - 实现阶段使用 test-driven-development先写测试再实现 - 每个子任务完成必须跑测试并 git commit注意CLAUDE.md 不是越长越好。我见过有人写上千行结果 Agent 根本读不进去。我建议控制在 40 行以内只写最高频、最不可妥协的约定。低频规则留给 skill 的 reference 文件让 Agent 按需查阅。另外一个小经验把“AI 助手工作约定”单独放在文件末尾用明确的“必须”句式。这是因为 CLAUDE.md 的内容会全量进入每次请求的上下文放太靠后容易被截断所以更要精炼同时“必须”类指令比“建议”类指令对 Agent 的约束力强得多。4. 实战记录让 Agent 按工程规范交付一个前端功能4.1 场景设定纸上谈兵没意思我直接拿一个真实小需求演示一遍。假设你在接手一个 React TypeScript 的中后台项目需求是在订单列表页加一个按状态筛选的功能筛选条件有全部、待支付、已支付、已取消选择后列表自动刷新同时新增筛选状态的 URL 参数刷新页面后状态不丢。要求完全符合上一节那份 CLAUDE.md 的规范。这个需求看似简单但对 Agent 来说其实是个多文件、跨层改动涉及类型定义、接口请求、查询参数同步、组件状态、路由读取和测试。正好是容易失控的典型场景也是 Superpowers 最擅长管住的场景。4.2 从 brainstorm 到 planAgent 先把话说清楚在 Claude Code 里我给它的第一句 prompt请帮我实现订单列表页的状态筛选功能需求细节见对话。先不要写代码按照 CLAUDE.md 的工作约定先澄清需求并输出计划。注意我特意加了“先不要写代码”和“先澄清需求并输出计划”。为什么因为哪怕装好了 skillsAgent 在收到一个看起来简单的请求时还是可能跳过 brainstorming 直接开写。你在 prompt 里点一下流程它是会听的不点它可能就按“最短路”走了。等用熟了你对它的信任度上来了可以慢慢撤掉这种显式约束。接下来 Agent 的表现很有意思。它没有直接写代码而是连续问了我几个问题筛选状态是前端枚举还是后端枚举切换筛选时要不要保留排序和分页参数URL 参数用什么 key接口是否支持按状态过滤这几个问题正好是后端联调前必须确认的边界条件。我确认完这些信息之后它调用 writing-plans生成了一份计划文件定义 OrderStatus 联合类型在 api/order.ts 增加 getOrders 的参数透传改造列表页读取 URL 参数并同步到筛选项为筛选交互补测试更新相关文档。每一步还标了验收标准。这个 plan 文件会存在项目里后面所有实现都会对着它做不是写在对话里聊完就忘。4.3 TDD 执行、自审与提交每一步都有迹可循计划就绪后它进入 executing-plans test-driven-development 阶段。如果我不拦着它会自动开始写代码。我的观察是它通常先写一个会失败的测试——比如针对 URL 参数和筛选状态互转的工具函数写用例跑一次看到测试红了再写实现跑绿然后再处理组件改造逐文件推进。到了提交阶段它会自动执行 git add 和 git commitcommit message 类似feat(orders): 添加订单状态筛选并将状态同步至 URL你翻 git log能看到这条提交干净利落没有夹杂其他文件。这个过程给人最大的安全感是它每一步改了什么你都能在 git diff 里看到任何一步不对直接 checkout 回去就行。整个功能改完它还会调用 reviewing-work 做一个自审重新跑 lint、tsc 和测试检查是否有未处理的类型问题、有没有绕过 CLAUDE.md 里的接口请求约定。我最后人工 review 时基本只需要看 diff不用再从头理解一遍整个改动负担小很多。4.4 实测效果与参数建议这类功能用自由发挥模式跑我试过成功率和无回归率大概在 60% 上下上了 Superpowers 这套流程之后我跑了十几个类似的中等改动基本稳定在 90% 以上剩下的失败也大多是需求理解偏差而不是“乱改代码”。这个提升不是模型变聪明了而是 Agent 的每一步都有人盯着、被文件记录着、被测试验证着自由发挥的空间被压缩到最小。关于权限模式我有个参数建议。Claude Code 有 permission mode可以设置成自动批准或者每步确认。我的习惯是文件读写可以放给 Agent但 git commit 和带副作用的命令比如删除文件、安装依赖一定要保留确认。前期别图省事开全自动等你在一个项目里摸清它的行为模式之后再针对高频操作慢慢放开也不迟。5. 常见问题与排查技巧实录5.1 Agent 不按 skill 走怎么治最常见的问题是skill 装了但 Agent 就是不用。我排查下来原因集中在三个地方。第一需求描述太模糊description 匹配不上。比如你只写“加个筛选”它会把它当成一个简单组件改动根本不触发 writing-plans。第二上下文里没有放 CLAUDE.md或者放了但内容太泛Agent 不知道项目里约定过“必须走计划”。第三skill 的 description 写得不好模型没读懂它的适用场景。我的做法是三步第一步在 prompt 里显式指定流程——“请你先调用 writing-plans再按计划执行”一次指定就能把 Agent 拉回正轨。第二步检查 CLAUDE.md 是否写清了工作约定把“必须”句式加上。第三步如果还是一直跑偏就看看是不是 skill 文件本身有问题比如 SKILL.md 的 frontmatter 写错导致没被识别。用/skills命令确认它确实出现在列表里。5.2 上下文爆掉、执行中断怎么办用 Superpowers 跑长任务最大的物理限制是上下文窗口。plan 文件、spec 文件、测试输出、每一步的 git diff 都会占 token跑到某个节点Agent 会出现一种“脑子进水”的状态忘了前面的决定、重复生成同一段代码、或者直接报错说 context length exceeded。热搜里那句 “agent execution terminated due to error” 我见了不知道多少次。我的办法有两个。一是主动压缩上下文执行到一半时让 Agent 先把已完成任务和关键决策整理成一个 summary 文件然后用/compact压缩对话再让它继续跑。二是拆任务一个 plan 文件里子任务超过七八个的话我就会把计划拆成两三个批次每批单独开对话而不是让一个对话从头跑到尾。拆出去的批次把 plan 文件作为输入上下文干净很多成功率也高很多。另外一个容易踩的坑plan 文件本身越写越长最后反而成了上下文的累赘。所以我现在要求 writing-plans 输出“能省则省”验收标准写清楚背景知识能引用 spec 就不重复粘贴。计划是给 Agent 的施工图不是教科书。5.3 skill 升级、多项目复用的团队坑如果你是个人用直接从 GitHub 拉最新版就行。但在团队里skill 版本不锁是会出事的——某天某个同事更新了 Superpowers然后你发现 Agent 的行为变了计划文件格式变了commit 习惯也变了。我建议在团队内把 skills 用 git submodule 或者 vendor 到仓库里锁定到你验证过的版本升级走 review不要所有人各自更新。还有一个小坑项目级 skills 和个人级 skills 同名冲突时行为不可控。比如项目里放了一份自定义的 writing-plans个人~/.claude/skills里也有一份两个都会被扫描到Agent 可能随机选用。我在一个项目里就遇到过计划格式忽好忽坏的怪事后来把个人级和项目级去重只保留一份才稳定下来。5.4 高频问题速查表我整理了一个速查表方便大家排查现象可能原因解决方式Agent 不写计划直接开写skill 未触发 / CLAUDE.md 缺少流程约定prompt 里显式指定先调用 writing-plans检查 CLAUDE.mdskill 列表为空安装目录不对确认 skills 放在 ~/.claude/skills 或 .claude/skills测试一直红需求理解偏差让 Agent 先跑 debugging skill贴出错误根因分析后再改上下文过长执行中断单对话任务过多拆分批任务、/compact 压缩、保留计划文件commit message 不规范没有用约定规范 skill让 Agent 在提交前用 conventional commits 规范生成出现同名 skill 行为冲突个人级与项目级重复安装只保留一个目录统一管理和升级这表格是我从自己和其他人的讨论里攒出来的不一定覆盖所有情况但八成问题都在里面。6. 适合场景、边界与落地建议6.1 哪些项目最适合这套玩法我先说结论凡是“需要稳定交付、需要代码评审、需要可追溯”的任务都适合。典型的有三类。第一全栈业务功能开发尤其是前后端联动、涉及数据流和状态管理的项目这类任务最容易跑偏也最需要 plan 和测试兜底。第二老项目重构比如把一个页面从 class component 迁移到 hooks或者调整目录结构Agent 很容易“顺手”破坏原有行为TDD 能兜住。第三团队协作场景多个 Agent 或多个开发者同时在同一个仓库工作有 plan 文件和规范 commit等于给 AI 参与协作立了规矩。如果你一个人开发需求又不复杂可能体会不到它的价值——但只要你开始做需要长期维护的项目或者要交付给别人的项目这套流程的收益会成倍增长。因为工程规范锁定的不止是代码质量还有“别人能不能看懂你让 AI 干了什么”。6.2 什么时候别硬上我也要泼点冷水。以下情况不建议用用了反而烦。第一一次性脚本或者临时调试比如你只是想跑个 API 拿点数据、写个小工具上一个完整 TDD 流程是自虐。第二探索性原型需求一天变三次你让它写 plan 纯属浪费这个阶段要的是快速试错不是流程规范。第三你的 Agent 宿主本身不支持 skills非要手搓一堆流程还不如先升级工具。说白了Superpowers 解决的是“工程化交付”问题不是“生产效率”问题。在需要纪律的地方它价值最大在需要放飞的地方它还属于多余装备。6.3 团队落地建议最后给想往团队里推的同行一点建议。第一先在一两个对 AI 接受度高的项目里试点不要一上来就让所有人都装。第二试点时要定一条硬性要求AI 产生的改动必须保留 plan 文件、测试结果和规范 commit否则视为无效交付。这条要求能逼着所有人感受到“纪律引擎”的价值。第三把 skills 和 CLAUDE.md 纳入 code review 的常规对象——不只是审代码也要审 Agent 是不是真的按流程走了有没有绕过测试。第四定期看 git log 和 review 记录用数据说话AI 交付的返工率降了多少、review 时间省了多少。用这些反馈倒推流程才能真正在团队里活下来而不是变成摆设。最后再分享一个我个人的体会。刚装 Superpowers 那几天我非常不适应——Agent 变“慢”了它不再像以前那样我一说需求就噼里啪啦写代码而是开始问我问题、写计划、跑测试感觉像是请了个爱写文档的闷葫芦。但用了一两周之后我回头看 git log突然觉得这个“闷葫芦”比之前那个“快手”靠谱太多了每个 commit 干净得像人工写的规范提交review 成本肉眼可见地降下来更关键的是再没有出现“改了个按钮、炸了整个模块”的深夜事故。我现在的新习惯是新功能必走 brainstorm改动稍大必写 plan写代码必开 TDD。这套东西并不是把 AI 的能力锁死而是把它从一个“灵光一现但随时会跳票的自由职业者”变成了一个“懂规矩、可配合、能上线的正式员工”。如果你也在被 Agent 的自由发挥折磨我建议你先拿一个中等规模的项目装上试试感受一下被纪律约束的 AI 到底有多稳。