用Superpowers为Claude Code搭建完整工作流：从写代码到工程交付

用 Claude Code 跑了小半年，我一直觉得这工具“能用，但差点意思”。它能写代码、能改 bug，但你让它从头负责一个稍复杂的任务时，它经常会一头扎进细节里，把方案选型、边界条件、验证步骤全抛在脑后。直到我装上了 Superpowers 这个插件，才反应过来：问题不在模型能力，是我压根没给它一套完整的工作流脚手架。

Superpowers 不是什么神秘增强包，它本质上是一套开源的技能（skills）集合，以 Markdown 文件的形式定义了一批可复用的工作方法，然后通过插件机制注入到 Claude Code 这类 AI 编程代理里。装上之后，AI 不再只是“你问一句它答一句”的聊天式编码，而是会自己先做头脑风暴、再写计划、再动手实现、再自查收尾，像个体面的外包工程师。这篇文章我会从设计思路、具体技能、安装步骤、使用姿势到自定义扩展，把我实际跑通的整套玩法讲清楚，适合正在用 Claude Code 但觉得产出不稳定，或者刚接触 AI 编程想少走弯路的朋友。

1. 先搞清楚它要解决什么问题：不是更多指令，而是一套工作流脚手架

1.1 模型不缺能力，缺的是“被显式调用的方法论”

你先想想一个现象：同一个模型，你让它“帮我修一下登录报错”，它可能直接改两行代码就说改完了；但如果你让它“先复现问题、查日志、定位根因、列出候选方案、选一个实施、再写验证用例”，它产出的质量会明显高一个档次。区别在哪？在于你有没有把方法论说清楚。

可问题来了，每次都要在 Prompt 里长篇大论地教它怎么做，既费 Token 又不稳定，换个项目、换台机器就全忘了。Superpowers 的思路就是：把这一类“高质量工作方法”固化成独立的 skill 文件，让 AI 在需要的时候主动读取、按步骤执行。它不改变底层模型，不微调权重，只是把一套可复现的工作流变成了 AI 的“肌肉记忆”。

以我接触的版本为例，Superpowers 的 skills 目录下维护着 brainstorming、planning、debugging、code review 等一组技能，每个技能都是一个带结构化参数的 Markdown 文档，里面写清楚了“这个技能解决什么问题”“什么时候该用它”“执行步骤是什么”“完成后要产出什么”。这套结构有一个专门的叫法：CRISP 技能格式，核心思想是把“技能描述”和“执行步骤”分离，让 AI 在开始干活前先理解目标，而不是机械地跑完清单。

1.2 为什么是“插件+技能”而不是改 system prompt

可能有人会想：我不装插件，直接在 CLAUDE.md 里写一段“你要遵守十条工作准则”，效果不是一样吗？我一开始也是这么干的，后来发现痛点很明显。

CLAUDE.md 内容一长，AI 的注意力会被稀释。你塞十条准则进去，它真正执行的时候可能只记住前两三条。而且每条准则都是抽象的原则，没有给出具体的“触发条件”和“操作步骤”，AI 遇到真实场景时并不知道该在哪一步调用哪条。Superpowers 这类插件对这个问题做了一个很巧妙的拆解：plugins 负责在启动时注入一个轻量的索引说明，告诉 AI“你有哪些技能、分别什么时候用”；skills 负责在需要时加载完整步骤。索引很轻，不占上下文；技能很重，但只在需要时才被读取。

举个生活化的例子，这就像你请了个实习生。你不该把一本三万字的手册塞进他脑子里，而是应该在墙上贴一张索引卡：“遇到报错查这页，做方案先看那页，要写测试翻附录”。他真正遇到问题的时候，自己去翻对应的页就行。Superpowers 干的就是这个事。

1.3 它带来的东西，本质上是把“个人经验”项目化

