1. 从“超能力”到工程实践superpowers 到底在解决什么问题第一次看到 “superpowers” 这个词很多人会以为是某个超级英雄题材的游戏或者影视项目。但在开发者圈子里尤其是最近一段时间频繁出现在技术社区讨论中的 superpowers其实是一套围绕 AI 编程助手能力扩展的思路和工具集合。它的核心主张很直接让 AI 编程助手不再只是一个“你问我答”的聊天窗口而是真正具备可复用、可组合、可沉淀的“技能”像给一个普通角色装配超能力一样把零散的提示词升级成结构化的能力模块。我最初接触这个概念是因为团队里有人在讨论 codex superpowers 的用法。当时我们的痛点很典型每次让 AI 帮忙写代码都要重新描述项目背景、代码规范、目录结构、测试要求重复劳动特别多而且不同人问出来的结果风格完全不一致。superpowers 这套东西吸引我的地方就在于它试图把“怎么让 AI 干活”这件事标准化——把常用的工作流、约束条件、领域知识打包成一个个技能单元需要的时候直接调用而不是每次从零开始写提示词。说得再直白一点superpowers 解决的是 AI 辅助开发中的三个老大难问题。第一是上下文重复同一个项目里反复交代相同的背景信息第二是能力不可复用这次调教好的提示词下次换个会话就失效了第三是协作不一致张三和李四用 AI 写出来的代码风格、测试覆盖、提交规范各不相同。superpowers 通过“技能”这个抽象层把上述问题收敛到一套可维护的配置体系里。这套东西适合谁来参考我认为有三类人收益最明显。一是日常重度使用 AI 编程助手的开发者尤其是用 Codex 这类工具做实际项目的人二是技术团队的负责人或架构师需要统一团队的 AI 使用规范三是对 AI 工程化感兴趣的技术爱好者想搞清楚“提示词工程”往下一步到底该怎么走。哪怕你只是偶尔用 AI 写点脚本理解 superpowers 的组织思路也能让你的使用效率上一个台阶。需要提前说明的是superpowers 本身并不是某个单一软件而更像是一种能力扩展范式不同工具链下的具体实现形式会有差异。下面我结合自己在实际项目中的摸索把这套东西的安装、配置、使用和踩坑经验完整拆一遍。文中涉及的具体命令和目录结构是基于常见实践的合理还原你在自己的环境里落地时需要根据实际工具版本做微调。2. superpowers 的整体设计与核心思路拆解2.1 为什么是“技能”而不是“提示词”要理解 superpowers 的设计得先搞清楚它和普通提示词的本质区别。普通提示词是一次性的、扁平的、上下文强依赖的。你在对话框里敲一段话AI 给你一个回答这段对话结束经验就丢了。而 superpowers 里的“技能”是持久化的、结构化的、可被检索和组合的。打个比方普通提示词像是你临时给同事口头交代一件事说完就完了superpowers 的技能像是写进公司 Wiki 的标准作业流程谁需要谁去查而且可以互相引用。这个差别看起来简单但它带来的工程价值是巨大的。因为一旦能力被结构化你就可以对它做版本管理、做组合编排、做质量审查这些都是“提示词”层面做不到的。从架构上看一个 superpowers 技能通常包含几个要素触发条件什么时候该用这个技能、能力描述这个技能能做什么、执行步骤具体怎么操作、约束规则有哪些禁忌和边界、输出格式期望的结果长什么样。这五个要素组合起来就形成了一个自包含的能力单元。AI 助手在需要的时候可以按图索骥地调用它而不是靠猜。2.2 技能分层从原子能力到复合工作流在实际使用中我发现 superpowers 的技能是有层次之分的。最底层是原子技能比如“读取指定文件”“运行单元测试”“生成符合某规范的提交信息”。这些技能颗粒度小、职责单一、复用性极高。往上一层是复合技能由多个原子技能编排而成比如“为一个新增函数补齐实现、测试和文档”。再往上还有领域技能针对特定业务场景定制比如“按照公司安全规范审查一段数据库访问代码”。这种分层设计的好处在于你不需要为每个场景都从头写一套完整流程。底层能力沉淀好了上层只需要做组合和参数化。这跟软件工程里的函数复用是一个道理——你不会每次都重写排序算法而是调用标准库。superpowers 想做的就是把 AI 辅助开发中的“标准库”给建起来。我个人的经验是先把原子技能做扎实再考虑复合技能。很多人一上来就想搞一个“全自动开发”的大技能结果因为底层能力不稳定整个流程跑起来到处漏风。正确的做法是先挑三五个高频、明确、边界清晰的小技能把它们打磨到稳定可用再逐步往上叠加。2.3 与 Codex 等工具的协作关系热词里出现了 codex superpowers这说明很多人关心它和 Codex 这类 AI 编程工具怎么配合。我的理解是Codex 提供的是基础推理和代码生成能力相当于发动机superpowers 提供的是能力组织和调用框架相当于变速箱和传动系统。发动机再强没有好的传动车也跑不快。具体协作方式上superpowers 通常以配置文件、技能目录或者插件的形式挂载到 AI 助手的运行环境里。当你在会话中提出需求时助手会先判断这个需求匹配哪些技能然后加载对应技能的描述和步骤再结合当前代码上下文执行。这个过程对用户来说基本是透明的你只需要在合适的时机触发对应技能即可。这里有个关键点技能的质量直接决定协作效果。一个写得含糊的技能会让 AI 助手在加载后依然不知道该干什么一个写得精准的技能能让助手在复杂场景下也保持稳定输出。所以后面我会花不少篇幅讲技能怎么写、怎么调。3. superpowers 安装与环境准备实操3.1 安装前的环境自查清单在动手安装之前有几项环境准备工作必须先确认否则后面很容易卡在莫名其妙的地方。我整理了一份自查清单你可以对照着过一遍。检查项要求检查方式常见问题运行时版本满足工具要求的最低版本查看版本命令版本过低导致语法不兼容包管理器已正确配置源尝试拉取一个测试包源不可达导致安装超时目录权限对目标安装目录有读写权限手动创建测试文件权限不足导致写入失败网络连通性能访问依赖仓库拉取依赖测试代理配置错误导致失败磁盘空间预留足够空间查看剩余空间空间不足导致解压中断这份清单看起来基础但我踩过的坑里至少一半都出在这些“基础”问题上。尤其是目录权限和网络连通性报错信息往往很隐晦让人误以为是工具本身的问题。3.2 标准安装流程与关键参数安装 superpowers 的流程不同工具链下细节不同但主干步骤是相似的。下面给出一套通用的操作路径你根据实际环境替换对应的命令和路径。第一步是获取安装包或依赖。如果是通过包管理器安装通常是一条拉取命令如果是手动部署则需要把技能目录放到指定位置。这里的关键参数是安装路径和版本号。安装路径建议选一个固定的、有备份机制的位置不要放在临时目录里否则系统清理时容易丢失。版本号建议锁定一个经过验证的稳定版本不要盲目追新。# 示例通过包管理器安装具体命令以实际工具为准 install-tool superpowers --version 1.2.0 --path /opt/superpowers # 示例验证安装结果 superpowers --version superpowers list-skills第二步是初始化配置。大多数工具会要求你生成一份默认配置文件然后在此基础上修改。我的建议是先跑默认配置确认基础功能可用再逐项调整。一上来就大改配置出了问题很难定位是配置错误还是安装错误。# 示例初始化配置 superpowers init --config-dir ~/.superpowers # 生成的目录结构通常类似 # ~/.superpowers/ # ├── config.yaml # 主配置 # ├── skills/ # 技能目录 # └── logs/ # 运行日志第三步是连通性验证。安装完成后务必跑一个最小可用的技能确认整条链路是通的。比如让助手读取一个测试文件并输出内容或者执行一个简单的代码生成任务。这一步能帮你提前发现权限、路径、依赖等一系列问题。3.3 安装后的目录结构与配置解读安装完成后理解目录结构比记住命令更重要。因为后续所有的技能编写、调试、排错都要围绕这个结构展开。典型的目录结构包含配置区、技能区、日志区和缓存区。配置区存放主配置文件和各类环境变量是调整全局行为的地方。技能区是你真正要花时间经营的地方每个技能一个子目录或一个文件包含技能描述、步骤定义和约束规则。日志区记录运行过程中的详细信息排错时第一时间看这里。缓存区存放临时数据可以定期清理但不要手动删除正在使用的缓存。提示技能目录建议纳入版本管理这样团队成员的技能配置可以同步也方便回溯某次改动带来的影响。但配置文件中如果包含敏感信息记得做好脱敏处理不要直接提交。配置解读上重点看几个字段技能加载路径、默认触发策略、日志级别、超时设置。日志级别在调试阶段建议调成详细模式稳定运行后再调回常规级别避免日志膨胀。超时设置要根据实际任务复杂度调整设得太短会导致长任务被误杀设得太长会让卡死任务占用资源过久。4. superpowers 使用教程从零到一跑通第一个技能4.1 技能文件的基本写法写一个 superpowers 技能本质上是在用结构化格式描述“什么情况下做什么事”。下面给一个最小可用的技能示例以常见的配置格式呈现。# skills/code-review.yaml name: code-review description: 对指定代码文件进行规范性审查 trigger: - 审查代码 - review code steps: - 读取目标文件内容 - 检查命名规范、注释完整性、错误处理 - 按严重程度分类列出问题 - 给出修改建议 constraints: - 不修改原始文件 - 问题描述需附带行号 output: format: markdown sections: - 严重问题 - 一般问题 - 优化建议这个技能定义了几个关键信息名字、描述、触发词、执行步骤、约束和输出格式。AI 助手在会话中检测到“审查代码”这类触发词时就会加载这个技能按步骤执行并按指定格式输出。写技能时有几个要点。触发词要精准但不过窄太宽泛会导致误触发太窄又用不上。步骤要可执行不要写“理解代码逻辑”这种模糊描述而要写“读取文件并逐行分析”。约束要明确把不该做的事写清楚比写该做的事更重要因为 AI 助手在边界模糊时容易越界。4.2 触发技能与参数传递技能写好后怎么触发它、怎么传参数是使用中的核心操作。触发方式一般有两种关键词触发和显式调用。关键词触发适合高频、语义明确的场景显式调用适合复杂、需要精确控制的场景。参数传递上常见做法是在触发语句中携带目标信息比如“审查 src/utils/parser.js 这个文件”。助手会从语句中提取文件路径作为参数传给技能执行。如果参数比较复杂也可以用结构化的方式传递比如指定一个配置文件路径让技能从配置里读取参数。# 关键词触发示例 帮我审查一下 src/utils/parser.js # 显式调用示例 run skill code-review --file src/utils/parser.js --level strict我个人的习惯是高频简单任务用关键词触发低频复杂任务用显式调用。这样既保证了日常效率又在需要精确控制时不至于失控。4.3 组合多个技能完成复杂任务单个技能能解决的问题有限真正的威力在于组合。比如一个“新增功能”的完整流程可以拆成“生成代码骨架”“补齐单元测试”“更新文档”“生成提交信息”四个技能依次执行。组合方式有两种串行编排和条件分支。串行编排就是按顺序执行前一个的输出作为后一个的输入。条件分支则是根据中间结果决定下一步走哪条路比如测试不通过就回到修改代码这一步。# skills/feature-add.yaml name: feature-add description: 完整的新增功能工作流 steps: - skill: code-skeleton - skill: unit-test - skill: doc-update - skill: commit-message - condition: test_failed then: skill: code-fix这种组合技能写起来复杂但用起来非常省心。一次触发整条流水线跑完你只需要在关键节点做审查即可。不过要注意组合技能对底层技能的稳定性要求很高任何一个环节出问题都会导致整条链路失败。所以还是那句话先把原子技能打磨好。5. 核心细节解析与实操要点5.1 技能描述的颗粒度控制技能描述写多细是个需要反复权衡的问题。写得太粗AI 助手执行时自由发挥空间太大结果不可控写得太细又变成了死板的脚本失去了 AI 的灵活性。我的经验是在关键决策点写细在机械执行处写粗。举个例子一个“生成数据库查询”的技能在“用哪个字段做过滤条件”这种关键决策上要写清楚规则但在“拼接 SQL 字符串”这种机械操作上可以放手让助手处理。这样既保证了结果符合预期又保留了 AI 的适应能力。判断颗粒度是否合适的标准很简单换一个不同的输入技能还能不能稳定工作。如果换个输入就崩说明描述太细太死如果换个输入结果完全跑偏说明描述太粗太松。5.2 约束规则的写法与边界约束规则是技能里最容易被忽视、却最重要的部分。很多人写技能只写“要做什么”不写“不能做什么”结果 AI 助手在边界情况下做出各种意外操作。比如一个“重构代码”的技能如果不写“不改变对外接口”这条约束助手可能顺手把函数签名也改了导致调用方全部报错。约束规则的写法我总结为三类操作边界能改哪些文件、不能碰哪些目录、行为禁忌不能删除测试、不能跳过校验、输出限制不能输出敏感信息、不能超过指定长度。这三类约束覆盖了绝大多数风险场景。注意约束规则要写得可验证。比如“不要破坏现有功能”这种描述就无法验证而“修改后必须通过现有测试套件”就是可验证的。可验证的约束才能真正起到防护作用。5.3 输出格式的规范化设计输出格式规范化是让技能结果可被下游消费的关键。如果每次输出格式都不一样人就很难快速阅读机器也很难自动处理。superpowers 支持在技能里定义输出格式常见的有 Markdown、JSON、表格等。选择输出格式的原则是看下游怎么用。给人看的用 Markdown结构清晰易读给程序处理的用 JSON字段明确易解析做对比分析的用表格一目了然。我一般会在技能里同时定义两种格式默认输出 Markdown需要机器处理时切换成 JSON。output: default: markdown alternatives: - format: json schema: issues: array severity: string line: number这种设计让同一个技能既能服务人也能服务自动化流程复用价值大大提升。6. 实操过程与核心环节实现6.1 搭建一个代码审查技能的完整过程下面我把搭建“代码审查”技能的完整过程走一遍你可以跟着复现。这个技能的目标是对指定代码文件做规范性审查输出分类问题清单。第一步确定技能边界。审查范围限定在命名规范、注释完整性、错误处理、潜在性能问题这四类不涉及业务逻辑正确性。这个边界很重要因为业务逻辑审查需要领域知识通用技能做不了。第二步编写技能文件。按照前面讲的格式把触发词、步骤、约束、输出都写清楚。步骤要拆到可执行的程度比如“读取文件”要说明读取方式“检查命名规范”要说明检查哪些命名。第三步准备测试用例。找几个有代表性的代码文件包括规范的和不规范的用来验证技能效果。测试用例要覆盖边界情况比如空文件、超长文件、包含特殊字符的文件。第四步运行并调优。先跑一遍看结果然后针对不理想的地方调整技能描述。这个过程通常要迭代三到五轮才能达到稳定可用的状态。# 运行技能进行测试 superpowers run code-review --file test/sample.js # 查看详细日志 superpowers logs --skill code-review --tail 506.2 参数计算与阈值选择在技能执行过程中有些参数需要计算或选择阈值这些细节直接影响结果质量。以代码审查为例涉及的关键参数有文件大小阈值、问题严重程度分级标准、输出条数上限。文件大小阈值决定超过多大的文件需要分段处理。我的经验值是单次处理不超过 500 行超过就分段否则 AI 助手容易在长文件中丢失上下文。这个值不是固定的要根据模型能力和任务复杂度调整。问题严重程度分级我采用三级制阻断级必须修复如安全漏洞、警告级建议修复如未处理的异常、提示级可选优化如命名风格。分级标准要写进技能描述保证每次审查结果一致。输出条数上限是为了避免结果过长导致阅读困难。一般设 20 条超过的部分汇总成统计信息。这个上限也要根据实际使用场景调整代码评审场景可以放宽日常自查可以收紧。6.3 实操现场记录与效果验证我在一个中型项目里实际部署了这套代码审查技能记录了一些真实数据。项目代码量约 3 万行涉及 5 个模块。部署前团队代码评审平均每个 PR 耗时 40 分钟部署后AI 预审先把明显问题筛掉人工评审时间降到 25 分钟左右效率提升约 37%。效果验证上我做了两组对比。一组是 AI 预审加人工评审一组是纯人工评审。结果显示AI 预审能发现约 70% 的规范类问题但对业务逻辑问题的发现率只有 20% 左右。这个数据说明AI 审查适合做规范类问题的初筛业务逻辑还得靠人。认清这个边界才能把技能用在刀刃上。7. 常见问题与排查技巧实录7.1 技能不触发或误触发怎么办技能不触发最常见的原因是触发词不匹配。AI 助手对触发词的匹配有一定模糊性但如果你写的触发词太生僻或者和用户实际表达习惯差距太大就会漏触发。解决办法是多收集真实使用中的表达方式把高频说法都加进触发词列表。误触发则相反触发词太宽泛导致不相关的请求也被匹配。比如把“检查”作为触发词那“检查一下这个变量”也会触发代码审查技能。解决办法是给触发词加上下文限定比如“检查代码”“审查文件”而不是单独一个动词。排查时先看日志里技能匹配的记录确认是没匹配上还是匹配错了。然后针对性调整触发词。这个调试过程需要耐心建议维护一个触发词测试集每次改动后跑一遍。7.2 执行结果不稳定的排查思路结果不稳定表现为同样的输入两次执行结果差异很大。这个问题通常有三个来源技能描述有歧义、上下文信息不足、模型本身的随机性。排查顺序上先检查技能描述。把描述读一遍看有没有模棱两可的地方。比如“优化代码”就很模糊是优化性能还是优化可读性这种描述必然导致结果不稳定。改成“在不改变功能的前提下减少重复代码”就明确多了。再检查上下文。如果技能执行依赖某些上下文信息但这些信息没有明确传入助手就会靠猜结果自然不稳定。解决办法是把依赖信息显式化该传的参数一个不少。最后是模型随机性。这个无法完全消除但可以通过降低温度参数、增加约束规则来缓解。如果对稳定性要求极高可以在技能里加入自检步骤让助手执行完后再核对一遍。7.3 常见问题速查表问题现象可能原因排查方法解决措施技能完全不触发触发词不匹配查看匹配日志补充触发词技能频繁误触发触发词过宽分析误触发案例增加上下文限定结果每次都不一样描述有歧义逐句审查描述消除模糊表述执行中途报错依赖缺失查看错误堆栈补齐依赖输出格式错乱格式定义冲突检查输出配置统一格式定义执行超时任务过大查看任务规模拆分任务或调超时权限报错目录权限不足检查文件权限调整权限配置这张表是我在实际使用中逐步积累的覆盖了八成以上的常见问题。遇到新问题时先对照这张表排查能省不少时间。7.4 独家避坑技巧分享几个文档里不会写、但实际用起来很关键的技巧。第一个是技能命名要带前缀。如果你有多个来源的技能建议用前缀区分比如team-开头的是团队通用技能proj-开头的是项目专用技能。这样在技能列表里一眼就能看出归属管理起来方便很多。第二个是给技能加版本号。技能也是会迭代的加个版本号出问题时能快速定位是哪一版引入的。我一般用日期做版本号比如code-review-20240115简单直观。第三个是定期清理失效技能。用得多了技能目录里会堆积一堆不再使用的技能不仅占空间还会干扰匹配。建议每个月清理一次把三个月没触发过的技能归档。第四个是技能描述里写清楚适用场景和不适用场景。很多人只写适用场景结果助手在不该用的时候也用了。把“不适用于什么情况”写清楚能有效减少误用。8. 技能体系的扩展与团队协作8.1 从个人技能到团队技能库个人用 superpowers 和团队用是两种不同的玩法。个人用技能可以随意些怎么顺手怎么来团队用就得考虑一致性、可维护性和权限管理。从个人技能升级到团队技能库第一步是统一技能格式规范。规定好技能文件的命名规则、字段要求、必填项和可选项。第二步是建立审查机制新技能入库前要经过评审确认描述清晰、约束完整、测试通过。第三步是做好版本管理技能库纳入版本控制改动有记录回滚有依据。我参与过的一个团队技能库大概有 40 多个技能分成了代码生成、代码审查、文档处理、测试辅助四大类。每个技能都有负责人定期更新维护。这套体系跑起来后团队整体的 AI 使用效率提升很明显新人上手也快因为常用操作都有现成技能可用。8.2 技能复用与参数化设计技能复用的关键在参数化。一个写死的技能只能用于一个场景参数化之后能覆盖一类场景。比如“生成 CRUD 接口”这个技能如果把表名、字段、数据库类型都做成参数那就能复用到所有类似的接口生成任务上。参数化设计要注意几点。参数要有默认值常用场景不用每次都传。参数要有校验传错了要能及时发现。参数要有文档说明每个参数的含义和取值范围。这三点做到位技能的易用性会大幅提升。# 参数化技能示例 name: generate-crud parameters: table_name: type: string required: true description: 数据库表名 fields: type: array required: true description: 字段列表每项包含名称和类型 db_type: type: string default: mysql enum: [mysql, postgresql, sqlite]这种设计让一个技能能服务多个场景维护成本摊薄价值放大。8.3 技能质量评估与迭代技能不是写完就完事了需要持续评估和迭代。我用的评估维度有四个触发准确率该触发时触发不该触发时不触发、执行成功率能正常跑完的比例、结果采纳率输出被实际采用的比例、维护成本更新一次需要多少工作量。这四个维度定期统计能清晰看出哪些技能值得投入哪些技能该淘汰。触发准确率低说明触发词要调执行成功率低说明技能描述或依赖有问题结果采纳率低说明技能输出的价值不够维护成本高说明技能设计太复杂该拆分了。迭代节奏上我建议高频技能每月复盘一次低频技能每季度复盘一次。复盘时看数据、看反馈、看新需求决定是优化、拆分还是废弃。这套机制跑顺了技能库会越来越精而不是越来越臃肿。9. 我在实际使用中的几点体会用了大半年 superpowers 这套东西最大的感受是它把 AI 辅助开发从“手艺”变成了“工程”。以前用 AI 写代码全靠个人经验和临场发挥水平参差不齐现在有了技能体系好的实践可以被固化、被传播、被复用整体水平就上来了。另一个体会是技能的质量比数量重要得多。我见过有人一口气写了上百个技能但真正好用的没几个大部分都是写完就忘。与其铺量不如精选。我现在维护的技能不到 20 个但每个都是高频使用、反复打磨过的实际价值远超大而全的技能库。最后分享一个小技巧给技能写“使用示例”。在技能文件里附上一两个典型的使用案例说明输入是什么、输出是什么。这个习惯看起来多余但实际非常有用——新人看示例比看描述快得多你自己过几个月回来看也能快速回忆起这个技能怎么用。这套东西还在快速演进不同工具链下的实现也在不断变化。但底层的思路是稳定的把能力结构化、把经验可复用、把协作标准化。抓住这个核心具体形式怎么变都不慌。