1. 从“superpowers”这个热词说起它到底是什么最近“superpowers”这个词在技术社区和效率工具圈子里被反复提起很多人第一次看到它是在某个开源项目的讨论区或者是在朋友转发的一条“我给我的编辑器装上了超能力”的动态里。简单来说superpowers 是一套面向 AI 辅助编程场景的能力扩展框架它本身不是一个独立软件而是挂载在现有 AI 编程工具比如 Claude Code、Cursor 这类支持插件或技能扩展的环境之上的一组“技能包”和“工作流规则”。你可以把它理解成给一个本来就很聪明的助手又配了一整套标准作业程序、检查清单和领域知识库让它在写代码、改 bug、做代码审查的时候不再凭感觉发挥而是按照资深工程师的套路来干活。它解决的问题非常具体AI 写代码快是快但经常不靠谱。你让它改一个函数它顺手把你三个无关文件也重构了你让它加个日志它给你引入了一个新依赖你让它修一个边界条件它把整个模块的逻辑都换了。这些问题的根源不是模型不够强而是缺少约束和流程。superpowers 的思路就是把这些约束和流程固化下来变成 AI 可以调用的“技能”让它在动手之前先想清楚、在动手之后自己检查一遍。适合谁来参考这篇文章如果你是那种已经在日常开发中重度使用 AI 编程工具、但总觉得“差点意思”的开发者这篇文章会帮你理清 superpowers 的设计逻辑和落地方法。如果你只是听说过这个词、还没实际用过那正好我会从安装配置讲到实际使用中的坑尽量把每一步都拆开说清楚。哪怕你用的是不同的编辑器或不同的 AI 助手这套思路本身也是可以迁移的。2. superpowers 的整体设计思路拆解2.1 为什么不是“再写一个更好的提示词”很多人第一次接触 superpowers 的时候会有一个疑问这不就是一套更长的提示词吗我直接把规则写在系统提示里不就行了这个问题我一开始也想过但实际用下来发现区别很大。提示词是“一次性”的而 superpowers 是“可组合、可复用、可版本管理”的。你把规则写在系统提示里它会一直占用上下文窗口而且不同任务需要的规则不一样你没法针对“代码审查”和“新功能开发”用两套完全不同的提示词除非你每次手动切换。superpowers 的做法是把能力拆成一个个独立的“技能文件”每个技能文件描述一个具体场景下的操作规范。比如有一个技能叫“写代码前先做需求澄清”有一个技能叫“修改代码后必须跑测试”还有一个技能叫“代码审查时按清单逐项检查”。当 AI 判断当前任务需要某个技能时它才会去加载对应的文件内容用完就释放。这样做的好处是上下文利用率高而且技能可以单独迭代——你今天觉得代码审查清单少了一条直接改那个文件就行不影响其他技能。提示如果你之前习惯把几百行规则一股脑塞进系统提示可以试试拆成技能文件的方式实测下来 AI 的遵循度会明显提升因为它每次只需要关注当前任务相关的那几条规则。2.2 核心机制技能发现与按需加载superpowers 最核心的机制我把它叫做“技能发现与按需加载”。具体来说它会在项目目录下维护一个技能库通常是一个文件夹结构每个技能是一个 Markdown 文件文件名就是技能名文件内容包含触发条件、操作步骤、检查清单和示例。AI 在接到任务后会先扫描技能库的索引判断哪些技能与当前任务相关然后只加载相关的技能文件。这个机制的关键在于索引和内容分离。索引文件通常很短只包含技能名称和一句话描述这样 AI 可以快速扫描所有可用技能而不占用太多上下文。当它决定使用某个技能时才去读取完整的技能文件。这就像你进一家餐厅先看菜单索引决定吃什么之后再让厨房做加载内容而不是一上来就把所有菜都端到你面前。我在实际配置的时候发现索引文件的描述写得越具体AI 判断的准确率越高。比如“代码审查”这个描述就太宽泛了改成“在提交代码前检查命名规范、边界条件、错误处理和测试覆盖”之后AI 在相关场景下调用这个技能的概率明显提高。2.3 与现有工具链的集成方式superpowers 本身不绑定特定的编辑器或 AI 服务它的集成方式取决于你用的工具。目前最常见的两种集成路径一种是通过编辑器的插件系统把技能库挂载到 AI 助手的上下文加载流程里另一种是通过项目根目录的配置文件让 AI 在启动时自动读取技能索引。以我自己的配置为例我在项目根目录下建了一个.skills文件夹里面放索引文件和各个技能文件然后在编辑器的 AI 配置里加了一行指向这个文件夹的路径。这样每次我打开这个项目AI 助手就会自动加载技能索引后续对话中它会根据任务类型决定是否加载具体技能。整个过程不需要我手动干预也不需要每次重复粘贴规则。注意不同编辑器对上下文加载的支持程度不一样有些工具可能不支持自动加载外部文件这种情况下你需要手动把技能内容粘贴到对话里或者用编辑器提供的“自定义指令”功能来引用。建议先确认你的工具支持哪种方式再决定怎么组织技能库。3. 核心细节解析与实操要点3.1 技能文件的结构设计一个高质量的技能文件应该包含四个部分触发条件、操作步骤、检查清单和反例。触发条件告诉 AI 什么情况下该用这个技能操作步骤是具体的执行流程检查清单用于事后验证反例则是告诉 AI 哪些做法是禁止的。这四个部分缺一不可尤其是反例部分很多人在写技能文件时会忽略但实际用下来反例对约束 AI 行为的效果非常明显。我拿一个实际用过的“安全修改现有代码”技能来举例。触发条件是“当任务涉及修改已有函数或模块时”。操作步骤包括先阅读目标函数及其调用方、确认修改影响范围、写出修改前后的行为对比、执行修改、运行相关测试。检查清单包括是否影响了其他调用方、是否改变了公开接口、是否更新了相关注释。反例部分则明确列出禁止在未阅读调用方的情况下修改函数签名、禁止顺手重构无关代码、禁止删除看起来没用的代码而不确认。这种结构的好处是 AI 在执行任务时有明确的路径可循而不是凭“感觉”去改代码。我实测下来加了反例之后AI 顺手改无关代码的概率下降了大概七成。3.2 技能粒度的把握技能粒度是很多人配置 superpowers 时最容易踩坑的地方。粒度太粗技能就变成了空泛的原则AI 没法执行粒度太细技能数量爆炸AI 在索引阶段就晕了。我的经验是一个技能应该对应一个“可独立完成的任务单元”而不是一个“原则”或“步骤”。举个例子“写好代码”这个粒度太粗了AI 看到这个技能名根本不知道要做什么。“变量命名使用驼峰式”又太细了这种规则应该放在代码规范文件里而不是单独做一个技能。比较合适的粒度是“新增一个 API 接口”或者“修复一个边界条件 bug”这种级别既有明确的操作对象又有可验证的完成标准。我目前维护的技能库大概有十五到二十个技能覆盖了日常开发中最高频的场景需求澄清、方案设计、代码实现、代码审查、测试编写、bug 修复、重构、文档更新。每个技能文件大概一到三页读起来不累AI 加载起来也快。3.3 索引文件的写法与维护索引文件是 superpowers 的入口它的质量直接决定了 AI 能不能在正确的时机调用正确的技能。我见过很多人把索引文件写成技能文件的摘要合集这是不对的。索引文件应该只包含技能名称和一句话描述描述要具体到“什么场景下用”和“解决什么问题”。比如“代码审查”这个技能索引里的描述可以写成“在提交代码前使用逐项检查命名规范、边界条件、错误处理、测试覆盖和文档更新。”这样 AI 在判断当前任务是否匹配时有足够的信息做决策。如果只写“代码审查”AI 可能会在写代码的时候就调用它而不是在提交前。索引文件还需要定期维护。当你新增或删除技能时记得同步更新索引。我建议把索引文件也纳入版本管理这样团队里其他人拉取代码后能直接用到最新的技能库。如果团队多人使用还可以在索引文件里标注每个技能的维护人方便追责和更新。3.4 与版本控制的配合superpowers 的技能库本质上就是一堆文本文件天然适合用 Git 管理。我自己的做法是把技能库放在项目仓库的一个独立目录下和代码一起提交。这样做有几个好处一是技能库的变更历史可追溯你能看到某个技能是什么时候加的、为什么加二是团队成员可以共享同一套技能减少沟通成本三是当项目技术栈发生变化时技能库可以跟着一起演进。提示如果你不想把技能库提交到主仓库也可以用 Git 子模块或者独立的技能库仓库然后在项目里引用。但不管用哪种方式一定要确保技能库有版本记录否则出了问题很难回滚。4. 实操过程与核心环节实现4.1 环境准备与目录结构搭建开始配置之前你需要确认两件事你的 AI 编程工具支持外部文件加载或自定义指令以及你有权限在项目目录下创建文件夹。大部分主流工具都支持这两种方式中的至少一种如果不确定可以先在工具文档里搜一下“自定义指令”或“上下文文件”相关的关键词。确认之后在项目根目录下创建技能库目录。我习惯用.skills作为目录名因为以点开头可以避免被某些构建工具扫描到。目录结构大概是这样的根目录下有一个index.md作为索引文件然后每个技能一个 Markdown 文件文件名用英文小写加连字符比如safe-code-modification.md、api-design-review.md。如果你技能比较多可以按类别再分一层子目录比如coding/、review/、testing/但索引文件里要写清楚每个技能的路径。创建完目录后先写一个最简单的索引文件只包含两三个你最高频使用的技能。不要一上来就搞几十个技能那样反而会降低 AI 的判断准确率。先用两三个跑通流程确认 AI 能在正确时机调用技能再逐步增加。4.2 编写第一个技能文件我建议从“需求澄清”这个技能开始写因为它是所有开发任务的第一步而且效果最直观。技能文件的内容可以这样组织触发条件写“当用户提出一个开发需求但需求描述不够具体时”操作步骤写“先复述你理解的需求、列出你不确定的点、向用户提问确认、得到确认后再进入方案设计”检查清单写“是否确认了输入输出、是否确认了边界条件、是否确认了性能要求”反例写“禁止在需求不明确的情况下直接开始写代码”。写完之后在索引文件里加上这个技能的条目描述写成“在需求描述不完整时使用通过提问澄清需求细节避免基于假设开发”。然后你就可以在 AI 助手里测试了。找一个模糊的需求比如“帮我优化一下这个查询”看看 AI 会不会先问你“优化目标是什么、当前性能瓶颈在哪里、有没有具体的指标要求”。如果它会问说明技能生效了如果它直接开始改代码说明触发条件或索引描述需要调整。4.3 技能加载的验证与调试技能配置好之后怎么确认 AI 真的在用我的做法是在技能文件里加一个“标记输出”比如在操作步骤的最后一步写“在回复末尾附上‘已应用需求澄清技能’”。这样每次 AI 调用这个技能时你都能在输出里看到标记一目了然。如果发现 AI 没有按预期调用技能排查顺序是这样的先看索引文件里的描述是否足够具体再看技能文件的触发条件是否写得太窄或太宽最后看你的工具是否真的加载了技能库。我遇到过最常见的问题是索引描述太笼统AI 判断不出来该不该用。把描述改具体之后问题基本都能解决。注意有些工具对上下文文件的大小有限制如果你的技能库太大可能会导致加载失败。这种情况下可以把技能库拆成多个索引文件按任务类型分别加载而不是一次性全部加载。4.4 从单技能到技能组合当你跑通了单个技能之后下一步是让多个技能协同工作。比如一个完整的开发流程可能涉及“需求澄清”“方案设计”“代码实现”“代码审查”“测试编写”五个技能它们之间有先后顺序。你可以在索引文件里加一个“工作流”描述告诉 AI 在什么阶段该调用哪个技能。我的做法是在索引文件顶部写一段“默认工作流”列出从需求到提交的推荐技能顺序。AI 在接到任务后会先看这段工作流然后按顺序调用相关技能。当然不是每个任务都需要走完整流程简单的修改可能只需要“代码实现”和“代码审查”两个技能。关键是让 AI 知道有哪些技能可用以及它们之间的推荐顺序。实测下来有了工作流描述之后AI 在复杂任务中的表现明显更稳定不会跳步也不会在需求还没确认的时候就急着写代码。5. 常见问题与排查技巧实录5.1 技能不生效的几种典型情况技能不生效是最常见的问题我整理了一个排查表按出现频率从高到低排列问题现象可能原因排查方法解决方案AI 完全不调用技能索引文件未被加载检查工具配置中的上下文路径确认路径正确重启工具AI 偶尔调用技能索引描述太笼统查看索引文件中的描述文字把描述改具体加入场景关键词AI 调用了错误的技能触发条件重叠对比多个技能文件的触发条件缩小触发条件范围增加区分度技能内容被截断文件太大或格式问题检查技能文件大小和 Markdown 语法拆分文件确保语法正确技能调用后无效果操作步骤不可执行逐条检查操作步骤是否具体把抽象描述改成具体动作这个表是我踩了无数次坑之后总结出来的基本上覆盖了九成以上的技能不生效问题。其中最常见的是索引描述太笼统很多人写索引的时候习惯用“代码质量”这种大词AI 根本判断不出来什么时候该用。改成“在提交代码前检查命名、边界、错误处理和测试覆盖”之后调用率立刻上来了。5.2 技能之间的冲突处理当技能数量增多之后冲突是不可避免的。比如“快速修复 bug”技能可能要求“最小化修改范围”而“代码重构”技能可能要求“顺手改善周边代码质量”。如果 AI 同时加载了这两个技能它可能会困惑到底该听谁的。我的处理方式是在索引文件里给每个技能标注优先级或者在技能文件里写明“当与其他技能冲突时以本技能为准”或“本技能优先级低于 XX 技能”。更稳妥的做法是在触发条件里就把场景区分开“快速修复 bug”的触发条件写成“当任务是修复一个已知的、影响范围明确的 bug 时”“代码重构”的触发条件写成“当任务是改善现有代码结构且不改变外部行为时”。这样 AI 在判断时就不会同时匹配两个技能。如果实在无法避免冲突可以在索引文件里加一条“冲突解决规则”告诉 AI 当多个技能同时匹配时优先使用哪个。我一般会把“安全修改”类技能的优先级设得最高因为改坏代码的代价比改得不够漂亮大得多。5.3 技能库的迭代与清理技能库不是建好就一劳永逸的它需要跟着项目一起演进。我每个月会花半个小时回顾一下技能库的使用情况哪些技能从来没被调用过、哪些技能调用后效果不好、哪些技能的内容已经过时了。没被调用过的技能要么是触发条件写得太窄要么是场景本身不常见可以考虑删除或合并。效果不好的技能需要看是操作步骤不够具体还是检查清单漏了关键项。提示删除技能之前先把它移到archive子目录里放一个月确认真的不需要了再彻底删掉。我有好几次删完第二天就发现还需要又得重新写很浪费时间。另外当项目技术栈发生变化时技能库也要同步更新。比如项目从 JavaScript 迁移到 TypeScript那“代码实现”技能里的示例和检查项就要跟着改。我一般会在技术栈变更的同一个提交里更新相关技能避免遗漏。5.4 团队协作中的技能库管理如果是团队使用技能库的管理需要额外注意几点。首先是命名规范要统一避免出现fix-bug.md和bug-fix.md这种同义不同名的情况。其次是每个技能文件头部加上维护人信息方便有问题时找到负责人。最后是变更流程我建议技能库的修改走和代码一样的 Pull Request 流程至少让一个人 review 过再合并避免有人不小心改坏了关键技能。团队使用还有一个好处是可以共享“踩坑经验”。比如某个同事发现 AI 在某个场景下总是犯错他可以把对应的反例加到技能文件里这样全团队都能受益。这种集体维护的技能库价值比个人维护的高得多。6. 我个人的使用体会与几个实用建议用了大半年 superpowers 这套东西之后我最大的体会是它不会让 AI 变聪明但会让 AI 变可靠。AI 本身的能力上限没有变化但它的下限被抬高了。以前你可能需要反复纠正 AI 的坏习惯现在这些纠正被固化在技能文件里AI 自己就会避开。这种感觉就像带一个新员工以前你得每次口头交代注意事项现在你给了他一本操作手册他照着做就行。如果你准备开始配置自己的技能库我的建议是从最小的可用集合开始。先写三个技能需求澄清、安全修改、提交前检查。这三个覆盖了最高频的场景而且效果最明显。跑通之后再逐步增加不要一上来就追求大而全。另外技能文件里的反例部分一定要认真写这是约束 AI 行为最有效的手段比正面描述管用得多。最后分享一个小技巧你可以把技能库和项目的代码规范文件放在一起让 AI 在加载技能的同时也能读到代码规范。这样技能里的操作步骤可以直接引用规范文件里的具体条款不用重复写一遍。我这样配置之后技能文件的维护成本降低了不少因为规范变更时只需要改一个地方。