Superpowers 实战：用 Skill 体系让 AI 编程从碰运气走向可复现

1. 为什么“能跑通”和“能交付”之间隔着一道鸿沟

写代码这件事，最近两年最大的变化不是某个语言出了新版本，而是写代码的人旁边多了一个随时待命的助手。Claude Code、各类 AI 编程工具轮番上阵，补全、生成、重构、写测试，几乎什么都能干。但真正把 AI 编程用在正经项目里的人都会有一个共同感受：它快得惊人，也飘得惊人。同一个需求问两遍，出来的代码结构可能完全不同；让它改一个函数，它顺手把你没让它动的三个文件也改了；跑测试的时候信誓旦旦说“已通过”，结果你手动一跑，红的。

这个问题的本质，不是模型不够聪明，而是缺少一套约束机制。模型的能力是概率性的，它每次都在“猜”你想要什么，猜对了就是惊喜，猜错了就是事故。而 Superpowers 这套东西要解决的，恰恰就是这个“猜”的问题——它把 AI 编程从“碰运气”拉向“可复现”。

我最初接触 Superpowers 的时候，第一反应是“又一个包装层”。但用下来发现，它的定位其实很清晰：它不是模型，也不是 IDE，而是一套给 AI 编程助手用的技能（Skill）体系。你可以把它理解成给 AI 装了一本“作业规范手册”——什么任务该走什么流程、每一步该产出什么、什么情况下必须停下来问人，全都写死在 Skill 里。这样一来，AI 的行为就从“自由发挥”变成了“按章办事”。

这篇文章适合三类人看：一是已经在用 Claude Code 或类似工具、但被它的不稳定性折磨过的开发者；二是想把 AI 编程引入团队、但担心代码质量失控的技术负责人；三是单纯好奇“Skill 到底是什么、值不值得折腾”的观望者。我会从 Skill 的底层逻辑讲起，把安装、配置、核心 Skill 的用法、踩坑经验、以及怎么把它接进真实项目流程，一层层拆开说。不吹不黑，讲清楚它到底解决了什么问题，以及它解决不了什么问题。

2. Skill 到底是什么：把“提示词”升级成“可执行规范”

2.1 从提示词到 Skill 的认知跃迁

大部分人用 AI 编程的方式，是在对话框里敲一段提示词，然后等结果。提示词写得好，结果就好一点；写得随意，结果就随缘。这种方式的问题在于，提示词是一次性的、不可复用的、无法版本管理的。你今天写了一段很精妙的提示词让 AI 做代码审查，明天换个项目，这段提示词就找不到了，或者环境变了就不适用了。

Skill 的思路完全不同。它把“怎么做一件事”固化成一个结构化的文件，里面包含触发条件、执行步骤、检查清单、输出格式。你可以把它提交到 Git 仓库里，可以 review，可以迭代。提示词是口头交代，Skill 是书面 SOP。这个区别听起来简单，但它带来的行为差异是巨大的。

举个具体的例子。你让 AI “帮我审查这段代码”，它可能给你一堆泛泛而谈的建议：“建议增加错误处理”“可以考虑提取公共方法”。但如果你用的是 Superpowers 里的代码审查 Skill，它会按照预设的检查维度逐项过：边界条件、并发安全、资源释放、命名一致性、测试覆盖。每一项都有明确的判断标准，输出也是结构化的。这就是“规范”和“建议”的区别。

2.2 Skill 的文件结构与加载机制

一个 Skill 本质上就是一个目录，里面通常包含一个主描述文件（一般是 Markdown 格式）和若干辅助资源。主描述文件里会写清楚这个 Skill 叫什么、什么时候触发、执行流程是什么、有哪些注意事项。辅助资源可能是模板文件、检查清单、示例代码。

加载机制上，Claude Code 这类工具会在启动时扫描指定的 Skill 目录，把可用的 Skill 注册进来。当你的对话内容匹配到某个 Skill 的触发条件时，它就会自动加载对应的规范来约束自己的行为。这个过程对用户是透明的——你不需要手动“调用”某个 Skill，只要你的需求落在它的覆盖范围内，它就会生效。

这里有个容易被忽略的细节：Skill 的触发是靠语义匹配的，不是靠关键词精确匹配。这意味着你写 Skill 描述的时候，触发条件的措辞会直接影响它能不能被正确激活。写得太窄，很多该触发的时候不触发；写得太宽，不该触发的时候乱触发。这个度需要根据实际使用情况反复调。

