1. 从“superpowers”这个热词说起它到底指什么“superpowers”这个词最近在技术社区和效率工具圈子里被反复提起很多人第一次看到它会下意识联想到漫威电影里的超能力但在当前的技术语境下它指的是一套围绕AI 编程助手能力扩展的方法论与工具集合。简单来说它试图解决一个非常具体的痛点大语言模型在写代码时往往缺乏对项目上下文、历史决策和团队规范的持续记忆导致每次对话都像“重新认识你一遍”。而 superpowers 这套思路就是通过结构化的技能定义、上下文注入和任务编排让 AI 助手在特定项目里表现得像是“开了挂”。我第一次接触这个概念是在一个前端重构项目里。当时团队用 AI 辅助生成组件代码效率确实有提升但问题也很明显生成的代码风格不统一、重复引入已经废弃的工具函数、对业务字段的命名习惯完全无视。后来有人提出能不能把项目的“规矩”提前告诉 AI让它每次生成之前先读一遍这个朴素的想法其实就是 superpowers 类工具的核心逻辑——把隐性的工程知识显性化再喂给模型。这篇文章适合几类人看一是已经在日常开发中重度使用 AI 编程助手但觉得“不够顺手”的工程师二是团队技术负责人想统一 AI 生成代码的质量标准三是对 AI 工作流感兴趣想了解如何把零散提示词沉淀为可复用资产的产品或运营同学。我会从核心机制、安装配置、技能编写、实战踩坑几个角度展开尽量把每个环节的“为什么”讲清楚让你看完能直接上手搭一套自己的 superpowers 工作流。需要提前说明的是superpowers 并不是某一个具体的商业产品而更像是一种模式。市面上有多个开源项目和个人实现都在用这个名字或类似概念它们的共同点是通过文件系统或配置层为 AI 助手提供可检索、可组合的“技能包”。所以你在搜索“想要安装 superpowers”时可能会看到不同的仓库和教程这很正常。关键是理解它的运作原理这样无论你选哪个实现都能快速迁移。2. superpowers 的核心机制技能包、上下文注入与任务编排2.1 技能包不是提示词模板而是带元数据的知识单元很多人第一次听说 superpowers会以为它就是“把提示词存成文件”。这个理解只对了一半。普通的提示词模板通常是纯文本比如“你是一个资深前端工程师请帮我写一个 React 组件”。而 superpowers 里的技能包往往包含几个关键部分触发条件、执行步骤、依赖工具、输出格式约束、以及失败回退策略。举个例子一个名为“生成符合团队规范的 API 请求函数”的技能包可能会这样定义当用户提到“新增接口调用”时触发执行步骤包括读取项目中的request.ts封装、检查是否有同名字段已存在、按照useXxxQuery的命名模式生成代码依赖工具是文件读取和代码搜索输出格式要求返回 TypeScript 代码块并附带字段映射说明。这种结构化的定义让 AI 助手不再是“随机发挥”而是按照预设的工程路径去执行。我自己的做法是把技能包分成三层基础层如代码格式化、提交信息生成、领域层如特定业务模块的 CRUD 生成、项目层如某个老系统的兼容性处理。基础层可以跨项目复用领域层和项目层则跟着仓库走。这样既保证了通用能力又不会让技能包变得臃肿。2.2 上下文注入的关键在于“按需检索”而非“全量塞入”大语言模型的上下文窗口是有限的即使现在动辄 128K 甚至更大把整个项目的代码都塞进去也是不现实的——成本高、噪音大、模型反而容易迷失重点。superpowers 类工具通常采用按需检索的策略根据当前任务的关键词从技能库和项目文件中动态拉取最相关的片段。具体实现上常见的有两种路径。一种是基于文件路径的约定比如把所有技能放在.ai/skills/目录下每个技能一个 Markdown 文件文件名就是技能 ID。当用户输入任务时工具会根据关键词匹配文件名和文件内容选出 Top N 个技能注入上下文。另一种是基于向量检索把技能描述和项目文档做嵌入用相似度搜索来召回。前者简单直接适合中小项目后者更灵活但需要额外的嵌入模型和向量库。我在实际使用中更倾向于第一种原因是可解释性强。当 AI 生成结果不符合预期时我可以直接去看它加载了哪些技能文件快速定位是技能写错了还是检索没匹配上。向量检索虽然召回率高但排查问题时要多绕一层对于追求稳定性的工程场景简单方案往往更可靠。2.3 任务编排让多个技能按顺序协同单个技能能解决的问题有限真正体现 superpowers 价值的是任务编排。比如“新增一个完整的业务模块”这个任务可以拆解为读取数据库 Schema → 生成 TypeScript 类型定义 → 生成 API 请求函数 → 生成表单组件 → 生成列表页面 → 生成单元测试。每个步骤对应一个技能编排层负责按顺序调用并把上一步的输出作为下一步的输入。这里有个容易忽略的细节步骤之间的数据传递格式。如果上一步输出的是自然语言描述下一步很难稳定解析。所以我在定义技能时会强制要求输出结构化数据比如 JSON 或特定格式的代码块。编排层只负责传递这些结构化片段而不是让模型去“理解”上一段的散文。这样做的好处是整个流程的确定性大幅提升即使中间某一步需要人工确认也能快速定位到具体环节。3. 安装与配置从零搭一套可用的 superpowers 环境3.1 选择适合你的实现方案前面提到superpowers 不是单一产品所以“安装”这个词需要拆开看。目前主流的落地方式有三种我列个表对比一下你可以根据自己的技术栈和团队情况选。方案类型典型形态优点缺点适合人群编辑器插件型VS Code / JetBrains 插件开箱即用与 IDE 深度集成自定义能力受插件限制个人开发者、小团队命令行工具型CLI 配置文件灵活可脚本化易集成 CI需要一定命令行基础有自动化需求的团队自建服务型本地服务 API 调用完全可控可对接内部系统维护成本高中大型团队、有平台能力我个人的建议是如果你只是想让 AI 助手在写代码时更懂你的项目先从编辑器插件型入手把技能文件放在项目根目录的.ai/文件夹里大多数插件都能识别。等用顺了再考虑迁移到 CLI 或自建服务。不要一上来就追求“大而全”那样很容易在配置阶段就耗尽耐心。3.2 目录结构与配置文件的最小可用示例不管选哪种方案目录结构的约定是通用的。下面是我在多个项目中沉淀下来的最小结构你可以直接复制project-root/ ├── .ai/ │ ├── skills/ │ │ ├── base-format.md │ │ ├── api-generator.md │ │ └── component-generator.md │ ├── context/ │ │ ├── project-overview.md │ │ └── coding-standards.md │ └── config.json ├── src/ └── package.jsonconfig.json里主要配置几个东西技能目录路径、上下文文件路径、每次注入的最大技能数量、以及是否开启自动检索。一个典型的配置长这样{ skillsDir: .ai/skills, contextFiles: [.ai/context/project-overview.md, .ai/context/coding-standards.md], maxSkillsPerRequest: 3, autoRetrieve: true, retrievalMode: keyword }这里maxSkillsPerRequest设成 3 是我踩过坑之后的经验值。设得太少复杂任务覆盖不全设得太多模型注意力被分散反而容易忽略关键约束。3 到 5 之间是比较舒服的区间具体看你的技能颗粒度。3.3 验证环境是否生效的简单方法配置完之后怎么知道 superpowers 真的在工作我的做法是做一个对照测试。先问 AI 一个项目相关的问题比如“帮我写一个用户登录的 API 请求函数”观察它是否引用了项目里的request.ts封装、是否遵循了命名规范。然后临时把.ai/skills/目录改名再问同样的问题。如果两次输出有明显差异说明技能注入生效了如果几乎一样那就要检查配置路径或检索逻辑。这个测试看起来简单但能帮你排除大部分“以为配好了其实没生效”的情况。我见过不少团队配置文件写了一大堆结果路径拼写错误AI 一直在“裸奔”白白浪费了前面的设计工作。4. 编写高质量技能包从“能跑”到“好用”的进阶技巧4.1 触发条件要具体避免“万能技能”新手写技能包最容易犯的错误是范围太宽。比如写一个“生成代码”的技能触发条件写成“当用户需要写代码时”。这种技能几乎等于没写因为 AI 每次生成代码都会触发它但它又没有提供任何具体约束最后输出的还是模型自己的默认风格。正确的做法是收窄触发条件。比如“当用户提到新增 React 函数组件且组件名以 Page 结尾时触发”然后在这个技能里明确规定必须使用项目里的usePageQuery钩子、必须导出默认组件、必须包含 loading 和 error 状态处理。条件越具体技能的可复用性和稳定性就越高。我通常会用一个简单的判断标准如果一个技能包超过 200 行就考虑拆分成多个。因为太长的技能文件模型在检索时很难完整加载而且维护起来也痛苦。拆分的维度可以按业务模块、按代码类型、按操作阶段怎么清晰怎么来。4.2 输出格式约束是稳定性的关键前面提到过结构化输出的重要性这里展开说一下具体怎么写。假设你要生成一个 API 请求函数可以在技能包里这样约束输出## 输出格式 请严格按照以下结构输出不要添加额外解释 typescript // 文件路径: src/api/[模块名].ts import { request } from /utils/request; export interface [接口名]Params { // 参数字段 } export interface [接口名]Result { // 返回字段 } export function [接口名](params: [接口名]Params) { return request.post[接口名]Result(/api/[路径], params); }字段命名规则参数字段使用 camelCase接口名使用 PascalCase以 Params / Result 结尾路径使用 kebab-case这种约束看起来繁琐但实际用起来非常省心。因为 AI 不需要“猜”你想要什么格式它只需要填空。而且当输出不符合预期时你可以直接对照技能文件看是哪条规则没写清楚迭代起来有据可依。 ### 4.3 失败回退策略让 AI 知道“搞不定时怎么办” 这是最容易被忽略、但实际价值极高的一部分。AI 不是万能的当它遇到技能包里没有覆盖的情况时如果没有明确的回退指令它可能会强行编造一个看似合理但实际错误的方案。我在技能包里会加一段“异常处理” 如果当前任务涉及技能包未定义的业务字段不要自行猜测字段含义而是输出“需要人工确认字段 X 的含义”并停止生成。如果项目中没有找到指定的工具函数输出“未找到依赖工具函数 Y”并列出可能的替代方案。 这段约束加上之后AI 的“幻觉”明显减少。因为它知道遇到不确定的情况停下来问比瞎猜更安全。对于团队协作来说这种“知道边界”的能力比“什么都能写”更重要。 ## 5. 实战踩坑记录那些文档里不会写的教训 ### 5.1 技能文件之间的冲突与优先级问题 当技能包数量超过十个之后冲突几乎不可避免。我遇到过一个典型场景一个技能规定“所有日期字段使用 ISO 8601 格式”另一个技能规定“日期字段使用时间戳”。两个技能同时被检索到AI 就懵了生成的代码里两种格式混着用。 解决这个问题的办法是**引入优先级机制**。在技能文件的元数据里加一个 priority 字段数值越大优先级越高。当多个技能对同一件事有不同规定时高优先级的覆盖低优先级的。同时在项目上下文文件里明确写出“全局规范”作为所有技能的兜底约束。这样三层结构——全局规范 高优先级技能 低优先级技能——就能把冲突降到可接受的范围。 另外我建议**定期做技能审计**。每隔两周把 .ai/skills/ 目录过一遍看看有没有功能重叠的、有没有已经过时的、有没有从来没被触发过的。技能库和代码库一样不维护就会腐烂。 ### 5.2 上下文窗口被“噪音”占满的排查过程 有一段时间我发现 AI 生成代码的质量突然下降经常忽略一些明明写在技能包里的约束。排查了半天最后发现是**上下文文件里塞了太多无关内容**。当时项目概述文件被不断追加从最初的 50 行膨胀到了 800 多行里面混杂了历史决策记录、会议纪要、甚至一些废弃的方案讨论。这些内容在检索时被大量加载把真正重要的技能约束挤到了后面模型自然就“记不住”了。 修复方法很简单把项目概述文件拆成“核心规范”和“历史归档”两部分只有核心规范会被注入上下文历史归档放在另一个目录需要时手动查询。同时给上下文文件加一个**行数上限**超过就强制拆分。这个教训让我意识到superpowers 的效果不仅取决于技能写得好不好还取决于**信息密度的管理**。少即是多在上下文注入这件事上尤其成立。 ### 5.3 团队协作中的技能版本管理 个人使用 superpowers 时技能文件随便改改问题不大。但一旦团队多人共用版本管理就成了刚需。我们团队的做法是把 .ai/ 目录纳入 Git 管理技能文件的修改走正常的代码评审流程。每次合并请求里如果改了技能文件必须说明改了什么、为什么改、影响哪些任务类型。 这样做的好处是技能库的演进有迹可循。当某个 AI 生成结果出问题时可以快速回溯到是哪次技能修改引入的。另外我们还会在技能文件头部加一个简单的变更记录 markdown ## 变更记录 - 2024-06-01: 新增字段命名约束修复与 api-generator 的冲突 - 2024-05-15: 初始版本别小看这几行字在排查问题时能省下大量沟通成本。6. 把 superpowers 用出效果的几个关键认知6.1 它不是“让 AI 更聪明”而是“让 AI 更懂你”很多人对 superpowers 的期待是“装上之后 AI 就能写出完美代码”这个预期本身就偏了。大语言模型的基础能力是固定的superpowers 做的是信息对齐——把你脑子里的隐性知识、项目里的显性规范用模型能理解的方式表达出来。它不会让模型突然学会新的编程语言但能让模型在你熟悉的领域里少犯低级错误。理解这一点很重要因为它决定了你的投入方向。与其花时间研究怎么“调教”模型不如花时间梳理项目的编码规范、整理常用工具函数、把重复性的决策写成技能包。这些工作即使没有 AI对团队也是有价值的资产。6.2 从“高频小任务”开始不要一上来就搞大流程我见过一些团队兴致勃勃地设计了一套覆盖需求分析、架构设计、编码、测试、部署的全流程 superpowers 方案结果用了两周就放弃了。原因很简单流程越长不确定性越大维护成本越高。一个环节出问题整条链路就断了而排查成本远超收益。更务实的做法是先挑一个高频、边界清晰、输出格式固定的小任务比如“生成 API 请求函数”或“生成表单校验规则”把它做到 90% 以上的准确率。等这个技能稳定运行一段时间团队建立了信心再逐步扩展到相邻环节。这种“小步快跑”的策略在 AI 工作流建设上同样适用。6.3 人工确认环节不能省无论技能包写得多完善我始终坚持在关键节点保留人工确认。比如生成数据库迁移脚本、修改公共工具函数、涉及权限判断的逻辑这些场景下 AI 的输出只作为草稿必须由人 review 后才能合并。这不是对 AI 不信任而是对工程负责。superpowers 的价值在于把人的精力从重复劳动中解放出来集中到真正需要判断力的地方。如果因为用了 AI 就跳过 review那是本末倒置。我在团队里推行的原则是AI 可以生成但合并请求的 reviewer 必须是人而且 reviewer 要能说清楚这段代码为什么是对的。7. 关于“想要安装 superpowers”的一些直接建议如果你看完前面这些还是不知道从哪下手我给你一个最小启动清单照着做就行。第一步在你的项目根目录建一个.ai/skills/文件夹先放一个技能文件内容就写你最常让 AI 做的那件事的规范。比如你经常让 AI 写 React 组件那就写清楚组件文件放哪、用什么导出方式、状态管理用哪个库、样式方案是什么。不用追求全面先把最痛的那个点覆盖住。第二步在你的 AI 助手对话里手动把技能文件内容粘贴进去测试几次看看输出是否符合预期。如果不符合就改技能文件直到满意为止。这一步是纯手工验证不要急着上自动化。第三步等你确认技能文件有效之后再去配置自动检索和注入。这时候你已经有了一个可用的“种子技能”后面的扩展都是在这个基础上生长出来的。第四步坚持记录。每次 AI 生成结果不符合预期不要只改代码要回头想想是技能文件缺了哪条约束。把这条约束补进去技能库就进化了一次。这个过程重复几十次之后你会发现 AI 助手真的变得“懂你”了。最后分享一个我自己的习惯我会在.ai/context/project-overview.md的开头写一句话——“本项目所有 AI 生成内容默认遵循以下规范除非技能文件另有说明。”这句话像一个总开关提醒模型先看全局约束再看具体技能。别小看这一句话它能让整个技能体系的稳定性提升一个档次。
