Superpowers 指南：用 Skill 机制让 Claude Code 从能跑变可靠

1. 为什么“能跑”和“可靠”之间隔着一整套工程习惯

我最早用 Claude Code 写代码的时候，心态跟大多数人一样：能自动补全、能生成函数、能跑通测试，就觉得已经赚到了。直到有一次，我让它在同一个项目里连续改了三个文件，结果它把上周刚修好的边界条件又改回去了，而且没有任何提示。那一刻我才意识到，AI 编程真正的问题从来不是“快不快”，而是“稳不稳”。

Superpowers 这套东西，本质上就是给 AI 编程加上一层工程约束。它不是某个单一工具，而是一组围绕 Claude Code 构建的 Skill 集合，核心目标只有一个：让 AI 在写代码的时候，像一个有经验的工程师那样思考，而不是像一个记忆力只有五分钟的实习生。

如果你现在还在用最原始的方式跟 Claude Code 对话——打开终端、输入需求、复制代码、手动粘贴——那这套指南就是写给你的。它适合三类人：第一类是完全没接触过 Claude Code 的新手，想从零搭一套能用的环境；第二类是已经在用但总觉得“差点意思”的中级用户，想让 AI 的输出更可控；第三类是在团队里推动 AI 编程规范的人，需要一套可复制、可审查的流程。

我下面要讲的东西，全部基于实际项目里的踩坑经验。有些配置看起来麻烦，但省下来的调试时间远超你的想象。

2. Superpowers 到底解决了什么问题

2.1 从“单次对话”到“持续协作”的转变

普通 AI 编程的模式是：你问一个问题，它给一个答案，然后对话结束。下次你再问，它已经忘了上次说过什么。这种模式在写小脚本的时候没问题，但一旦项目超过三个文件，就会开始出乱子。

Superpowers 的第一个核心优势，是把 AI 编程从“单次对话”变成了“持续协作”。它通过 Skill 机制，让 Claude Code 在每次执行任务之前，先读取一套预定义的规则和上下文。这套规则里包含了项目的代码风格、目录结构、命名约定、测试要求，甚至包括“哪些文件绝对不能动”。

我举个例子。在一个 React 项目里，我配置了一个 Skill，规定所有新组件必须放在src/components/下面，必须用 TypeScript，必须导出默认组件，必须写 PropTypes 或者 TypeScript 类型。配置完之后，我再让 Claude Code 生成组件，它就不会再把文件扔到根目录，也不会用 JavaScript 糊弄过去。

这个转变的意义在于：你不需要每次都在提示词里重复同样的要求。Skill 把那些“每次都要说”的东西固化下来了。

2.2 代码审查从“事后补救”变成“事前约束”

大多数人用 AI 写代码的流程是：生成、运行、报错、再生成、再运行。这个循环里，代码审查是缺失的。Superpowers 里有一个很关键的 Skill 类型，叫“代码审查 Skill”。它的作用是在 AI 生成代码之后、你手动运行之前，自动做一轮静态检查。

具体来说，它会检查这些东西：有没有硬编码的密钥、有没有未处理的 Promise rejection、有没有明显的性能问题（比如在循环里查数据库）、有没有违反项目约定的命名。如果发现问题，它会直接告诉你“这段代码有问题，原因是 XXX”，而不是等你运行到一半才崩。

我实测下来，这个环节能拦掉大概 60% 的低级错误。剩下的 40% 里，有一半是逻辑错误，需要你自己判断；另一半是环境问题，跟代码本身无关。

2.3 让 AI 记住“上次是怎么修的”

Superpowers 还有一个容易被忽略的优势：它会记录每次修改的上下文。比如你上周让 Claude Code 修了一个 bug，这周它又遇到类似的问题，它会优先参考上次的修复方案，而不是重新发明一遍。

这个机制在大型项目里特别有用。因为大型项目里很多 bug 是“似曾相识”的——同样的边界条件、同样的并发问题、同样的空指针。如果 AI 能记住上次是怎么处理的，你就不需要每次都重新解释一遍业务逻辑。

3. 环境搭建：从零开始配置一套能用的 Claude Code

3.1 安装 Claude Code 的三种方式

Claude Code 的安装方式取决于你的操作系统和使用习惯。我下面分别说 Windows、macOS 和 Ubuntu 的情况。

在 macOS 上，最省事的方式是用 Homebrew：

brew install claude-code

装完之后，直接在终端输入claude就能启动。如果你用的是 zsh，建议把claude加到 PATH 里，这样在任何目录下都能调用。

在 Ubuntu 上，官方推荐用 npm 安装：

npm install -g @anthropic-ai/claude-code

这里有个坑：如果你的 Node.js 版本低于 18，安装会失败。我建议先用node -v检查一下版本，如果太低，先用 nvm 升级：

nvm install 20 nvm use 20

在 Windows 上，情况稍微复杂一点。官方提供了桌面版，但如果你习惯用命令行，建议在 WSL2 里装 Ubuntu 版本。我试过直接在 PowerShell 里跑，偶尔会遇到路径分隔符的问题，WSL2 里就没这个毛病。