2.3 为什么“约束”反而提升了效率

直觉上，给 AI 加约束应该会让它变慢。但实际用下来恰恰相反。原因在于，AI 编程最大的时间浪费不是生成代码，而是返工。它生成得快，你发现不对，重新描述需求，它再生成，你再发现不对……这个循环才是真正吃时间的。

Skill 通过提前锁定流程，把返工消灭在源头。比如一个“新功能开发”的 Skill 会强制要求：先确认需求边界，再写接口定义，再写实现，最后写测试。每一步都有产出物，每一步都可以被检查。看起来步骤多了，但因为每一步都是对的，整体反而更快。这就像装修房子，先出图纸再施工，比边砌墙边改设计要快得多。

3. 安装与配置：那些文档里不会写的细节

3.1 环境准备的真实门槛

Superpowers 的安装本身不复杂，但它对运行环境有要求。你需要一个支持 Skill 机制的 AI 编程工具作为宿主，目前主流的是 Claude Code。安装 Claude Code 的方式根据操作系统不同有差异，Windows、macOS、Linux 各有各的路径。这里不展开具体命令，重点说几个实际安装时容易卡住的地方。

第一个坑是权限问题。Skill 目录通常需要工具本身有读写权限，如果你把它放在系统保护目录下，加载会静默失败——不报错，但 Skill 就是不生效。建议放在用户目录下的专用文件夹里，路径里不要有中文和空格。

第二个坑是版本兼容。Skill 机制本身在迭代，不同版本的宿主工具对 Skill 文件格式的支持程度不一样。如果你从别人那里拷来一个 Skill 用不了，先别怀疑 Skill 写错了，大概率是版本对不上。养成习惯：拿到一个 Skill，先看它的说明里有没有标注适配的宿主版本。

第三个坑是网络环境。有些 Skill 在执行过程中需要访问外部资源，如果你的环境访问不了，Skill 会在某一步卡住。这种情况下的表现往往是“执行到一半没反应了”，而不是明确报错。排查的时候要有意识地去想“这一步是不是需要联网”。

3.2 目录组织与命名约定

Skill 放多了之后，目录组织就变成一个真问题。我的建议是按功能域分目录，而不是按来源分。比如：

skills/ code-review/ testing/ refactor/ docs/ project-setup/

每个目录下放对应的 Skill。这样找起来快，也方便你按需启用或禁用某一类。命名上，用动词开头、小写、连字符分隔，比如review-pull-request、generate-unit-test。别用中文名，别用驼峰，别用空格——这些在跨平台和脚本调用时都会出问题。

还有一个经验：给每个 Skill 写一个 README。哪怕只有三行，写清楚它干什么、什么时候用、有什么前提条件。三个月后你自己回来看，没有 README 的 Skill 你根本不敢用。

3.3 验证 Skill 是否真正生效

装完之后怎么确认它真的在工作？最直接的办法是故意触发一次。找一个明确落在某个 Skill 覆盖范围内的任务，比如让 AI 做一次代码审查，然后观察它的输出格式。如果输出是结构化的、有明确检查维度的，说明 Skill 生效了；如果还是那种泛泛而谈的风格，说明没生效。

没生效的排查顺序：先看目录路径对不对，再看文件格式是否符合规范，然后看宿主工具的日志里有没有加载记录。这三步能解决八成问题。剩下两成，通常是 Skill 描述里的触发条件写得太模糊，导致语义匹配没命中。

提示：不要一次性装几十个 Skill。装太多会导致触发冲突——同一个需求可能同时匹配到多个 Skill，行为就不可预测了。建议按项目需要，一次启用五到八个，用完再换。

4. 核心 Skill 拆解：代码审查、测试生成与重构

4.1 代码审查 Skill：把“感觉不对”变成“逐项核对”

代码审查是 Superpowers 里价值最高的 Skill 之一。人工审查代码的问题在于，注意力是有限的、标准是不统一的。同一个人上午审和下午审，严格程度可能都不一样。AI 审查如果不受约束，问题更大——它会漏掉关键问题，却对无关紧要的风格问题喋喋不休。

一个设计良好的代码审查 Skill，会把审查拆成几个固定维度，每个维度有明确的检查项。常见的维度包括：

这个表格本身就是 Skill 的一部分。AI 拿到它之后，会逐项过一遍，而不是凭感觉给建议。实测下来，这种结构化审查能抓出的人工遗漏率明显更低，尤其是在边界条件和资源管理这两块。

