如果你最近在用 Claude Code 写代码，应该没少刷到 superpowers 这个名字。这不是又一个“精选提示词”网站，也不是玄学调参或者魔法脚本，它是给 Claude Code 装进一套“技能系统”的插件：通过官方 plugin 机制，把一批结构化、可复用的 skills（比如 brainstorming、writing-plans、tdd、debugging、code-review）直接注入到 AI 的工作流里。我自己的体验是，装之前 Claude 像个聪明但毛躁的实习生，装之后像一位手里拿着 SOP 的老工程师——同一个模型，做同一件事，产出质量几乎不在一个档位。
这篇不打算写成文档翻译。我按自己折腾和用了两个多月的经历，从“它到底是什么、装在系统哪一层”讲起，然后是安装的两种靠谱方法，接着逐个拆解核心 skills、modes 和 personas，最后给一份实战回放和常见坑位清单。如果你正纠结“要不要装、装了怎么用”，照着往下看就行。
1. superpowers 到底是什么：先搞清楚它装在系统的哪一层
1.1 插件不是提示词包
先纠正一个最常见的误解：superpowers 不是一段“万能提示词”，也不是把一堆 prompt 塞到 system prompt 里的那种配置。它是一个真正的 plugin 包，走的是 Claude Code 的插件机制。你可以把它理解成给 IDE 装扩展：装完不是我告诉 AI“你该怎么做”，而是 AI 的系统里天然多了一批“可调用技能”，它自己会根据任务内容判断什么时候该调用哪个技能。
装完插件后，Claude 的上下文里会多出一份“技能清单”——每个技能是一个 SKILL.md 文件，文件头部有name和description两个字段，正文则是具体的执行步骤、检查清单和注意事项。当你的请求命中某个技能的描述时，Claude 会主动去读取该技能的完整内容，然后像执行操作规程一样一步步来。
这个设计最大的价值是稳定性。平时我们靠提示词约束 AI，模型经常“想了想就飘了”；技能不一样，它相当于一份 AI 一定会去读的详细操作手册，步骤、产出物、验收点都写死了，模型跑偏的概率小非常多。
1.2 插件包里装了什么
打开 superpowers 的插件目录，能看到它比普通插件“重”不少。大致有四类东西：
- skills 目录：核心资产，几十个 SKILL.md 文件。每个技能都是一个独立文件夹，负责一类任务，从头脑风暴到写 commit message 都有。
- modes 目录：自定义模式，也就是 Claude Code 里的斜杠模式。比如 architect、code、debug、plan、review 这类“岗位视角”，切换后 AI 的行为倾向会跟着变。
- personas 目录：人格预设，调整 AI 的表达风格和协作方式，属于可选项。
- custom instructions（自定义指令）：插件自带的一段系统级说明，它告诉模型“遇到什么情况读哪个技能、技能没覆盖时要自己补写技能”，是整个系统的粘合剂。
理解这四类东西的分工很重要：skills 管“做什么、按什么步骤做”，modes 管“用什么视角做”，personas 管“用什么口气做”，custom instructions 管“什么时候调动前面三样”。后面几节我会逐个展开。
1.3 核心机制：技能描述驱动的自动加载
superpowers 之所以好用，关键在“自动加载”这个机制。Claude Code 本身支持技能：AI 在每次会话里都能看到当前项目（.claude/skills）、用户目录（~/.claude/skills）以及插件提供的技能清单。它不用把所有技能全文读进上下文——那样 token 早爆了——而是先看每个技能的description，觉得哪个和当前任务相关，才去读对应 SKILL.md 的正文。
举个例子：你说“帮我把搜索接口的响应慢问题查一下”，模型扫到技能清单里debugging的 description 写着“用于系统化定位并修复 bug”，它就会自动加载这份技能，然后按“复现-假设-验证-定位-修复-回归”的流程走，而不是上来就瞎打日志、随手改代码。
这个机制带来的隐性收益是 token 效率。几十个技能只占“清单”那份量，真正占上下文的是当前命中的那几个技能正文。所以你不用担心装完插件后上下文全被撑爆——只要不是为了写代码而让它硬加载技能，开销其实是可控的。
2. 安装与引入：两种最常用的装法
问得最多的问题就是“想要安装 superpowers，怎么弄”。其实路子有两条：一条在 Claude Code 界面里点，一条在终端敲命令。我建议初次使用走界面那一条，更不容易出错。
2.1 安装的前置条件
先把前提说清楚。superpowers 是 Claude Code 的插件，所以你需要：
- 安装并登录 Claude Code 命令行工具，能正常开始一个会话；
- 网络能正常访问插件市场；
- 建议先把它装到项目级，而不是全局。技能会注入上下文，如果所有项目都全局启用，非开发类项目也会背着这份开销。
提示：安装前如果旧会话还开着，建议先退出。插件加载发生在会话启动阶段，中途安装的插件，当前的会话不一定能感知到。
2.2 方法一：在 Claude Code 里用 /plugin 安装（推荐）
打开 Claude Code，在输入框敲：
/plugin回车后会弹出插件管理界面。这里有两种走法：
- 如果市场里已经能搜到 superpowers：直接在搜索框输入
superpowers，回车，选中插件，确认安装。 - 如果搜不到（市场需要手动添加）：在插件管理界面里选“添加 marketplace”，输入官方市场地址
https://superpowers.obra.dev，添加成功后重新搜索superpowers，再安装。
安装完成后界面会提示“需要重启会话以应用更改”。这时退出当前会话，重新开一个，插件就生效了。整个过程不需要碰配置文件，适合第一次接触插件机制的同学。
2.3 方法二：命令行直接装
习惯终端的同学可以用命令装，两条命令搞定：
claude plugin marketplace add jessevincent/superpowers-marketplace claude plugin install superpowers@jessevincent/superpowers-marketplace第一条把官方 marketplace 注册进来，第二条从市场里安装 superpowers 插件。命令执行完同样需要新开会话。
需要注意，插件市场的仓库路径会随项目维护动态变化，如果上述地址不匹配，以官方文档页（superpowers.obra.dev）展示的最新市场地址为准。我看到过不少人照抄旧教程导致装不上的，遇到 404 或者 unknown marketplace 先别慌，回官方页确认一下市场地址。
如果你连插件都不太想装，只想拿走技能文件，也有个精简方案：把仓库里的skills/目录整个复制到你项目的.claude/skills下。这样 Claude Code 也能读到这些技能，只是没有 custom instructions 和 modes 的加持，“技能自动判断该不该加载”这件事表现会弱一些，核心步骤技能还是能用的。我建议还是完整装插件，精简版适合只想体验下技能文件格式的场景。
2.4 装完怎么确认生效
装完后别急着开始干活，先确认一下到底加载成功没有。新开会话，直接问一句：
你现在加载了哪些可用的 skill？请列出技能名称和各自的作用。
如果看到 brainstorming、writing-plans、tdd 这些名字，说明生效了。如果它回答“没有额外技能”或者只列出系统内置的，多半是会话没重启，或者装到了别的项目目录。也可以在终端用claude plugin list之类的命令查看插件状态（不同版本命令名略有差异，不记得就先敲个claude plugin看帮助）。
第一次用的时候，我还建议你专门测试一下“技能触发”：对 Claude 说“帮我 brainstorm 一下这个功能的三个方案”，看它是不是真的进入“先提问、再发散、后收敛”的节奏，而不是直接甩答案。这一步能确认 custom instructions 生效了没有。
3. 核心 skills 逐项解读：这些技能到底让 AI 做了什么
这是大家最关心的一节：superpowers 具体有哪些 skills，分别用在什么场景。我先把常用技能按类别列出来，再挑几个重点展开讲背后的运行逻辑。
3.1 常用技能地图
不同版本的技能清单会略有增删，但核心那十几个是很稳定的。我按使用频率整理了一张表：
| 技能名称 | 触发场景 | 核心产出 |
|---|---|---|
| brainstorming | 需求不明确、方案发散 | 问题清单、候选方案、收敛后的建议 |
| writing-plans | 拿到需求要拆解执行 | 分阶段计划、每阶段的验收标准 |
| developing-with-test-driven-development | 写新功能 | 先写失败测试，再最小实现，循环变绿 |
| debugging | 线上或测试挂了 | 根因定位报告，而不是“猜一个修一个” |
| troubleshooting | 环境、构建、配置问题 | 假设-验证闭环 |
| code-review | 提交前审查代码 | 按严重程度分级的意见清单 |
| system-design | 系统/模块设计 | 约束、组件、接口、取舍说明 |
| writing-design-docs | 需要设计文档沉淀 | 结构化设计文档 |
| writing-clean-code | 重构、优化既有代码 | 简化实现、明确命名、理清职责 |
| creating-components | 前端组件开发 | 带测试和文档的完整组件 |
| writing-commit-messages | 提交代码 | 结构化 commit message |
看这个表你会发现，superpowers 的技能覆盖了“从零到上线”的完整链路，而且底子是很正统的软件工程方法论：先想清楚、再定计划、再测试驱动、最后审查。它把很多团队靠 culture 才能推行的实践，直接编码成了 AI 的执行步骤。
3.2 brainstorming 与 writing-plans：把“发散-收敛”变成流程
先说 brainstorming。很多人觉得这技能没必要——“我又不是不会跟 AI 聊天”。但你对比一下就知道了：普通对话里你说“给我几个方案”，AI 会立刻给你三个看起来合理但实际上没经过推敲的答案。而 brainstorming 技能加载后，它会按固定流程走：先确认目标、盘点约束，然后提出澄清问题，再发散出尽可能多的方向，最后按标准评估收敛。
我实际用下来的感受是，它的最大价值是“阻止 AI 抢跑”。模型太爱直接给答案了，但很多需求我们自己的脑子其实都没理清。brainstorming 强制先问问题、先对齐目标，这恰恰是普通对话模式下最难得的部分。
writing-plans 则是承接 brainstorming 的下一环。它负责把“我们决定做 X”拆成“分几步做、每步做什么、怎么算完成”。加载这个技能后，Claude 输出的计划会自带验收标准，每一条任务都不是模糊的“优化一下”，而是“完成 A 功能，当且仅当测试 B 通过”。这直接决定了后面的执行质量——计划写得含糊，执行就全靠运气。
3.3 tdd、debugging 与 troubleshooting：质量类技能的底层逻辑
superpowers 最让我服气的是它默认要求测试驱动开发。tdd 技能的核心循环是：先把需求变成一个会失败的测试，再写刚好能让它通过的实现，然后重构，循环往复。模型加载这个技能后，会主动先写测试再写代码，而不是兴致勃勃地先把实现写完再说。
这里有个细节值得注意：tdd 技能不是“让你写测试”这么简单，它内部定义了严格的阶段——红（测试失败）、绿（测试通过）、重构（清理实现）。每一个阶段都有明确的产物和退出条件。正是这种严格的顺序，才让 AI 的产出从“能跑”变成“可验证”。
debugging 和 troubleshooting 则是给“出了问题”场景用的。debugging 处理的是代码逻辑问题，它的流程是：先复现、再建立假设、用最小实验验证、查到根因、修复、最后回归验证。troubleshooting 处理的是环境、配置、构建这类“不是代码逻辑但就是跑不起来”的问题，走的是类似的假设-验证闭环。
这两个技能解决的是 AI 最典型的毛病：猜一个原因、改一行代码、跑一下、还不行、再猜。加载技能之后，模型会先收集证据再动手，错误定位的准确率提升非常明显。
3.4 code-review、system-design 与 design-docs：工程化协作类技能
code-review 技能适合在提交代码前让 Claude 做一轮审查。它的输出不是“这代码不错”这种废话，而是按严重等级给意见：哪些是阻断性问题（会导致 bug 或安全问题）、哪些是质量问题（可读性、可维护性）、哪些只是风格建议。它还会检查边界条件、安全风险、错误处理这些 AI 单写代码时最容易漏掉的地方。
system-design 是一套相当重的技能，它把架构设计当作一个“先充分理解问题”的过程：先问清约束（用户量、时延、可用性要求），再列组件、接口、数据模型，最后做权衡说明。如果你让 Claude 直接设计系统，它默认给你一个“看起来完整但完全没法落地的玩具架构”；加载这个技能后，它会先追问一堆关键问题，出来的方案才真正能讨论。
writing-design-docs 则是把 system-design 的结果落成文档，两者的搭配逻辑和 brainstorming→writing-plans 一样：一个负责思考，一个负责沉淀。
4. modes 与 personas：把同一个人格切换成不同岗位
skills 管的是“任务怎么做”，但同一个任务，站在不同视角做出来完全不一样。superpowers 里的 modes 和 personas 解决的就是这个“视角”问题。
4.1 内置 modes 的效果与选择
mode（模式）在 Claude Code 里是比技能更轻的一层配置，它主要影响的是模型在会话里的默认行为倾向。superpowers 装好后，你会多出几个斜杠模式，典型的像 architect、code、debug、plan、review 这几个：
- architect：偏架构视角，适合在动手前讨论方案、权衡取舍，它会刻意把“实现细节”往后放；
- code：偏实现视角，专注写代码、跑测试、处理编译错误；
- debug：侦查视角，遇到问题带着怀疑去求证，特别强调先复现、后定位；
- plan：拆解视角，适合把目标切成可执行、可验收的任务块；
- review：审查视角，用来检查已有代码，输出结构化审查意见。
切换方式很简单，在会话里输入/mode就能看到可用的模式列表。我自己的习惯是：一个需求进来，先用 architect 讨论方案，方案定了切 plan 拆任务，执行时切 code，出问题切 debug。模式之间可以随时切，它不是锁死的。
4.2 persona 的作用
persona 是表达层的人格预设，它不改技能和方法论，只改“AI 协作时的口气和风格”。比如有的 persona 会让模型更像一个谨慎的同伴（习惯先质疑再确认），有的则更像一个高效的执行者（少废话多干活）。这属于锦上添花的功能：新手可以先不用管，默认配置就够用；如果你对 AI 的“说话方式”有偏好，可以进去翻翻，找到对味的留下。
有人可能会问：persona 和 mode 会不会冲突？其实不会。mode 决定它“用什么角色思考”，persona 决定它“用什么语气说话”，一个管内容一个管形式，两者正交。实际用的时候，mode 按任务切换，persona 基本一次设好就不用动了。
4.3 自定义 mode 的实操配方
如果你不想用默认模式，完全可以自己写。Claude Code 的自定义模式实际上就是一个带元信息的 Markdown 文件，放在项目的.claude/modes/目录下。文件头用 YAML 写：
name: api-design description: 用于 API 设计的模式，优先考虑接口契约和兼容性正文就写这个模式下你应该遵守的行为准则：比如“先定义请求响应结构，再写实现”“每次改动都要考虑向后兼容”“禁止跳过对外文档”。写完保存，回到会话敲/mode，就能在列表里看到它。
这里给一个配方建议：自定义 mode 的 description 一定要写清楚“什么场景用”，因为 Claude Code 会根据描述帮你推荐模式。如果你描述写得太宽泛，比如“用于开发”，那它什么都往里套，模式反而失去意义。定制原则跟写技能 description 一样：宁可窄一点、准一点。
5. 实战记录：从需求到落地的技能驱动流程
讲了半天原理，我们来看一次完整实操。这是我最近给一个内部工具加“标签筛选”功能的记录，按 superpowers 的完整流程走了一遍，从需求模糊到代码落地大概用了一个多小时。
5.1 一次完整工作流回放
第一步，我先切到 architect 模式，然后对 Claude 说：“我们内部工具现在文章列表没有筛选能力，想加一个按标签筛选，先别写代码，我们讨论下方案。”
它按 system-design 的思路开始追问：标签是单选还是多选？筛选是前端过滤还是走接口？标签从哪来、量级多大？这些问题其实我自己都没完全想清楚，它问完我反而把需求补全了。讨论完它给出两个方案：一个纯前端过滤（适合数据量小），一个后端查询参数（适合数据量大、将来要分页），并明确建议先用后端方案，因为列表本身已经走接口，将来加搜索也顺路。
第二步，我说“把方案写成计划”。writing-plans 技能自动加载，输出了一份三段计划：第一段加接口查询参数和对应测试，第二段前端加多选标签组件和状态管理，第三段做端到端验证。每段都有验收标准，非常清楚。
第三步，执行第一段时我说“用 tdd 来做”。模型进入红绿循环：先写了接口测试（此时新的查询参数还没实现，测试红），然后补实现让测试变绿，再跑一遍完整测试套件确认没破坏老功能。全程它自己决定，几乎不需要我干预。
第四步，前端改完准备提交前，我让它“review 一下这次改动”。code-review 技能先扫了一遍，还真抓到一个问题：标签参数传多个值时，接口只取第一个，这是个真实的坑。它按严重级别标了“需要修复：多选场景只生效第一个值”，我立刻修掉了。
5.2 技能自动触发和手动干预的配合
这一轮下来，我的体感是：superpowers 的自动触发基本靠谱，但你不能完全当甩手掌柜。比如我在第一步根本没有明确说“用 brainstorming 技能”，它是根据“讨论下方案”这句话自己判断该走 brainstorm 路线的；第三步我明确说了“用 tdd”，它就重点加载 tdd 技能。
这里有个经验：重要节点显式点名，常规节点让它自动判断。越是关键环节（比如要开始写代码了、要提交了），越值得在话里带上技能名或模式名，省得它识别偏差。普通对话里的自动触发更多是“辅助”角色，给 AI 一个默认的优质行为基线。
另外，技能的执行过程是可以打断的。如果你发现它在哪一步明显理解错了需求，直接说“等一下，这里情况是……”，它会重新读技能步骤并调整，不用重新开会话。
5.3 我自己固定下来的一套高复用流程
跑了两个多月，我沉淀了一套固定流程，现在几乎每个功能都这么走：
- 新需求进来，先
/mode architect+ 一句话描述，逼自己把需求和约束说清楚； - 讨论完主动说“产出计划”，让 writing-plans 拆任务；
- 执行阶段明确要求 tdd，代码质量靠红绿循环兜底；
- 代码完成说“review”，让它按严重级别出意见；
- 提交前让它写 commit message，保持提交信息规范。
这套流程最大的好处不是每个环节都多么智能，而是它把“工程质量”这件事分摊到了日常的每一步。以前我靠事后 code review 和质量工具补救，现在 AI 在写的那一刻就走对了流程，返工量少了一大截。
6. 常见问题与避坑实录
最后这部分全是干货。写两个多月下来，我踩过不少坑，也看群里朋友踩过不少坑，整理成问答形式，方便你直接对号入座。
6.1 技能没有自动触发怎么办
最常遇到的问题就是：我明明装了插件，但它完全不按技能走。排查顺序是：
- 确认会话是新开的。插件只在会话启动时加载，装完没重启就会“像没装一样”；
- 确认装到了当前项目。如果装到 A 项目，在 B 项目开会话是读不到的；
- 确认请求能命中描述。技能触发靠 description 匹配，“帮我看看为啥慢”比“debug”更容易命中 debugging 技能，太简洁或太奇怪的说法确实可能识别不到；
- 最后兜底手段：直接说“使用 brainstorming 技能”或“加载 tdd 技能”，显式点名一定有效。
测试技能是否生效，最笨也最可靠的办法就是开头说的那招：问它“你现在有哪些技能”。如果它背不出几个技能名，说明根本没加载。
6.2 上下文膨胀和多个技能互相打架
有朋友反馈“装完以后感觉模型变笨了”，很多情况其实是上下文被撑大之后，注意力被稀释了。我的缓解办法有两条。一是别把 superpowers 装成全局插件，只在正经开发的工程目录装；二是一个会话里不要同时触发多个大技能，比如 brainstorm 完了就不要再让它“顺便 review 一下代码”，一个会话聚焦一个核心任务，换任务就新开。
多个技能“打架”也是真实存在的。最典型的是 tdd 和 writing-plans 同时在场时，模型的行动顺序会纠结：是先按计划走，还是先走红绿循环？我的处理方式是显式排序：“先看计划，然后按 tdd 执行第一阶段”。给 AI 一个明确的主从关系，它就不纠结了。
6.3 让 AI 自己写新技能：超能力里最被低估的功能
superpowers 有个很有意思的设计：当 Claude 发现没有现成技能匹配当前任务时，它会被引导去“自己写一个新技能”，然后存到项目的技能目录里。也就是说，技能的边界不是死的，你可以让 AI 把反复出现的任务固化成技能，下次直接自动加载。
我试过几次，比如团队里经常要做“数据库迁移回滚方案”，我让 AI“把这类任务写成一个新技能”，它真的生成了一个 SKILL.md，包含迁移前检查、备份策略、回滚步骤、验证清单，放到.claude/skills下。之后再遇到迁移任务，它会自动命中这个技能。
这里有个提醒：让 AI 生成的技能，description 一定要人工看一眼。description 写太宽会导致技能过度触发，把所有相关任务都吸过来，那反而成了负资产。我一般会顺手把 description 改窄一点，只匹配真正需要它的场景。
6.4 与自定义配置冲突和处理建议
如果你项目里已经有一套自己的.claude/settings.json、内存文件（memory）或者 hooks 配置，装插件后偶尔会出现“行为叠加”——比如你自己定的规则说“永远不要改测试文件”，但 tdd 技能要求先写测试。这种冲突一旦出现，以显式指令优先：你在对话里说的、或者 settings 里的强制规则，优先级高于技能建议。如果不想要这种叠加，可以在技能要点到来时直接说“这条技能步骤先跳过”。
另一个建议是保持插件更新。superpowers 迭代挺快的，技能内容本身也在持续完善。定期在/plugin界面看看有没有更新，或者直接重跑一次安装命令拉最新版。旧版本可能因为没有最新的 skill 定义，行为反而打折扣。
提示：如果你用了多个 AI 编程工具（比如还配了其他 agent 框架），注意技能目录格式不通用。superpowers 的 skills 是 Claude Code 生态的产物，SKILL.md 的 frontmatter 字段和加载机制跟别的工具不一定兼容，迁移时要重新适配，别指望直接复制过去就能用。
最后再分享一条体会。很多人把 superpowers 当成“装完就变强”的挂件，但我的真实体验是，它更像一面镜子：你的需求描述越清晰，它发挥的余地越大。用它的正确姿势，不是把思考外包给 AI，而是把“思考的流程”固定下来，让 AI 每一步都走在可靠的轨道上。这套东西我用了两个月，现在回头看，最大的改变不是代码写得快了，而是我不再依赖“运气型编程”了——每个功能从想法到落地，路径都变得可以预期，这种确定性，才是最值钱的部分。