我之所以推荐大家从 Superpowers 开始玩技能体系，还有一个更实际的原因：它把“个人 Prompt 技巧”从聊天记录里解放出来了。以前你调教好一段好用的指令，只能存在某个会话里，换个项目就没了；现在它是一个独立文件，可以提交到 Git 仓库、随项目分发、让团队成员共用。这意味着，你在这个项目里积累的调试方法、代码规范执行方式、需求拆解流程，都变成了可版本化、可评审、可迭代的资产。

这事情在团队里尤其重要。一个 5 人团队，每个人给 Claude 的指示风格完全不一样，产出自然七零八落。如果团队约定只用同一套 Superpowers 技能库，至少在“AI 怎么思考”这个层面，大家的基准线是一致的。

2. 核心技能盘点：它自带的这些技能到底能干什么

2.1 从模糊想法到可执行计划：Brainstorming 与 Planning

我最先感受到明显变化的是 brainstorming 这个技能。以前我丢给 AI 一句“帮我想想这个功能怎么做”，它多半会直接给一个方案，然后被我挑出一堆毛病，来回拉扯好几轮。现在有了 brainstorming，它会在动手之前先“发散”：列出候选方向、每个方向的风险、需要向用户确认的开放问题，甚至会主动提醒我“你给的需求里有两个边界条件还不清楚”。

等发散完成，planning 技能接手，把事情收敛成一步步可执行的计划。它生成的计划不是简单的一句话列表，而是带依赖关系、验证方式和完成定义的。比如它会写成“第一步：先确定接口数据格式，完成标志是 mock 数据能通过类型检查”，这种颗粒度才是工程级协作需要的。

我自己试下来的体验是：这两个技能合在一起，最大的好处是“把返工提前消灭了”。以前改三版方案是常态，现在 AI 先自己把坑标出来，你只需要在关键决策点上做拍板，沟通成本至少降一半。

2.2 让 AI 学会自己排查问题：Debugging 与 Root Cause Analysis

调试类的技能对我来说是第二惊喜。我遇到过很多次这种情况：代码跑挂了，AI 扫一眼代码说“可能是这里的问题”，然后改一下就完事，结果下一个测试用例又炸了。Root Cause Analysis 这个技能会强制 AI 按一套标准流程走：先复现问题、再收集证据、列出所有可能原因、逐个排除、找到根因、修复、写回归用例、确认没有副作用。

你可能觉得这些都是常识，但对语言模型来说，“常识”恰恰是最容易跳过的部分。它天生倾向于“快速给出看起来合理的答案”，而不是“做一次严谨的诊断”。技能文件的意义就是给这类场景层层设卡，让 AI 无法偷懒。我遇到一个数据错乱的 bug，AI 按流程排查到最后发现根本不是写入逻辑的问题，而是缓存未失效，这个结论靠“扫一眼代码”是得不出来的。

2.3 代码评审与重构：把交付前的最后一道闸门交给流程

code review 和 refactoring 技能也值得单独拿出来说。在没有技能约束的时候，你请 AI 做 Code Review，它大概率会回复“这段代码写得很不错，只有一些小优化空间”，用处不大。但 Superpowers 的 code review 技能会要求它按正确性、安全性、性能、可维护性、测试覆盖这几个维度交叉检查，而且必须给出“具体的问题描述 + 为什么它是问题 + 建议怎么改”。

我有一次用它审查一段支付回调的逻辑，AI 直接指出“这个验签失败后的处理分支没有记录审计日志，而且重复通知会被重复入账”。这两个问题如果靠人工 reviewers 不一定当场看得出，但它因为按 checklist 走，就不会漏。可能你要说“这不是因为它更聪明，只是它更听话”，对，这就是技能存在的意义。

2.4 长任务的拆解与子代理调度

另外一个值得一提的能力是 subagent 相关的技能。现在的 Claude Code 其实就是一套 agent 循环，主对话线程负责理解意图、协调工作计划，子代理承担具体的研究和编码任务。Superpowers 里也有专门教 AI 如何拆解任务、如何给子代理下达清晰指令的技能。

