Superpowers技能包：给Claude Code打造结构化AI编程协作流程

1. 项目概述

1.1 Superpowers到底是什么

如果你已经在用 Claude Code、Cline 这类 AI 编程助手写代码，大概率会遇到同一个尴尬：AI 虽然很强，但是每次对话都像第一次认识你一样，毛手毛脚，没有章法。改个需求，它能给你把整个项目目录拆了重造；写个测试，它能写出三百个断言然后告诉你“我觉得我覆盖得很全面”；做代码审查，它倒是积极，但净找些拼写错误和“建议加个注释”之类的废话当成果。

Superpowers 就是为了治这个毛病出现的。

简单来说，它是 GitHub 上一个开源的技能包集合，专门给 Claude Code 这类编程助手增加一套结构化、可复用的“技能树”。安装之后，你可以在对话里明确地告诉 Claude：“使用 code-reviewer 技能审查这段代码”“用 master-planner 技能先做任务规划”，然后 Claude 就会调用对应的技能，按预设的流程、步骤、输出格式来工作。你拿到的就不再是“AI 的随性发挥”，而是一套相对稳定、可预期、有检查点的协作流程。

这个项目火起来不是没有原因的。它的核心是把大量真实开发场景中“老师傅才会做的事”固化成了一套可执行的技能文件——比如重构、代码审查、决策判断、TDD（测试驱动开发）、架构探索、任务拆解——然后让 Claude 照着做。等于说你给 AI 请了一群“特聘顾问”，按需点名干活。

适合谁？三类人最该看：被 AI 生成代码搞到血压高的个人开发者；想在团队里统一 AI 协作规范的技术负责人；以及刚接触 Claude Code 但想直接上手高级用法的新手。

1.2 它的核心使用场景

我把这几个月用下来的实际感受先放这儿：这个技能包最值钱的三个场景是——复杂任务拆解、代码审查、基于测试驱动的功能开发。

先说任务拆解。以前让 Claude 处理“帮我给这个模块加个离线缓存”这种需求，它通常会闷头开始写代码，写完才发现接口设计不合理，返工是家常便饭。用 master-planner 技能之后，它会先做上下文分析、列出影响面、拆出步骤、标注风险点、给出回滚计划——这些做完才会动手。第一次看到它输出这么完整的规划，我确实愣了一下：这不就是一个合格工程师该有的职业病吗。

代码审查就更实用了。code-reviewer 技能会按一套固定的审查清单去扫代码——设计缺陷、并发问题、边界条件、可测试性，而不是盯着代码风格挑毛病。有一回我故意丢了一段带明显并发 bug 的代码给它，它不只找出了竞态条件，还直接把触发时序画成了文本图，那个专业程度比我见过的不少同事都靠谱。

至于 TDD（测试驱动开发），tdd-guide 技能会严格按“先写失败测试→实现最小代码→验证通过→重构”的循环来推进。对习惯了“先实现再补测试”的人来说，这个技能会让你整个开发节奏脱胎换骨。

后面我会把安装方法、技能体系、实战拆解、踩坑总结全部展开来讲，保证你看完能直接上手。

2. 核心价值拆解：为什么这个技能包值得装

2.1 从“会说话的代码生成器”到“有章法的协作者”

要理解 Superpowers 的价值，得先理解 Claude Code 这类工具在默认状态下有多“没谱”。默认的 Claude 就像个天资极高但没受过正规训练的新人——你给它一个模糊任务，它能给你写出一大堆代码，看起来什么都干了，但仔细一查，命名混乱、边界没处理、扩展性为零。你要是有耐心一步步追问和纠正，它也能改好，但这个过程极其消耗精力，比你自己写还累。

Superpowers 做的事情本质上是把“好工程师的工作方式”标准化。它的每个技能文件里都写了非常具体的指令——比如“在开始重构之前，必须先列出所有受影响的调用点”“在写任何测试之前，必须先确认失败的断言是什么”“在给出方案之前，必须先列出至少两个备选并说明取舍”。这些指令约束了 AI 的行为模式，把它从“有话就说”变成“先想后说、按章办事”。

