1. 从“superpowers”这个热词说起：它到底是什么
最近一段时间，superpowers这个词在技术社区里出现的频率明显高了起来。很多人第一次看到它，会以为是某个新出的编程语言或者框架，其实不是。它本质上是一套面向 AI 编程助手的技能扩展体系，你可以把它理解成给 AI 助手装上一批“专业工具箱”，让它在处理具体任务时不再只会泛泛而谈，而是能按照一套经过验证的流程去干活。
我最初接触superpowers是因为团队里有人在讨论“怎么让 AI 助手写代码更靠谱”。当时大家的痛点很一致：直接让 AI 写一个功能，它往往能给出能跑的代码，但结构混乱、边界情况不考虑、测试也不写。后来有人提到了superpowers这套东西，说它把很多工程实践固化成了可复用的技能模块。我花了两天时间研究它的组织方式和使用逻辑，实测下来确实解决了不少问题。
这篇文章适合几类人看：一是已经在用 AI 编程助手、但觉得输出质量不稳定的开发者；二是想了解“技能（skills）”这种扩展机制到底怎么运作的技术爱好者；三是想给自己团队搭建一套 AI 辅助开发规范的技术负责人。我会从它的整体设计思路讲起，然后拆解核心技能模块，再给出完整的安装和引入步骤，最后分享我在实际使用中踩过的坑和总结出来的排查技巧。整篇内容基于我对这套体系的实操理解，涉及具体操作的地方都会给出可直接参考的方案。
需要提前说明的是，superpowers本身不是一个独立运行的软件，它依附于特定的 AI 编程助手环境。所以你在看后面的安装步骤时，要先确认自己用的助手是否支持这种技能扩展机制。如果不支持，那后面的内容可以当作了解设计思路来读，也能帮你判断未来要不要迁移到支持的环境。
2. 整体设计思路拆解：为什么要把技能拆成模块
2.1 核心问题：AI 助手的“通用性陷阱”
AI 编程助手有一个天然矛盾：它被训练成什么都能聊、什么都能写，但真正落到工程场景里，通用性反而成了负担。你让它写一个 HTTP 接口，它可能给你一个能跑但没有任何错误处理、没有参数校验、没有日志的版本。你让它改一个 bug，它可能顺手把周围代码也重构了，引入新的问题。
这个矛盾的根源在于，AI 助手没有一个明确的“当前任务应该遵循什么流程”的约束。它每次都在根据你的 prompt 即兴发挥，而 prompt 本身很难把所有工程规范都写进去。你不可能每次都说“请遵循分层架构、请写单元测试、请处理边界情况、请加日志”，那样 prompt 会长得没法维护。
superpowers的思路就是把这些约束从 prompt 里抽出来，变成独立的、可组合的技能模块。每个技能模块定义了一类任务的标准流程和检查清单。当 AI 助手识别到当前任务属于某个技能范畴时，就自动加载对应的流程来执行。这样既保证了输出质量的一致性，又不用每次都在 prompt 里重复写规范。
2.2 技能模块的粒度设计
我研究下来发现，superpowers的技能粒度设计得比较讲究。它不是按“语言”或“框架”来分，而是按工程活动来分。比如有专门负责“写测试”的技能、专门负责“代码审查”的技能、专门负责“调试”的技能、专门负责“重构”的技能。这种分法的好处是跨语言通用——不管你写 Python 还是 TypeScript，调试的流程逻辑是相似的。
另一个设计特点是技能之间可以串联。比如你先用“需求分析”技能把模糊需求拆成具体任务，再用“实现”技能写代码，最后用“审查”技能检查。每个技能的输出会成为下一个技能的输入，形成一条流水线。这比让 AI 一次性完成所有事情要可靠得多，因为每一步都有明确的输入输出边界，出了问题容易定位。
2.3 为什么这种设计比“大 prompt”更有效
我试过两种方式：一种是把所有规范写在一个超长 prompt 里，另一种是用superpowers的技能模块。实测下来，技能模块的方式在三个方面明显更好。
第一是可维护性。规范变了只需要改对应的技能文件，不用去翻几十个 prompt 模板。第二是可组合性。不同项目可以按需启用不同技能，比如一个脚本项目可能不需要“架构设计”技能，但一个大型服务就需要。第三是可解释性。当 AI 输出不符合预期时，你可以去看它加载了哪个技能、技能里定义了什么流程，从而判断是技能定义有问题还是 AI 执行有问题。大 prompt 方式下，你很难知道 AI 到底关注了哪部分指令。
提示：如果你现在还在用大 prompt 方式，建议先挑一个最常做的任务（比如写单元测试），把它抽成一个独立的技能文件试试。不用一次性全改，逐步迁移更容易看到效果。
3. 核心技能模块解析与实操要点
3.1 需求拆解类技能：把模糊描述变成可执行任务
这类技能解决的是“用户说了一句模糊的话，怎么变成具体开发任务”的问题。比如用户说“帮我加个登录功能”，这背后涉及路由、表单、校验、会话管理、错误提示等一系列子任务。需求拆解技能会引导 AI 按固定维度去提问和拆解，而不是直接开始写代码。
我在实际使用中发现，这类技能最关键的是提问清单。好的技能会定义一组必问问题，比如“认证方式是什么”“是否需要记住登录状态”“失败几次锁定”“密码强度要求”等。AI 会带着这些问题去和用户交互，把答案补全后再进入实现阶段。这比直接写代码然后反复改要高效得多。
实操要点：使用这类技能时，你要有耐心回答 AI 的提问。我见过有人嫌麻烦直接说“你看着办”，结果 AI 按默认假设做出来的东西和预期差很远。技能的价值就在于把隐含假设显式化，你配合得越好，输出越准。
3.2 代码实现类技能：约束输出结构和边界处理
代码实现类技能是使用频率最高的。它定义了一套代码组织规范，比如函数长度限制、错误处理模式、日志埋点位置、命名约定等。AI 在写代码时会参照这些规范，而不是自由发挥。
我对比过启用和未启用这类技能的输出差异。未启用时，AI 写的函数经常超过一百行，错误处理就是一句console.log，边界情况基本不考虑。启用后，函数会被拆成多个小函数，每个都有明确的职责，错误处理会区分可恢复和不可恢复，边界情况会有显式判断。代码量可能多了百分之二三十，但可维护性提升明显。
这里有个细节值得说：技能里通常会定义代码审查清单，AI 在写完后会自己对照清单检查一遍。我实测发现这个自检环节能拦下不少低级问题，比如忘记处理空值、忘记关闭资源、硬编码配置等。虽然不能完全替代人工审查，但能减少很多返工。
3.3 测试与调试类技能：让 AI 自己验证自己的输出
测试类技能要求 AI 在实现功能后必须写对应的测试，并且测试要覆盖正常路径、边界路径和异常路径。调试类技能则定义了一套排查流程：先复现、再定位、再假设验证、最后修复并加回归测试。
我特别喜欢调试类技能里的假设验证环节。传统调试时人容易凭直觉猜原因，然后改一处试一处。技能会强制 AI 先列出可能的根因假设，然后设计最小验证步骤去逐个排除。这个方法我在带新人的时候也经常强调，但人往往做不到，AI 反而能严格执行。
注意事项：测试类技能生成的测试用例质量参差不齐。我遇到过 AI 写的测试只断言了“函数被调用”，没有断言实际行为。所以启用技能后还是要抽查测试代码，必要时在技能定义里补充断言规范。
3.4 代码审查类技能：把 review 经验固化成检查项
代码审查类技能把常见的 review 关注点整理成了检查清单，比如安全漏洞、性能隐患、并发问题、资源泄漏、命名一致性等。AI 在审查时会逐项过一遍，并给出具体行号和修改建议。
我用这个技能审查过团队里一个老模块，它找出了三处潜在的资源未释放问题和一处并发写入风险。这些问题人工 review 时因为代码太长被忽略了。当然它也有误报，比如把一些有意的设计当成问题，但整体上作为第一道过滤网很有价值。
注意：代码审查技能不能替代人工审查，尤其是涉及业务逻辑正确性的部分。AI 不懂你的业务规则，它只能从通用工程角度检查。建议把 AI 审查放在人工审查之前，先过滤掉通用问题，让人专注于业务逻辑。
4. 完整安装与引入流程：从零到跑通
4.1 环境确认与前置检查
在安装之前，你需要确认三件事。第一，你用的 AI 编程助手是否支持外部技能文件加载。目前主流的一些助手通过配置文件或插件机制支持，具体要看官方文档。第二，你的项目目录结构是否允许放置技能文件。通常技能文件放在项目根目录下的特定文件夹里，比如.skills/或.assistant/skills/。第三，确认你的助手版本是否支持技能串联，老版本可能只支持单个技能加载。
我建议先在一个测试项目里跑通流程，不要直接在主项目上操作。因为技能文件加载后可能会影响助手的默认行为，万一配置有问题，在测试项目里排查成本更低。
4.2 获取技能文件的几种途径
获取superpowers技能文件通常有几种方式。一种是从社区维护的技能仓库里直接下载，这种方式最省事，但要注意版本兼容性。另一种是根据自己的需求手写技能文件，这种方式最灵活，但需要你清楚技能文件的格式规范。还有一种是基于现有技能修改，适合在通用技能基础上加入团队特定规范。
我个人的做法是：先从社区仓库拉一份基础技能集，跑通流程后，再根据团队情况逐步替换和补充。这样起步快，也不会一开始就陷入写技能文件的细节里。社区技能集通常覆盖了需求拆解、实现、测试、审查这几个核心环节，够用一阵子了。
4.3 技能文件的目录组织与加载配置
技能文件的目录组织直接影响加载效率。我推荐按“活动类型”分文件夹，比如skills/analysis/、skills/implementation/、skills/testing/、skills/review/。每个技能一个文件，文件名用动词开头，比如analyze-requirements.md、implement-feature.md、write-tests.md、review-code.md。
加载配置通常在助手的配置文件里，你需要指定技能目录路径和启用哪些技能。有些助手支持自动扫描目录，有些需要显式列出。我建议显式列出，这样你能清楚知道当前启用了哪些技能，排查问题时也方便。
# 示例配置，具体字段名以你使用的助手文档为准 skills: directory: ./.skills enabled: - analyze-requirements - implement-feature - write-tests - review-code auto_load: true4.4 验证技能是否生效的实操方法
配置完成后，怎么确认技能真的生效了？我的方法是设计一个对照测试。先在不启用技能的情况下让助手写一个简单功能，记录输出特征。然后启用技能，再让助手写同样的功能，对比输出差异。如果技能生效，你应该能看到输出结构更规范、边界处理更完整、测试用例更全面。
另一个验证方法是直接问助手“你当前加载了哪些技能”。有些助手会列出已加载的技能列表。如果列表和你的配置一致，说明加载成功。如果为空或缺少，就要检查配置路径和格式。
我踩过的一个坑是：技能文件里的格式标记写错了，导致助手加载了文件但解析失败，表现是技能列表里有名字但行为没变化。后来发现是文件头部的元数据字段少了一个冒号。所以配置完后一定要做行为验证，不能只看列表。
5. 常见问题与排查技巧实录
5.1 技能不生效的排查顺序
技能不生效是最常见的问题。我总结了一个排查顺序，按这个顺序走基本能定位到原因。
| 排查步骤 | 检查内容 | 常见问题 |
|---|---|---|
| 1 | 配置文件路径是否正确 | 相对路径基准目录搞错 |
| 2 | 技能文件格式是否合法 | 元数据字段缺失或拼写错误 |
| 3 | 助手版本是否支持 | 老版本不支持技能串联 |
| 4 | 技能是否被其他配置覆盖 | 多个配置文件冲突 |
| 5 | 任务类型是否匹配技能触发条件 | 技能只对特定任务生效 |
我遇到最多的是第二步，技能文件格式问题。尤其是从社区下载的技能文件，不同版本格式可能有差异。建议先用一个最简单的技能文件测试，确认格式没问题后再批量导入。
5.2 技能之间冲突怎么处理
当你启用多个技能时，可能会出现指令冲突。比如一个技能要求“函数不超过 50 行”，另一个技能要求“所有逻辑写在一个函数里”。这种冲突会导致助手行为不稳定。
处理方法是明确技能优先级。在配置文件里给技能设置优先级，高优先级的技能指令覆盖低优先级的。或者更彻底一点，把冲突的技能拆成互斥组，同一时间只启用一组。我在项目里把技能分成“开发阶段”和“审查阶段”两组，开发时启用实现和测试技能，审查时切换到审查技能，避免冲突。
5.3 技能输出质量不稳定的应对
即使启用了技能，输出质量也可能波动。我观察到的原因是助手对技能指令的遵循程度受任务复杂度影响。任务越复杂，助手越容易“忘记”技能里的约束。
应对方法有两个。一是把大任务拆小，每个小任务单独走技能流程。比如不要一次性让助手实现整个模块，而是按函数或按接口逐个实现。二是在 prompt 里显式提醒，比如“请严格按照当前加载的技能流程执行”。这个提醒看起来多余，但实测能提升遵循度。
5.4 技能文件的版本管理建议
技能文件应该纳入版本管理，和代码一起提交。因为技能定义直接影响 AI 的输出行为，相当于团队规范的一部分。我建议在技能文件头部加版本号和变更记录，方便追溯。当输出质量出现变化时，可以先检查技能文件最近有没有改动。
另外，不同项目可能需要不同的技能集。我通常会在项目根目录放一份技能配置，然后在团队共享仓库里维护一份基础技能集。项目配置引用基础技能集，再叠加项目特定技能。这样基础技能更新时，所有项目都能受益，同时项目特定需求也能满足。
6. 我个人的使用体会与后续扩展方向
用了一段时间superpowers之后，我最大的感受是它把“AI 辅助开发”从“碰运气”变成了“可预期”。以前让 AI 写代码，质量好坏很大程度取决于 prompt 写得好不好，而 prompt 质量又取决于当时的状态。现在有了技能模块，至少核心流程是稳定的，输出质量的下限被抬高了。
当然它也不是万能的。技能定义得再好，AI 对复杂业务逻辑的理解仍然有限。我的做法是把 AI 定位成“执行者”而不是“决策者”——流程和规范由技能定义，具体业务决策还是人来定。这样分工下来，效率提升明显，返工也少了很多。
后续我打算在两个方面继续扩展。一是把团队代码审查中反复出现的问题补充到审查技能里，让 AI 提前拦截。二是尝试把技能和 CI 流程结合，在提交代码时自动触发 AI 审查技能，作为人工审查前的预检。这两个方向都还在试验阶段，等跑通了再整理出来分享。
如果你刚开始接触superpowers，我的建议是不要贪多。先挑一个你最痛的点，比如测试写得少，就只启用测试技能，跑两周看看效果。有效果了再逐步加其他技能。一次性全启用反而容易因为配置复杂而放弃。技能体系的价值在于持续使用和迭代，不在于一次配齐。