注意：安装过程中如果提示“your organization has disabled claude subscription access”，说明你的账号权限有问题，需要联系管理员开通，跟安装方式无关。

3.2 VS Code 配置：让 Claude Code 在编辑器里跑起来

如果你不想在终端和编辑器之间来回切换，可以把 Claude Code 集成到 VS Code 里。步骤不复杂：

1. 在 VS Code 里安装 “Claude Code for VS Code” 扩展。
2. 打开设置，搜索claude-code.path，填入 Claude Code 的可执行文件路径。
3. 重启 VS Code，在命令面板里输入Claude: Start Session，就能在侧边栏里跟 Claude Code 对话。

这个配置的好处是，Claude Code 能直接读取你当前打开的文件，不需要你手动复制粘贴。我平时写代码的时候，左边是编辑器，右边是 Claude Code 的对话窗口，改完直接看 diff，效率比纯终端高不少。

3.3 接入第三方模型：什么时候需要，怎么配

Claude Code 默认用的是 Anthropic 的模型。但有时候你可能想接入其他模型，比如 DeepSeek、Qwen 或者 GLM。这时候需要用到cc switch这个工具。

安装方式：

npm install -g cc-switch

装完之后，用cc switch命令切换模型。比如要接入 DeepSeek：

cc switch deepseek

然后按照提示填入 API Key 和 Base URL。这里有个细节：不同模型的上下文长度不一样，DeepSeek 的上下文窗口比 Claude 小，所以在处理大文件的时候，可能需要手动拆分。

提示：如果你在内网环境里部署，需要先把模型服务跑起来，然后把 Base URL 指向内网地址。这一步跟 Superpowers 本身没关系，但会影响 Skill 的加载速度。

4. Skill 机制深度拆解：从“提示词”到“可复用能力”

4.1 Skill 到底是什么，跟普通提示词有什么区别

很多人第一次听到 Skill 的时候，会把它理解成“高级提示词”。这个理解不算错，但不完整。普通提示词是一次性的，你这次说了，下次还得再说。Skill 是持久化的，它存在文件里，每次启动 Claude Code 的时候自动加载。

更关键的是，Skill 可以包含逻辑。它不只是一段文字，还可以包含条件判断、文件读取、甚至调用外部脚本。比如你可以写一个 Skill，规定“如果当前目录下有package.json，就读取里面的依赖列表，然后根据依赖版本推荐兼容的代码写法”。

我自己的项目里有一个 Skill，专门用来处理数据库迁移。它的逻辑是：先检查migrations/目录下最新的文件编号，然后生成下一个编号的迁移文件，最后在文件头部写入当前时间戳和操作人。这个流程如果每次都用提示词说，至少得写五行；写成 Skill 之后，一句话就能触发。

4.2 Skill 的目录结构和加载顺序

Claude Code 加载 Skill 的时候，会按照一定的顺序扫描目录。默认情况下，它会先读全局 Skill 目录，再读项目级 Skill 目录。全局目录一般在~/.claude/skills/，项目级目录在项目根目录的.claude/skills/。

这个顺序很重要。因为项目级 Skill 会覆盖全局 Skill。也就是说，你可以在全局配置一套通用的代码规范，然后在具体项目里覆盖掉某些规则。比如全局规定“所有函数必须写注释”，但某个老项目里注释已经太多了，你可以在项目级 Skill 里关掉这条规则。

每个 Skill 是一个独立的文件夹，里面至少包含一个skill.md文件。这个文件用 Markdown 格式写，头部可以加 YAML 元数据，用来描述 Skill 的名称、触发条件、优先级。

--- name: react-component-generator trigger: when user asks to create a new React component priority: high ---

下面才是具体的规则内容。我建议把规则写得尽量具体，不要写“代码要整洁”这种模糊的话，而要写“组件文件必须放在 src/components/ 下，文件名用 PascalCase，必须导出 default”。

4.3 怎么引入现成的 Skill

如果你不想从零写 Skill，可以直接引入社区里现成的。目前比较活跃的来源有几个：一个是 GitHub 上的superpowers-skills仓库，里面收集了上百个常用 Skill；另一个是book-to-skill项目，它能把技术书籍里的最佳实践自动转成 Skill。

引入方式很简单，把对应的文件夹复制到你的.claude/skills/目录下就行。但这里有个坑：不同 Skill 之间可能会冲突。比如两个 Skill 都规定了文件命名规则，一个说用 camelCase，一个说用 snake_case。这时候 Claude Code 会按照优先级决定用哪个，如果优先级相同，就用最后加载的那个。

我建议引入新 Skill 之后，先在一个小项目里测试一下，确认没有冲突再放到大项目里用。

5. 实操：从零搭建一套带代码审查的 AI 编程流程

5.1 第一步：初始化项目级 Skill 目录

假设你有一个新项目，目录结构是这样的：

my-project/ src/ tests/ package.json

首先在项目根目录下创建 Skill 目录：

mkdir -p .claude/skills

然后创建一个基础的代码规范 Skill：

touch .claude/skills/code-style.md

在code-style.md里写入以下内容：