这个对大型重构特别管用。比如你有一个 2 万行的老模块要迁移，如果没有拆解意识，AI 会一头扎进去改到一半才发现方向错了。有了任务拆解技能，它会在动手前把大目标切成若干个小批次，每个批次都有明确的输入输出和验证方式，然后像流水线一样逐个执行。主观感受就是：长任务的“断裂感”变少了，中途崩溃的概率小了很多。

3. 安装与引入实操：三步让技能跑起来

3.1 环境准备：先把基础工具确认到位

在装 Superpowers 之前，我建议你先确认几个基础条件。第一，Claude Code 的版本别太旧，技能类插件的加载依赖比较新的 CLI 能力，如果版本太老会出现“插件装了但技能不加载”的情况；第二，本机要有 Git 环境，因为目前最常见的安装方式还是直接克隆仓库；第三，Node.js 环境尽量保持在 18 或更高版本，一些插件脚本会用到 Node 运行时。

如果这些环境都没问题，再开始安装就会很顺。我自己习惯在装之前先跑一下claude --version和git --version，确认版本号正常，总比装到一半报错再来排查要省事。

3.2 安装插件本体：克隆到插件目录，做好命名收敛

不同版本的 Claude Code 对插件目录的位置支持不太一样，常见的是在项目根目录下建一个.claude/plugins目录，或者在用户全局配置目录下放插件。以我目前在用的方式为例，我会先创建一个插件目录，然后把 Superpowers 仓库克隆进去：

mkdir -p ~/.claude/plugins cd ~/.claude/plugins git clone https://github.com/obra/superpowers.git

克隆完之后，建议确认一下目录结构。正常情况下你会看到一个skills目录，里面就是一排 Markdown 技能文件或子目录，还有一个plugins或配置文件用来声明插件入口。只要看到skills目录存在，说明核心内容已经在本地了。

这里有个细节要提醒你：如果你同时装了多个插件，注意不要互相覆盖。之前我为了让技能路径更整洁，手动改过目录名，结果插件加载时找不到对应路径，技能一直不出来。后来还是老实保持仓库原本的目录名，省心。

3.3 在 Claude Code 里引入技能：让索引进入系统提示词

插件克隆到本地只是第一步，真正让它生效的是“技能索引被注入到 AI 的上下文”。在 Claude Code 的较新版本中，插件机制会在会话启动时自动读取.claude/plugins下的插件声明，并把插件配置里的技能说明注入系统提示词。

你可以在会话里直接问一句：“你当前加载了哪些技能？”它如果准确列出 brainstorming、planning、debugging 等名称，说明索引已经注入成功。如果它回答得含糊不清，或者表示不知道有技能这回事，那大概率是插件没有被识别，需要检查路径和配置。

为了在项目内让 AI 更明确地感知这些技能，我还会在自己的项目文档里加一段索引说明，比如在 CLAUDE.md 末尾追加：

## 技能索引 本项目的 AI 工作流将使用 superpowers 插件提供的技能。 当需要拆解模糊需求时，使用 brainstorming 技能； 当需要制定实施计划时，使用 planning 技能； 当遇到未预期行为时，使用 root_cause_analysis 技能进行排查。

别小看这段索引文字，它等于给 AI 一个“路标”，让它在没有用户明确要求时也懂得在合适场景调用对应技能。比起直接问“你有哪些技能”，你主动告诉它“这些场景下要用这些技能”，命中率要高得多。

3.4 验证安装效果：用一个小需求做冒烟测试

安装完不验证等于白装。我建议你找一个真实的小需求做一轮“冒烟测试”，不要用 hello world 这种太简单的任务，否则技能没有发挥空间。比如你可以说：“我想在项目里加一个 CSV 导入功能，支持重复数据去重，帮我推进一下。”

如果安装正常，AI 不会直接掏代码，而是会先进入类似 brainstorming 的思考流程，反问你几个问题：文件大小上限是多少？重复数据以哪个字段为准？去重后要做日志吗？等你回答完，它再给出计划，然后才开始实现。这个“回答前先问问题”的行为，就是技能在起作用的明显特征。

