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 Code3.1 安装 Claude Code 的三种方式Claude Code 的安装方式取决于你的操作系统和使用习惯。我下面分别说 Windows、macOS 和 Ubuntu 的情况。在 macOS 上最省事的方式是用 Homebrewbrew 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 里。步骤不复杂在 VS Code 里安装 “Claude Code for VS Code” 扩展。打开设置搜索claude-code.path填入 Claude Code 的可执行文件路径。重启 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命令切换模型。比如要接入 DeepSeekcc 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然后创建一个基础的代码规范 Skilltouch .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 完全没反应目录路径不对确认.claude/skills/在项目根目录下部分规则生效部分不生效规则之间有冲突检查优先级设置确保高优先级的 Skill 先加载重启后 Skill 丢失文件没保存或路径写错用ls -la .claude/skills/确认文件存在触发条件不匹配trigger 写得太窄把 trigger 改成always测试一下我踩过最坑的一次是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。如果只是偶尔用一次写在提示词里就够了。