Superpowers实战：给Claude Code装上AI编程工作纪律

1. 项目概述为什么我们需要给AI编程上“纪律”1.1 核心需求解析先说个现象。我身边越来越多团队开始用 Claude Code、Cursor 这类 AI 编程工具做实际项目但大家普遍遇到一个同样的问题AI 写代码确实快可是质量极不稳定。一个简单的帮我加个登录功能它能给你输出几百行代码跑起来后各种边界问题、命名混乱、模块耦合代码风格前后不一今天让它写了一版明天换个人问它又写出了完全不同的实现。最后代码库变成一个谁都不敢动的缝合怪。这就是 AI Agent 的自由发挥问题。底层模型本身只学会了根据上下文预测下一个 token它没有一个工程规范的概念没有项目全局视角更没有这个项目里哪些文件是核心逻辑不能乱动的边界意识。让它写一个函数没问题让它独立交付一个完整项目它就飘了。所以就有了 Superpowers 这个项目的出现。github.com/obra/superpowers 是我最近在实战中用的最多、也推荐给团队的一套 Claude Code Skills 集合核心思路就一句话给 Agent 装上一套工作纪律系统把自由发挥变成工程规范。1.2 这套方案解决了什么问题Superpowers 解决的其实不是AI 不会写代码的问题而是AI 没有工作方法的问题。我打个简单的比方一个新入职的初级程序员技术能力可能不差但是不懂团队的开发流程——不知道要先看需求文档、不知道要写设计文档、不知道改哪里的代码要跑哪些测试、不知道提交代码前要怎么做 code review。你直接让他上手改线上代码他也能改但大概率会捅娄子。AI Agent 就是那个技术还行但没有工作方法的新人。而 Superpowers 做的事就是给这套 Agent 装上一套规矩先规划、再执行先写测试、再写实现每完成一个阶段任务必须停下来检查而不是一口气梭哈到底。这套技能集最打动我的一个设计是它把项目开发拆成了 brainstorming头脑风暴、writing-plans写计划、executing-plans执行计划三个大阶段每个阶段都有对应的 skill 文件Agent 在特定阶段会加载特定的行为规范。我把这套东西接到实际的 Web 全栈项目里跑了两周交付质量明显比裸用 Claude Code 要稳定得多。2. 项目设计与核心思路拆解2.1 Superpowers 的整体设计思路先说我理解的整体架构。Superpowers 不是一个单体应用而是一个基于 Claude Code Skills 机制的技能包。Claude Code 本身支持从.claude/skills目录加载各种 skill 文件每个 skill 由两部分组成一个 SKILL.md描述这个技能是干什么的、在什么场景下用、怎么用外加若干辅助脚本或模板文件。Superpowers 的核心设计哲学是工作流驱动。它不直接告诉 Agent 你要写什么而是告诉 Agent 你该怎么思考、怎么安排工作顺序。举个例子在 brainstorming 阶段Agent 会按照 skill 里的指令先引导用户把需求聊透逐个拆解每一个功能点在 writing-plans 阶段Agent 会把头脑风暴的结果整理成可执行的开发计划到了 executing-plans 阶段Agent 会一行一行按照计划来实现每完成一个小任务就停下来自测。这个思路好在哪里它把AI 生成代码这个黑盒变成了需求分析 → 方案设计 → 执行实现 → 验证反馈的标准化流程。其实这套理念在传统软件工程里早就有了瀑布模型那一套嘛只是我们以前把这些流程用在人身上现在把它用在 AI 身上。2.2 为什么选择 Skill 机制而不是直接改 Prompt很多人会问你说的这些东西不是可以用一个 system prompt 写在配置文件里吗为什么要单独搞一套 Skill 机制我一开始也是这么想的直到我实际测试对比了一轮才明白设计的精妙之处。一个巨大的 system prompt 会让 AI 在每轮对话中都背着这些上下文不仅费 token而且指令优先级会被稀释——特别长的 prompt 里模型很难分辨哪些指令是最高优先级的哪些只是参考。最后的结果就是prompt 越长Agent 越偏科只执行最近或者最醒目的指令其他全忽略。Skill 机制是按需加载的。Agent 在代码补全、对话回答、执行多步骤任务等不同场景会灵活加载对应的 skill把上下文压缩到最小。Superpowers 正是利用了这一点把复杂的流程规范拆成了多个 skill让 Agent 只在自己需要的时候加载那部分指导。实测下来这种方式比一套固定的大 prompt 响应质量高得多token 消耗也相对可控。2.3 从自由发挥到工程规范的关键转变说实话刚开始我自己用 Claude Code 的时候也踩过这个坑项目写了一半让它重构一个模块它的实现思路跟前几轮完全冲突关键接口说改就改调了半天最后项目直接跑不起来了。后来我才意识到问题不是模型能力不够而是它缺少一个项目上下文和变更纪律的约束。Superpowers 方案里面的 skill 文件本质上是在模拟一个资深技术负责人的角色。它会强制 Agent 在改核心接口之前先列出影响面、先说明变更方案在某些危险操作前要求用户确认。这样 AI 就不是一个闷头写代码的枪手而是变成了一个有职业操守的员工。我还观察到另一个关键转变写代码之前的思考密度。在没有 Superpowers 的情况下AI 通常是边聊边写——你用自然语言描述个大概它马上给出代码。而有了 skill 引导后Agent 会先输出需求理解、设计方案、预估工作量把用户强制拉入思考过程。这个强制很重要因为很多时候需求本身是模糊的你不跟用户把需求核对清楚就开始写写出来的东西注定是要返工的。3. 实操准备环境要求与安装配置3.1 环境依赖与前置检查先说环境需求。这套 Superpowers 目前主要面向 Claude Code 用户官方文档里也强调是 Claude Code 的 Skills 插件所以在折腾之前先把 Cl Code 装上。除了基础的 Node.js 环境要求之外我建议提前确认一下你的 Claude Code 版本不能太老——有些旧版本对SKILL.md的解析支持不完整轻则 skill 不生效重则直接把自定义指令全忽略了。操作系统方面我在 macOS 和 Ubuntu 上跑过都没什么问题Windows 用户建议优先用 WSL因为整个 Skill 体系里会用到较多 shell 脚本直接在 CMD/PowerShell 里跑容易遇到权限或路径兼容性的坑。如果你用的不是 Claude Code而是其他支持类似 Skill 机制的编程助手比如 opencode、pi agent 这类新兴的 Agent 开发工具也可以参考这套思路去迁移但要做一些适配。用的时候留意日志里 skill 是否被正常加载。3.2 安装 Superpowers 的两种方式安装方式其实非常简单就两步一个是把仓库 clone 下来另一个是把相关 skill 目录链接到你的项目或全局配置里。方式一项目级安装在目标项目的根目录下执行命令把默认 skill 集合放进.claude/skills目录这样只有这个项目会加载这套规范。适合单个项目需求比较特殊、不想全局污染的场景。方式二全局安装直接修改~/.claude/skills这个用户级目录这样你在任何项目里打开 Claude Code 都会自动加载。我自己偏好全局安装因为我的工作流里几乎每个项目都需要规划先行全局开启省得每个项目重复配。安装完后最好先跑一次claude交互输入/skills指令查看已经加载的技能列表确认技能已经生效再往下走。3.3 与 OpenSpec、Claude Code 的组合使用把 Superpowers 单独拿出来用效果已经不错但要是想让 AI 稳定交付全栈项目我建议你把它和另外两个工具组合成一套三件套Claude Code OpenSpec Superpowers。分工大概是这样的Claude Code 是执行引擎负责跑命令、读文件、写代码、调终端OpenSpec 负责定义需求边界和验收标准把需求写成机器可读的 spec 文档Superpowers 负责给 Agent 管工作流——破题、列计划、按步执行、阶段自检。可以理解为OpenSpec 告诉 AI 做什么、怎样算做完Superpowers 告诉 AI 先做什么、中间该检查什么、出了问题怎么处理。这套组合是我在实战中验证比较稳的搭配。之前我用裸 Claude Code 做全栈项目交付质量看运气把这三件套接上之后至少东西能不能跑这个底线是可以保证的剩下的就是迭代和打磨。4. 实战流程从需求到交付的闭环4.1 阶段一用 Brainstorming Skill 梳理需求很多人用 AI 编程的时候上来第一句就是帮我写个日程管理应用然后期望 AI 直接给出完整代码。这就是最典型的不懂工作流的表现。你用 Superpowers 的时候第一步应该是先触发 brainstorming 过程把日程管理应用这个模糊想法变成一个清晰的需求描述。具体操作上我会在 Claude Code 对话框里直接给出初始需求然后让它按照 brainstorming 的 skill 开始引导我回答问题。注意这里的主角人物关系是反过来的——大多数时候是你问 AI 问题但在这个阶段AI 是提问方你是回答方。它会问你诸如目标用户是谁最核心的三个功能是什么是否需要在移动端使用数据是否需要多端同步等等。我建议在这个阶段多花点时间把所有能想到的边角需求都摊开。我自己就把离线也能看日程这种非功能需求都给出来了。因为了一次性想清楚后面写计划和写代码就顺很多。4.2 阶段二用 Writing-Plans Skill 生成开发计划需求聊透了接下来进入计划阶段。Agent 会基于 brainstorming 阶段的产出生成一份结构化的开发计划里面通常包含功能模块拆分、技术选型建议、实施顺序、每个阶段的验收标准。有人会觉得这一步多余直接开写不就完了但我的经验是这个计划文档在后续执行过程中是防止 Agent跑偏的关键锚点。因为执行阶段的 skill 会要求 Agent 遵循已写好的计划不能随便跳过步骤。如果执行过程中发现计划有问题正确的做法不是悄悄改而是回到计划阶段先把计划更新了再继续执行。另外一个实践经验在计划阶段最好让 Agent 把文件级改动清单给列出来——哪几个文件要新增、哪几个要修改、哪些是核心文件不允许随便动。有了这张清单后续执行效率能高很多而且你作为 review 的人也能一眼看出它到底改了哪些地方。4.3 阶段三用 Executing-Plans Skill 逐步实现计划定好之后Agent 才开始进入写代码的模式。但是注意这不是我们习惯的那种一股脑把代码全部写完而是严格按照计划里的阶段任务一个一个来。每完成一个小阶段Agent 会主动停下展示当前改动跑相关测试然后让你确认是否继续。在 executing-plans 阶段的 skill 指令里它要求 agent 每一步都要自解释——清楚说明这一步在做什么、为什么这样做、会影响哪些现有功能。这对于 review 代码的人来说体验极佳省去了很多逐行理解的时间。我实测下来执行阶段的代码质量比自由发挥模式高非常多尤其是代码风格一致性、变量命名、错误处理这些细节。有一点值得提醒在执行阶段尽量让 Agent一次只做一件事。如果你同时让它改好登录功能、顺便把首页 UI 也刷新一下、再加个导出 Excel 的功能它往往会顾此失彼。纪律的核心就是聚焦跟人工作一个道理。4.4 验证与反馈让 AI 自测与迭代三个阶段走完之后并不意味着项目结束。Superpowers 的 skill 体系还会要求 Agent 在交付前进行一轮全面的自检有没有遗漏的需求点、有没有死代码、有没有明显的安全漏洞、所有测试是否通过。这个过程很像传统的代码审查Code Review只不过审查者是 AI 自己。好处是它可以快速扫描整个项目比人肉眼 review 更全面坏处是它有时也会自我感觉良好——所以我建议在验收节点上还是要自己或者让团队成员实际跑一下功能而不是完全信赖 AI 的自测报告。如果测试发现问题不需要推倒重来直接把问题描述反馈给 Agent它会修改计划中的对应步骤然后重新执行。这个计划—执行—反馈—调整的闭环才是这套方法真正值钱的地方。5. 常见问题与避坑技巧5.1 Skill 没有生效怎么办我见过最多的报错就是装完了 skill但 Agent 完全没有按 skill 的套路来还是老样子自由发挥。这里有个很隐蔽的坑——Claude Code 在部分场景下对 SKILL.md 的首次触发是有延迟的不是每个对话都会严格读取。排查方法先用/skills命令确认技能已被加载然后在需求描述里显式点一下技能名——比如我们先用 brainstorming 流程过一遍需求。因为大多数 Agent 框架是热词触发机制你提到技能名它就会主动加载对应指导不提的话它会根据语义自行判断是否需要。另外版本兼容性问题也会导致 skill 加载失败特别是如果你用了一些还没合并进主分支的开发版 skill安装时要看清楚 README 里声明的最低版本要求。5.2 Agent 执行计划时中途失忆这是另一个常见问题计划阶段明明写得好好的执行到一半 Agent 突然忘了之前的约定实现方式跟计划里写的完全不一致。原因其实不复杂——超长上下文的注意力稀释问题对话轮次太多之后模型对早期约定的关注度会急剧下降。我目前的解决方案有两种。一种是每执行 3 到 5 个步骤就让 Agent 把当前进度、下一步计划、关键约定总结一遍把摘要固定到上下文里另一种是直接把关键约定写进项目根目录的CLAUDE.md文件里带全局记忆性质每个新会话启动就会读取。Superpowers 本身的 skill 文件里也内置了brag document和progress tracking的辅助设计大家可以在使用时留意一下这些子文件的功能说明。用好了能显著缓解失忆问题。5.3 常见错误对照速查表现象根因解决方案Skill 未触发Agent 自由发挥SKILL.md 加载延迟或版本过旧用 /skills 检查加载情况显式触发技能名Agent 中途偏离计划长上下文注意力稀释定期让 Agent 总结进度关键约定写入 CLAUDE.md执行阶段一次改太多文件用户一次性提了太多需求拆解为多个小阶段一次只交付一个功能点自测报告全绿但功能实际有 bugAgent 自测覆盖不全人工实测关键路径不盲信自测代码风格与既有代码不一致缺少风格指引在项目上下文中明确写入规范要求5.4 我的几条独家实战心得最后分享几条我自己实际用下来最有价值的经验。第一别跳过计划的 review 环节。Superpowers 生成的计划不一定完美但它逼着你在动手之前先看一遍全局。计划 review 花的时间后面还你十倍的返工成本这买卖划算。第二关键路径上的代码一定要人工 review。AI 写的工具类、脚本类代码让它自己跑测试基本够用但是涉及核心业务逻辑、权限控制、支付流程这些部分无论 AI 自测报告写得多漂亮你必须自己看一遍代码。这不是不信任是对生产环境负责。第三通用的规则写进 CLAUDE.md而不是每次对话里现说。比如本项目使用 TypeScript所有新增文件必须通过 eslint 校验数据库 schema 变更必须写 migration 文件这些固定规则放到全局记忆里能让 Agent 每一次行为都遵守省掉大量重复沟通成本。6. 这套方法的边界与后续扩展6.1 目前还做不到的事没有万能方案。Superpowers 这套工作流逻辑最适合的是中大型、有明确交付边界、需要分阶段完成的软件项目。如果你只是让 AI 帮你写一个正则表达式、调一个 API、改一个样式 bug让它自由发挥反而更快——这种情况下引入全套流程显得杀鸡用牛刀也不划算。另外它解决的是工程流程纪律问题不是模型能力问题。底层模型如果本身代码生成能力不行比如某些场景下复数文件的项目理解能力不足你给它再好的工作流也写不出能跑的代码。Skill 是放大器不是能力本身。还有一点这套体系目前对跨会话的长周期项目支持得还比较弱。虽然有 CLAUDE.md、progress tracking 这类设计但如果你是需要跑几个月的超大型项目上下文跨会话丢失仍然是一个需要人工介入管理的麻烦点。6.2 可以怎么扩展对于已经有一定 Agent 开发经验的读者我建议可以尝试基于 Superpowers 的架构思路去构建你自己的 Skills 集合。所有 skill 本质上就是 Markdown 指令文件加脚本你完全可以把自己的团队规范、代码风格、项目约定沉淀成 skill。比如我们团队就把前端组件必须用 Storybook 维护接口文档必须同步到指定目录这样的规则写成了自定义 skillAgent 在对应场景就会自动遵循。另外一个方向是把这套流程思路迁移到其他 Agent 开发平台。现在主流的 Agent 框架无论是偏对话的还是偏自动化的大多支持某种形式的技能/插件机制理解 Superpowers 的设计逻辑之后你再看其他平台的技能开发文档会有一种一通百通的感觉。核心的东西永远不是某个具体工具而是让 Agent 先思考、再计划、后执行、勤检查这套工作哲学。