--- name: project-code-style trigger: always priority: high --- - 所有 JavaScript 文件使用 ES Module 语法 - 函数名使用 camelCase，类名使用 PascalCase - 每个函数不超过 50 行 - 禁止使用 var，统一用 const 或 let - 异步操作必须用 try-catch 包裹

这个 Skill 会在每次对话开始时自动加载，确保 Claude Code 生成的代码符合项目规范。

5.2 第二步：配置代码审查 Skill

代码审查 Skill 稍微复杂一点，因为它需要在生成代码之后触发。我通常把它写成两个部分：一部分是检查规则，一部分是触发条件。

--- name: code-review trigger: after code generation priority: high --- 检查以下内容： 1. 是否有硬编码的 API Key 或密码 2. 是否有未处理的 Promise rejection 3. 是否有在循环里执行数据库查询 4. 是否有未使用的变量或导入 5. 是否有明显的 SQL 注入风险 如果发现问题，输出格式为： [问题类型] 文件:行号 - 问题描述 - 建议修复方式

配置完之后，每次 Claude Code 生成代码，都会自动跑一遍这个检查。我实测下来，这个环节能拦掉大部分低级错误。

5.3 第三步：测试 Skill 是否生效

配置完 Skill 之后，不要直接上大项目。先在一个测试文件里验证一下。比如让 Claude Code 生成一个简单的函数：

请生成一个函数，接收用户 ID，从数据库查询用户信息并返回。

如果 Skill 生效了，Claude Code 应该会输出类似这样的代码：

async function getUserById(userId) { try { const user = await db.query('SELECT * FROM users WHERE id = ?', [userId]); return user; } catch (error) { console.error('Failed to fetch user:', error); throw error; } }

注意看，它用了参数化查询（防止 SQL 注入），用了 try-catch（处理异步错误），而且没有硬编码任何密钥。如果它输出的是db.query(\SELECT * FROM users WHERE id = ${userId}`)`，说明 Skill 没生效，需要检查配置。

5.4 第四步：把 Skill 纳入版本控制

Skill 文件应该跟代码一起提交到 Git 仓库。这样团队里每个人拉下代码之后，都能用同一套规范。我通常会在.gitignore里排除掉个人配置，但保留.claude/skills/目录。

.claude/settings.local.json .claude/cache/

这样做的另一个好处是，当 Skill 需要更新的时候，可以通过 Pull Request 来审查。比如有人想加一条新规则，可以先提 PR，团队讨论之后再合并。

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

6.1 Skill 不生效的几种原因

这是最常见的问题。我整理了一个排查表：

我踩过最坑的一次是，Skill 文件里用了中文标点，导致 YAML 解析失败。后来养成习惯，所有 Skill 文件的元数据部分都用英文标点。

6.2 Claude Code 执行终端命令时的权限问题

Claude Code 有时候需要执行终端命令，比如npm install或者git status。默认情况下，它会先问你“是否允许执行”，你确认之后才会跑。如果你觉得每次确认太麻烦，可以在设置里开启自动执行。

但这里有个风险：如果 Skill 里包含恶意命令，自动执行就会直接跑。所以我建议只在可信的项目里开启自动执行，而且定期检查 Skill 文件的内容。

6.3 处理大文件时的上下文溢出

Claude Code 的上下文窗口是有限的。如果你让它处理一个几千行的文件，它可能会截断一部分内容。这时候有两个解决办法：一是把大文件拆成小文件，二是用 Skill 指定“只读取前 500 行”。

我通常的做法是，在 Skill 里加一条规则：“处理文件时，如果文件超过 1000 行，先读取文件头部和尾部的注释，了解大致结构，再决定是否读取全文。”

6.4 第三方模型接入后的兼容性问题

接入 DeepSeek 或者 Qwen 之后，你可能会发现某些 Skill 不生效了。原因是不同模型对提示词的解析方式不一样。Claude 对 YAML 元数据的支持比较好，但有些模型可能不认识。

解决办法是把 Skill 的元数据部分改成纯文本描述，比如把trigger: always改成This skill should always be applied。虽然不够优雅，但兼容性更好。

7. 我个人的一些使用心得

用了大半年 Superpowers 之后，我最大的感受是：它把 AI 编程从“碰运气”变成了“可预期”。以前我让 AI 写代码，心里没底，不知道它会不会突然抽风。现在有了 Skill 约束，至少代码风格和基本规范是稳定的。

另一个心得是，Skill 不要一次写太多。我一开始贪心，写了二十多条规则，结果 Claude Code 每次加载都要花好几秒，而且规则之间经常打架。后来我精简到八条核心规则，效率反而更高。

还有一点，Skill 需要定期维护。项目在变，规范也在变。我每个月会花半个小时 review 一下现有的 Skill，把过时的规则删掉，把新踩的坑加进去。这个习惯坚持下来，Skill 库就变成了团队的知识沉淀。

最后分享一个小技巧：如果你不确定某条规则该不该写成 Skill，先手动用提示词试几次。如果连续三次都需要说同样的话，那就值得写成 Skill。如果只是偶尔用一次，写在提示词里就够了。