打个比方：默认 Claude 就像一个没做过餐饮的亲戚来帮你做年夜饭，热情很高，但切菜手法全凭感觉。装完 Superpowers 之后，相当于你给了他一本“米其林后厨手册”——什么时候备菜、什么时候热锅、什么火候起菜、出菜前怎么摆盘，全有固定流程。端上桌的菜不一定能拿三星，但至少不会翻车。

我自己实测下来，装了技能包之后，AI 在几个关键维度上的表现提升是肉眼可见的：

• 上下文意识：它会主动声明“我基于当前项目的哪些信息做出了这个判断”，而不是凭空发挥
• 风险前置：动手前先讲风险、先列影响面、先提回滚方案
• 输出稳定性：同一类任务，十次输出的一致性明显提高，不再是每次都要重新调教
• 可监督性：它的推理过程被拆成了明确的步骤，你能在它做每一步的时候及时纠偏

2.2 技术原理：技能包到底做了什么

很多第一次接触的朋友会好奇：这不就是一堆 Markdown 文件吗，凭什么能“改造” AI 行为？原理确实不复杂，但很聪明。

Superpowers 的核心机制依托于 Claude Code 的Agent Skills能力。简单来说，Claude 在对话中可以通过读取技能文件来获得“临时专业知识”。技能包利用这个机制，在项目里放了一套skills/目录，每个技能是一个或多个 Markdown 文件，里面包含：技能的职责边界、工作流程、操作步骤、输出格式、检查清单，甚至还有不允许做的事项。

当你在对话里明确说出某个技能名称时，Claude 会把对应的技能文件内容加载进上下文，然后严格按照指令执行。比如skills/code-reviewer.md里写明了“审查时必须从正确性、并发安全、错误处理、可扩展性四个维度进行，每发现一个问题必须标注严重级别并给出修复建议”，Claude 加载之后，审查质量会直接刷新一个档次。

这里有一个“为什么值得关注”的点：这个东西没有改变模型本身的推理能力，它改变的是输出的组织方式和思考路径。模型的能力上限就在那儿，但技能包能让它把能力用在正确的地方、按合适的顺序输出。这叫“外挂工程纪律”。

2.3 安装它需要什么基础条件

动手装之前，先确认几件事，免得装到一半发现环境不兼容，自己在那折腾半天。

第一，安装前提是有 Claude Code 或其他兼容 Agent Skills 机制的终端工具。Superpowers 部分功能需要较新的 Claude 模型版本，太老的模型不支持技能加载机制，装上也白装。

第二，对终端基本操作要熟练。整个安装过程没有可视化界面，全程命令行操作。你不会cd、不理解相对路径和绝对路径的区别，装起来会比较痛苦。这个门槛不高，但确实存在。

第三，最好对 Git 的基本用法有概念——你至少得知道git clone是在干什么。后续技能包要更新，也得靠 git pull 拉新版本。

如果你满足上面三个条件，那接下来按照我的操作步骤走，整个过程大概十分钟左右。我第一次装的时候慢一点，花了十五分钟，主要是在思考目录结构该怎么规划，这个我下面会专门讲。

3. 安装与引入：一步一步实操

3.1 获取技能包：克隆仓库

安装 Superpowers 的第一步，是把项目从 GitHub 克隆到本地。打开终端，进入你计划存放技能包的工作目录（我个人的习惯是放在~/skills/这个统一目录下，因为多个项目可以共用同一份技能文件，不用每个项目都复制一份）：

cd ~/skills git clone https://github.com/obra/superpowers.git

克隆完成后，检查一下目录结构：

cd superpowers ls -la

正常情况下你应该能看到skills/目录，里面是各种技能文件；可能还有superpowers/子目录用于存放主配置。确认没问题后，这个步骤就算完成。

注意：如果你所在网络环境访问 GitHub 不稳定，可以考虑使用可靠的镜像站点或适当调整网络方案后再操作，但这里不展开讨论网络层面的内容。

3.2 将技能包关联到项目

