做 AI 辅助开发这两年我试过不少工具但真正让我觉得像给 Copilot、Codex 这类助手装上“外挂”的是 superpowers 这个 VS Code 扩展。它不是又一个聊天面板也不是什么代码生成模型而是一套把“你怎么跟 AI 描述需求”这件事结构化的系统。简单说它解决的是那种“AI 好像听得懂人话但总是差一点意思”的尴尬局面——你唠叨半小时它还是胡写别人用同样的模型三句话就拿到能跑的代码差别往往不在模型而在上下文管理。这篇文章我会把 superpowers 的安装、核心概念、实操流程和我在真实项目里踩过的坑一次讲完。不吹概念全是能直接抄作业的东西。适合正在用 Copilot、Codex、Continue 这类工具的开发者也适合想系统管理 AI 提示词、让团队 AI 产出更稳定的技术负责人。1. 先说清楚superpowers 到底是个什么东西1.1 它解决的核心痛点如果你跟我一样每天跟 AI 结对写代码大概率经历过这几个阶段。第一阶段是兴奋期觉得 AI 真能写什么需求丢过去都能给个差不多。第二阶段是怀疑期发现 AI 写十次有八次要修而且每次对话都像第一次认识你昨天说好的技术栈今天又忘干净了。第三阶段才是觉悟期——问题的根源不是模型不够聪明而是你给它的指令太随意、太零散、太没有体系。superpowers 这个扩展本质上是给 AI 对话加了一层“项目管理”能力。它把你想让 AI 遵循的规则、偏好、代码规范、架构约束全部拆成一个个可以被随时调用的“技能文件”然后在对话启动时按需注入给 AI。这样一来AI 每次开工前都能看到一份明确的“员工手册”而不是靠你现想现说。我第一次用的时候觉得这不就是提示词管理工具嘛市面上同类不少。但真正用下来发现它的设计逻辑不太一样别的工具是帮你写一条更好的提示词superpowers 是帮你建一整个可复用的技能库让提示词从“一次性口头交代”升级成“结构化知识资产”。这两者的差别就好比一个是让员工每次上班都听你重新讲一遍流程另一个是把操作手册钉在墙上谁来了照着做就行。1.2 它的本质把“口头嘱咐 AI”变成“结构化技能库”你可以把 superpowers 想象成一个 AI 的“入职培训系统”。传统的 Copilot 用法是你在对话框里打“帮我写一个用户登录接口用 Spring Boot注意参数校验”AI 就照着这句话自由发挥。superpowers 的做法是你先写好一个文档里面详细定义了什么叫“好的登录接口”——包括项目用的框架版本、包结构规范、异常处理方式、返回体格式、甚至代码注释风格。然后在需要的时候通过一条斜杠命令或者快捷键把这个文档“喂”给 AI。这套机制绕开了很多 AI 编程工具共同的问题上下文窗口有限。你的项目可能有几百个文件、几十条规范AI 不可能全部记住。superpowers 的解决方案是“按需加载”——你需要写接口的时候只给它接口相关的规范你需要写测试的时候再给测试相关的规范。这样每一轮对话里AI 看到的信息都是高密度、强相关的产出的代码质量自然会上去。而且它跟具体模型绑定不强Copilot、Codex、Continue、Cline 这些都能接。核心这层逻辑是自己实现的把技能文件转成系统提示词的一部分在对话开始前注入。理解了这一点你就明白了为什么它叫 superpowers——不是模型变强了是模型每次出手前脑子里的“上下文”变强了。2. 安装与环境准备5 分钟跑通第一版2.1 前置依赖先有 AI 编辑器再有 superpowerssuperpowers 不是一个独立工作的应用它是在 VS Code 里给 AI 编程助手“加 buff”的扩展。所以第一步你得先装好一个能对话的 AI 插件比较常见的是 GitHub Copilot、OpenAI Codex 扩展或者 Continue 这类开源方案。我自己主力用的是 Codex 扩展也在 Copilot 上试过都能正常工作。装好 AI 插件之后再在 VS Code 扩展市场里搜“superpowers”。注意认准作者和图标这个项目是社区开发者 obra 发起的全名就叫 Superpowers扩展 ID 大致的格式是charmbracelet.superpowers你在应用商店直接搜 superpowers 一般第一个就是。这里有个小的坑别装到那种波浪线很多的仿冒插件装完发现命令面板里找不到 Swifty 开头的那几个命令基本就装错了。还需要确认你的 VS Code 版本不要太老建议 1.80 以上因为扩展内部用了不少较新的 API。装完扩展记得重启一下编辑器窗口让扩展正确激活。2.2 初始化工作区创建 .superpowers 目录装好后打开你的项目根目录按Cmd/CtrlShiftP打开命令面板输入Swifty: Initialize这是 superpowers 的核心命令。执行之后它会在你的项目根目录下创建一个.superpowers/文件夹里面自带一套基本的技能模板和配置文件。这一步做完你就能在文件树里看到类似这样的目录结构不同版本略有差异但主体一致.superpowers/ ├── skills/ # 技能文件目录所有技能以 Markdown 格式存放 │ ├── frontend.md # 前端开发相关规范与指令 │ └── patterns.md # 架构模式与代码风格约定 ├── context/ # 上下文目录放你想让 AI 自动阅读的全局文档 │ └── project.md # 项目说明、技术栈、目录结构等 └── config.json # 扩展的配置包含启用的 AI 插件等这个目录本质上是“项目级设置”只对当前项目生效。如果你在多个仓库里工作每个仓库都可以有自己的 superpowers 配置互不干扰。这一点我很喜欢——它不搞全局那种一刀切不同项目的规范本来就不一样混着来反而难受。2.3 验证安装效果初始化完成后最简单的验证方式是打开命令面板输入Swifty: List Skills。如果能看到扩展内置的几个示例技能比如“代码审查”“测试生成”之类的说明安装成功。这一步我建议立刻测试一下随便打开一个代码文件让 AI 帮你审查代码然后观察对话的开头。如果你用的 Codex 扩展打开对话面板后会看到 superpowers 自动在消息里注入了一段隐藏的系统提示里面包含了你在技能库里启用的文件内容。用 Copilot 的 Chat 面板也一样它不会显示这些注入内容但生成结果明显更“懂”你的项目。第一次看到效果的时候我还是挺惊讶的——同一段代码没用技能前 AI 给的建议比较泛用了技能之后它直接指出我哪里不符合项目既有的封装规范说明上下文确实生效了。3. 核心功能拆解skills、上下文目录与折叠注释3.1 skills 技能机制把规则写成文件随用随取技能Skill是 superpowers 最核心的概念。一个技能就是一个 Markdown 文件里面写的是你希望 AI 在某类任务中遵循的指令。命名无所谓关键是文件头部的 YAML 元信息和正文内容元信息里定义了技能的描述、适用场景等AI 会通过这份描述来判断“当前任务该不该激活这个技能”。举个例子我在一个 Java 后端项目里写了个技能文件内容大致长这样已经简化过--- name: java-interface-guard description: 当用户要求编写或修改 Controller / Service 接口时使用 when_to_use: 涉及 REST API、参数校验、异常返回 tags: - java - spring --- ## 接口编写规范 1. 所有入参使用 DTO 对象接收不允许直接使用 Map。 2. 参数校验使用 jakarta.validation 注解分组校验按场景拆分。 3. 返回统一结构 ResultT错误码定义在 ErrorCode 枚举中。 4. Controller 层只做参数装配和路由业务逻辑全部下沉到 Service。 5. 方法级注释说明业务含义禁止复制粘贴式注释。写好保存后AI 在会话中收到相关需求时比如你说“帮我写个查询订单的接口”superpowers 会把这个技能文件的内容注入到系统提示里于是 AI 从第一步起就知道要用 DTO、要返回 Result、逻辑要放 Service。它不是靠“猜”你的规范而是直接把规范原文喂给了模型。你可能会问这样会不会跟 AI 自己的判断冲突我实测下来基本不会。因为技术规范这种东西本来就没有绝对的对错关键是团队统一。superpowers 只是让“统一”这件事变得可维护了——规范变了改一个 Markdown 文件就行不用每次对话前重新交代。3.2 上下文目录全局背景信息一次喂全除了按需触发的技能superpowers 还支持一个“上下文目录”的概念。放在.superpowers/context/下的文件会在每次 AI 对话初始化时被自动加载相当于给 AI 一份“常驻记忆”。适合放什么项目背景说明、技术栈清单、目录结构、编码约定、甚至你希望 AI 默认使用的语言风格。比如我会在 context 里放一段项目简介告诉 AI 这是个支付网关服务依赖 Spring Cloud 体系API 风格偏 RESTful 而非 RPC当前迭代重点是交易对账模块。这样一来每一次对话 AI 都天然知道自己在哪个项目里、什么技术栈、当前做什么方向而不是每次都靠你临时打字“我们这是个支付项目”。这里有个平衡点要把握好context 不是越大越好。上下文窗口是有限的你塞二十页背景文档进去真正关键时刻的代码生成反而没空间了。我个人的建议是context 目录只放那种“每轮对话都需要的”背景信息其他细节放到技能里按需触发。好钢用在刀刃上AI 的注意力也一样。3.3 折叠注释让 AI 聚焦“需要改的那几行”折叠注释fold comments是 superpowers 里一个很实用的细节功能。它的原理是当你在代码文件里用特定的注释格式标记某些区域后AI 在读取文件时会默认隐藏折叠这些区域从而把注意力集中在当前任务相关的代码段上。举个例子假设一个文件有 500 行你只想让 AI 修改其中第 120 到 180 行的方法。你可以在方法上下用注释标记范围告诉 superpowers“只关注这个块”。AI 就不会被前后几百行的无关逻辑干扰修改的准确率会高不少。它解决的问题非常真实——AI 在长文件里经常“找不着重点”改了 A 处的代码结果被 B 处无关逻辑带偏最终给你来个混合体。我自己的习惯是想让 AI 帮忙重构一个方法时先把方法用折叠注释包起来然后让 AI 只看这块。效果立竿见影修改前后对比比整文件让 AI 瞎猜要稳得多。折叠注释的具体语法版本间可能略有差异你在命令面板搜Swifty: Toggle Fold相关命令就能用上用着用着会形成肌肉记忆。4. 实操案例用 superpowers 驱动一个 Java 接口生成4.1 先写技能文件再生成代码这一节我用一个实际的项目片段来说明完整流程里面也正好覆盖了你在搜索词里看到的superpowers java这类场景看看技能机制到底怎么在工作中落地。假设我现在接到一个任务在 Spring Boot 项目里新增“创建优惠券”的后端接口。过去我的做法是打开对话框噼里啪啦把需求打给 AI然后等着它生成一坨代码再花半小时改规范。用了 superpowers 之后流程变成这样先在.superpowers/skills/下新建一个coupon-api.md写清楚优惠券接口的专属约束。比如优惠券编码必须唯一、创建时要校验时间范围和库存上限、需要一个幂等键防止重复提交、异常必须走全局错误码等等。这个文件一次写好以后所有优惠券相关的开发都能复用。然后回到代码文件里把光标放在要写代码的位置打开 AI 对话输入类似“根据技能里的规范帮我写创建优惠券的 Controller 和 Service”。superpowers 会自动匹配并注入coupon-api.md里定义的规则。4.2 生成结果的对比有没有技能差别很大同样的模型、同样的需求描述有技能和没技能生成的结果差别在细节上体现得很明显。没技能的时候AI 经常写一个贫血的 Controller直接在里面堆业务逻辑返回结构五花八门校验注解也时有时无。有技能注入后AI 生成的 Controller 层代码干净利落接收的CreateCouponRequestDTO 上自动加了NotBlank、Future、DecimalMin这些校验注解模板方法里调用了统一的ResultT包装业务逻辑乖乖放在CouponService里事务注解也带上了。这里我不放完整的业务代码了不同项目的规范差别太大但你可以试试对比——同一句话技能开启前后的输出会有肉眼可见的差异。我多次实测下来带技能的版本平均需要人工修正的次数少很多尤其是命名一致性、异常处理、分层边界这三类最容易出问题的地方。4.3 参数调整匹配你的实际项目版本技能文件不是固定的模板里面定义的规范越符合你项目的真实情况AI 的表现越好。我建议你把下面这些信息放到技能里优先级从高到低项目的基础框架和版本比如 Spring Boot 3.2、MyBatis-Plus 3.5包结构的组织方式比如 controller / service / mapper 分层统一返回体和错误码的定义位置数据库操作层的使用约定比如禁止手写 JDBC、必须走 MyBatis 注解日志规范比如必须用 SLF4J 占位符禁止字符串拼接测试类命名规范和断言风格把这些写清楚之后AI 生成的代码几乎就是照着你们团队的代码规范“填空”而不是自由创作。当然你不需要一次全写完先写最常踩的几条也行慢慢迭代。我自己的技能库就是从一页纸的规范慢慢长成几十条细则的知识沉淀是个渐进的过程。5. 常见问题与排查技巧实录5.1 AI 没有调用技能怎么办这个问题几乎每个新手都会遇到技能写好了但 AI 好像根本不看回答内容跟没用 superpowers 一模一样。先检查技能文件的description字段写的是否清晰。AI 是根据描述来判断“现在该不该用这个技能”的如果描述太空泛比如只写“Java 技能”它很难跟你的具体需求关联上。改成“当用户要求编写或修改 Spring 相关的 Controller、Service、Mapper 代码时使用”这种带触发场景的描述命中率会高很多。再一个常见原因是技能文件本身有语法错误。YAML 的元信息块解析失败时整个技能会被静默忽略而且 VS Code 不一定会报错。我遇到过一次少了行首冒号排查了半天才发现。建议每次写完技能文件用命令面板里的Swifty: List Skills确认一下技能是否出现在列表里看不到就说明解析出了问题。5.2 技能文件太长上下文爆炸怎么办技能写太多太细每个都几万字AI 的上下文会被淹没反而影响生成质量。这个问题没有银弹只能靠归类。把使用频率高的技能做成“轻量版”只写最关键、最容易出错的约束比如 10 条以内。那些很少用到的深层规范拆成独立文件用到的时候再通过命令临时加载。把项目背景常驻信息与任务级规范分成两个目录保存避免 context 被无关内容塞满。我个人的经验是一个项目同时启用的技能数量控制在 5 个以内总字数控制在 3000 字左右。超出这个量级的要么说明规范本身太啰嗦要么说明你该给技能分组了而不是追求“一次全喂给 AI”。5.3 多项目之间技能共享公司里可能有多个项目共用同一套代码规范但每个项目又是独立的 Git 仓库、独立的.superpowers目录。如果每个项目都复制一份技能文件维护起来就是灾难——改了规范要挨个仓库同步。我的做法是在团队内部维护一个“技能模板仓库”里面放公共技能新项目初始化时用命令把它复制到各自的.superpowers目录。至于那些跟具体项目强相关的规范比如业务约束、模块划分那就不应该共享留在项目自己的目录里。公共技能和项目私有技能分开放既保证一致性又保留灵活性。这一步最好配合 Git 子模块或者直接复制粘贴怎么方便怎么来。5.4 常见问题速查表现象可能原因处理方法技能列表里看不到新增的文件YAML 元信息语法错误检查文件头部的name和description字段格式AI 完全不使用技能description 太模糊触发条件不明确重写描述加上具体的触发场景关键词启用技能后 AI 输出变啰嗦技能文件内容过多精简技能只保留核心约束或者拆分技能上下文注入无效AI 插件版本过旧或不兼容升级 AI 插件和 VS Code确认扩展激活多个技能互相冲突不同技能规范观点不一致检查技能内容明确优先级规则项目初始化后没有.superpowers目录初始化命令没有执行成功重开工作区重新执行Swifty: Initialize另外补充一个我踩过的小坑如果你同时装了多个 AI 扩展superpowers 注入的上下文可能默认只对其中一个生效。我当时装了 Copilot 和 Continue切到 Continue 发现技能不生效翻设置才发现扩展配置里默认绑定了 Copilot。需要去设置文件里改一下defaultProvider之类的字段把它指向你实际使用的那个 AI 插件。6. 最后分享一个我自己的使用心法试过不少提示词管理工具之后我越来越觉得 superpowers 最厉害的点不是某个具体功能而是它逼着你把“跟 AI 协作的规范”当成一等公民来维护。以前我总觉得 AI 表现不稳定是模型的问题用了 superpowers 之后才明白大部分不稳定来自上下文缺失——AI 每次都是“失忆”状态开始工作的你指望它稳定发挥本来就很难。我现在的工作流基本固定每天早上先打开项目的.superpowers目录花几分钟更新 skill 文件把昨天遇到的新坑写进去比如“这个模块的缓存键必须带版本号”“这个服务不允许直接写库”之类。等下次 AI 再碰到类似场景它就会自动避开这些坑。如果你刚开始接触我建议你先别搞复杂。就写一个最简单的技能把你们团队最重要的三条代码规范丢进去跑通流程感受一下 AI 输出的变化。等你把这套机制用顺手了再慢慢往里面加东西。工具这东西用起来才是真的好。