但要注意，代码审查 Skill 不能替代人的判断。它能告诉你“这里可能有问题”，但“这个问题在这个业务场景下是否真的严重”，还是得人来定。我的用法是：让 Skill 做第一遍扫描，把可疑点列出来，然后我针对性地看。这样比我自己从头读一遍快得多，也比让 AI 自由发挥靠谱得多。

4.2 测试生成 Skill：从“补测试”到“按契约写测试”

测试生成是另一个高频场景。大部分人让 AI 写测试的方式是“给这个函数写个测试”，结果出来的测试往往只覆盖了正常路径，边界和异常路径基本没有。这不是 AI 偷懒，而是它不知道你的测试标准是什么。

测试生成 Skill 的核心价值在于定义“什么算一个合格的测试”。一个典型的测试 Skill 会要求：

• 每个公开方法至少覆盖正常路径、边界路径、异常路径三类用例
• 测试命名要能反映被测行为和预期结果
• 断言要具体，不能只断言“不抛异常”
• Mock 的范围要最小化，能不用就不用

有了这些约束，AI 生成的测试质量会稳定很多。我自己的习惯是，在 Skill 里再加一条：生成的测试必须先跑一遍，确认能通过再交付。这一条能过滤掉大量“看起来对但跑不起来”的测试代码。

这里有个实操心得：测试 Skill 最好和你的测试框架绑定。不同框架的断言风格、Mock 方式、异步处理都不一样。如果你的项目用 Jest，Skill 里就写 Jest 的规范；用 pytest，就写 pytest 的。通用型的测试 Skill 看起来适用范围广，实际用起来哪哪都不顺手。

4.3 重构 Skill：小步走，每步都可回退

重构是最容易出事的场景。AI 重构的典型问题是步子太大——它可能一次性改十几个文件，你根本 review 不过来，出了问题也不知道是哪一步引入的。

重构 Skill 的设计原则应该是强制小步提交。具体来说，Skill 会要求：

1. 每次只重构一个逻辑单元
2. 重构前后必须能通过同一套测试
3. 如果测试覆盖不足，先补测试再重构
4. 每一步的改动范围要明确列出

这套约束看起来繁琐，但它把重构从“高风险操作”变成了“可控的渐进过程”。我踩过的最大的坑，就是让 AI 一次性重构一个模块，结果它把某个方法的语义悄悄改了，测试没覆盖到，上线后才发现。从那以后，我用的重构 Skill 里第一条就是“禁止跨文件批量修改，除非明确授权”。

5. 把 Skill 接进真实项目流程的几种姿势

5.1 个人开发者的轻量用法

如果你是一个人写项目，Skill 的用法可以很轻。我的建议是只装三个：代码审查、测试生成、提交信息规范。这三个覆盖了日常最高频的场景，而且互相不冲突。

工作流大概是这样：写完一个功能，先让审查 Skill 过一遍，把明显问题修掉；然后让测试 Skill 补测试；最后提交的时候，提交信息 Skill 会帮你把 commit message 写规范。整个过程你还是在主导，Skill 只是在你容易疏忽的地方兜底。

这种用法的好处是心智负担低。你不需要记住每个 Skill 的细节，只需要知道“写完代码之后走这三步”。习惯养成之后，代码质量的底线就被抬高了。

5.2 团队协作中的 Skill 共享

团队用 Skill，核心问题是标准统一。如果每个人用的 Skill 不一样，那 AI 产出的代码风格就会五花八门，review 的时候又是一场灾难。

正确的做法是：把 Skill 纳入版本管理，作为项目规范的一部分。新成员入职，拉下代码的同时也拉下 Skill 目录，配置好之后，AI 的行为就和团队标准对齐了。这比写一堆文档然后指望大家去看要有效得多——文档没人看，但 Skill 是 AI 强制执行。

团队场景下，Skill 的迭代也要走 review 流程。谁想改审查标准，提 PR，大家讨论，合并。这样 Skill 本身的质量也有保障。我见过一些团队，Skill 目录比业务代码还乱，那还不如不用。

5.3 和 CI/CD 的结合点

Skill 能不能接进 CI/CD？可以，但要分清边界。Skill 负责的是“生成阶段”的约束，CI 负责的是“验证阶段”的把关。两者是互补的，不是替代关系。

