1. 从“superpowers”这个热词说起它到底是什么最近一段时间“superpowers”这个词在技术社区和效率工具圈子里被反复提起很多人第一次看到它是在某个开源项目的讨论帖里也有人是在折腾 AI 编程助手时被朋友安利的。简单来说superpowers 是一套面向 AI 编程助手的能力扩展框架它通过一组结构化的技能文件skills和指令模板让原本只会“你问我答”的 AI 助手变成能够主动规划、分步执行、自我检查的“工程搭档”。它解决的核心问题是大多数人在用 AI 写代码时得到的往往是一段看似合理但经不起推敲的代码片段而 superpowers 试图把“资深工程师的工作方法论”固化下来让 AI 按照真实的工程流程去思考和产出。你可能会问这不就是提示词工程吗不完全是。提示词工程解决的是“怎么问”而 superpowers 解决的是“怎么让 AI 形成一套稳定的工作习惯”。它更像是一套给 AI 用的“操作手册 检查清单 角色定义”的组合包。适合谁来参考如果你日常用 AI 辅助写代码、做技术方案、排查问题但总觉得输出质量不稳定、需要反复纠正那这套东西值得花时间研究。如果你只是偶尔让 AI 帮忙写个正则表达式那可能暂时用不上。我第一次接触 superpowers 是在一个深夜调试一个并发问题时朋友甩过来一个链接说“你试试这个它会让 AI 先问你问题再动手”。当时我半信半疑但试过之后确实发现AI 的输出从“直接给答案”变成了“先确认需求、再拆解步骤、最后逐段实现”这个转变带来的质量提升是肉眼可见的。下面我就把这套东西的来龙去脉、核心机制、安装配置和实操经验完整地拆一遍。2. 核心设计思路拆解为什么它能让 AI 变“聪明”2.1 从“单次问答”到“工程流程”的范式转变大多数人用 AI 编程的默认模式是描述问题 → 得到代码 → 复制粘贴 → 发现问题 → 再描述 → 再得到代码。这个循环的问题在于AI 每次都在“重新理解”你的项目它不知道你之前做了什么、为什么这么做、下一步要往哪走。superpowers 的核心洞察是把 AI 的工作方式从“无状态问答”改造成“有状态流程”。具体怎么做的它定义了一套技能体系每个技能是一个 Markdown 文件里面写清楚了“在什么场景下触发、需要收集哪些信息、按什么步骤执行、产出什么格式的结果”。当你在 AI 助手里加载了这套技能后AI 在遇到对应场景时会自动调用相应的技能而不是凭感觉回答。比如你让它“帮我加一个用户登录功能”它不会直接甩一段代码而是先触发“需求澄清”技能问你几个关键问题用什么认证方式、要不要记住登录状态、密码强度要求是什么。这些问题问完之后它才会进入“方案设计”技能给出技术选型和接口定义最后才进入“代码实现”技能。这个设计背后的逻辑其实很朴素资深工程师在动手之前一定会先想清楚而 AI 缺的就是这个“想清楚”的环节。superpowers 把这个环节显式化了用文件的形式固化下来让 AI 每次都能按部就班地走一遍。2.2 技能文件的结构与触发机制每个技能文件通常包含几个关键部分触发条件、前置检查、执行步骤、输出格式、常见陷阱。触发条件决定了 AI 在什么情况下会加载这个技能比如“当用户要求实现一个新功能时”或者“当代码出现报错需要排查时”。前置检查是一组问题AI 需要先确认这些信息才能继续避免在信息不足的情况下瞎猜。执行步骤是核心通常是一组有序的操作指令告诉 AI 先做什么、再做什么。输出格式规定了 AI 应该以什么结构呈现结果比如“先给方案对比表再给推荐方案最后给代码”。常见陷阱则是把踩过的坑写进去提醒 AI 不要犯同样的错误。我拆过几个典型的技能文件发现它们的写法很有讲究。比如“代码审查”技能里执行步骤不是简单的“检查代码质量”而是拆成了“检查命名规范 → 检查边界条件 → 检查错误处理 → 检查性能隐患 → 检查可测试性”五个子步骤每个子步骤都有具体的检查点和示例。这种颗粒度让 AI 的输出变得非常稳定不会因为提示词的微小变化就产生巨大波动。2.3 为什么选择 Markdown 而不是代码或配置你可能会好奇为什么这些技能文件用 Markdown 写而不是用 JSON、YAML 或者某种 DSL。我一开始也觉得奇怪后来想明白了Markdown 是 AI 最容易理解的格式同时也是人最容易维护的格式。JSON 和 YAML 虽然结构化程度高但写起来啰嗦改起来容易出错而且 AI 在解析时反而容易因为格式问题产生误解。Markdown 的标题、列表、引用块天然就是分层的AI 在训练时见过海量的 Markdown 文档对它的理解非常到位。另一个好处是Markdown 文件可以直接放在项目仓库里跟代码一起做版本管理。你可以像 review 代码一样 review 技能文件的改动也可以针对不同项目定制不同的技能集。这种“技能即代码”的思路让整套体系的可维护性上了一个台阶。3. 安装与配置实操从零把 superpowers 跑起来3.1 环境准备与前置条件确认在动手安装之前有几件事需要先确认清楚。首先superpowers 本身不是一个独立运行的软件它需要依附在一个支持技能加载的 AI 编程助手上。目前主流的支持方式是通过助手的“自定义指令”或“技能目录”功能来加载。所以第一步是确认你用的助手是否支持从本地目录读取技能文件。如果不支持那就需要退而求其次把技能内容手动粘贴到系统提示词里但这种方式维护起来比较麻烦不推荐长期使用。其次确认你的项目目录结构。superpowers 通常建议在项目根目录下创建一个专门的技能目录比如.ai-skills/或者skills/然后把技能文件放进去。这样做的好处是技能跟项目绑定换项目时不会互相干扰。如果你希望技能在所有项目中通用也可以放在用户主目录下的全局配置目录里但要注意不同项目的技术栈差异可能会导致技能触发不准确。最后确认你的 AI 助手版本。不同版本对技能加载的支持程度不一样有些老版本可能只支持单个指令文件不支持多文件技能目录。建议先升级到最新版本避免在配置过程中遇到莫名其妙的兼容性问题。3.2 获取技能文件的三种途径获取 superpowers 技能文件主要有三种途径各有优劣我分别说一下。第一种是直接从开源仓库克隆。这是最推荐的方式因为你可以拿到完整的技能集而且后续更新也方便。通常的做法是git clone https://github.com/example/superpowers-skills.git .ai-skills克隆下来之后你会看到一堆.md文件每个文件对应一个技能。有些仓库还会提供一个index.md或者manifest.json来列出所有可用技能及其触发条件。这种方式的好处是透明、可定制你可以随时修改某个技能文件来适配自己的习惯。第二种是通过包管理器安装。有些社区维护的版本会发布到 npm 或 pip 上安装命令类似npm install -g superpowers-skills安装完成后技能文件会被放到全局目录下你需要在助手配置里指向这个目录。这种方式适合不想折腾 git 的人但缺点是版本更新可能滞后而且你不太容易知道具体装了哪些技能。第三种是手动创建。如果你只需要几个核心技能完全可以自己写。一个最简单的技能文件长这样# 技能名称需求澄清 ## 触发条件 当用户提出一个模糊的功能需求时触发。 ## 执行步骤 1. 复述用户的需求确认理解无误。 2. 提出三个关键问题覆盖输入、输出、边界条件。 3. 等待用户回答后再进入下一步。 ## 输出格式 以列表形式列出问题和用户的回答。手动创建的好处是完全贴合自己的需求缺点是费时间而且容易遗漏重要细节。我的建议是先用克隆的方式拿到一套完整的然后根据自己的使用习惯逐步裁剪和补充。3.3 配置助手加载技能目录技能文件准备好之后下一步是让 AI 助手知道去哪里加载它们。不同助手的配置方式不一样但大体思路是相似的在设置里找到“技能”或“自定义指令”相关的选项然后填入技能目录的路径。以常见的配置为例你需要在助手的配置文件里加上类似这样的内容{ skills: { enabled: true, directories: [.ai-skills], autoLoad: true } }autoLoad设为 true 表示助手在启动时自动加载所有技能文件这样你就不需要每次手动指定了。有些助手还支持按项目加载也就是只在当前项目目录下查找技能文件这样不同项目可以用不同的技能集。配置完成后建议做一个简单的验证新建一个对话输入一个模糊的需求比如“帮我优化一下这段代码”看看助手是否会先触发“需求澄清”技能问你几个问题。如果它直接开始改代码说明技能没有加载成功需要检查路径和配置格式。注意技能目录的路径写法在不同操作系统上可能有差异Windows 下用反斜杠macOS 和 Linux 下用正斜杠。如果路径包含空格记得用引号包起来。3.4 验证安装是否成功的三个检查点安装完成后怎么确认一切正常我总结了三个检查点。第一个检查点是看助手是否识别到了技能数量。有些助手会在启动日志里输出“已加载 N 个技能”如果 N 是 0说明路径配错了或者文件格式有问题。第二个检查点是触发一个明确的技能场景比如让助手“帮我写一个单元测试”看看它是否按照技能文件里定义的步骤来执行而不是随意发挥。第三个检查点是检查技能之间的协作是否正常比如“需求澄清”技能完成后是否会自动衔接到“方案设计”技能而不是卡在半路。如果这三个检查点都通过了说明安装配置没问题可以开始正式使用了。4. 核心技能详解与实操要点4.1 需求澄清技能把模糊需求变成明确规格需求澄清是 superpowers 里最基础也最重要的技能。它的作用是在 AI 动手之前先把用户脑子里模糊的想法逼成明确的规格。这个技能的触发条件通常是“用户提出一个功能需求但没有给出足够细节”。执行步骤一般包括复述需求、识别缺失信息、提出关键问题、等待回答、整理成需求文档。我实测下来这个技能的效果取决于问题问得准不准。好的问题应该覆盖三个维度输入是什么、输出是什么、边界条件是什么。比如用户说“帮我加一个搜索功能”AI 应该问搜索的数据源是什么、搜索的关键词匹配规则是什么、结果怎么排序、分页大小是多少、空结果怎么处理。这些问题问完需求基本就清晰了。实操心得我在使用这个技能时会额外在技能文件里加一条“如果用户连续两次回答‘随便’或‘你决定’则直接给出一个默认方案并说明理由不再继续追问”。这样可以避免陷入无限追问的循环。4.2 方案设计技能先对比再推荐方案设计技能的核心是先给选项再给建议。它不会直接告诉你“用 Redis 做缓存”而是先列出两到三个可行方案对比各自的优缺点然后根据项目实际情况推荐一个。这个技能的执行步骤通常是识别技术选型点、列出候选方案、从性能/复杂度/维护成本三个维度对比、给出推荐及理由。我特别喜欢这个技能的一点是它会强制 AI 把“不选某个方案的理由”也写出来。比如推荐用 PostgreSQL 而不是 MongoDB 时它会说明“虽然 MongoDB 的文档模型更灵活但当前项目的查询模式以关联查询为主关系型数据库更合适”。这种对比让决策过程变得透明也方便后续复盘。4.3 代码实现技能分步执行与自检代码实现技能是 superpowers 里最“重”的一个它把写代码拆成了多个子步骤接口定义 → 核心逻辑 → 错误处理 → 单元测试 → 自检。每个子步骤完成后AI 会暂停一下确认没有问题再继续。这个设计的好处是如果中间某一步出了问题你可以及时发现并纠正而不是等到整个功能写完才发现方向错了。自检环节是这个技能的亮点。AI 会按照一份检查清单逐项确认命名是否清晰、边界条件是否覆盖、错误处理是否完整、是否有硬编码、是否可以通过现有测试。这份清单是从大量真实代码审查经验中提炼出来的覆盖了最常见的代码质量问题。注意分步执行会增加交互轮次如果你赶时间可以在技能文件里把“每步暂停”改成“每三步暂停一次”在质量和效率之间找个平衡。4.4 问题排查技能从现象到根因的推理链问题排查技能是我用得最多的一个。它的执行步骤是收集现象 → 列出可能原因 → 逐一排除 → 定位根因 → 给出修复方案 → 验证修复。关键在于“逐一排除”这一步AI 会为每个可能原因设计一个验证方法比如“如果是缓存问题清除缓存后重试看是否复现”。这个技能里有一个很实用的设计要求 AI 在排查过程中记录每一步的结论形成一条推理链。这样即使最后没有找到根因你也能看到它排除了哪些可能性避免重复劳动。我在排查一个偶发的超时问题时就是靠这条推理链发现真正的原因是连接池配置不当而不是最初怀疑的网络抖动。4.5 技能之间的协作与优先级superpowers 里的技能不是孤立的它们之间有触发顺序和优先级。一般来说需求澄清优先级最高方案设计次之代码实现再次之问题排查则在出现错误时触发。但实际使用中这些技能可能会交叉触发。比如在代码实现过程中发现一个设计问题可能会回退到方案设计技能重新评估。我在配置时会设置一个“技能优先级表”明确哪些技能可以打断当前流程哪些必须等当前流程结束。这样可以避免 AI 在写代码写到一半突然跳去问需求问题导致上下文混乱。技能名称触发时机可打断其他技能典型输出需求澄清需求模糊时是需求规格列表方案设计需要技术选型时是方案对比表代码实现需求明确后否代码测试问题排查出现错误时是推理链修复方案代码审查代码完成后否审查报告5. 常见问题与排查技巧实录5.1 技能不触发或触发错误怎么办这是最常见的问题。表现是 AI 没有按照技能文件里的步骤执行或者触发了错误的技能。排查思路分三步先确认技能文件是否被正确加载再确认触发条件是否匹配当前场景最后确认技能之间是否有冲突。技能不加载的原因通常是路径错误或文件格式问题。检查路径时注意相对路径是相对于助手的工作目录而不是项目根目录。文件格式方面确保每个技能文件都有明确的标题和触发条件段落有些助手对格式比较敏感缺少必要段落会导致解析失败。触发错误则通常是触发条件写得太宽泛。比如“当用户提出问题时触发”这种条件几乎会匹配所有对话导致技能被滥用。好的触发条件应该是具体的比如“当用户要求实现新功能且未指定技术栈时触发”。5.2 技能执行到一半卡住或跑偏有时候 AI 会执行到某个步骤后停下来或者偏离了技能定义的流程。这种情况通常是因为上下文太长导致 AI “忘记”了技能内容或者遇到了技能文件里没有覆盖的边界情况。解决办法有两个一是在技能文件里增加“如果遇到未覆盖的情况先暂停并询问用户”的指令二是定期清理对话上下文避免历史信息干扰当前技能的执行。我个人的习惯是每完成一个完整的功能开发就新开一个对话保持上下文干净。5.3 多个技能冲突时的处理策略当两个技能同时被触发时AI 可能会无所适从。比如你让 AI “优化这段代码”它可能同时触发“代码审查”和“方案设计”两个技能。这时候需要在技能文件里定义优先级或者在助手的全局配置里设置技能的执行顺序。我的做法是在每个技能文件的开头加一行priority: N数字越小优先级越高。然后在助手配置里设置“同一时刻只执行优先级最高的技能其他技能排队等待”。这样可以保证流程有序不会出现两个技能互相打断的情况。5.4 技能文件更新后不生效修改了技能文件但 AI 的行为没有变化这通常是因为助手缓存了旧版本的技能内容。解决办法是重启助手或者手动触发一次“重新加载技能”的操作。有些助手支持热加载修改文件后自动生效但大多数还是需要手动刷新。另外注意如果你用的是 git 克隆的方式更新技能文件后需要先git pull拉取最新版本再重启助手。我踩过一次坑改了本地的技能文件但忘了提交结果换了一台机器后发现行为不一致排查了半天才想起来是本地修改没同步。5.5 常见问题速查表问题现象可能原因排查方法解决措施技能完全不触发路径错误/格式错误检查助手日志中的技能加载数量修正路径补全必要段落触发错误技能触发条件太宽泛查看技能文件的触发条件描述收窄触发条件增加限定词执行中途卡住上下文过长/边界未覆盖检查对话历史长度新开对话补充边界处理指令多技能冲突优先级未定义观察哪些技能同时触发设置 priority 字段更新不生效缓存未刷新确认文件修改时间重启助手或手动刷新实操心得我建议在项目初期就把技能文件纳入版本管理每次修改都写清楚改了什么、为什么改。这样当 AI 行为出现异常时可以快速定位到是哪次修改导致的。6. 进阶用法定制属于自己的技能集6.1 从现有技能派生新技能superpowers 自带的技能是通用型的但每个团队、每个项目都有自己的特殊流程。这时候可以从现有技能派生新技能。比如你们团队要求所有数据库操作必须走 ORM不允许裸写 SQL那就可以在“代码实现”技能的基础上派生一个“数据库操作规范”技能在触发条件里加上“当涉及数据库操作时”在执行步骤里加上“检查是否使用了 ORM”。派生技能的好处是不用从零写起继承原有技能的结构只修改差异部分。维护起来也方便上游技能更新时可以合并过来。6.2 把团队规范写成技能文件团队规范往往是口口相传的新人来了要花很长时间才能摸清楚。把这些规范写成技能文件不仅 AI 能遵守新人也能通过阅读技能文件快速了解团队的做事方式。比如代码提交规范、分支命名规范、接口设计规范都可以写成技能文件。我帮一个团队做过这件事把他们散落在 wiki、聊天记录、代码注释里的规范整理成了十几个技能文件。效果很明显AI 生成的代码一次通过率从不到一半提升到了八成以上新人的上手时间也缩短了。6.3 技能文件的版本管理与团队共享技能文件应该跟代码一样做版本管理。建议放在项目仓库的.ai-skills/目录下跟代码一起提交。这样每个人拿到的都是同一套技能AI 的行为也保持一致。如果团队规模较大可以单独建一个技能仓库通过 git submodule 的方式引入到各个项目中。共享时要注意脱敏不要把包含敏感信息的技能文件提交到公开仓库。比如包含内部 API 地址、数据库连接串的技能文件应该放在私有仓库或者本地目录里。6.4 性能优化减少技能加载开销技能文件太多会导致助手启动变慢因为每次都要解析所有文件。优化方法有几个一是只加载当前项目需要的技能把不用的技能文件移到其他目录二是把多个小技能合并成一个大技能减少文件数量三是定期清理过时或重复的技能。我实测下来技能文件控制在 20 个以内时加载开销基本可以忽略。超过 50 个后启动时间会明显增加。所以建议按项目类型维护不同的技能集而不是把所有技能都堆在一起。7. 我踩过的坑与实战建议7.1 不要一次性加载所有技能我刚开始用的时候把能找到的技能全加载了结果 AI 变得非常“啰嗦”每个简单问题都要走一遍完整流程效率反而下降了。后来我学乖了只加载当前项目真正需要的技能比如做后端开发就加载需求澄清、方案设计、代码实现、问题排查这四个核心技能其他的按需加载。7.2 技能文件要定期回顾和修剪技能文件不是写完就完了需要定期回顾。我在每个季度会花半小时翻一遍所有技能文件把不再适用的删掉把经常出问题的改掉把新总结的经验加进去。这个习惯让我的技能集始终保持“精炼”状态AI 的表现也越来越稳定。7.3 给技能加上“退出条件”有些技能执行到一半会陷入死循环比如需求澄清技能一直追问细节用户不耐烦了还在问。后来我在每个技能文件里都加了一个“退出条件”如果用户明确表示“就这样吧”或者连续两次没有提供新信息就停止追问基于现有信息给出方案。这个小改动大大提升了使用体验。7.4 用真实项目验证技能效果技能文件改完后不要只看 AI 的输出是否“看起来合理”要用真实项目验证。我的做法是拿一个已经完成的小功能让 AI 用新技能重新做一遍对比输出质量和原来的差异。如果新技能产出的代码更清晰、更少 bug说明改动是有效的。如果只是“看起来更规范”但实际质量没提升那就要重新思考改动的价值。7.5 保持技能文件的“人味”最后一点可能有点抽象但很重要技能文件不要写得太机械。AI 在训练时见过大量人类写的文档那些带有个人风格、口语化表达、真实案例的文档往往比干巴巴的规则列表更容易被理解和执行。所以我在写技能文件时会刻意加入一些“我试过”“踩过的坑是”这样的表达让 AI 感受到这是一个有经验的人在分享而不是一份冷冰冰的规范。这套东西说到底核心价值不在于技术有多高深而在于它把“好的工作习惯”变成了可复用、可传播的资产。你花时间打磨技能文件的过程其实也是在梳理自己的方法论。等这套体系跑顺了你会发现不仅 AI 变强了你自己对项目的理解也更清晰了。