如果它还是像以前一样直接给代码，先别急，到第 5 章的排查表去逐项检查。按我的经验，九成情况是插件路径没被读到，或者技能索引没被注入。

4. 实际使用中的调用姿势：一批我自己跑通的建议

4.1 对话开场就点技能名，别等 AI 自己悟

技能装好了，不等于 AI 每次都会自动用。它毕竟还是依赖上下文判断的模型，你不能指望它在所有场景里都精准命中技能。所以我的习惯是“明确点名”。想让 AI 做头脑风暴，开场就说“用 brainstorming 技能帮我把这个需求拆一下”；想让 AI 审代码，就直接说“对这次改动执行 code review 技能”。

点名有两个好处：一是省去 AI 自行判断要用哪个技能的过程，直接命中；二是让它从对话最开始就走对工作流，而不是先输出一版不完整的答案，你再来纠正。这就像你给外包团队打电话，第一句就说“按我们规范里的流程走”，比让他们自由发挥靠谱得多。

而且点名之后，你要留意它的输出格式。比如它说“我先按照 brainstorming 技能提问几个问题”，这是正常的；但如果它只是口头说“好的，我帮你想想”，却没有任何结构化输出，那技能大概率没生效，你就得停下来查配置。

4.2 让 AI 在技能间自动切换：把流程串成流水线

点名单技能只是初级玩法，高级一点的用法是让 AI 自己串联多个技能。比如我常在一个需求描述里写：“先用 brainstorming 技能明确方案边界，再用 planning 技能输出实施计划，确认后开始编码，最后用 code review 技能自查一遍。”

你可能会担心这么复杂的要求，AI 执行不过来。实际跑下来其实还好，因为每个技能的触发都会在对话流中留下一个“环节标记”，AI 会在合适的位置调用后续技能。你不需要频繁介入，只在关键决策点回应它的问题就好。整个过程像个半自动流水线，你负责验收，它负责严格执行流程。

这里有一个建议：每一轮技能切换的间隙，让 AI 先输出一个简短的“本次结论”，你再决定是否进入下一阶段。这能避免它在一个技能里跑太深、忽视全局目标。相当于每个阶段加了一道人工闸门，成本不高，但能让大任务的走向始终可控。

4.3 一个真实的调试场景复盘

我把一个典型场景完整还原给你看。当时我遇到的问题是：服务偶发超时，但看日志又找不到明显异常。如果没有技能，我猜 AI 大概率会列几个常见原因，然后建议我加日志再观察。但那次我在对话里明确指定“用 root_cause_analysis 技能排查”。

它的执行过程完全不一样。第一步，先要求我提供复现频率和触发条件；第二步，让我打开慢查询日志和网关访问日志；第三步，列出了五个嫌疑点，包括连接池耗尽、数据库锁等待、GC 停顿、外部接口慢调用、线程池队列堆积；第四步，逐个分析证据，排除了数据库锁等待，因为有慢查询但无锁等待事件；最后把根因锁定在线程池队列堆积，因为某个上游接口在整点秒杀活动时响应变慢，导致调用线程被占满。

修复方案也很完整：给该上游接口加独立线程池、设置超时熔断、增加队列监控告警。这一整套下来，不是模型变聪明了，而是技能逼着它走完了“假设-验证-排除-定位”的完整闭环。我自己是越来越依赖这种强制流程了，因为人脑会累会漏，技能不会。

4.4 把技能引入团队规范：从个人经验到团队资产

如果你不是单打独斗，我强烈建议把 Superpowers 纳入团队仓库。具体做法很简单：在项目根目录的 CLAUDE.md 里写入技能索引，把插件目录提交到一个共享仓库或让团队各自按统一命令安装，然后在 PR 模板里加一句“AI 代码评审须执行 code review 技能”。

这么做最大的收益是稳定。团队里每个人使用 AI 的方式不一样，有人喜欢让 AI 直接改代码，有人喜欢让 AI 先列计划，最终产出风格天差地别。约定同一套技能体系后，AI 干活前先做需求澄清、再出计划、再实现、再自查，这一套动作变成默认行为，省掉大量无谓的扯皮。