技能包下载到本地还不够，你需要让 Claude Code 知道去哪里找这些技能。Claude Code 加载技能的方式是在项目目录下通过配置文件来引用的。主流做法是编辑项目根目录下的CLAUDE.md文件（如果项目还没有这个文件，就手动新建一个）。

在CLAUDE.md里写入下面这段引用配置：

# 项目指南 ## Skills 引用 本项目使用 Superpowers 技能包。技能包位于 `~/skills/superpowers/skills/`。 当用户请求执行以下任务时，必须加载并使用对应技能： - 任务规划/拆解 → master-planner - 代码审查 → code-reviewer - 测试开发 → tdd-guide - 决策辅助 → decider - 其他技能请从技能目录中按需加载

这段配置的作用是：每次 Claude Code 在这个项目目录下启动时，它会读取CLAUDE.md，从而知道自己可以从哪个路径加载技能文件。配置务必写对路径，不然 Claude 找不到技能就会出现“技能不存在”的报错。

如果你的技能包放在其他位置，替换上面的路径即可。还有一点要提醒：技能包路径尽量不要带空格和中文，有些工具对路径的解析不够健壮，会让加载失败。

3.3 配置自动加载与验证

CLAUDE.md只是告诉 Claude“有这个技能、放哪了”，但具体要不要自动加载，取决于你的配置。如果你想省事，可以让 Claude 在每次会话启动时自动扫描技能目录并做索引，这样你就不需要手动“点名”了。在CLAUDE.md里增加一段：

## 技能加载 会话启动时，请扫描 `~/skills/superpowers/skills/` 目录，加载所有技能文件，并建立技能索引。后续对话中，当任务涉及相关领域时，自动选用对应技能执行。

配置完成后，重启 Claude Code 会话，输入一条简单的指令验证是否生效：

列出当前可用的技能名称，并简述每个技能的主要用途

如果配置成功，Claude 会给你列出一个技能清单，比如 code-reviewer、master-planner、tdd-guide、decider、visual-debugger、architecture-explorer 等等。看到这个清单，恭喜你，安装已经成功，接下来就是正经使用了。

4. 技能体系全盘点：有哪些干货能用

4.1 核心技能逐个拆解

装好之后，我建议你先别急着用，花十分钟把这个技能包里到底有哪些东西摸清楚。技能包内置了十几个技能，每个都有自己的适用场景。我挑几个重点的详细介绍，其他的简单过一遍。

master-planner（主规划师）——最常用的技能之一。当你面对一个复杂的开发任务时，直接说“用 master-planner 技能规划这个任务”，它会要求你先补充任务背景、目标、约束条件，然后输出：任务理解、影响面分析、实施步骤、风险清单、验收标准、回滚方案。实测下来，这一步能极大地减少“AI 闷头写崩了再返工”的概率。

code-reviewer（代码审查员）——专门做代码审查。它会按一套严肃的审查纪律来扫代码：先整体理解模块职责，再逐个检查正确性边界、并发问题、错误处理路径、资源释放、可扩展性设计。每发现一个问题，标注严重级别（Critical / Major / Minor），并给出具体修复建议。我试过投喂一段自己写的有 bug 的代码，它找到的 80% 的问题确实是真问题。

tdd-guide（测试驱动开发向导）——严格按 TDD 的红-绿-重构循环工作。它会要求你先写测试，确认测试确实失败（红），再写最小实现代码让测试通过（绿），然后做重构。这技能适合正在学习 TDD、或者想训练 AI 按 TDD 节奏写代码的人。需要提醒的是：使用这个技能之前，你最好对 TDD 的基本概念有所了解，否则 Claude 会从头“教育”你，那个过程有点煎熬。

decider（决策者）——当你面临方案取舍时使用。比如你纠结“这个功能是放前端算还是后端算”“用 PostgreSQL 还是 MongoDB”“该不该引入消息队列”，decider 会引导你把问题结构化拆解——列出关键决策因素、给每个因素权重、对比各选项的得分、最后给出带理由的结论。它不是替你拍板，是逼你把决策过程想清楚，实测对个人项目和技术选型很有帮助。

