1. 从“superpowers”这个热词说起它到底是什么最近“superpowers”这个词在技术社区和效率工具圈子里被反复提起很多人第一次看到它是在某个开源项目的讨论区或者是在朋友分享的终端截图里。简单来说superpowers 是一套面向 AI 编程助手的能力扩展框架它通过一系列结构化的“技能包”和“工作流指令”让原本只会被动回答问题的 AI 助手变成能够主动规划、分步执行、自我检查的“超级助手”。你可以把它理解成给 AI 装上了一套“职业操作手册”——原本它只会跟你聊天装上之后它知道先做什么、再做什么、遇到问题怎么排查、交付前怎么自检。这个项目解决的核心痛点非常明确大多数人在使用 AI 编程助手时得到的输出质量极不稳定。同一个问题换个问法结果天差地别复杂任务经常做到一半就跑偏生成的代码缺少测试、没有边界处理、不考虑现有项目规范。superpowers 的思路不是去改模型本身而是通过一套精心设计的提示词工程和工作流编排把“资深工程师的做事方式”固化下来让 AI 每次都能按照相对靠谱的流程走。它适合谁如果你属于以下几类人superpowers 值得花时间研究日常用 AI 辅助写代码的开发者、需要 AI 帮忙处理复杂多步任务的技术人员、对提示词工程和工作流设计感兴趣的学习者以及希望把 AI 助手调教得更“懂规矩”的团队。哪怕你只是偶尔用 AI 写写脚本、改改配置了解这套框架的设计思路也能帮你显著提升输出质量。接下来的内容我会从设计思路、核心机制、安装配置、实操流程到常见问题完整拆一遍。2. 核心设计思路拆解为什么是“技能包”而不是“万能提示词”2.1 单一巨型提示词的困境很多人刚开始用 AI 助手时的直觉是写一个特别长、特别详细的系统提示词把所有要求都塞进去不就行了我早期也这么干过结果很快撞墙。一个包含代码规范、测试要求、文档格式、错误处理、性能优化等所有内容的提示词动辄两三千字模型在长上下文里会“遗忘”中间部分的要求而且不同任务需要的侧重点完全不同——写一个新功能和处理一个 bug 修复关注点能一样吗更麻烦的是维护成本。每次想调整某个环节的行为都要在一个巨型文本里找到对应位置修改改完还得担心有没有影响到其他部分。这种“大一统”的思路在实际使用中很快会变成一团乱麻。2.2 技能包模式的分而治之superpowers 采用的核心策略是把能力拆成独立的技能包每个技能包聚焦一个具体场景。比如有专门负责“需求澄清”的技能、专门负责“方案设计”的技能、专门负责“代码实现”的技能、专门负责“测试验证”的技能。每个技能包内部包含触发条件、执行步骤、检查清单、输出格式要求。这样做的好处非常明显。第一按需加载。处理一个简单任务时只需要激活相关的一两个技能不会让无关指令干扰模型注意力。第二独立迭代。你觉得“代码审查”这个技能不够好单独改它就行不影响其他部分。第三可组合。复杂任务可以串联多个技能形成一条完整的工作流。提示技能包的粒度设计是关键。太粗了跟巨型提示词没区别太细了会导致技能数量爆炸、组合复杂度失控。superpowers 的实践表明每个技能包对应一个“可独立交付的工作环节”是比较合理的粒度。2.3 工作流编排让 AI 学会“先想再做”光有技能包还不够还得决定什么时候用哪个技能、按什么顺序用。superpowers 引入了工作流编排的概念本质上是一套状态机当前处于哪个阶段、下一步该做什么、什么条件下可以进入下一阶段、什么情况下需要回退。举个例子一个完整的功能开发工作流可能是需求理解 → 方案设计 → 用户确认 → 代码实现 → 自测 → 代码审查 → 交付。每个阶段对应一个或多个技能包阶段之间有明确的准入准出条件。比如“代码实现”阶段的准出条件是“自测通过且无语法错误”不满足就不能进入“代码审查”。这种编排让 AI 的行为变得可预测、可追溯。你能清楚知道它现在在干什么、为什么这么干、下一步要干什么。出了问题也容易定位是哪个环节的指令不够清晰。3. 核心机制深度解析技能包内部到底有什么3.1 触发条件的设计每个技能包开头都有一段触发条件描述告诉 AI 在什么情况下应该激活这个技能。触发条件通常包含几个要素任务类型关键词比如“重构”“新增”“修复”、上下文特征比如“涉及多个文件”“需要修改数据库”、前置状态比如“方案已确认”“测试已通过”。设计触发条件时最容易犯的错误是写得太宽泛。比如“当用户要求写代码时”这种条件几乎覆盖所有场景等于没有触发条件。好的触发条件应该是具体且可判断的比如“当用户要求新增一个 API 接口且该接口需要访问数据库时”。3.2 执行步骤的编排技能包的核心是执行步骤通常以有序列表的形式呈现。每一步都应该是可操作的具体动作而不是模糊的方向性描述。对比一下模糊描述“分析代码结构”——AI 不知道分析到什么程度算完。具体步骤“列出当前模块的所有导出函数标注每个函数的入参类型和返回值类型识别其中被其他模块引用的函数”——这就很明确。superpowers 在步骤设计上有一个重要原则每一步都要有可验证的输出。也就是说执行完这一步应该能产出一个具体的东西——一段分析文字、一个文件、一个命令的执行结果。这样 AI 自己也能判断是否完成了这一步。3.3 检查清单与自检机制这是 superpowers 区别于普通提示词模板的关键设计。每个技能包末尾都附有一个检查清单列出交付前必须确认的事项。比如代码实现技能的检查清单可能包括是否处理了空值输入、是否有对应的单元测试、是否更新了相关文档、是否遵循了项目的命名规范。AI 在执行完主要步骤后会被要求逐项核对检查清单对未满足的项进行补充或修正。这个机制模拟了资深工程师“交付前过一遍脑子”的习惯能拦截掉大量低级问题。注意检查清单不宜过长一般控制在 5 到 8 项。太长了 AI 会敷衍了事每项都打个勾但实际没认真检查。优先放那些“一旦遗漏就会造成明显问题”的项。3.4 输出格式的约束superpowers 对每个技能的输出格式都有明确规定。这不是为了好看而是为了让输出可被后续环节消费。比如“方案设计”技能要求输出包含方案概述、涉及文件列表、关键改动点、风险与回滚方案。下一个环节“代码实现”就能直接读取这些结构化信息不需要再去猜测上一环节到底说了什么。格式约束通常用 Markdown 的标题层级和列表来实现既对人友好也方便 AI 解析。有些实现还会用 JSON 或 YAML 来定义更严格的格式但可读性会下降需要权衡。4. 安装与配置实操从零把 superpowers 跑起来4.1 环境准备与前置检查在开始安装之前先确认你的环境满足基本要求。superpowers 本身是一套配置文件和指令集不依赖特定的运行时但它需要配合一个支持自定义指令的 AI 编程助手使用。常见的搭配包括各类支持系统提示词或项目级指令文件的 AI 编码工具。你需要准备的东西一个可用的 AI 编程助手环境、一个用于存放配置的项目目录、基本的命令行操作能力。如果你用的是支持项目级指令文件的工具superpowers 的配置通常放在项目根目录下的特定文件夹中。先检查你的工具是否支持以下能力读取项目级指令文件、在对话中引用文件内容、执行多轮工具调用。这三项是运行 superpowers 工作流的基础。如果缺少任何一项体验会打折扣。4.2 获取与放置配置文件superpowers 的配置通常以一组 Markdown 文件的形式分发。你需要把这些文件放到 AI 助手能够读取到的位置。具体路径取决于你使用的工具常见的位置包括项目根目录下的.assistant/、.ai/或类似的约定目录。放置时注意保持目录结构完整。技能包之间可能存在引用关系比如工作流编排文件会引用具体的技能包文件。如果目录结构被打乱引用就会失效。建议直接克隆或下载完整的配置包不要手动挑拣文件。# 假设你已经在项目根目录 # 创建配置目录具体名称以你使用的工具文档为准 mkdir -p .assistant/skills mkdir -p .assistant/workflows # 将下载的配置文件复制到对应目录 # 技能包放入 skills工作流放入 workflows4.3 关键配置项说明配置文件中有几个关键项需要根据你的实际情况调整。第一是项目技术栈声明告诉 AI 你用的是哪种语言、哪个框架、什么代码风格。这个信息会影响代码实现技能的具体行为。第二是文件路径约定比如源码放在哪个目录、测试放在哪个目录、文档放在哪个目录。第三是命名规范包括文件命名、变量命名、函数命名等。这些配置项通常以键值对的形式写在配置文件的头部区域。修改时注意保持格式正确YAML 对缩进敏感Markdown 则相对宽松。提示初次配置时不要追求面面俱到。先把技术栈和目录约定填好命名规范可以用默认值等实际使用中发现不符合习惯的地方再逐步调整。一次性配置太多反而容易出错。4.4 验证安装是否成功配置完成后用一个简单任务验证是否生效。比如让 AI 助手“新增一个返回当前时间的函数”。如果 superpowers 正常工作你应该能观察到以下行为AI 先确认需求细节比如函数放在哪个文件、返回什么格式的时间然后给出实现方案接着写代码最后运行测试或给出测试建议。如果 AI 的行为跟平时没有区别直接甩出一段代码就完事说明配置没有生效。排查方向配置文件路径是否正确、文件格式是否被工具识别、是否需要在对话中显式引用配置文件。不同工具的激活方式不同有的自动读取有的需要手动触发。5. 完整实操流程用 superpowers 完成一个真实任务5.1 任务设定与需求澄清假设我们要完成一个真实任务给一个现有的用户管理模块新增“批量导入用户”功能。这个任务涉及文件读取、数据校验、数据库写入、错误处理等多个环节适合用来展示 superpowers 的完整工作流。启动任务后需求澄清技能首先被激活。AI 会提出一系列问题导入的文件格式是什么CSV 还是 Excel数据量大概多大遇到重复用户怎么处理跳过还是更新导入失败时是全部回滚还是部分成功这些问题的答案会直接影响后续的方案设计。这一步的价值在于把模糊需求变成明确规格。平时我们直接让 AI 写代码它往往会自行假设这些细节假设错了就得返工。花几分钟澄清后面省几小时调试。5.2 方案设计与确认需求明确后进入方案设计阶段。AI 会输出一份结构化的方案文档通常包含整体思路、涉及的文件列表、每个文件的改动点、关键数据结构设计、错误处理策略、测试计划。以批量导入为例方案可能包括新增一个导入服务类、在现有控制器中增加导入接口、设计导入结果的数据结构成功数、失败数、失败原因列表、确定使用数据库事务来保证一致性。方案输出后AI 会等待你确认再进入实现阶段。这个“等待确认”的环节非常重要。它是成本最低的纠错点——方案阶段改一句话比代码写完再改省事得多。我自己的习惯是认真读一遍方案重点看文件列表和数据结构设计这两处最容易出现理解偏差。5.3 代码实现与分步验证确认方案后进入实现阶段。superpowers 的实现技能会按照方案中的文件列表逐个处理每完成一个文件就做一次基本检查语法是否正确、导入是否完整。而不是一口气写完所有文件再统一检查。这种小步验证的策略能快速定位问题。如果写到第三个文件时发现前两个文件的接口对不上立刻就能发现并修正不用等到全部写完再回头排查。实现过程中 AI 还会同步生成或更新对应的测试文件。# 示例导入结果数据结构AI 根据方案自动生成 class ImportResult: def __init__(self): self.success_count 0 self.failure_count 0 self.failures [] # 每项包含行号和失败原因 def add_success(self): self.success_count 1 def add_failure(self, row_number, reason): self.failure_count 1 self.failures.append({row: row_number, reason: reason})5.4 自测与代码审查代码写完后自测技能被激活。AI 会运行现有的测试套件确认没有破坏已有功能然后针对新增功能运行新写的测试。如果测试失败它会尝试分析原因并修复而不是直接把失败信息丢给你。自测通过后进入代码审查环节。审查技能会从几个维度检查代码边界条件处理空文件、超大文件、格式错误的行、安全性文件内容是否经过校验、是否有注入风险、性能大数据量下是否会内存溢出、可维护性是否有重复代码、命名是否清晰。审查发现的问题会被逐条列出AI 给出修改建议并执行修改。这个环节相当于有一个经验丰富的同事帮你做了一次 code review。5.5 交付与文档更新最后是交付环节。AI 会整理一份变更摘要包括新增了哪些文件、修改了哪些文件、如何运行测试、如何回滚。如果项目有文档目录它还会更新相关文档比如在 API 文档中增加新接口的说明。整个流程走下来从需求澄清到交付AI 的行为始终在预设的轨道上运行。你不需要反复提醒它“记得写测试”“注意错误处理”这些都已经固化在技能包里了。6. 常见问题与排查技巧实录6.1 技能不触发或触发错误最常见的问题是技能该触发的时候没触发或者不该触发的时候乱触发。原因通常是触发条件写得不够精确。排查方法是打开技能包文件逐条核对触发条件看当前任务的特征是否真的匹配。如果发现某个技能频繁误触发可以给它增加更严格的限定条件。比如“代码实现”技能原本的触发条件是“用户要求写代码”可以改成“用户要求写代码且方案已确认”。如果某个技能该触发却没触发检查它的触发条件里是否包含了当前任务不具备的特征。6.2 工作流卡在某个环节工作流卡住通常表现为 AI 反复执行同一个步骤或者停在某个环节不动。原因可能是准出条件无法满足。比如“自测通过”这个准出条件如果测试环境本身有问题导致测试永远失败工作流就会卡住。解决办法是检查准出条件是否可达。必要时可以手动干预告诉 AI“跳过自测直接进入审查”或者先修复环境问题再继续。superpowers 的工作流通常支持手动跳过某个环节具体方式看编排文件的定义。6.3 输出质量不稳定即使有技能包约束输出质量仍可能波动。常见原因有三个上下文太长导致指令被稀释、技能包版本与任务不匹配、配置项与实际项目不符。排查顺序先看对话历史是不是太长了必要时开新对话重新开始再检查技能包是否针对当前任务类型做了优化最后核对配置项特别是技术栈和目录约定这两项错了会导致 AI 按错误的假设工作。6.4 常见问题速查表问题现象可能原因排查动作技能完全不触发配置文件未被读取检查文件路径和工具激活方式技能误触发触发条件太宽泛增加限定条件缩小触发范围工作流卡住准出条件不可达检查条件定义必要时手动跳过输出格式不对格式约束被忽略检查上下文长度缩短对话历史代码不符合项目规范配置项未更新核对技术栈和命名规范配置测试总是失败测试环境问题先手动运行测试确认环境正常6.5 独家避坑经验第一不要一次性启用所有技能包。技能包之间有依赖关系全启用会导致 AI 在无关技能之间反复横跳。建议按任务类型选择性启用比如做新功能时启用需求、设计、实现、测试四个技能做 bug 修复时只启用排查和修复两个技能。第二定期回顾和修剪技能包。用了一段时间后你会发现有些技能包从来没触发过有些技能包的步骤已经不符合当前项目情况。每个月花半小时清理一次删掉没用的更新过时的保持技能集精简有效。第三给技能包写“变更日志”。每次修改技能包后在文件头部记一笔改了什么、为什么改、什么时候改的。过几个月回头看能快速回忆起当时的考虑避免重复踩坑。第四不要指望 superpowers 解决所有问题。它是一套流程约束不是万能药。对于探索性任务比如“帮我看看这个性能问题出在哪”过于严格的工作流反而会限制 AI 的发挥。这类任务适合关掉编排让 AI 自由发挥。7. 进阶玩法定制属于你自己的技能包7.1 从现有技能包改起完全从零写一个技能包难度较大更实际的做法是找一个最接近你需求的现有技能包在它的基础上修改。比如你想加一个“数据库迁移”技能可以先看“代码实现”技能的结构保留它的框架替换掉具体步骤和检查清单。修改时注意保持格式一致。触发条件、执行步骤、检查清单、输出格式这四个部分缺一不可。删掉任何一个部分都会影响技能的正常工作。7.2 技能包的组合与嵌套当你有了一定数量的自定义技能包后可以尝试把它们组合成新的工作流。比如把“数据库迁移”和“数据校验”组合成一个“数据迁移”工作流把“接口设计”和“文档生成”组合成“API 开发”工作流。组合时注意明确环节之间的输入输出关系。上一个环节的输出格式要能被下一个环节直接消费否则中间需要加一个转换步骤。这个转换步骤本身也可以做成一个技能包。7.3 团队协作中的技能包管理如果是团队使用技能包需要纳入版本管理。建议把技能包放在项目的版本控制目录中跟代码一起提交。这样每个人拉取项目后都能获得最新的技能配置不会出现“我这边能用你那边不能用”的情况。团队协作时还需要约定技能包的修改流程。谁可以改、改完怎么通知、是否需要评审这些规则最好提前定好。技能包是团队共享的“AI 行为规范”随意修改会影响所有人的使用体验。注意团队共享的技能包中不要包含个人偏好设置比如“我习惯用某种特定的代码风格”。个人偏好应该放在本地配置中不要污染团队共享的技能包。8. 我个人的使用体会与几个实用建议用 superpowers 这套框架有一段时间了最大的感受是它把 AI 助手从“聪明但随性”变成了“靠谱但需要调教”。刚开始配置的时候会觉得麻烦要写触发条件、要设计步骤、要维护检查清单比直接甩问题给 AI 费事多了。但一旦跑顺了后面省下的返工时间远超前期投入。几个实际用下来觉得最有价值的点需求澄清环节拦截了最多的问题很多次都是在这个环节发现需求理解有偏差避免了后面白写代码检查清单机制显著降低了低级错误尤其是空值处理和边界条件这类容易遗漏的地方工作流的分步验证让调试成本大幅下降不用在一大堆代码里大海捞针。如果让我给刚接触的人一个建议那就是从一个小任务开始只启用两三个核心技能跑通整个流程后再逐步增加。不要一上来就搞一套大而全的配置那样很容易被复杂度劝退。先用起来再慢慢调优这个顺序不能反。另外技能包不是写完就一劳永逸的。项目在变、需求在变、你自己的习惯也在变技能包需要跟着调整。我现在的做法是每个季度花一个小时回顾一遍所有技能包删掉过时的、补充新发现的坑、优化表达不清的步骤。这个维护成本不高但能让整套框架始终保持好用。