包括 code review 环节，我见过不少团队把“让 AI 按技能做审查”作为 PR 流水线里的一个固定步骤。人工 reviewer 可以站在更高层做决策，琐碎的代码规范检查交给技能去跑。效率和公平性都更好了。

5. 常见问题与排查技巧实录

5.1 技能没生效：先查索引，再查路径，最后查环境

“技能没生效”是我被问到最多的一个问题。现象很统一：装完插件，AI 还是老样子，直接给答案，不拆解、不追问。我建议按下面这个顺序排查。

第一步，在会话里问“你当前加载了哪些技能”，如果回答里根本没有 Superpowers 相关技能名，说明索引没注入，问题出在插件加载链路。这时候检查插件目录是否在 Claude Code 的识别范围内、目录名是否匹配、配置声明是否被读取。第二步，如果索引有，但 AI 不主动用，那就不是安装问题，是提示词引导问题。回到 CLAUDE.md，把你希望 AI 使用技能的场景明确写出来。第三步，检查版本兼容性。老版本 CLI 对插件目录的自动发现支持得不好，如果前两步都没问题，优先考虑升级 CLI 版本。

我整理了一个速查表，贴在这里方便你对照处理。

5.2 上下文窗口被技能占用：学会按需加载，别一股脑全开

还有一类问题是：技能文件比较多，AI 可能在会话初期就把它们全读进上下文，导致可用 token 变少，长任务跑到一半提示上下文不够。这种情况通常出现在技能库比较大的版本，或者你同时加载了多个插件。

解决思路很简单，让技能按需加载。也就是说，不要依赖系统一次性把所有技能说明都告诉 AI，而是通过 CLAUDE.md 提供一个“索引 + 触发条件”，AI 在真正遇到对应场景时再去读取技能文件细节。这需要插件设计上支持延迟加载，Superpowers 的 CRISP 格式本身就是为了支持这种模式设计的，但如果你的版本加载逻辑比较“粗暴”，还是会出现全量加载的情况。

实战中我会做减法：只保留当前项目会用到的几个技能目录，把不相关的技能暂时移出插件目录。比如纯后端项目，就不需要保留前端相关的技能文件，让 AI 的注意力更聚焦。

5.3 与代理、网络环境相关的加载问题

有朋友遇到过这种情况：插件装在本地，技能也能看到，但 AI 在读取远程技能仓库里的内容时非常慢，甚至超时。这通常是因为技能文件里引用了外部资源，比如某个模板地址、某个文档链接，AI 尝试访问时受限于网络环境。

我的处理办法是：所有外部引用一律改成本地路径。把技能文件里引用的模板、样例代码、参考文档全部下载到项目里，避免 AI 在干活的间隙去请求外部地址。这既保证了加载速度，也能减少不必要的隐私与安全问题。团队内部分享时，建议把整个技能库打进内网仓库，而不是依赖个人机器上的缓存。

顺便说一句，技能本身只是一堆 Markdown 和少量脚本代码，内容透明可审计。但在引入任何第三方技能包之前，还是建议你肉眼过一遍里面的内容，尤其是带有脚本或指令的部分。我自己一直保持这个习惯，安全底线不能放松。

5.4 自定义技能时的常见错误：格式、触发条件、迭代顺序

学会自定义之后，最常见的错误有三个。第一个是 YAML front matter 写错，比如漏了name或description字段，或者把allowed-tools写成了不存在的工具名，AI 读取时就会静默跳过。第二个是触发条件写得太笼统，比如只写“当需要写代码时”，几乎对所有编码场景都命中，技能就失去了“专注”的意义。第三个是步骤写得太抽象，没有给 AI 明确的下一步动作，比如写“分析问题”但没告诉它“从哪些维度分析、产出一个什么格式的结论”。

