superpowers：为AI编程助手装上“上下文外挂”

做 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 编辑器，再有 superpowers

superpowers 不是一个独立工作的应用，它是在 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/Ctrl+Shift+P打开命令面板，输入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. 返回统一结构 Result<T>，错误码定义在 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这些校验注解；模板方法里调用了统一的Result<T>包装；业务逻辑乖乖放在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 常见问题速查表

另外补充一个我踩过的小坑：如果你同时装了多个 AI 扩展，superpowers 注入的上下文可能默认只对其中一个生效。我当时装了 Copilot 和 Continue，切到 Continue 发现技能不生效，翻设置才发现扩展配置里默认绑定了 Copilot。需要去设置文件里改一下defaultProvider之类的字段，把它指向你实际使用的那个 AI 插件。

6. 最后分享一个我自己的使用心法

试过不少提示词管理工具之后，我越来越觉得 superpowers 最厉害的点不是某个具体功能，而是它逼着你把“跟 AI 协作的规范”当成一等公民来维护。以前我总觉得 AI 表现不稳定是模型的问题，用了 superpowers 之后才明白，大部分不稳定来自上下文缺失——AI 每次都是“失忆”状态开始工作的，你指望它稳定发挥本来就很难。

我现在的工作流基本固定：每天早上先打开项目的.superpowers目录，花几分钟更新 skill 文件，把昨天遇到的新坑写进去，比如“这个模块的缓存键必须带版本号”“这个服务不允许直接写库”之类。等下次 AI 再碰到类似场景，它就会自动避开这些坑。

如果你刚开始接触，我建议你先别搞复杂。就写一个最简单的技能，把你们团队最重要的三条代码规范丢进去，跑通流程，感受一下 AI 输出的变化。等你把这套机制用顺手了，再慢慢往里面加东西。工具这东西，用起来才是真的好。