bias-detector（偏见检测器）——专门检查方案里的思维误区。比如是否过度工程化、是否被首因效应带偏、是否忽略了沉默成本。这技能适合在重大技术决策前先跑一遍，给方案“照个 CT”。

system-guide（系统思维引导）——当问题比较复杂、影响面超出单点时使用。它会要求你用系统思维的方式看问题：存量-流量、反馈循环、滞后效应、涌现行为。我一般在分析系统性能瓶颈或架构演进路径时会调用它。

kiss-protocol（保持简单协议）——督促你用最小可用方案解决问题。它的核心指令是“在提出任何方案前，必须先定义这个问题的最小解决路径”。对容易陷入“设计癖”的人来说，这个技能就是一剂清醒药。

visual-debugger（视觉调试器）——主要用于前端样式、布局和视觉问题的定位。你贴段 HTML/CSS，它会用文本形式描述渲染信息和层级关系，帮你定位样式问题。

architecture-explorer（架构探索者）——用于理解当前项目或代码库的架构。你告诉它项目概况，它会主动探索目录结构、模块依赖、数据流，然后输出架构地图、关键模块说明、扩展性风险。

4.2 技能之间的组合用法

技能不缺，更重要的是会组合。我实际用下来，最顺手的几个组合套路分享给你：

规划 + 决策 + 审查的三步走。接到复杂需求，先用 master-planner 做整体规划，发现关键节点上有多个技术方案时调用 decider 做取舍，方案定下来之后在实施过程中用 code-reviewer 做阶段性质检。这一套组合能覆盖大部分需求的完整生命周期。

TDD + 审查的闭环开发。写新功能模块时，用 tdd-guide 从测试开始推着走，实现完成后立刻用 code-reviewer 对测试质量和实现质量做一轮审查。你会发现 AI 自己审查自己写出来的代码时，还挺能挑错的——因为它换了一个技能模式，思考路径完全不同。

系统思维 + 审查的性能专项。遇到性能优化的课题，先用 system-guide 构建对整体运行机制的理解，再用 code-reviewer 聚焦热点代码做精细化审查，最后用 decider 来决定优化方案。这套组合在处理棘手的性能问题时出奇地稳。

技能包的价值不在于某一个技能多强，而在于它让你跟 AI 的协作有了一整套“工作流”，什么时候该用哪个技能、什么环节该检查什么，都变成了明确的约定，而不是每次新手见面的猜谜游戏。

5. 一个完整实战：从需求到验收的全流程

5.1 任务背景与我设定的目标

为了让你对使用流程有体感，我拿一个自己最近做的真实模块举例——给一个内容管理系统的文章模块新增“定时发布”功能。需求不复杂：用户可以指定一个未来时间，系统到点自动把草稿状态的文章变为已发布。

这个任务按正常开发估计要一天左右，我刻意用 Superpowers 的流程来走一遍，看看 AI 协作模式下能压缩到什么程度。我给自己设的目标是：代码能跑、测试能过、代码质量过得去、整个流程有记录。

5.2 用 master-planner 完成任务规划

会话开始，我输入：

用 master-planner 技能来规划这个任务：文章模块新增定时发布功能，用户可以指定未来时间自动发布草稿。请先做完整的规划。

Claude 加载 master-planner 技能后，没有直接丢实现方案，而是先向我确认了几个问题：定时发布是“到点自动触发”还是“允许用户取消”？定时任务在服务端用什么调度机制？失败重试策略是什么？我把需求细化之后告诉它，它给出了一份规划：

• 影响面分析：涉及文章表结构（新增 scheduled_publish_at 字段）、文章状态机（草稿→定时中→已发布）、后台任务调度器、文章列表页展示
• 实施步骤：分四步——第一步改数据库表结构；第二步改文章状态逻辑；第三步写定时任务处理器；第四步改管理后台上传/编辑逻辑
• 风险清单：时区问题（用户输入的时间是本地时间还是 UTC）、定时任务的精度、任务失败后的状态恢复
• 验收标准：草稿文章可设置定时发布、到点自动转为已发布、列表页有状态标识、失败任务有日志

