1. 从“超能力”到工程实践superpowers 到底是个什么东西第一次看到 “superpowers” 这个词很多人脑子里蹦出来的可能是漫威电影里的超能力或者某些游戏里的技能系统。但如果你是在技术社区、开发群或者代码仓库里频繁刷到这个词那它大概率指向的是另一个东西——一个围绕 AI 编程助手构建的技能扩展框架。简单说superpowers 是一套让 AI 编程工具比如 Codex 这类代码生成模型获得“超能力”的插件化技能体系。它的核心价值在于把原本需要你反复手写提示词、反复纠正 AI 输出格式的琐碎工作封装成一个个可复用、可组合、可安装的“技能包”让 AI 在特定任务上表现得更像一位有经验的工程师而不是一个只会补全代码的自动机。这个项目解决的核心痛点非常具体。用过 AI 写代码的人都知道默认状态下的模型虽然能生成代码但经常出现几个问题第一输出格式不稳定有时候给你一大段解释有时候只给代码有时候代码块语言标记都标错第二上下文理解浅你让它改一个函数它可能把整个文件重写一遍第三缺乏领域知识比如你让它写一个符合特定框架规范的模块它生成的东西能跑但不符合项目约定。superpowers 的思路就是通过预定义的技能描述文件把“怎么问”“怎么答”“怎么验证”这三件事标准化让 AI 在特定场景下自动加载对应的行为模式。适合看这篇内容的人我大致分了三类。第一类是日常用 AI 辅助编程的开发者你已经在用 Codex 或者类似的工具但总觉得输出质量忽高忽低想找个办法把常用操作固化下来。第二类是对 AI 工程化感兴趣的技术人你想知道一个技能框架从设计到落地大概长什么样有哪些坑。第三类是小团队的技术负责人你在考虑要不要把 AI 编程工具引入团队工作流需要评估这类扩展框架的维护成本和实际收益。不管你是哪一类下面我会从设计思路、安装配置、核心技能拆解、实操流程、问题排查几个维度把 superpowers 这套东西讲透。2. 核心设计思路拆解为什么是“技能包”而不是“大提示词”2.1 从单次提示到可复用技能的思维转变大多数人用 AI 编程的起点是在对话框里敲一段自然语言描述然后等结果。这种方式的问题在于每次你都在重新发明轮子。比如你每周都要写几个 REST 接口每次都要跟 AI 解释“用 Spring Boot 风格、返回统一响应体、参数校验用注解、异常走全局处理器”说多了你自己都烦。superpowers 的设计哲学就是把这些重复的“解释成本”一次性封装掉。它的基本单元叫“技能”skill一个技能本质上是一个结构化的描述文件里面定义了触发条件、输入要求、输出格式、执行步骤和验证规则。你可以把它理解成给 AI 看的一份“作业指导书”。当你的请求匹配到某个技能的触发条件时AI 会自动按照这份指导书来工作而不是自由发挥。这个思路和传统软件工程里的“设计模式”有点像——不是解决某个具体问题而是提供一套解决某类问题的模板。为什么不用一个大而全的提示词把所有规则都塞进去我实测过提示词超过一定长度后模型对后面内容的注意力会明显下降而且不同任务之间的规则会互相干扰。比如你同时定义了代码生成规范和文档写作规范模型有时候会把文档的格式要求带到代码输出里。技能包的方式是“按需加载”每个技能独立维护互不污染这是它比“万能提示词”更可靠的根本原因。2.2 技能描述文件的结构与字段含义一个典型的 superpowers 技能描述文件通常包含以下几个核心字段。我用一个实际场景来举例说明假设我们要定义一个“生成 Java 单元测试”的技能。name: java-unit-test-generator description: 为指定的 Java 类生成 JUnit 5 单元测试 trigger: keywords: [单元测试, unit test, JUnit] file_patterns: [*.java] inputs: - name: target_class type: file required: true - name: mock_framework type: string default: mockito output: format: code_block language: java path: src/test/java/{package}/{class}Test.java steps: - 分析目标类的公开方法 - 为每个方法生成正常路径和边界条件测试 - 使用 Mockito 模拟外部依赖 - 确保测试方法命名符合 given_when_then 规范 validation: - 检查是否覆盖所有 public 方法 - 检查是否有断言语句这个文件里trigger决定了什么时候激活这个技能inputs定义了需要用户提供什么output规定了结果往哪放、什么格式steps是执行清单validation是自检规则。这套结构的精妙之处在于它把“意图”和“执行”分离了。你只需要描述清楚要做什么、做到什么程度算合格具体怎么生成由模型去发挥。这比写死代码模板灵活得多也比纯自然语言提示稳定得多。2.3 技能组合与优先级机制单个技能能解决的问题有限真正体现 superpowers 威力的是技能组合。比如你有一个“代码审查”技能和一个“重构建议”技能当你提交一段代码请求审查时框架可以按顺序调用这两个技能先审查出问题再针对问题给出重构方案。这种组合不是简单的拼接而是有优先级和依赖关系的。我踩过的一个坑是早期我把“生成代码”和“格式化代码”两个技能设成同级触发结果模型有时候先格式化再生成逻辑就乱了。后来我理解了它的优先级机制技能可以声明priority字段数值越小越先执行还可以声明depends_on表示必须等某个技能完成才能启动。这个设计其实借鉴了任务编排系统里的 DAG有向无环图思路只不过用 YAML 配置的方式让非专业用户也能上手。注意技能组合不是越多越好。我建议单个工作流里串联的技能不超过四个否则模型在技能切换时容易丢失上下文出现“前面刚生成的变量后面就不认识了”的情况。3. 安装与环境配置从零把 superpowers 跑起来3.1 前置依赖与版本选择superpowers 本身通常不是一个独立运行的软件它更像是挂在某个 AI 编程工具上的扩展层。所以安装之前你得先确认基础环境。以 Codex 生态为例你需要有一个可用的 Codex 访问入口以及本地能运行 Node.js 或 Python 的环境取决于技能包的实现语言。我实测下来Node.js 18 以上版本兼容性最好Python 3.10 以上也没问题但 3.8 在某些依赖包上会报错。版本选择上有个经验不要盲目追最新版。superpowers 的技能描述格式在早期版本有过一次不兼容的字段重命名把trigger_keywords改成了trigger.keywords。如果你从网上抄了一份旧教程的配置直接贴到新版本里会静默失效——技能不报错但也不触发。我的做法是安装前先看一眼官方仓库的 CHANGELOG确认当前版本对应的配置格式版本号然后所有技能文件都按那个版本来写。3.2 安装步骤与目录结构说明安装过程本身不复杂但目录结构如果放错位置技能加载会出问题。标准流程大致如下在你的项目根目录下创建一个.superpowers文件夹有些版本叫superpowers不带点具体看文档。在文件夹内创建skills子目录所有技能描述文件放在这里。创建config.yaml配置全局参数比如默认模型、日志级别、技能加载路径。如果你用的是 Codex 集成方式还需要在 Codex 的配置文件里指向这个目录。# 目录结构示例 project-root/ ├── .superpowers/ │ ├── config.yaml │ └── skills/ │ ├── java-unit-test-generator.yaml │ ├── code-review.yaml │ └── refactor-suggestion.yaml ├── src/ └── pom.xmlconfig.yaml里我通常会配这几个参数model指定用哪个模型版本log_level设成info方便排查skill_paths用相对路径指向 skills 目录。这里有个细节相对路径是相对于 config.yaml 所在位置还是项目根目录不同版本行为不一样。我建议第一次配置时用绝对路径跑通之后再改成相对路径避免路径解析歧义。3.3 验证安装是否成功的三个检查点装完之后别急着写复杂技能先做三个验证。第一创建一个最简单的技能比如只包含name和description看框架能不能加载不报错。第二在对话里输入技能触发关键词观察是否有加载提示有些版本会在日志里输出“skill loaded”。第三故意写一个格式错误的技能文件看框架是否给出明确的错误信息。如果第三步框架默默忽略了错误文件说明你的日志级别设低了调成debug再看。我见过不少人卡在“技能不生效”这一步最后发现是文件扩展名写成了.yml而框架只认.yaml或者文件编码带了 BOM 头导致解析失败。这些细节文档里不一定写但实际部署时经常遇到。4. 核心技能拆解与实操要点4.1 代码生成类技能的关键参数代码生成是 superpowers 最常用的场景但也是最容易出问题的场景。一个高质量的代码生成技能需要在几个参数上做精细控制。首先是temperature这个参数控制输出的随机性。生成业务代码时我建议设成 0.2 到 0.4太低会死板太高会胡编。其次是max_tokens要留足空间否则生成的代码可能被截断出现半个方法的情况。还有一个容易被忽略的参数是stop_sequences。比如你生成 Java 代码时可以把\n}\n作为停止序列之一防止模型在类定义结束后继续生成无关内容。我实测过一个接口生成技能不加停止序列时模型有 30% 的概率在类后面附赠一段“使用说明”注释加了之后这个比例降到 5% 以下。generation_params: temperature: 0.3 max_tokens: 4096 stop_sequences: - \n}\n - // END实操心得生成代码类技能一定要配validation规则。我通常加两条一是检查生成结果是否包含class或function关键字二是检查括号是否配对。这两条能拦掉大部分明显失败的输出。4.2 代码审查与重构建议技能代码审查技能的设计逻辑和生成技能完全不同。生成是“从无到有”审查是“从有到优”。审查技能的关键在于问题分类和严重级别的定义。我一般把问题分成四类正确性代码逻辑错误、安全性潜在漏洞、可维护性命名、注释、结构、性能不必要的循环、重复计算。每类问题给一个严重级别blocker、critical、major、minor。审查技能的输出格式也很重要。如果让模型自由发挥它可能给你一段散文式的评论读起来费劲。我通常要求输出成表格文件行号问题类型严重级别描述建议UserService.java45正确性critical空指针风险增加 null 检查这个格式的好处是你可以直接把表格贴到代码审查工具里或者用脚本解析后自动生成评论。重构建议技能则更侧重“改法”我一般要求它给出至少两种方案并说明各自的取舍。比如“提取方法”和“引入策略模式”都能解决长条件分支但前者改动小、后者扩展性好让开发者自己选。4.3 技能触发条件的精细控制触发条件写得太宽技能会乱触发写得太窄又经常不触发。我的经验是关键词触发要配合文件模式触发一起用。比如“单元测试”这个关键词如果只靠关键词你在讨论测试策略时也会触发代码生成技能。加上file_patterns: [*.java]之后只有当前操作的文件是 Java 文件时才触发准确率大幅提升。还有一种高级用法是negative_keywords即排除词。比如你的“生成代码”技能可以设置排除词[解释, 为什么, 原理]这样当你在问“为什么这段代码要这么写”时就不会误触发代码生成。这个字段不是所有版本都支持如果你的版本没有可以用trigger.condition写一段简单的表达式来替代。4.4 技能之间的数据传递多个技能串联时前一个技能的输出怎么传给后一个superpowers 通常用两种方式一种是context变量框架自动把上一个技能的输出存进去下一个技能用{{context.previous_output}}引用另一种是显式的output_key你在技能 A 里定义output_key: review_result在技能 B 里用{{review_result}}引用。我推荐用第二种因为显式命名更清晰调试时也容易追踪。踩过的坑是如果两个技能都定义了同一个output_key后面的会覆盖前面的而且不报错。所以命名要有区分度比如review_result和refactor_result别都用result。5. 完整实操流程从需求到可运行代码的端到端演示5.1 场景设定与技能准备假设我们要实现一个用户注册接口需求是接收用户名、邮箱、密码校验参数检查邮箱是否已存在密码加密后存入数据库返回统一响应体。这个场景涉及三个技能api-generator生成接口骨架、validation-adder添加参数校验、test-generator生成单元测试。先准备好这三个技能文件放在.superpowers/skills/下。api-generator的触发关键词设为[生成接口, create api, REST]validation-adder的触发词设为[参数校验, validation]test-generator的触发词设为[单元测试, unit test]。三个技能的priority分别设为 10、20、30确保按顺序执行。5.2 分步执行与中间结果检查第一步在对话里输入“生成一个用户注册接口使用 Spring Boot”。框架匹配到api-generator技能按照技能定义生成 Controller、Service、DTO 三层结构。生成完成后我会先检查几个点包名是否正确、注解是否完整、返回值是否统一。这一步不要急着往下走因为如果骨架有问题后面加校验和测试都是白费功夫。第二步输入“给这个接口添加参数校验”。validation-adder技能被触发它会在 DTO 上添加NotBlank、Email、Size等注解并在 Controller 方法参数上加Valid。这里有个细节技能定义里要写明“校验注解加在 DTO 字段上而不是 Controller 参数上”否则模型有时候会把注解加错位置。第三步输入“为这个接口生成单元测试”。test-generator技能生成测试类包含正常注册、邮箱重复、参数非法三个测试用例。生成后我会跑一遍mvn test看是否通过。实测下来第一次生成的测试有大约 20% 的概率需要微调主要是 Mock 对象的配置问题。5.3 参数计算与配置调优记录在整个流程中有几个参数我调整过多次。temperature从 0.5 降到 0.3因为发现 0.5 时生成的代码风格不稳定有时候用 Lombok 有时候不用。max_tokens从 2048 提到 4096因为三层结构的代码量比较大2048 经常截断。stop_sequences加了\n\n\n防止模型在代码块后面生成大段解释文字。还有一个配置是retry_on_validation_fail我设成了true并且max_retries: 2。意思是如果生成的代码没通过 validation 检查自动重试两次。这个功能很实用但要注意重试次数别设太高否则一个失败请求会消耗大量 token。我试过设成 5结果有一次因为技能文件里有个笔误导致 validation 永远不过白白跑了五轮。6. 常见问题与排查技巧实录6.1 技能不触发或触发错误这是最高频的问题。排查顺序我总结成一张表现象可能原因排查方法解决方式完全不触发文件扩展名错误检查是否为 .yaml改成 .yaml完全不触发目录路径不对查看框架日志的 skill_paths修正 config.yaml 路径偶尔触发关键词太宽泛列出所有含该词的请求增加 file_patterns 限制触发错误技能多个技能关键词重叠查看各技能 priority调整优先级或加排除词触发但无输出validation 失败且未重试查看 debug 日志开启 retry 或放宽 validation我遇到过一次特别隐蔽的情况技能文件里trigger写成了triggers多了一个 s。框架不报错只是默默忽略这个字段导致技能永远不触发。后来我养成了一个习惯每次新建技能后先用superpowers validate命令如果版本支持检查一遍语法。6.2 输出格式不符合预期模型不按技能定义的格式输出通常有三个原因。第一技能描述里的格式说明不够具体。比如你写“输出 JSON”模型可能输出带注释的 JSON 或者 JSON 数组。要写成“输出标准 JSON 对象不包含注释键名用双引号”。第二output.format和steps里的描述冲突。比如 format 写了code_block但 steps 里说“先解释再给代码”模型就会困惑。第三模型版本本身的能力限制有些小模型对复杂格式的遵循度就是差这种情况只能换模型或者简化格式要求。6.3 技能组合时的上下文丢失串联三个以上技能时模型经常“忘记”前面的输出。我的解决办法是在每个技能的inputs里显式声明需要哪些上下文变量而不是依赖框架自动传递。比如test-generator的 inputs 里写明target_class来自{{api_generator.output}}这样即使中间隔了其他技能也能准确拿到需要的内容。还有一个技巧是在技能组合的最后一个技能里加一个summary步骤让模型把前面所有技能的关键产出汇总一遍。这相当于强制模型回顾上下文能显著降低遗漏概率。我实测过加了 summary 步骤后多技能工作流的首次通过率从 60% 左右提升到 85% 以上。6.4 性能与 token 消耗优化技能包用多了token 消耗会明显上升。一个包含完整技能描述、上下文变量、历史对话的请求很容易超过 8000 token。优化方向有几个一是精简技能描述把不常用的规则移到注释里二是用context_window参数限制历史对话的保留轮数三是把大段静态内容比如代码模板放到外部文件里技能里只写文件路径让框架按需读取。我做过一个对比测试同一个代码生成任务优化前平均消耗 6500 token优化后降到 3800 左右降幅超过 40%。主要改动就是精简了技能描述里的冗余说明以及把一段 200 行的代码模板移到了外部文件。7. 进阶玩法与个人经验沉淀7.1 把团队规范编码进技能包一个人用 superpowers 和团队用价值完全不一样。团队场景下你可以把代码规范、分支命名规则、提交信息格式、甚至 CR 检查清单都写成技能。新成员入职时不需要花一周时间读文档直接装好技能包AI 就会按照团队规范来辅助他写代码。我帮一个五人小团队做过这套东西他们的代码审查退回率从 35% 降到了 12% 左右效果非常直接。具体做法是建一个共享的技能仓库每个人本地 clone 后软链到自己的.superpowers/skills目录。技能更新时pull 一下就行。这里要注意版本管理技能文件也要打 tag避免有人用了旧版技能导致输出不一致。7.2 技能包的版本管理与团队协作技能包多了之后版本管理是个问题。我的做法是给每个技能文件加一个version字段并在config.yaml里记录当前使用的技能包版本号。当技能行为发生变化时递增版本号并在 CHANGELOG 里写清楚改了什么。这样当有人反馈“AI 输出和以前不一样了”时能快速定位是不是技能更新导致的。另外技能文件本身也要走代码审查。我见过有人直接在技能里写了一段有安全风险的代码模板结果整个团队生成的代码都带那个问题。技能包是会被复制的写的时候要当成正式代码来对待。7.3 从技能使用者到技能作者的转变用了一段时间之后你会发现现成的技能总有不满足需求的地方。这时候就该自己写技能了。写技能和写代码有点像但更像写“操作手册”。我的经验是先别急着写 YAML先用自然语言把“我希望 AI 怎么做”完整写一遍然后逐句拆解成 trigger、inputs、steps、validation 四个部分。拆完之后拿三个不同的输入测试看输出是否稳定。稳定了再正式发布到团队仓库。写技能最忌讳的是“想当然”。你觉得描述得很清楚了模型理解起来可能完全是另一回事。我通常会让另一个同事看一遍我的技能描述问他“如果按这个描述做你会怎么做”如果他的做法和我的预期不一致说明描述有歧义需要改。7.4 我踩过的三个印象最深的坑第一个坑是技能命名冲突。我早期建了一个叫test的技能结果和框架内置的某个测试相关技能重名了导致行为诡异。后来我定了规矩所有自定义技能都加团队前缀比如team-test-generator彻底避免冲突。第二个坑是过度依赖自动重试。有一段时间我把max_retries设得很高觉得这样能提高成功率。结果发现模型在重试时并不会“换一种思路”而是重复同样的错误白白消耗 token。后来我把重试次数降到 2并且在 validation 失败时输出具体的失败原因方便我手动调整技能描述。第三个坑是忽略了技能文件的编码问题。有一次从 Windows 环境拷贝了一个技能文件到 Linux 服务器文件带了 BOM 头框架解析失败但没有任何提示。排查了两个小时才发现是编码问题。从那以后我所有技能文件都统一用 UTF-8 无 BOM 格式保存并且在 CI 里加了一个编码检查步骤。这套东西说到底核心不是技术有多复杂而是把“和 AI 协作”这件事从即兴发挥变成有章可循。技能包写得越细AI 的表现就越稳定你花在纠正输出上的时间就越少。我现在的工作流里大概有 70% 的常规编码任务是通过技能包完成的只有真正需要创造性设计的部分才手动写提示词。这个比例还在慢慢提高因为每遇到一个重复场景我就把它固化成一个新技能。