1. AI 写代码不缺能力缺的是“边界感”先讲一个我上个月的真实经历。当时我用 Claude 写一个内部工具的后端接口需求很简单从第三方服务拉取数据、清洗、落库、给前端返回分页结果。我把需求描述得足够清楚模型也给出了看起来非常合理的实现。结果代码 review 的时候我发现它在没有任何提示的情况下自作主张给数据库表加了两个索引、引入了一个自己觉得“更好”的 ORM 方法、还把分页参数从 offset/limit 改成了 cursor 风格。单看每一处改动单独拎出来可能都算合理优化。但放在一个团队项目里这种“自由发挥”就是灾难——你没有跟别人对齐就动表结构轻则埋坑重则直接影响到上下游服务的契约。这其实就是现在 AI 编程最核心的痛点模型本身的能力已经不是瓶颈瓶颈是它没有工程纪律。它像一个能力很强但没有受过职业训练的新人你让它“写个模块”它恨不得把整个架构都重构了。你让它“改个 bug”它能顺手把旁边的文件也格式化一遍。后来我开始系统性使用 Superpowers 这套 skills 体系来约束 Agent 行为配合 Claude Code 和 OpenSpec 一起用实测下来效果非常明显。这篇文章我就把完整的思路、安装方法、核心技能拆解和实战记录分享出来希望能帮到在 AI 编程里被“失控感”困扰的人。尤其适合这几类人参考正在用 Cursor、Windsurf、Claude Code 做全栈项目的开发者想给团队引入统一 AI 编码规范的技术负责人以及被 Agent 生成的“一次性代码”搞到不敢合并 PR 的人。2. 先搞懂一个关键问题Agent 为什么总爱“自由发挥”2.1 失控的根源LLM 天然是“接龙机器”抛开所有花哨的概念大模型本质上是“根据上文预测下文”的统计模型。它没有“项目全局观”也没有“稳定的长期记忆”。每生成一个 token它都在做同一件事猜测“接下来最应该出现的字符是什么”。这就带来两个致命问题。第一模型没有工作流意识。它不知道“先写测试再写实现”和“先写实现再补测试”有什么区别更不知道“先确认需求再动手”和“边写边猜”哪个更稳妥。它只会根据 prompt 里的信息用最省力的路径生成内容。你让它“写一个登录接口”它就直接开始写接口代码完全不会考虑“这个接口跟现有用户系统的关系是什么”。第二模型的输出倾向是“补完”而不是“执行”。你给它一个需求它会倾向于生成一个“看起来完整”的方案而不是“执行当前就需要的部分”。所以你会看到它疯狂给自己加戏——补你没提的参数校验、加它认为需要的索引、重构它觉得不优雅的代码这些都是“补完倾向”的体现。我用一个生活化的类比来解释普通对话式 AI 像一个反应很快的实习生你说什么它都能接上但你不盯着它它就会按自己的喜好干活。Superpowers 的作用是给这个实习生发一本厚厚的工作手册上面写清楚接到任务第一步干什么、第二步干什么、什么情况下需要停下来问人、什么情况下可以自己做主。2.2 传统 prompt 为什么解决不了这个问题很多人尝试用“超级 prompt”来约束 Agent。我也试过。比如在系统提示词里写“你必须遵循以下步骤1. 理解需求 2. 搜索代码 3. 制定计划 4. 执行计划 5. 自测”。问题在于Prompt 是静态文本而 Agent 的执行是动态过程。你写了一大段规则模型在开始阶段确实会遵循但一旦对话轮次变长、上下文变复杂这些规则就会被稀释、遗忘、甚至被后续内容覆盖。举个很具体的例子。我在 Cursor 里用过一个很长的系统提示词要求 AI 每次改动前先读相关文件。前两轮对话它确实照做了。到了第五轮我问它“顺便把这个按钮的颜色改一下”它直接就改代码完全跳过了“读文件”这个步骤。原因很简单——模型认为“改颜色”是个简单任务没必要走完整流程。所以问题不是 prompt 写得不够长而是prompt 没有把“流程”固化成“能力”。你需要的不是一段写在系统提示词里的文本而是一套能被 Agent 主动识别、主动调用、按步骤执行的技能模块。2.3 Superpowers 的解法把流程变成“技能包”Superpowers 的核心理念就是把软件开发中的高频工作流——头脑风暴、任务拆解、计划执行、调试排错、提交信息规范——封装成一个个独立的技能文件。每个技能包含完整的操作步骤、指标定义、执行规则和自查清单。它的工作机制是你在对话里用一个特定语法比如 superpowers 或 brainstorming唤起对应技能Agent 就会按技能文件里的步骤执行。这跟普通 prompt 最大的区别在于——技能文件是在执行时动态加载的不会占用你宝贵的上下文窗口也不会被后续对话稀释。我更愿意把它理解成一套**“工程级的行为规范系统”**不改变模型的推理能力只约束模型的做事方式。就像围棋高手不是靠“背规则”赢棋而是靠“行棋规范”保证每步棋的质量下限。Superpowers 要保证的就是 AI 每次动手写代码的“质量下限”。2.4 Superpowers 和 OpenSpec 的分工一个管“怎么干活”一个管“干什么活”很多人在了解 Superpowers 时会同时听到另一个名词OpenSpec。这两个工具经常被一起推荐但它们的定位完全不同。简单来说Superpowers 管的是“怎么干活”——怎么分析需求、怎么拆解任务、怎么按计划执行、怎么系统化调试。它约束的是 Agent 的行为方式。OpenSpec 管的是“干什么活”——它定义了一套需求描述规范把需求拆成带有明确验收标准的 spec 文档让 Agent 在动手前先明确“完成”的定义。它约束的是 Agent 的工作对象。打个比方Superpowers 是工作流程手册OpenSpec 是项目需求清单。有了流程手册但清单不清晰Agent 会高效地做错事有了清晰清单但没有流程约束Agent 会自由发挥到让你崩溃。两者配合使用才是完整方案——这也是“Claude Code OpenSpec Superpowers 三件套”这个词会流行的原因。3. Superpowers 到底包含哪些技能核心模块梳理项目本身是一个开源的 skills 集合完整内容在 GitHub 上。我建议你拿到手之后先做一个整体浏览搞清楚每个 skill 大概负责什么场景不然真到实战时你都不知道该唤起哪个。3.1 核心工作流技能战舰版本的“主炮”技能名称定位核心作用brainstorming需求分析在和 Agent 对话中澄清需求、探索方案、识别风险writing-plans计划制定把需求拆解成有依赖关系、验收标准的执行计划executing-plans计划执行按计划逐项实现每完成一项就检查一项debugging系统调试用“提出假设、验证假设”的方法定位并修复 bug这四个技能是整套体系的骨架。它们对应的是软件开发中最基础的四个阶段理解需求、制定方案、执行方案、修复问题。没有这套流程Agent 的所有输出都是“即兴发挥”有了这套流程Agent 的每一步都有章可循。3.2 辅助技能让工程规范更完整的“零件”除了四大核心技能Superpowers 还附带了一些辅助技能我实际使用下来觉得价值也非常高writing-commits约束 Agent 写规范的 Git 提交信息避免出现“fix stuff”“update code”这类毫无信息量的提交。checklists让 Agent 在任务完成前生成检查清单并逐项自查相当于模拟人工 Code Review 的第一道闸门。TDD测试驱动开发相关技能约束 Agent 按“先写测试、再写实现、最后重构”的顺序开发。spec-generation结合 OpenSpec 使用将需求文档自动转化为带验收标准的规格说明。3.3 skill 和 agent 到底有什么区别这个关键词挺热的经常有人混淆。我在使用中总结了一个最简单的区分方式Agent 是“执行体”Skill 是“能力包”。Agent 负责调用模型、管理上下文、执行动作比如读写文件、运行命令Skill 是给 Agent 提供的“操作手册”告诉它某类任务应该按什么步骤来做。类比一下Agent 是厨师本人Skill 是菜谱。没有厨师菜谱只是一堆纸没有菜谱厨师只能凭经验自由发挥。Agent 的灵活性和 Skill 的规范性结合才能稳定地产出高质量的代码。4. 安装与配置全流程Claude Code / Cursor / Windsurf 一次讲清4.1 整体安装思路三个步骤搞定Superpowers 的安装逻辑很简单把技能文件克隆到本地再让 AI 编程工具能读取这些文件。不涉及编译、不涉及复杂的依赖关系本质上就是“放文件”和“告诉工具去哪找文件”这两件事。不同工具的读取方式不太一样Claude Code通过skills命令直接在 CLI 里添加。Cursor / Windsurf需要在项目根目录或全局.cursor/skills目录下放置技能文件。OpenCode 等开源工具按各自约定的 skills 目录放置即可。我的建议是先从 Claude Code 入手因为它的 skills 机制最成熟社区案例最多。等你熟悉了技能文件的结构再迁移到其他工具就很轻松了。4.2 Claude Code 下的完整安装步骤Claude Code 的安装算是三种工具里最顺畅的。打开终端执行以下命令# 先进入 Claude Code 的配置目录 cd ~/.claude # 查看当前可用的 skills 命令 claude skills如果你是第一次安装需要先初始化 skills 目录。然后从 GitHub 拉取 Superpowers 项目git clone https://github.com/obra/superpowers.git # 用 Claude Code 自带的 skills 命令添加技能 claude skills add superpowers这里有个细节我要特别强调不同版本的 Claude Code 命令略有差异。老版本可能没有skills add子命令需要手动把技能目录链接或复制到~/.claude/skills/下。我的建议是先跑一下claude --version确认版本再对照官方文档操作。安装完成后在 Claude Code 里输入superpowers如果能正常唤起技能列表就说明安装成功了。4.3 Cursor / Windsurf 下的安装方式如果你主要在 Cursor 或 Windsurf 里工作安装思路稍微不同。这两个工具没有类似claude skills的命令行入口需要手动放置技能目录。以 Cursor 为例# 进入你的项目目录 cd your-project # 创建 .cursor/skills 目录 mkdir -p .cursor/skills # 克隆 Superpowers 到该目录 git clone https://github.com/obra/superpowers.git .cursor/skills/superpowers克隆完成后你在 Cursor 的对话里用superpowers或直接提到相关技能名比如 brainstorming它就能读取到技能内容。我在实际使用中有一个小经验Cursor 直接引用子技能的成功率更高。比如我输入brainstorming往往比输入superpowers更稳定原因是 Cursor 对嵌套目录里的文件识别可能会有遗漏。所以我会在.cursor/skills/下创建一个SKILL.md索引文件把常用技能的名字和路径列清楚这样 Agent 找不到的时候还能看一眼索引。4.4 验证安装是否成功一个 30 秒自测方法装完之后别急着开工先做一个快速验证。我在第一次安装时就踩过“以为自己装好了结果根本没生效”的坑。进入你的 AI 编程工具输入这样一句话请列出你当前可用的所有 skills并简要说明每个 skill 的用途。如果安装成功Agent 会列出 superpowers 相关技能的清单和说明。如果它回答“我没有 skills”或者答非所问说明技能文件没有被正确读取。还有一个更直接的方法直接输入brainstorming或者writing-plans如果 Agent 开始按技能里的步骤引导你提问说明它已经成功加载了技能内容。5. 核心技能实战拆解Superpowers 是怎么让 Agent“守规矩”的5.1 brainstorming让 Agent先学会“问”而不是“猜”我最初犯的一个错误是给了 Agent 一个需求直接让它开始写代码。结果它写了半天我一看方向就不对。后来我才意识到问题的根源是我和 Agent 之间没有做一个“需求对齐”的环节。Superpowers 的 brainstorming 技能就是专门解决这个问题的。它的典型执行流程是Agent 会先根据你的初始描述拆解出它认为需要澄清的问题然后一个一个地问你。举个例子。我让它开发一个“用户积分系统”按照 brainstorming 技能它会先问积分获取规则有哪些充值、消费、签到、邀请积分过期策略是什么永久有效还是按年度清零积分可以抵扣的订单类型有哪几种积分变动需要记录明细吗是否需要展示给用户这些问题看着简单但如果你直接让 Agent 写代码它大概率会“帮”你拍板然后按它自己的理解实现。等做完了你才发现“这不是我要的”返工成本极高。实操心得这个阶段不要嫌烦。刚开始我会觉得这些问题耽误时间但实测下来多花 5 分钟做需求澄清往往能省下后面几个小时的返工时间。而且很多问题你会发现自己也没想清楚Agent 帮你提前把坑踩出来这是白赚的。5.2 writing-plans把“写代码”变成“做工程”当需求澄清到位后Superpowers 会引导 Agent 生成一份执行计划。这个步骤对应的是软件开发里的“概要设计 详细设计”。我在用 writing-plans 时感受最深的一点是它会要求 Agent 明确每个任务的验收标准。也就是说不止要写“实现用户注册接口”这个任务还要写清楚“注册成功返回 200重复手机号返回 409请求参数缺失返回 400”这样的具体标准。这样做有两个明显收益。第一执行阶段不走样。有了明确的验收标准Agent 在写代码时会自觉对照标准检查输出而不是“写完了再说”。第二人工 review 有抓手。我只需要看计划里的验收标准就能快速判断 Agent 对需求的理解是否正确不需要一行行读它的代码。拿“用户积分系统”举例一份合格的执行计划大概长这样任务 1创建积分流水表 验收标准包含用户 ID、积分变动数量、变动类型、关联订单号、创建时间字段有索引建议。 任务 2实现积分变更服务 验收标准支持增加/扣减/冻结三种操作变动前后需要记录余额快照并发场景下不出现超扣。 任务 3实现积分明细查询接口 验收标准支持分页支持按时间范围过滤返回字段包含变动类型描述和时间。5.3 executing-plans让每一步都“有据可查”计划制定完成后就进入了 executing-plans 阶段。这个技能的核心任务是按计划逐项实现每完成一项就自查一项。我观察到的一个常见问题是很多人在计划制定后会忍不住“推着” Agent 直接开干。但 executing-plans 的意义恰恰在于它让 Agent 在每个任务完成后都停下来做一次“完成度检查”再决定是继续下一个任务还是回头修复当前任务。这里有个参数细节值得注意。Superpowers 在 executing-plans 阶段默认会要求 Agent每一项任务都要读取相关文件而不是凭对话记忆写代码确保实现和当前代码库的实际状态一致。这个设计极大减少了“凭空开发”带来的兼容性问题。我实测下来的体感是executing-plans 显著提高了首次编码的正确率。以前让 Agent 写一个跨模块功能经常出现“接口路径和现有路由不匹配”“导入的模块根本不存在”这类低级错误现在基本不会发生了——因为它在执行计划第一步就会去读路由文件和模块索引。5.4 debugging从“盲猜”到“科学排查”如果说前面三个技能是“预防”那 debugging 技能就是“补救”。Agent 写的代码不可能永远一次通过但关键是出 bug 之后它的排查方式是否科学。传统模式下Agent 看到报错信息第一反应是“猜一个可能的原因然后直接改代码”。它可能试三五次还修不对反而把代码越改越乱。Superpowers 的 debugging 技能要求 Agent 遵循一套严谨的排查流程复现问题收集完整的错误信息。针对错误信息提出多个可能的原因假设。设计验证方法比如打日志、写测试用例逐项验证假设。找到根因后再动手修复。修复后运行回归测试确认问题没有复发。我在实际使用中最能感受到这一套流程价值的地方是它治好了 Agent 的“急于表现”。以前它看到报错就东改一榔头西改一棒槌现在它会老老实实先复现、再假设、再验证每个步骤都有章法debug 效率反而高了很多。6. 一个真实案例从“自由发挥”到“规范交付”的完整变化说了这么多概念我把最近一个实战项目拿出来拆解一遍。我最近在给团队内部做一个轻量级的“任务管理系统”需要对接企业微信的通知推送。放到以前我可能会直接把需求甩给 Claude让它放手写。这次我用了一套完整流程来约束它。6.1 从需求到计划的完整链路我先用 brainstorming 让 Agent 帮我澄清需求。它问了大概 8 个问题其中最关键的三个是任务状态流转的规则是什么待办→进行中→已完成还是允许跳过企业微信推送是每次变更都推还是只在关键状态推任务的优先级是固定死还是允许用户自定义这三个问题直接影响了后面的建表设计、消息模板设计和接口设计。如果我没做这一步Agent 大概率会按一个“看起来合理”的方案去实现然后做出来的东西就不符合团队的运营习惯。需求对齐之后我用 writing-plans 让 Agent 生成执行计划。它列出了 6 个任务每个都有明确的验收标准。我逐条 review发现它对“任务关闭后是否允许重新打开”这个业务规则理解有偏差在计划阶段就纠正了避免了一次返工。6.2 执行阶段的“四步验证法”在 executing-plans 阶段我观察到 Agent 的行为模式发生了明显变化。以前它会连续写十几个文件然后告诉你“完成了”这次它每完成一个任务都会停下来做四件事读取相关文件确认代码和现有逻辑兼容。检查是否有测试可以运行来验证改动。对照验收标准逐项自检。汇报完成情况等待我确认后再进入下一个任务。整个过程下来我没有一次“中途叫停”的经历。这在以前几乎是不可能的——以前用对话式 AI 写项目我平均每次都要打断它两三次因为方向偏了或者实现方式和现有代码冲突。6.3 实测下来的量化对比我这里没有做严格的双盲实验但凭实际操作体感做一个量化对比供参考维度无 Superpowers使用 Superpowers从需求到计划的耗时10 分钟25 分钟在计划阶段发现的语义错误0-1 个3-4 个首轮编码通过率指逻辑正确约 40%约 80%中途需要人工干预的次数3-5 次0-1 次最终代码 review 需要修的细节较多明显减少数据仅供参考。我的核心体感是前期多花的时间非常值因为它把“返工成本”转移成了“规划成本”而规划成本比返工成本低得多。6.4 需要提前准备的工作把 OpenSpec 加进来如果你决定用三件套我的建议是先把 OpenSpec 的 spec 文档写好再让 Superpowers 干活。实际顺序是用 OpenSpec 定义需求文档和验收标准。在 Claude Code 里加载对应 spec让 Agent 明确“完成”的定义。用 Superpowers 的 brainstorming 做需求澄清。用 writing-plans 做计划拆解。用 executing-plans 按计划执行。每个阶段结束都有产出物不管是一个文档、一份计划还是几个文件方便你 review。这套组合下来AI 编程从一个“黑箱”变成了一个“有中间产物、有检查点、可 review、可回滚”的工程流程。这才是“工程规范”的真实含义。7. 常见问题与避坑实录我踩过的坑和解决方案7.1 新项目从零开始 vs 存量项目改造策略不同用 Superpowers 在一个全新项目上开始体感是最好的——因为没有历史包袱所有流程都能顺畅执行。但大部分人的实际情况是手里有一堆存量项目。我的建议是存量项目不要一上来就全流程改造。先挑一个功能模块做试点用 brainstorming writing-plans 把计划做出来让 Agent 按计划执行对比一下和以前“直接让它写”的效果差异。等这套流程在新模块上跑顺了再逐步扩展到全局。我试过把一个维护了一年多的老项目直接套三件套结果 Agent 在建计划阶段就被老项目的复杂依赖绕晕了产出的计划质量很差。后来改成小步试点情况才好转。7.2 模型选型的差异Claude 和国产模型的表现很多人在问“这种东西在国产模型上能用吗”我实测下来的判断是能跑但体验有差距。Superpowers 本身是纯文本技能文件任何支持长上下文和工具调用的模型都能读取。但实际效果取决于模型“遵循指令”的能力。Claude 系模型如 Opus、Sonnet在遵循复杂多步指令方面表现最稳定部分国产模型在简单的单步任务上没问题但在多步骤、多层嵌套的流程执行中偶尔会跳步或简化流程。如果你用的是国产模型我的建议是先跑最核心的 brainstorming 和 writing-plans 两个技能把需求对齐和计划拆解这两步抓好执行环节可以让模型自由度高一点。等模型能力迭代了再逐步放开。7.3 token 消耗明显上升这是正常现象用了这套流程后很多人第一个感受就是“怎么 token 用得这么快”。这很正常。brainstorming 阶段要多轮问答writing-plans 阶段要生成完整计划文档executing-plans 阶段每步还要读文件自查——这些都要消耗 token。我的经验是不要因为 token 消耗大就跳过规划阶段。你算一笔账规划阶段多花的 token 成本通常远低于一次错误实现带来的返工成本。时间才是更贵的资源。如果你真的想省 token可以把 brainstorming 的问题改成语义更紧凑的表述或者限定 Agent“最多问 5 个最核心的问题”。7.4 技能不生效先检查这五个位置我遇到过一次“技能完全没生效”的情况排查下来发现是技能目录放错了位置。如果你也遇到技能不生效的问题按这个顺序排查技能文件是否放在了工具认可的目录Claude Code 是~/.claude/skills/Cursor 是.cursor/skills/。技能文件名是否为SKILL.md有些工具只识别特定命名。当前对话是否有足够的上下文窗口加载技能文件窗口太小可能会截断。是否在对话中正确唤起了技能输入superpowers或对应的子技能。模型是否拒绝遵循技能文件中的指令某些安全对齐较强的模型会拒绝“按文件执行”这类指令。实操心得如果第 5 条发生最有效的办法是换模型或者把技能文件的关键步骤直接粘贴到对话里。我遇到过几次模型对“多步骤指令文件”有保留的情况直接把核心步骤复制到对话上下文里就解决了。7.5 别把技能当银弹质量上限还是要靠“人”最后说一个容易被忽略的点。Superpowers 解决的问题是“质量下限”——它保证 Agent 不会乱来不会跳过关键步骤不会在没澄清需求之前就动手。但它解决不了“质量上限”——Agent 的最终产出质量还是受限于模型能力和你的需求描述质量。我见过有人用 Superpowers 之后以为可以完全放手了结果代码质量还是没有达到预期因此跑来吐槽“这套东西没用”。其实这里有一个被忽略的事实工具约束的是流程人提供的是方向。如果你自己都不清楚需求到底要什么再强的技能系统也帮你做不出一个没想清楚的东西。用 Superpowers 前后我最大的心态变化是从“写完代码再检查”变成了“写之前先对齐”。对齐需求、对齐计划、对齐验收标准——这个过程看着多了几个步骤实际上每一分钟都是花在刀刃上的。8. 扩展思路和后续玩法8.1 自己定制团队专属 SkillSuperpowers 是开源的这意味着你可以基于它定制适合自己团队的技能。比如团队有统一的代码风格规范、数据库设计规范、接口命名规范都可以写成一个新的 SKILL.md 文件让 Agent 在开发时自动遵守。我目前就在维护两个团队内部技能一个是“数据库迁移规范”要求 Agent 在涉及数据库改动时先检查是否有破坏性变更另一个是“接口兼容性检查”要求在修改接口时自动检查现有调用方是否受影响。这两个技能极大地减少了团队内的低级 review 意见。8.2 与 CI/CD 流程结合另一个可以玩的方向是把 Superpowers 的产物比如计划文档、检查清单接入 CI/CD 流程。比如要求每次 MR 必须附带 writing-plans 生成的验收标准清单CI 自动检查这些清单是否被满足。这相当于把一个“约束 Agent 行为”的机制升级成了“约束团队协作流程”的机制。老实讲我在这个方向的尝试还比较浅但我认为它对技术管理的价值潜力很大。毕竟 AI 编程的终局不是“一个人用 AI 写代码”而是**“一个团队用一套标准来使用 AI 写代码”**。8.3 多 Agent 协作场景下的纪律保证最后提一下多 Agent 协作。现在 Agent 框架越来越流行一个系统里可能会有多个 Agent 协同工作。如果没有统一的技能体系约束每个 Agent 都按自己的偏好发挥协调成本会非常高。Superpowers 这类技能体系的价值在这里会被进一步放大——它提供了一种“团队共同语言”让不同 Agent 在执行同一类任务时行为模式保持一致。我自己在做 agent 框架方案设计时已经把技能体系作为架构的一部分纳入了。它不会直接决定 Agent 做什么但它决定了 Agent 做事的“行为基线”而行为基线正是一个团队能够协作的前提。我个人的建议是不要把它当成一个“插件”而是当成一套“流程资产”来经营。前期花一点时间熟悉、定制、沉淀后面每个使用 AI 编程的人都能稳定从这套资产里获益。