最近不少用 Claude Code、Codex CLI 这类编程智能体的朋友都在聊 superpowers。其实我第一次听到这个名字也愣了一下以为是某个超级英雄游戏后来才搞明白这是给命令行 AI 编码助手配的一套“技能包”框架。核心思路很简单——把测试、调试、重构、代码审查这些高频工程动作固化成一个个标准的技能文件让 AI 不再每次聊天式地“自由发挥”而是按你定义好的流程干活。对已经受够了 AI 乱写乱改、想让编码助手真正工程化的人来说这几乎是刚需。这篇内容我按自己的实操经验写适合正在用编程智能体、但觉得默认行为不够稳定的开发者参考。编辑器里敲代码只是 AI 辅助编程的初级形态真正让 AI 托管一个仓库、跑完整开发闭环的时候你会发现光靠对话根本压不住它。superpowers 解决的正是这个问题给 AI 装上一套可复用的“职业习惯”。下面我拆开讲。1. superpowers 到底是什么——先解决“名词误解”1.1 AI 编码助手缺的不是模型是流程现在的编码智能体模型能力确实强一段话能给你生成几百行代码但问题恰恰出在“生成”上它没有固定的工程纪律。你让它“修个 bug”它可能直接改一行就完事根本不跑测试你让它“加个功能”它可能跳过重构、不写文档、不检查边界条件。这些不是模型不懂而是你没有给它一套可执行的流程约束。superpowers 的定位就是补齐这层约束。它不是某个单点工具而是一套技能文件的集合。每个技能就是一个文件夹里面有一个 SKILL.md 文件相当于技能的说明书外加若干参考文档、脚本、模板。AI 在开始干活之前会读取这些技能文件按照里面写的步骤来执行。换句话说你不需要每次对话都长篇大论地告诉 AI“先测后写、每步确认”只要在需要的时候说一句“用 xx 技能来做”它就会按技能里定义好的流程走。我实际用下来的感受是它把 AI 从一个“聪明的实习生”变成了“有 SOP 的资深工程师”。流程感这东西平时不起眼但一旦项目规模上来、多人协作、代码库复杂差别是真的明显。1.2 superpowers 与传统 prompt 工程的区别很多人可能觉得我不装什么技能框架直接在系统提示词里写“你是一个专家请遵循 TDD每次先写测试再写实现”效果不是一样吗还真不一样。传统 prompt 工程靠的是“临场话术”。你每次对话都要提醒AI 每次都要从你的话里提取规则遇到长对话还会“遗忘”。而且 prompt 写多了token 消耗大模型注意力也会被稀释。更麻烦的是规则一旦变了你就要改一大段系统提示词维护成本很高。superpowers 走的是“文件化技能”路线。每个技能单独存放AI 只在你调用它或检测到相关任务时才加载对应文件不会一直占着上下文。技能文件里可以写检查清单、命令示例、失败处理逻辑甚至带配套脚本。这样规则是结构化存储的可复用、可版本管理、可分享。改规则只需要改文件不用改每次对话的内容。我打个比方传统 prompt 是“口头交代工作”superpowers 是“把工作流程写进操作手册”。手册可以随身带可以复用可以迭代而口头交代每次都得重新说一遍还总有遗漏。1.3 它适合谁不适合谁先说适合谁。第一类是深度使用 Claude Code、Codex CLI 这类工具的开发者尤其是那些让 AI 实际参与功能开发、bug 修复、测试维护的人。第二类是团队场景你希望所有成员用同一套 AI 工作流而不是每个人对 AI 的调教方式都不一样。第三类是做项目维护的人代码库大、历史包袱重需要 AI 有纪律地改动而非乱捅。不适合谁如果你只是偶尔让 AI 补全一段函数、写个 SQL、改个样式那 superpowers 确实有点重没必要为这种轻量使用去搭一套技能框架。另外如果你的项目连测试都没有、代码结构一团乱技能框架也救不了你——它只是让 AI 遵循流程不能替你解决工程债。2. 环境准备与安装全流程2.1 前置条件先把编码智能体跑起来安装 superpowers 之前你的本机至少要有一个能跑起来的编程智能体 CLI。目前社区里用得比较多的是 Claude Code 和 Codex CLI两者都走命令行交互支持读取项目目录、执行命令、读写文件。superpowers 本质上是给这类 CLI 用的扩展资源所以不依赖图形界面也不用单独启动服务。另外最好确认 Node.js 环境是正常的。很多编码智能体本身依赖 Node 运行如果你的环境已经能正常跑 Claude Code 或 Codex CLI这一步基本就满足了。不需要单独装什么依赖包superpowers 就是一堆 Markdown 文件加少量脚本没有编译过程。我第一次装的时候差点误会了以为是跑个npm install -g superpowers之类的命令就完事。实际上它的安装更像是“把一套技能文件放到 AI 能读到的地方”。搞清楚这点后面就顺了。2.2 安装步骤两种常见方式社区里最通用的方式是把技能仓库克隆到智能体的技能目录。以 Claude Code 为例它默认会扫描~/.claude/skills目录下的技能项目级别则可以放在.claude/skills。Codex CLI 也支持类似的 skills 目录具体路径取决于版本但思路一致。我实际用的配置流程大致是这样# 1) 创建技能目录如果不存在 mkdir -p ~/.claude/skills # 2) 克隆 superpowers 技能仓库到目录内 git clone superpowers-repo-url ~/.claude/skills/superpowers # 3) 进入项目目录确认智能体能识别技能 cd /path/to/your/project克隆完之后建议看一眼目录结构确认每个技能子目录下都有 SKILL.md而不是把仓库套了一层多余文件夹。如果技能没被识别最常见的原因就是路径层级不对。另一种方式是走 plugin插件机制。有些版本的 Claude Code 支持 plugins 市场把 superpowers 注册为一个 plugin然后直接启用。这种方式的好处是更新方便source 指向固定仓库用plugin update就能拉最新版本。缺点是老版本 CLI 不一定支持所以我自己更推荐直接克隆到 skills 目录简单可控。2.3 快速验证让 AI 自己报告已装载的技能装完别急着用先验证。在 CLI 交互窗口里直接问一句“你有哪些可用技能”或“列出你加载的 skills”。如果安装正确它会把 superpowers 里的技能一个一个报出来比如 debugging、test-driven-development、code-review 等。如果它说没有发现任何额外技能不用慌按这个顺序排查先确认技能目录路径是否就是 CLI 扫描的那个路径再看目录层级是否有多余嵌套最后确认技能文件命名是否为 SKILL.md。我遇到过最蠢的一次是克隆成了superpowers-master文件夹里面还有一层superpowers导致 AI 完全没感知到。验证通过后再做一个轻量测试随便挑一个明显的 bug故意不修然后让 AI “用 debugging 技能帮我查这个问题”。看它是否先建假设、再动手改、最后跑测试。这个行为模式和普通对话明显不一样能直观感受到技能框架的作用。3. 核心技能拆解与实操用法3.1 技能文件到底长什么样你打开任意一个技能目录都会看到 SKILL.md。这个文件是技能的入口通常带一段 YAML 格式的头部信息包含技能名称、描述、适用场景、版本号等。正文部分就是具体的执行流程、检查清单、常用命令、注意事项。有些复杂技能还带reference子目录放更详细的参考资料比如“代码审查维度清单”“TDD 常见误区”之类。一个典型 SKILL.md 的结构大概是--- name: test-driven-development description: 在实现新功能之前先写失败测试按 TDD 节奏推进 when_to_use: 新增功能、修复 bug、重构前需要行为保护 version: 1.0.0 --- ## 执行步骤 1. 先编写一个会失败的测试用例描述期望行为 2. 运行测试确认失败 3. 写最简实现让测试通过 4. 重构保持测试绿色 ...这个格式不是死的你可以按需扩展字段。核心是让 AI 能通过description和when_to_use自行判断“这个任务该不该用技能”以及在调用后严格按步骤走。没有花哨的魔法就是把流程写清楚而已。3.2 三类高频技能调试、测试驱动、代码审查superpowers 技能集里最常用的几类我拆开讲一下实际用法。调试debugging技能。它的核心约束是“先定位、再修改、后验证”。普通 AI 遇到 bug 往往直接猜原因改代码运气成分很大。开启 debugging 技能后它会先让你描述复现步骤然后检查日志、缩小范围、建立假设每次只改一个变量最后跑测试确认。这个过程很像老工程师做根因分析而不是新手乱试。我在一个 Java 后端项目里用它查过一个偶发空指针AI 第一步不是改代码而是建议看调用链和传参最后定位到某个缓存未判空的问题过程非常稳。测试驱动开发TDD技能。这个技能贯彻“先红后绿”的节奏。实际体验是你让它“用 TDD 技能给用户模块加一个限流逻辑”它会先设计测试用例再跑一遍看失败然后写最小实现最后重构。整个过程它都会对照检查清单不会因为你说“赶时间”就跳过测试。这一点对养成 AI 的测试习惯特别管用。代码审查code review技能。它会把审查维度拆成安全、性能、可读性、边界条件、依赖风险等几个层面逐项输出结论。我一般让它在提 MR 之前先跑一遍比自己人肉看省不少时间。它的输出是结构化的改动文件、风险点、修改建议都列得清楚可以直接贴到评审区。3.3 自定义技能与团队共享技能框架最大的价值其实在“自定义”。你不用局限于社区提供的那些技能完全可以把自己团队的开发规范写成技能。比如你们规定所有接口都必须加日志埋点、所有数据库操作都必须走事务封装那就写一个backend-standards技能把这些规则列进去以后让 AI 干活前先调用它。写好一个自定义技能的套路也不复杂。先建目录写 SKILL.md头部的description要写得足够明确方便 AI 判断触发场景。正文把步骤拆细每步配上命令示例和完成标准。关键动作后面加“检查点”防止 AI 跳过。最后在技能目录里放一两个reference文档把细则展开写。团队共享就更简单了。把整套 skills 目录放到 Git 仓库里项目级放在.claude/skills大家 clone 下来就能用。新成员进来不需要再口头教 AI 规范技能文件本身就是最好的文档。我们还配合 plugin 机制做了自动同步每次更新规范后团队成员执行一次更新命令就能拉到最新技能。这套玩法一旦跑起来团队 AI 行为会非常一致。4. 实践中遇到的坑与排查方法4.1 技能没生效、AI 不按流程走多半是这些原因技能不生效或者说“AI 好像没看见技能”是最常见的问题。我把遇到过的异常现象和对应排查方向整理成了个速查表现象可能原因处理方式技能列表能列出但 AI 干活时不主动用描述信息写得不够具体AI 没判断出适用场景优化when_to_use把触发条件写清楚技能完全列不出来目录路径不对或嵌套层级错误确认技能在~/.claude/skills下且每个技能文件夹内直接有 SKILL.mdAI 用了技能但跳过关键步骤技能正文缺少命令或检查点约束力不够在步骤中增加“检查点”要求 AI 输出执行结果后才能继续部署到团队仓库后成员不生效成员本地技能缓存或路径不一致统一使用相同安装路径或用 plugin 机制分发多语言项目里技能表现不稳定技能里的命令示例与实际环境不符把命令参数改成与项目技术栈匹配的通用形式或分场景写多个脚本这里面最值得说的是“AI 用了技能但跳过关键步骤”。一开始我以为把步骤写在 SKILL.md 里 AI 就会照做后来发现如果步骤之间缺少强制校验AI 会优化掉它认为“不重要”的环节。解决办法是加检查点比如“执行完测试后必须把测试输出贴到对话中再继续下一步”。一旦需要输出证据AI 就很难蒙混过关了。4.2 工作流技巧怎么用好技能框架提升效率技巧一不要常驻加载所有技能。技能文件虽然只在调用时加载但让 AI 每次从几十个技能里挑它也可能选错。我会在项目根目录放一个.claude/skills只包含这个项目真正用得上的几个技能全局目录放通用技能。这样可以减少决策负担。技巧二在关键动作上强制人工确认。技能里可以写“在修改依赖或执行破坏性命令前必须停下来询问用户”。这样 AI 不会因为流程过于自动化而搞出大动静。我吃过一次亏AI 按照“重构”技能自动跑了一堆文件迁移结果有些配置没兼容旧逻辑差点把分支搞坏。后来所有破坏性操作都加了人工确认点。技巧三把技能纳入版本管理。技能本身就是代码资产改动要有记录。我们团队现在会把 SKILL.md 的变更和业务代码的 MR 绑定改规范的时候走代码评审。这样既能追溯也避免某个人悄悄改了 AI 行为影响全项目。技巧四定期试跑并对比行为。技能不是写完就完事模型版本更新后同一个 SKILL.md 的执行效果可能漂移。我会每隔一段时间跑一个标准任务看 AI 是否还严格遵守步骤。发现有偏差就调整技能措辞让约束更明确。4.3 避坑指南这几件事千万别做第一别把技能写成“万能指令”。有人喜欢在一个技能里塞几十条规则结果 AI 反而抓不住重点。更合理的做法是拆分测试一个技能、调试一个技能、代码风格一个技能。每个技能聚焦一个目标执行效果才稳定。第二别依赖 AI 自动触发技能。虽然技能可以按description自动匹配但准确率不是 100%。关键任务上我会显式指定比如“用 debugging 技能查这个报错”。这样既保证 AI 一定会加载正确技能也省去了它犹豫的过程。第三别忽略技能的失败处理。SKILL.md 里除了步骤还要写“如果测试失败了不要继续先回到上一步检查”。没有这类异常兜底AI 很可能在中间状态继续往下走越改越乱。之前就遇到过AI 在重构过程中测试挂了它没有停下来而是继续改了一堆文件最后整个模块全线飘红。第四别把技能框架当万能药。superpowers 能让 AI 的行为更规范但它替代不了人对项目的理解。涉及重大架构调整、安全敏感模块、第三方依赖升级这类事该人工评审的环节还是要人工评审。技能只是把“该做的事”按顺序摆出来了最后拍板的还是你自己。最后分享一个小技巧如果你维护多个项目可以考虑按技术栈拆分技能集。Java 后端项目、前端项目、数据脚本项目它们的最佳实践差很多放在一个全局技能包里不但冗余还容易误触发。把技能文件跟着项目仓库走效果比全量安装好得多。我现在每个仓库的.claude/skills都是精简过的只有和这个项目真正相关的技能。这个做法让 AI 的行为更像一个熟悉该项目的团队成员而不是什么都懂一点、什么都干不深入的万金油。