看到这份规划，我是比较满意的。它把时区问题和失败恢复都列出来了，这些恰恰是定时发布功能里最容易翻车的两个点。这个环节，充分体现了技能包把 AI 从“写码工”变成“工程师”的核心价值。

5.3 用 tdd-guide 驱动功能实现

规划确认后，我让 Claude 进入实现环节，这次点名用 tdd-guide 技能：

用 tdd-guide 技能来实现定时发布的后端逻辑。先写测试，再写实现。

tdd-guide 技能会严格指挥节奏：先写失败测试→运行确认失败→写最小实现→运行确认通过→重构。实际执行下来，AI 写了三组测试：文章可设置定时发布时间；未到时间状态保持“草稿”且查询接口不返回；时间到达后状态自动转为“已发布”。每组测试都先跑一遍红了再加实现，节奏把握得很好。中途我注意到它的实现里对时区处理用了timezone.utc，主动问了一句“为什么不用本地时间”，它引用技能里的检查清单回答说：定时任务服务器通常部署在 UTC 环境，所有持久化时间统一用 UTC，前端展示再转换。这个回答在点上，说明技能里固化的最佳实践真的被模型执行了。

5.4 用 code-reviewer 做阶段质检

实现完成后，我没有立刻收工，而是让 Claude 用 code-reviewer 技能对刚才的代码做一轮彻底审查：

用 code-reviewer 技能审查刚才写好的定时发布功能代码。重点检查并发安全、时区处理、失败恢复。

审查结果让我挺意外——它抓到了三个我自己没注意到的问题。第一，定时任务扫描文章中，在 SQL 查询里对scheduled_publish_at做时间判断时，没有索引，文章量大了之后会全表扫描；第二，如果服务器在任务执行中途宕机，已置为“发布中”状态但未真正发布的文章会卡死；第三，请求取消定时发布时，数据库更新和任务队列移除操作不在一个事务里，可能造成状态不一致。

这些问题的级别被 code-reviewer 标为 Major 和 Critical，它给的修复建议也都对路。在这个环节，我强烈感受到技能包的价值——如果不开这个技能，AI 自己是不会主动回头审视这些边角问题的。

5.5 用 decider 敲定失败恢复方案

关于失败恢复，我在 review 阶段发现了一个方案分歧：失败任务的恢复，是用“状态机回滚”还是“任务调度器补偿”。我让 Claude 用 decider 技能帮我做决策。

decider 带我走了一遍完整决策流程：列出决策因素——实现复杂度、数据一致性、运维可观测性、故障恢复时间；给权重——数据一致性最高、复杂度其次；对比方案——状态机回滚实现简单但一致性弱，调度器补偿实现复杂但能在秒级恢复且一致性强；最终结论是调度器补偿方案更优，但建议分阶段实施——第一版先做状态机回滚加失败日志，后续迭代再做真正的补偿调度。这个结论理性且务实，决策过程也完全透明。整个任务从规划到实现到审查到决策，全程大概花了一个半小时，放到正常开发节奏里，这个速度是比较可观的。

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

6.1 安装与加载阶段的坑

装技能包的过程中，最容易踩的坑是路径问题。我统计了一下自己和其他使用者的反馈，90% 的首次安装失败都出在技能路径没写对上。典型场景是：技能包放在~/skills/superpowers/skills/，但CLAUDE.md里写成了~/superpowers/skills/或者相对路径写错了。症状是：调用技能时 Claude 提示“未找到该技能”或“技能文件不存在”。

排查方法很简单，先手动确认路径有没有问题：

ls ~/skills/superpowers/skills/

如果能看到master-planner.md、code-reviewer.md这些文件，说明路径没错；如果ls都报错，那配置文件里大概率也是错的。还有一种情况是技能包放在项目目录内部了（比如/项目名/superpowers/skills/），这时候CLAUDE.md里应该写相对路径，但我实测下来，绝对路径的加载成功率更高，因为相对路径在不同启动方式下会有偏差。