具体来说，你可以在 CI 里加一步：检查本次提交的代码是否经过了审查 Skill 的处理（比如检查有没有审查报告文件）。但这只是形式上的检查，真正的质量还是靠 Skill 在生成阶段就约束住。指望 CI 去抓 AI 生成代码的所有问题，不现实——CI 跑的是测试和静态检查，它抓不到“逻辑写错了但测试也写错了”这种情况。

6. 踩坑实录：Skill 不生效、乱触发、输出跑偏怎么排查

6.1 Skill 装了但没反应

这是最高频的问题。表现是：你明明装了某个 Skill，但 AI 的行为和没装一样。排查链路应该是这样的：

第一步，确认文件被加载了。看宿主工具的启动日志，或者用一个明确的测试任务去触发，观察有没有 Skill 相关的输出。如果日志里根本没有加载记录，那就是路径或权限问题。

第二步，确认触发条件匹配。Skill 的触发是靠语义匹配的，如果你的需求描述和 Skill 里写的触发条件措辞差异太大，可能就匹配不上。解决办法是在 Skill 的触发条件里多写几个同义表述，覆盖不同的说法。

第三步，确认没有冲突。如果同时有多个 Skill 匹配到了同一个需求，宿主工具可能会选择一个或者干脆都不选。这时候要检查 Skill 之间的覆盖范围有没有重叠，有的话要收窄。

6.2 Skill 乱触发导致行为异常

和上一个问题相反，这个是有时候不该触发的时候触发了。典型表现是：你只是想让 AI 改个错别字，结果它启动了一整套代码审查流程，输出一大堆你不需要的东西。

这个问题的根源通常是触发条件写得太宽。比如一个代码审查 Skill，如果触发条件只写“涉及代码”，那基本上任何和代码相关的对话都会触发它。正确的写法应该是加上限定，比如“当用户明确要求审查、检查、review 代码时触发”。

调整触发条件是个反复试的过程。我的经验是，宁可写窄一点，用的时候手动触发，也不要写太宽导致到处乱触发。手动触发虽然多一步，但行为可预测。

6.3 输出格式不符合预期

有时候 Skill 确实触发了，但输出格式和你想要的不一样。这通常是 Skill 描述里的输出模板写得不够具体。比如你希望审查结果是一个表格，但 Skill 里只写了“列出问题”，那 AI 就可能用段落、用列表、用各种格式。

解决办法是在 Skill 里给出明确的输出示例。不要只描述“输出一个表格”，而是直接写一个 Markdown 表格的样例。AI 对示例的遵循程度远高于对描述的遵循程度。这个技巧在写所有 Skill 的时候都适用——示例比描述管用。

7. 关于 Skill 的边界：它解决什么，不解决什么

用了这么久，我对 Superpowers 这类 Skill 体系的定位越来越清晰。它解决的是流程规范化和行为可复现的问题。它让 AI 编程从“每次都是新的冒险”变成“每次都在已知轨道上运行”。这个价值是实打实的，尤其是在需要长期维护的项目里。

但它不解决判断力的问题。Skill 能告诉 AI“检查边界条件”，但“这个边界条件在这个业务里是否重要”，还是得人来判断。Skill 能生成测试，但“这个测试是否测到了真正重要的东西”，还是得人来 review。Skill 是放大器，不是替代品。你的工程判断力越强，Skill 帮你放大的效果越好；你的判断力越弱，Skill 也只是让你更快地产生一堆看起来规范但实际没用的东西。

还有一个现实问题：维护 Skill 本身是有成本的。写一个 Skill、调触发条件、迭代输出格式，这些都要花时间。如果你的项目是一次性的、用完就扔的，那投入产出比可能不划算。但如果是一个要维护半年以上的项目，那前期在 Skill 上的投入，后面会以“少返工、少救火”的形式加倍还回来。

我自己的做法是，从最小的 Skill 开始。先写一个代码审查的，用两周，觉得有价值再加测试生成的。不要一上来就搞一套大而全的体系，那样大概率会因为维护不过来而废弃。Skill 这东西，用起来的才有价值，躺在目录里的只是负担。

最后分享一个我踩过的坑：我曾经写了一个特别详细的 Skill，把某个模块的所有编码规范都塞进去了，结果 AI 每次触发都要处理一大堆上下文，响应变慢不说，还经常因为信息过载而抓不住重点。后来我把它拆成了三个小 Skill，每个只聚焦一个方面，效果反而好得多。Skill 的粒度，宁小勿大。