1. 为什么Agent会“自由发挥”先搞懂问题出在哪先说个现象。我身边越来越多朋友开始用Claude Code、Codex这类AI编程工具跑全栈项目但大部分人反馈惊人的一致小需求很爽大项目必翻车。单个函数、单个页面Agent基本能一次写对。可一旦需求变成“做一个带用户体系、支付回调、后台管理的完整系统”它就开始表演了一会儿自己“发明”一个数据库字段一会儿跳过了异常处理一会儿把前端样式写成了自己以为的样子压根没按你项目的约定来。这不是模型不够聪明而是Agent根本没有一套可执行的“行为契约”。模型的天性是“概率续写”你给它一个模糊指令它就会按训练数据里最常见的方式去“自由发挥”。工程规范恰恰要求“一致、可验证、按约定执行”这两者的冲突就是所有AI编程翻车的根源。对这个痛点GitHub上最近热度很高的开源项目Superpowers就是一套专门解决问题的答案。它不是一个IDE插件也不是一个大模型而是一组非常巧妙的“技能包纪律流程”用严格的执行步骤约束Agent先思考、再规划、后动手、必须测试。说白了就是给Agent装上纪律引擎让AI从“自由发挥”切换到“工程规范”模式。这篇文章我会结合自己的实际体验把Superpowers的定位、安装、核心技能、实战流程、常见坑一次性讲透。适合正在用Claude Code等Agent工具做真实项目、但经常被“烂尾代码”折磨的人。1.1 大模型的天性与工程规范的冲突我一直觉得工程规范的本质是“反自由的”。它要求每个人在写代码之前先理解上下文、遵守约定、按照既定流程执行。而大模型恰恰相反——它每一步都在“猜”最可能的答案没有全局记忆也没有“责任意识”。你让Agent做一个登录功能它大概率会写一个标准模板用户名密码输入框、校验、调接口、存Token。它不会主动问你的项目里有没有现成的请求封装、有没有统一的错误码规范、UI组件库用的是哪套。因为问问题是“成本”直接写是“收益”模型天然倾向低成本的路径。这就是“自由发挥”的真相不是Agent笨是它没有机制去强制自己“先了解再动手”。传统团队靠Code Review、技术方案评审来约束人可Agent场景下谁来约束模型Superpowers就是来解决这个“谁约束模型”的问题的。1.2 普通提示词工程的两大短板很多人说那我用提示词约束它不就行了“你是一个严谨的工程师先分析需求再写代码别忘了写测试。”听起来对实际没用。原因有两个第一提示词是“软约束”不是“硬流程”。模型没有“执行完步骤1才能进入步骤2”的意识它可能读完你的提示词转头就按习惯生成代码了。提示词写得再好也只是提高了“遵循概率”不是100%可靠。第二一次性提示词没有“状态管理”。真实项目开发是分多轮对话、多阶段验证的。你需要Agent先出方案、你确认、再写代码、跑测试、修bug。普通对话里这个流程靠人肉SDLC一不小心就会乱。Superpowers把这两件事补上了它用一个个独立的技能文件把流程拆成可重复执行的步骤再用CLAUDE.md这类规则文件把纪律写进Agent的“潜意识”。这不是提示词的量变是约束机制的质变。1.3 Superpowers的对症解法让“纪律”变成可执行代码我打一个比方。普通提示词是“你跟AI口头说你要守规矩啊”Superpowers等于“你直接给AI装了一套SOP手册检查清单门禁闸机”。具体来说它的核心设计有三层技能目录按需加载的一组Markdown技能文件比如“头脑风暴”“编写计划”“架构设计”“TDD实施”每个技能都定义了标准操作流程。全局纪律文件通过项目的CLAUDE.md或Agent配置告诉AI“动手之前必须经过哪些流程”“哪些状态不允许直接进入编码”。可验证的流程节点关键步骤设计成“先输出方案、等待人类确认、确认后再继续”相当于在Agent的执行链路上加了一道道人工门禁。这三层配合下来Agent的“自由发挥空间”被压到最低——不是靠模型自觉而是靠流程强制。我自己跑下来的感受是第一次觉得AI编程有了“工程感”像带了一个流程意识极强的外包工程师而不是一个脑子灵活但不懂规矩的实习生。2. Superpowers到底是什么拆解这套“纪律引擎”有了前面的铺垫你大概知道Superpowers是干什么的了。下面我们把它拆开看弄清楚它到底包含什么、怎么运行、和你可能听过的其他工具是什么关系。2.1 官方定位与核心组成Superpowers由Jesse Vincent知名开发者也是Hackintosh项目的维护者之一发起GitHub仓库名叫obra/superpowers。它定位非常清晰为Claude Code等编程Agent提供“技能增强流程纪律”的能力层。最初是为Claude Code设计的现在也能适配其他支持MCP或技能加载的Agent工具。我之前搜到有人说“Superpowers skill是干嘛的”其实“skill”就是它的灵魂。整仓库安装后Agent的skills目录里会出现几套成体系的技能文件每一套都是一份“带步骤的标准化作业指导书”。我归纳一下核心组成有三块组成作用备注CLAUDE.md全局纪律规则相当于给Agent开机的“第一课”写明了编码前必须走的流程skills/技能包集合Brainstorming、Writing Plans、TDD、Architect等commands/斜杠命令提供/plan、/review等快捷入口让操作更顺手这套结构非常像人类团队里的“规章制度岗位手册”。CLAUDE.md是公司制度skills是每类工作的SOPcommands是常用指令的快捷按钮。2.2 从Brainstorm到Architect核心技能解码Superpowers最有价值的是它内置的几个核心技能。我逐一说说它们各自管什么。Brainstorming头脑风暴这个技能负责“需求澄清”。AI拿到一个模糊需求后不是直接写代码而是先向你提一堆问题这个功能面向谁有没有边界条件你倾向于方案A还是方案B它通过多轮对话把模糊的意图压成明确的需求描述。这个环节看起来“废话多”但恰恰是最能避免后期返工的部分。Writing Plans编写执行计划需求明确后Agent不会立刻动手而是先把任务拆解成一份可执行的计划要改哪些文件、新增哪些模块、先后顺序是什么、风险点在哪里。它还会主动识别出“哪些实现你可以接受哪些不行”。这相当于技术方案评审的AI版。TDD测试驱动开发这是我个人最欣赏的部分。Superpowers把TDD的循环严格固化进Agent先写一个失败的测试 → 运行测试确认失败 → 写最小实现代码 → 运行测试确认通过 → 重构。每一步都有明确的“验证动作”不允许跳过。你想想这比让AI直接甩给你一大段代码再慢慢调bug不知道高到哪里去了。Architect架构设计当一个任务涉及多个模块、数据流、依赖关系时这个技能会先帮Agent建立起“系统级视野”。它不会急着写具体类而是先画出模块边界、定义接口契约、梳理数据流最后才进入编码阶段。相当于给Agent装了一个“架构师前置检查器”。2.3 和OpenSpec、Claude Code的关系你该装哪些很多人在搜“claude codeopenspecsuperpowers三件套”我也被这个组合种草过。实际用下来三者的分工是这样的Claude Code底层Agent负责理解语言、操作文件系统、执行命令相当于“双手”。OpenSpec一个轻量级的“规格管理”工具负责把需求变成结构化的规格文档spec相当于“需求翻译器”。Superpowers负责“流程纪律”约束Agent按工程规范执行相当于“大脑的强制流程引擎”。你可以把Superpowers单独用也可以和OpenSpec叠加。我的建议是如果你已经用Claude Code跑过几个小项目、被翻车折磨过那直接上Superpowers就够如果你在建一个需要多人协作、长期维护的复杂项目再叠加OpenSpec做规格层管理。它们不是竞争关系是互补关系。3. 安装与实操把纪律引擎装进你的Agent好理论说完了下面进入动手环节。我会按我实际安装使用的顺序逐步讲清楚每一步怎么操作、会遇到什么坑。3.1 环境准备你需要什么前置条件先列一下我用的环境供参考操作系统macOSLinux、Windows的WSL也支持已安装Node.js 18用来跑Claude CodeAgent环境Claude Code CLI我已配置好API Key额外工具Git严格来说Superpowers只是一个“技能包”不需要编译安装但它依赖Claude Code或类似支持skills机制的Agent来运行。所以你得先把Agent本体配好。如果你还没装Claude Code官方文档有很详细的引导核心就两步安装CLI工具然后用Claude账号授权或配置API Key。这里我不展开直接进入Superpowers的安装。3.2 安装步骤详解克隆仓库、配置CLAUDE.md、加载技能官方推荐的安装方式非常简单。我把我的实际操作过程完整抄出来。第一步克隆技能仓库到本地git clone https://github.com/obra/superpowers.git注意别把仓库克隆到系统临时目录。我建议放在一个稳定的路径比如~/projects/superpowers。因为后面你需要用绝对路径引用它。第二步把技能复制进项目的skills目录这里有一个关键点Superpowers的技能是“按项目加载”的。你需要在每一个要用它的项目目录下把技能文件放进去。cd ~/your-project mkdir -p .claude/skills cp -r ~/projects/superpowers/skills/* .claude/skills/如果你用的是Claude Code它会自动读取.claude目录下的技能配置。这一步做完Agent就“看到”了这些技能。第三步配置CLAUDE.md注入纪律规则Superpowers仓库里自带了CLAUDE.md的模板你需要在项目根目录创建一份或合并进已有的CLAUDE.md。cp ~/projects/superpowers/CLAUDE.md ./CLAUDE.md我有一次图省事直接跳过了这步结果Agent虽然加载了技能文件但完全没按照“先计划再执行”的流程走。原因就在于CLAUDE.md才是“纪律”的入口技能文件只是工具缺了纪律文件等于光有工具没人管理。第四步重启Agent会话验证加载配置完成后关掉当前Claude Code会话重新启动。然后输入一条命令确认技能是否被识别/help如果配置成功帮助信息里会列出superpowers相关的技能条目。看到它们就说明安装成功了。3.3 第一次实战从头脑风暴到任务拆解安装只是热身真正让我觉得“这玩意儿值”的是第一次完整跑通流程。我拿一个很典型的Demo来演示。假设你走进Agent说“帮我给博客加一个评论功能。”换成平常Agent马上就开始建表、写接口、画前端了。但装了Superpowers之后它会先进入思考模式然后紧接着触发Brainstorming技能。它不会急着写代码而是先问你“评论功能目前的设计范围是什么只有登录用户才能评论还是允许匿名”“是否需要嵌套回复还是只做平铺列表”“数据存储有没有现成的表结构还是需要我新建”“前端样式有没有设计要求还是先用默认样式”这个阶段其实就是在帮你把需求从“一句话”细化成“一段明确的规格”。等你逐条回答完它才会生成一份执行计划列出具体操作步骤。整个过程非常像一个靠谱的产品经理在跟你确认需求。我建议新手用第一次就跑一遍这个流程别嫌它“多话”——后面省下的返工时间是这几分钟问问题的十倍以上。4. 核心环节实录用Superpowers跑通一个全栈小功能这一节我拿自己最近做的一个内部工具页面来举例完整展示它是怎么把“需求-计划-实现-测试”串起来的。为了方便理解我把过程压缩成三部分需求定义、实施执行、验收复盘。4.1 从一句话需求到完整方案BrainstormingPlanning的联动我的需求很具体“给后台管理页面加一个用户列表支持按邮箱搜索展示最近登录时间。”以前我直接把它丢给Agent它大概10秒就开始写代码。这次在Superpowers的“监督”下它先进入Brainstorming反复确认了几个关键点用户字段到底包含哪些光“最近登录时间”就追问了是数据库里的last_login_at还是需要从别的服务拉取搜索是基于前端过滤还是后端接口查询这决定了要不要新写接口分页要不要做最多展示多少条现有项目有没有统一的Table组件样式风格用哪套这些问题一个一个问下来我当时差点有点不耐烦但事后看每一个问题都恰好卡在“会导致后期返工”的决策点上。确认完之后它生成了一份结构化的plan.md包含要新增的组件、要改的接口、要建的数据库索引、以及测试覆盖范围。这份文档直接在项目里生成我可以随时review。这个环节给我的最大启发是Superpowers不是让AI变得“更聪明”而是让AI变得“更认怂”——承认需求有歧义、主动确认而不是瞎猜。这恰恰是所有资深工程师最该有的习惯。4.2 测试驱动实施的完整链路红-绿-重构循环方案确认后进入代码实施阶段。Superpowers默认走的是TDD流程整个过程让我印象很深。第一步它先写一个测试文件。比如对于“按邮箱搜索”这个功能它先定义好测试用例传入一个邮箱关键词返回匹配的用户列表传入空关键词返回全量列表传入不存在的邮箱返回空列表。跑完测试结果当然是失败——因为功能还没写。第二步它才去写最小实现代码。把接口逻辑补上、查询语句写好然后再次运行测试直到全部通过。第三步它进入重构阶段检查代码风格、抽离重复逻辑、补充异常处理。整个过程中每一段代码都先有测试“背书”。这基本上杜绝了“Agent自己写完就跑一堆隐藏bug”的情况。我以前跑普通AI编程最怕的就是它自信满满输出300行代码后说“完成了”一跑全是问题。现在它跑完会主动说“测试已经通过但我在重构时发现email字段存在把空字符串当成有效值的问题已自动处理并补了一条测试。”这种“自主补测试再修复”的行为是真的有工程素养了。4.3 流程中的关键节点哪些步骤不建议跳过如果你自己上手跑有四个节点我强烈建议你别偷懒跳过不要跳过Brainstorming环节。哪怕你的需求已经很明确也要让Agent至少列一遍它理解的约束。很多坑就是在“我以为是A它以为是B”中埋下的。不要直接批准它一次性写完所有功能。Superpowers允许你分步走比如先做数据层、再做接口、最后做前端。你完全可以每一步结束都“检查一下再继续”。只有重要里程碑才需要你介入细节速度不用太担心。不要忽略它的“测试失败”日志。如果它主动说“这个测试挂了”先别急着让它“修好就行”可以追问一句“挂掉的深层原因是什么”。很多时候Agent会自己发现额外的边界问题。不要在计划阶段随意打断它。计划生成过程中Agent会按模板列出文件清单、任务依赖。这个阶段你只需要看不需要频繁插话。我自己总结的一个小经验越是看起来“多此一举”的步骤越可能在后期帮你挡下大坑。Superpowers的设计者把大量工程最佳实践塞进了流程你只管顺着走就行。5. 常见问题与排查技巧实录最后整理几个我在使用中遇到过的典型问题和排查方法。如果你是刚入手这份速查表能帮你少走不少弯路。5.1 安装与配置阶段的坑问题1我克隆了仓库、复制了skills但Agent就是不按流程走直接开始写代码。排查思路大概率是CLAUDE.md没生效。确认一下项目根目录有没有CLAUDE.md文件以及文件里是否包含always think then act这类关键纪律声明。另外Agent有时需要重启会话才能重新加载配置。问题2技能文件复制过去了但/help里看不到。排查思路确认复制路径是否准确。是.claude/skills/不是skills/也不是.claude/skill/。我有次打错了单词弄了半天才发现。问题3技能加载了但Agent执行起来很“啰嗦”一直在提问效率变低了。排查思路这其实不是故障是特性。但如果觉得过度可以在CLAUDE.md里调整“确认次数”。比如为低风险任务设置“默认可直接执行无需额外确认”。灵活调整纪律强度是合法的毕竟不同项目容错度不一样。5.2 使用过程中的运行问题问题4执行到一半Agent卡住了没有继续下一步。排查思路多数情况是它在你没有注意到的位置等待确认。看看终端输出里有没有“[]”或者“等待你的意见”之类的提示。有时候是因为网络波动或工具链超时直接输入“继续”即可。问题5测试全过了但我手动一测发现功能还是不符合预期。排查思路大概率是需求理解偏差不是代码逻辑错误。回到Brainstorming环节把你真实想要的场景重新描述一遍然后重新生成计划。这种情况在传统开发里叫“需求变更”很正常Superpowers的优势是变更起来很快——有测试兜底改动不用担心连锁反应。问题6在团队项目里其他人不相信AI生成的代码怎么办排查思路把TDD测试记录留下。我现在的做法是Agent每完成一部分就保留对应的测试文件和运行日志。这样不管是自己还是同事review都能直观看到“这段代码有测试证明”。这是最有力的说服材料。5.3 最后的几条独家建议建议给每个项目都单独安装一套Superpowers不要搞成全局一次性配置。每个项目的工程约定不一样独立的技能包隔离性更好。除了编码也可以让它用Superpowers的流程做重构。有一次我让它梳理一个老项目的混乱模块它同样走了“分析现状-写计划-小步重构-测试验证”的路径体验很好。关注仓库的更新。Superpowers迭代很快新技能和流程优化经常出现。保持仓库最新能持续吃到工程规范方面的改进红利。把Superpowers调顺之后我个人最大的体会是AI编程的瓶颈从来不是模型能力而是流程缺失。模型再聪明没有一个强制的纪律框架它依然是个聪明但不受控的实习生。而一旦纪律装上它的产出质量会迅速向“资深工程师”靠拢。这个转变就是Superpowers这类工具存在的最大价值。如果你也在用Agent做项目真心建议花一个晚上装上它、跑一遍流程相信你会回来感谢我的推荐。