另一个高频问题：自定义技能文件放不进技能列表。原因是 Claude Code 对技能文件的命名和目录层级有要求——每个技能必须单独成目录，目录内必须有SKILL.md文件，文件名不能有空格和特殊字符。如果你把一堆技能文件平铺在目录下，Claude 是识别不了的。

6.2 使用过程中的翻车现场

第一个翻车现场是技能冲突。有次我同时让 Claude 处理一个重构任务，又要求它严格遵守 TDD 流程，结果 Claude 在“先写测试”和“重构现有代码”之间产生了逻辑打结——它不确定該先做哪个。后来我在指令里明确了优先级：重构任务用 code-reviewer 做前置分析，TDD 只约束新代码部分，冲突立刻消失。经验是：多个技能同时使用时，一定要写清楚它们的边界和调用顺序。

第二个翻车现场是上下文超载。技能文件本身写得很详细，同时加载十几个技能后，上下文窗口会被大量技能文本占满，留给实际代码的空间变小，模型容易“忘掉”你最早给的需求。实测下来，10 个技能同时常驻会让 200K 上下文的可用空间减少约四分之一。解决办法：只在CLAUDE.md里写最常用的三到五个技能，其他技能临时用临时点名。

第三个坑是技能被过度执行。有些时候你只是随口问一句“这段代码你觉得怎么样”，Claude 如果默认加载了 code-reviewer，就会输出一大篇正式审查报告。解决方法是给技能设定激活条件——在CLAUDE.md里写清楚，“只有在用户明确要求审查时才使用 code-reviewer”。

6.3 常见问题速查表

这张表是我自己踩过的坑浓缩出来的，贴在这儿给后来人当个速查手册。实际遇到问题的时候，先对着表排查一遍，绝大多数都能解决。

7. 几个独家心得与调优建议

7.1 根据自己的工作流裁剪技能包

Superpowers 自带的技能很全，但全不等于适合你。我建议拿到包之后，先把你自己的日常工作流列一遍，然后从技能包中挑选真正匹配的，做个“最小技能集”。

以我自己为例，我做独立开发，日常工作是写后端接口、做数据库设计、偶尔改前端样式。我最终保留的常驻技能只有五个：master-planner（规划）、code-reviewer（审查）、tdd-guide（开发）、decider（决策）、visual-debugger（样式排查）。剩下的技能我全部从常驻列表移除了，要用的时候手动点名。这个操作让我和 Claude 的协作效率明显上升——上下文被技能占用的比例降低，Claude 在对话中的“记忆”更准确了。

7.2 把技能包和你的项目沉淀结合

技能包是通用工具，但你的项目有特定的规范、偏好和约定。一个提升巨大的做法是把这些项目特有的规范追加到技能包里，形成“专属增强版”。

比如我的项目里有一条约定：错误信息必须用统一格式、必须关联错误码。我把这条写进了code-reviewer.md的检查清单里，每次审查时 Claude 就会格外留意错误处理代码是否符合这个规范。再用一段时间，你甚至可以为项目写一个专属技能，比如“本项目的接口设计规范审查”，每次出接口设计时自动跑一遍，效果非常稳定。

7.3 后续可以怎么扩展

Superpowers 的潜力远不止 Claude Code 这一个场景。我最近在实验的是把这套技能文件用在自己的笔记系统和文档体系里——因为技能的本质就是“标准作业流程”，你完全可以把写作任务、审核任务、数据分析任务都用同样的格式固化下来。比如我给自己的技术博客写了一个“writer-skill”，内容是文章选题、结构、引入、代码示例、配图建议的检查清单，写文章时让 Claude 按这个流程来，输出质量稳定很多。

也就是说，学完这个技能包的安装和使用之后，你带走的不只是一套工具，更是一个可以复用到任何领域的“流程思维”：把好的做事方法标准化、文件化、可执行化。这个东西比工具本身值钱得多。

根据我个人试用的体会，Superpowers 目前已经是 AI 辅助开发这个方向上最值得推荐的技能体系之一。如果你还在“AI 生成代码但返工严重”的阶段挣扎，装好它、用好它，把 AI 当新员工来带而不是当搜索引擎来用，你的产出速度和代码质量，都会有一个非常实在的提升。