我的迭代顺序建议是：先写一个最小可行的 skill 文件，目标只解决一个非常具体的场景；在真实会话里试用一次，观察 AI 的输出是否符合预期；再根据实际表现调整步骤措辞和触发条件。不要一开始就追求大而全，否则你连是哪里出了问题都定位不到。

6. 自定义自己的 skills：不满足于内置技能时的升级路线

6.1 skill 文件该怎么组织：一个小型可用的最小结构

等你对内置技能跑熟之后，大概率会产生“我想让 AI 按我们团队的规范来做某件事”的需求。比如发布前检查清单、数据库变更评审流程、接口文档生成规范，这些都可以写成自己的 skill 文件。

最小结构其实很简单：一个 Markdown 文件，最上面是 YAML 格式的元信息，包含name、description、when_to_use这些字段；下面是正文，写执行步骤。以我写的一个“发布前自检”技能为例，大概是这个样子：

--- name: release-checklist description: 在准备发布前，按团队规范检查代码、配置、文档与回滚方案 when_to_use: 当用户提到“发布”“上线”“release”等关键词，且改动涉及服务端代码时 --- ## 执行步骤 1. 列出本次发布涉及的所有变更文件，按代码、配置、数据库脚本分类。 2. 检查数据库脚本是否存在不可逆操作，若有则确认是否已准备备份与回滚方案。 3. 检查配置中心条目与本地配置的 diff，确认没有遗漏新增配置项。 4. 检查监控面板与告警规则，确认关键指标已覆盖。 5. 输出发布清单，每个检查项标注“通过/不通过/需人工确认”。

这个技能不会像传统程序一样被“执行”，它更像是给 AI 看的一份标准作业流程。AI 会在合适的场景读取它，然后按照这个流程输出结果。你把它放在 skills 目录下，命名成和技能主题相关的名字，AI 就可以在需要时加载。

6.2 写技能最有价值的部分：把隐性规范显性化

写自定义技能的过程，同时也是梳理团队规范的过程。以前我们可能有一套“潜规则”，比如上线前必须跑迁移脚本的回滚测试、接口变更必须同步更新 Mock 数据等，这些规则散落在各个老同事的脑子里。把它们写成技能文件，等于把隐性知识变成了显性的、可复用的流程。

实操里有个技巧：不要试图在一个技能里塞太多内容。一个技能只解决一个场景，描述要具体到 AI 不会产生歧义。比如“检查配置”这种描述就太模糊，应该写成“打开 deploy/config/production.yml，与 staging 配置逐项对比，列出所有新增与变更项”。越具体，AI 的执行质量越高。

写完技能后一定要做本地验证。我通常的做法是新建一个临时项目，让 AI 全程只依赖我写的这个技能来推进任务，看它会不会读文件、按不按步骤走、最终产出是否让我满意。验证通过后，才把它提交到团队共享目录。

6.3 把自定义技能分享给团队：注意路径、权限与版本管理

自定义技能进入团队流程，需要注意几件事。第一，路径要统一。你们可以约定团队所有项目的.claude/plugins目录都指向同一个内网仓库路径，避免不同成员本地副本不一致。第二，内容要审查。技能文件里的脚本如非必要，尽量不要加，加了就要让懂的人逐行看过。第三，变更要走版本管理。技能文件更新后，最好在每个文件顶部维护一个version字段，并在更新说明里写明变更点。

这套做法跑顺之后，你会发现团队协作的“标准动作”越来越多，AI 的产出质量越来越可预期。与其反复在对话里纠正 AI 的行为，不如把这些“纠偏经验”沉淀成一份份技能文件，让每一次会话都站在同一个高质量起点上。

我自己实际用下来的最大体会是：Superpowers 这类工具的价值并不在于它让 AI 突然变得无所不能，而在于它让 AI 变得“有章法”。模型还是那个模型，但你给了它一套经过验证的做事的顺序和判据，它就能稳定地交付比“随手写”高一个质量档次的结果。如果你也想让手头的 AI 编程工具从“可用”变成“好用”，不妨从装一套技能库开始，再逐步沉淀出自己的技能包。