1. 从“superpowers”这个热词说起它到底是什么最近一段时间“superpowers”这个词在技术社区和效率工具圈子里被反复提及很多人第一次看到它是在某个开源项目的讨论区或者是在朋友转发的一条“效率翻倍”的分享里。紧接着就冒出一堆问题“superpowers是什么”、“想要安装superpowers”、“这东西装完能干嘛”。我一开始也以为又是哪个新出的浏览器插件或者系统增强工具花了两天时间把它的来龙去脉摸了一遍又在自己两台机器上完整跑通了安装和配置流程才敢下笔写这篇东西。先把结论摆在前面superpowers 本质上是一套面向 AI 编程助手的能力扩展框架它本身不是一个独立软件而是依附在已有的 AI 编码工具之上通过注入一套结构化的“技能包”和“工作流约束”让原本只会聊天的助手变成能按规范干活的工程搭档。你可以把它理解成给一个刚入职的实习生发了一本《团队开发手册》外加一整套模板文件——人还是那个人但产出质量完全不一样了。它解决的问题非常具体大部分人在用 AI 写代码时遇到的最大痛点不是“它不会写”而是“它写得太随意”。你让它加个功能它一口气给你生成三百行变量命名风格前后不一致边界条件全靠猜测试用例一个没有最后你还得花比手写更多的时间去审查和返工。superpowers 的思路就是把这些“随意”用一套明确的规则和流程框住让 AI 在动手之前先想清楚要做什么、怎么做、做完怎么验证。适合谁来参考这篇内容三类人最值得往下看第一类是日常已经在用 AI 辅助编码、但总觉得产出不够稳定的开发者第二类是团队里负责制定开发规范、想让 AI 生成代码符合内部标准的技术负责人第三类是对 AI 工作流设计本身感兴趣、想看看别人是怎么把提示词工程做成一套可复用体系的学习者。哪怕你暂时不打算安装理解它的设计思路对你自己调教 AI 助手也有直接帮助。2. 核心设计思路拆解为什么是“技能包”而不是“更长的提示词”2.1 一个关键判断提示词堆得越长效果反而越差很多人调教 AI 的第一反应是写一个超长的系统提示词把能想到的规则全塞进去。我早期也这么干过结果发现两个问题一是模型对超长提示词的注意力是衰减的排在后面的规则基本被忽略二是不同任务需要的规则完全不同写代码要强调测试写文档要强调结构你没法用一套提示词同时满足所有场景。superpowers 的做法是把能力拆成一个个独立的“技能包”每个技能包只负责一类任务比如“写单元测试”、“做代码审查”、“设计数据库表结构”。当你需要某个能力时只加载对应的技能包提示词上下文保持精简模型对当前任务的专注度就上来了。这个思路其实和微服务架构很像——不是把所有逻辑塞进一个巨型单体应用而是拆成职责单一的小服务按需调用。2.2 技能包的内部结构不只是提示词还有流程和检查点我拆开看了几个技能包的内容发现它并不是简单的一段文字说明而是包含三个层次角色定义层明确告诉 AI 在这个技能下它扮演什么角色比如“你是一名有十年经验的测试工程师”这个设定会显著影响输出的语气和严谨程度。流程约束层规定做这件事必须按什么步骤走比如写测试必须先列出所有边界条件再逐个写用例最后检查覆盖率。这一步是防止 AI 跳步的关键。输出模板层给出最终产出的格式要求包括文件命名、注释风格、提交信息格式等保证不同时间、不同任务产出的东西风格统一。这三层叠在一起才构成一个完整的技能包。我实测下来只加角色定义效果提升大概两成加上流程约束能到五成三层齐全之后产出质量基本能稳定在一个可用的水平线上。2.3 为什么选择“注入式”而不是“独立运行”有人可能会问为什么不干脆做一个独立的 AI 编程工具非要以插件或配置的形式依附在现有工具上我的理解是成本和生态两个原因。独立工具意味着要自己处理模型调用、上下文管理、文件读写、版本控制集成这一大堆脏活累活而现有的 AI 编码工具已经把这些问题解决得差不多了。superpowers 只做自己最擅长的那部分——定义“怎么干活”把“用什么干活”交给底层工具这是一种很务实的取舍。从使用者角度看这也降低了迁移成本。你不需要换掉已经用顺手的编辑器或助手只需要在现有配置里加一层技能包加载逻辑就行。我自己的配置就是在原有基础上加了不到二十行没有动任何核心设置。3. 安装前的准备工作别急着敲命令先把这几件事理清楚3.1 确认你的底层工具支持扩展机制superpowers 不是万能的它依赖底层 AI 编码工具提供的能力注入接口。目前主流的两类工具支持程度比较好一类是支持自定义指令文件或规则文件的编辑器插件另一类是提供系统提示词覆盖或扩展点的命令行助手。你在安装之前先确认自己用的工具属于哪一类以及它的扩展接口文档在哪里。我踩过的一个坑是早期版本的某个工具虽然号称支持自定义规则但实际上规则文件的加载优先级低于内置提示词导致技能包被覆盖怎么调都没效果。后来升级到新版本才解决。所以建议你先去工具的官方文档里搜一下“自定义指令”、“规则文件”、“扩展点”这几个关键词确认接口存在且可用。3.2 检查你的工作目录结构技能包通常需要放在一个固定的目录下才能被正确加载不同工具的约定不一样。常见的有放在项目根目录的.ai或.assistant文件夹下也有放在用户主目录的全局配置文件夹里的。你需要先确定两件事一是放全局还是放项目级二是目录名称和层级要求。我的建议是通用技能包放全局项目专属技能包放项目级。比如“代码审查”这种哪个项目都用得上的放全局“这个项目的数据库表命名规范”这种只对当前项目有效的放项目级。这样既保证通用能力随时可用又不会让项目配置污染全局环境。3.3 准备好版本管理这一点很多人会忽略。技能包本质上是一堆文本配置文件你调教它的过程就是不断修改这些文件的过程。如果没有版本管理改坏了想回退都回不去。我的做法是给全局技能包目录单独建一个 Git 仓库每次调整都提交一次提交信息写清楚改了什么、为什么改。项目级的技能包就跟着项目仓库一起管理。提示技能包的调整是一个迭代过程不要指望一次配置就达到理想效果。有版本记录你才能对比不同配置的实际产出差异逐步逼近最优解。4. 完整安装与配置实操从零到跑通的全流程4.1 获取技能包文件技能包的分发方式通常有两种一种是通过包管理器安装一种是从代码仓库直接克隆。包管理器的方式更省心但版本更新可能滞后直接克隆的方式能拿到最新内容但需要自己处理依赖和更新。我选择的是直接克隆到本地一个固定目录然后用软链接的方式链接到各个工具的配置目录。这样做的好处是技能包本体只有一份更新的时候只需要在克隆目录里拉取最新代码所有链接过去的工具自动生效不用每个工具单独更新。# 假设你把技能包克隆到用户主目录下的 ai-skills 文件夹 git clone 技能包仓库地址 ~/ai-skills # 进入目录查看结构 cd ~/ai-skills ls -la克隆完成后你会看到类似skills/、templates/、config/这样的目录结构。skills下面按技能名称分子目录每个子目录里通常有一个主定义文件可能是 markdown 或 yaml 格式和若干辅助文件。4.2 配置底层工具的加载路径这一步是安装过程中最容易出问题的环节。不同工具的配置方式差异很大我以最常见的“规则文件加载”模式为例说明思路。假设你的工具支持在配置文件中指定额外的规则目录你需要找到那个配置文件通常叫config.json、settings.yaml或类似的名字。在里面找到类似rulesPaths、instructionDirs、skillDirectories这样的字段把技能包目录的路径加进去。{ assistant: { instructionDirs: [ ~/ai-skills/skills ], loadStrategy: on-demand } }这里有个关键参数loadStrategy我强烈建议设为按需加载而不是全部加载。全部加载会把所有技能包的提示词一次性塞进上下文既浪费 token 又稀释注意力。按需加载则是根据当前任务类型自动匹配相关技能包效果明显更好。4.3 验证加载是否成功配置改完之后不要急着干活先做一次验证。最简单的办法是问 AI 一个和某个技能包相关的问题看它的回答风格是否发生了变化。比如你加载了“代码审查”技能包就问它“帮我审查这段代码”如果它开始按“边界条件、命名规范、测试覆盖”这样的结构化方式回答说明加载成功了。如果没变化按这个顺序排查配置文件路径对不对、目录权限够不够、技能包文件格式是否符合工具要求、工具版本是否支持该扩展点。我遇到过一次是文件编码问题技能包文件是 UTF-8 带 BOM 的工具解析不了改成不带 BOM 的 UTF-8 就好了。4.4 按需启用与禁用技能包跑通之后你会发现同时启用太多技能包反而会让 AI 变得犹豫不决因为它不知道该优先遵循哪套规则。我的做法是维护一个“当前激活列表”只把最近常用的三到五个技能包设为激活状态其他的保持可用但不加载。具体操作方式取决于工具有的支持在对话开头用命令切换有的需要手动改配置文件。我用的工具支持在项目根目录放一个.active-skills文件里面每行写一个技能包名称工具启动时读取这个文件决定加载哪些。这个机制很灵活不同项目可以有不同的激活组合。5. 核心技能包详解与参数调优5.1 代码生成技能包约束越具体产出越可控代码生成是最常用的技能包也是调优空间最大的一个。默认配置下它已经能保证基本的命名规范和注释风格但如果你有更具体的要求可以在技能包定义里追加项目专属规则。我自己的做法是在项目级技能包里加了一段关于“错误处理”的约束所有外部调用必须有超时设置所有可能为空的返回值必须显式判断所有异常必须记录日志且日志里包含请求标识。加上这三条之后AI 生成的代码在健壮性上提升非常明显以前经常出现的“裸调用”基本消失了。参数方面我建议关注两个一是maxRetries控制 AI 在生成失败时的重试次数设太高会浪费时间设太低容易半途而废我一般设 2二是contextWindow控制加载多少上下文信息设太大拖慢速度设太小信息不足我一般设 8000 到 12000 之间具体看任务复杂度。5.2 代码审查技能包把团队规范变成可执行的检查项代码审查技能包的价值在于把“老员工脑子里的经验”变成“AI 可以执行的检查清单”。我在配置里把团队积累的审查要点逐条翻译成了检查项比如“数据库查询必须走索引”、“接口返回必须包含错误码”、“敏感字段必须脱敏”。这里有个技巧检查项要写成“可判定”的形式不要写“代码应该优雅”这种模糊表述要写“单个函数不超过 50 行”、“嵌套层级不超过 3 层”这种有明确标准的。AI 对可量化标准的执行准确率远高于模糊描述。5.3 测试生成技能包先列边界再写用例测试生成是我觉得提升最明显的一个技能包。默认情况下 AI 写测试就是顺着正常流程写一遍边界条件基本靠运气。加载技能包之后它会强制先输出一个边界条件清单包括空值、极值、并发、异常输入等然后针对每个边界条件写对应用例。我实测对比过同一个函数不加载技能包生成的测试覆盖率大概在 60% 左右加载之后能到 85% 以上而且遗漏的边界明显减少。这个提升在涉及金额计算、权限判断这类逻辑上尤其重要。5.4 技能包之间的优先级与冲突处理当你同时加载多个技能包时可能会遇到规则冲突。比如代码生成技能包说“函数尽量短”测试生成技能包说“测试用例要覆盖所有分支”一个测试函数可能因为分支太多而变得很长。这时候需要定义优先级。我的处理原则是安全相关规则优先级最高其次是可维护性规则最后是风格类规则。具体到配置里可以在每个技能包定义中加一个priority字段数值越大优先级越高。冲突时高优先级规则覆盖低优先级规则。这个机制需要底层工具支持如果不支持就只能靠手动调整技能包内容来避免冲突。6. 实操过程中遇到的典型问题与排查记录6.1 技能包加载了但完全不生效这是最常见的问题我遇到过三次原因各不相同。第一次是路径写错了用了相对路径但工具的工作目录和我想的不一样第二次是文件权限问题技能包目录对当前用户不可读第三次是工具缓存了旧的配置需要重启才生效。排查顺序建议这样走先确认路径是绝对路径且存在再确认文件权限是 644 或 755然后重启工具清缓存最后检查工具日志里有没有加载相关的报错信息。大部分情况前三步就能解决。6.2 技能包生效了但产出风格不稳定有时候同一个技能包上午用和下午用效果不一样或者换个项目就不行了。这种情况通常是上下文污染导致的——之前的对话内容还在上下文里干扰了技能包的规则执行。解决办法是在切换任务类型时开新对话或者用工具提供的“清空上下文”功能。我养成的习惯是写代码、写测试、做审查这三类任务之间一定开新会话不混在一起。混着用的时候 AI 会试图同时满足多套规则结果哪套都没执行好。6.3 多个技能包互相干扰前面提到过优先级机制但实际用下来发现光靠优先级还不够。有些干扰是隐性的比如两个技能包都定义了“输出格式”一个要求用 markdown 表格一个要求用列表AI 会随机选一个导致产出格式飘忽不定。我的应对策略是功能重叠的技能包不要同时激活。比如你已经有代码生成技能包了就不要再单独加载一个“代码注释生成”技能包把注释要求合并到代码生成技能包里就行。技能包数量控制在五个以内超过之后管理成本急剧上升。6.4 常见问题速查表问题现象可能原因排查动作解决方式技能包完全不生效路径错误、权限不足、缓存未清检查绝对路径、文件权限、重启工具修正路径、改权限、清缓存重启产出风格不稳定上下文污染、多技能包冲突检查当前会话历史、检查激活列表开新会话、减少同时激活的技能包规则执行不完整提示词过长、优先级未定义检查技能包内容长度、检查优先级配置精简技能包、设置优先级字段加载后工具变慢加载策略为全部加载检查 loadStrategy 配置改为按需加载更新技能包后无变化软链接失效、工具未重载检查软链接指向、手动重载配置重建软链接、重启工具7. 进阶玩法把 superpowers 用出你自己的风格7.1 从“用别人的技能包”到“写自己的技能包”用了一段时间之后你会发现通用技能包只能解决八成问题剩下两成是你所在领域或团队特有的。这时候就该动手写自己的技能包了。写技能包不需要编程基础本质上就是写一份结构化的说明书。我的第一个自建技能包是“接口文档生成”因为团队对接口文档的字段说明有特殊要求。写的时候参考了现有技能包的结构把角色定义、流程约束、输出模板三层都填上大概花了四十分钟之后每次生成接口文档都能省下十几分钟的手动调整时间。7.2 技能包的版本管理与团队共享个人用的时候版本管理可以随意一点但如果是团队共享就需要一套约定。我的做法是技能包仓库设一个主分支存放稳定版本每个人在自己的分支上实验新规则验证有效之后提合并请求由负责人审核后合入主分支。审核的重点是看新规则是否和现有规则冲突、是否过于具体导致适用范围太窄、是否有明确的判定标准。我见过有人写了一条“代码要写得漂亮”这种规则合进去只会让 AI 困惑必须打回去重写成可判定的形式。7.3 根据项目阶段动态调整技能包组合同一个项目在不同阶段需要的技能包组合是不一样的。项目初期以快速原型为主代码生成技能包可以放宽约束优先保证速度项目中期进入功能完善阶段测试生成和代码审查技能包的权重就要提上来项目后期临近发布需要加上“发布检查”技能包强制检查版本号、变更日志、配置项这些容易遗漏的东西。我现在的做法是在项目根目录维护一个skills-by-phase目录里面按阶段分文件夹存放不同的激活列表切换阶段时只需要改一个软链接指向就行。7.4 技能包与自动化流程的结合如果你已经把技能包用顺了可以考虑把它接入自动化流程。比如在提交代码前自动触发一次代码审查技能包把审查结果作为提交的附件或者在生成测试用例后自动运行覆盖率检查不达标就阻止合并。这一步需要底层工具支持命令行调用或 API 调用。我目前只做到了半自动——手动触发审查然后把结果贴到提交信息里全自动还在摸索中。但即便只是半自动也已经把很多低级问题挡在了代码审查之前。8. 一些个人体会和后续可以尝试的方向我在两台机器上完整跑了一遍安装配置流程又用了一个多月做日常开发最大的感受是superpowers 这类工具的价值不在于让 AI 变得更聪明而在于让 AI 变得更“守规矩”。聪明程度是模型本身决定的你改不了但守不守规矩是工作流决定的这个你可以控制。把可控的部分做到极致整体产出质量就能上一个台阶。踩过的坑主要集中在配置环节技能包本身反而没出过什么大问题。所以如果你准备安装我的建议是把八成精力花在确认底层工具的扩展机制和路径配置上剩下两成用来挑选和调整技能包内容。配置对了后面就是一马平川。后续我打算尝试的方向有两个一是把技能包和项目的代码规范检查工具打通让 AI 生成的代码直接过一遍 lint不通过就自动重写二是针对我们团队特有的业务领域写一套领域专用技能包把那些“只有老员工才知道的坑”固化进去。这两个方向如果有进展我会再整理出来分享。