1. 从“superpowers”说起：一个让AI编程助手真正“能打”的技能框架
第一次看到“superpowers”这个词，是在一个开发者的讨论帖里。有人问：“为什么我的Claude Code写出来的代码总是差那么点意思？”底下最高赞的回复是：“你缺的不是模型，是superpowers。”当时我就来了兴趣——一个技能框架，凭什么能决定AI编程工具的上限？
说白了，superpowers是一个面向AI编程助手的技能增强框架，它本身不是模型，也不是IDE插件，而是一套方法论加工具链的组合。它的核心思路很直接：把软件开发中那些“老手才知道该怎么做”的隐性知识，拆解成AI能理解、能执行的技能模块，然后注入到Claude Code、Codex CLI这类工具的工作流里。你用它，相当于给AI配了一个经验丰富的技术主管，在每次写代码之前先帮它理清思路、选对方案、避开坑。
这东西解决的是什么问题？我举个例子你就明白了。默认状态下，你让Claude Code写一个用户登录功能，它大概率会直接给你生成一个包含用户名密码验证的函数，看起来没问题，但实际跑起来你会发现：密码没加盐、没有防暴力破解、session管理用的是最简陋的方式。不是模型不会，而是它不知道你的项目上下文里“什么叫做对”。superpowers做的事情，就是通过一套结构化的技能定义，告诉AI：“在这个场景下，你应该先考虑这些约束，再动手写代码。”
适合谁来用？三类人最受益。第一类是刚接触AI编程助手的开发者，你还不清楚怎么跟AI高效协作，superpowers能帮你建立正确的工作流。第二类是已经在用Claude Code或Codex CLI但觉得效果不稳定的人，你的问题很可能出在“没有给AI足够的结构化引导”。第三类是团队技术负责人，你想把团队的开发规范沉淀成AI能执行的技能，superpowers提供了一套可复用的框架。
我自己的体验是，用了superpowers之后，Claude Code生成代码的一次通过率大概从原来的六成提升到了八成以上。这个提升不是玄学，而是因为AI在动手之前被强制走了一遍“思考流程”。接下来我会把这套框架的核心逻辑、安装配置、实操细节和踩坑经验全部拆开讲清楚。
2. 核心设计思路拆解：为什么是“技能”而不是“提示词”
2.1 提示词工程的瓶颈在哪里
大多数人用Claude Code或者Codex CLI的方式，是在对话框里敲一段自然语言描述，然后等结果。这种方式在简单任务上没问题，但一旦涉及多步骤、多约束的开发任务，就会暴露三个致命问题。
第一个问题是上下文漂移。你跟AI聊了十几轮之后，它可能已经忘了你最开始说的“这个项目用TypeScript严格模式”或者“所有API调用必须走统一的错误处理中间件”。第二个问题是约束遗漏。你不可能在每次对话里把所有项目规范都重复一遍，但AI不会主动问你“你们团队的代码风格是什么”。第三个问题是决策质量不稳定。同一个需求，你今天问和明天问，AI给出的方案可能完全不同，因为它每次都在“即兴发挥”。
superpowers的设计者显然想清楚了这件事：与其让用户每次手动写一大段提示词，不如把常见的开发场景抽象成可复用的技能模块。每个技能模块本质上是一组结构化的指令，包含触发条件、执行步骤、约束检查和输出规范。当AI识别到当前任务匹配某个技能时，就自动加载对应的指令集。
2.2 技能框架的三层结构
我拆解了superpowers的架构，它大致分为三层。
最底层是技能定义层。每个技能是一个独立的配置文件，通常用YAML或JSON格式描述。里面定义了技能名称、适用场景、前置条件、执行步骤和验证规则。比如一个“REST API端点开发”技能，会明确规定：必须先定义请求和响应的数据模型，再写路由处理函数，最后补充参数校验和错误处理。
中间层是技能调度层。这一层负责判断当前任务应该激活哪些技能。它根据用户输入的关键词、当前打开的文件类型、甚至Git分支的名称来做匹配。比如你正在编辑一个.test.ts文件，调度层就会自动加载“单元测试编写”技能。
最上层是执行与反馈层。AI按照技能定义的步骤执行任务，每完成一步都会做一次自检。如果发现输出不符合技能定义的验证规则，就会自动回退重做。这个机制是superpowers区别于普通提示词模板的关键——它有闭环校验。
2.3 为什么选择“框架”而不是“插件”
有人可能会问：为什么不直接做一个IDE插件，把所有这些规则硬编码进去？答案是灵活性。插件的方式意味着每次调整规则都要等开发者更新版本，而框架的方式允许用户自己定义技能。你可以把团队内部的代码规范写成技能文件，也可以针对特定项目定制专属技能。这种开放性让superpowers能适配各种不同的技术栈和团队文化。
另一个考虑是跨工具兼容。Claude Code、Codex CLI、甚至未来可能出现的其他AI编程工具，都可以接入同一套技能定义。你不需要为每个工具单独维护一套规则。这对于同时使用多个AI编程助手的开发者来说，省了很多重复劳动。
注意：技能定义文件的质量直接决定了框架的效果。我见过有人把技能文件写成了一大段模糊的自然语言描述，结果AI执行起来跟没加载技能差不多。技能定义必须具体到可操作、可验证的程度。
3. 环境准备与安装配置：从零把superpowers跑起来
3.1 前置条件检查
在安装superpowers之前，你需要先确保基础环境就绪。根据我的实操经验，以下条件是必须满足的。
- Node.js 18以上：superpowers的CLI工具和部分技能运行时依赖Node环境。用
node -v检查版本，低于18的话建议用nvm升级。 - Claude Code或Codex CLI已安装并可用：superpowers本身不提供AI能力，它是对现有工具的增强。你需要先确保至少一个AI编程助手能正常工作。
- Git环境：技能文件的版本管理和部分自动化流程依赖Git。确保
git --version能正常输出。 - 一个可用的代码编辑器：VS Code是首选，因为Claude Code的VS Code插件体验最完整。如果你用其他编辑器，CLI模式也能用，但部分交互功能会受限。
关于Claude Code的安装，不同系统略有差异。macOS用户可以通过官方提供的安装脚本一键完成，Ubuntu用户需要注意权限问题，建议用sudo安装到全局路径。Windows用户如果遇到“与64位版本不兼容”的提示，通常是因为Node版本不对，换成64位版本即可。
3.2 superpowers的安装步骤
superpowers的安装方式取决于你使用的AI编程工具。目前主流的方式是通过npm全局安装CLI工具，然后在项目目录下初始化技能配置。
# 全局安装superpowers CLI npm install -g @superpowers/cli # 在项目根目录初始化 cd your-project superpowers init执行superpowers init之后，会在项目根目录生成一个.superpowers文件夹，里面包含默认的技能定义文件和配置文件。默认技能集覆盖了常见的开发场景：代码审查、单元测试、API开发、数据库迁移、重构等。
如果你用的是Claude Code，还需要在Claude Code的配置中注册superpowers的技能目录。具体操作是在Claude Code的设置里找到“技能路径”或“扩展配置”选项，把.superpowers/skills目录的绝对路径填进去。Codex CLI的配置方式类似，但配置文件的位置不同，通常在~/.codex/config.yaml中。
3.3 验证安装是否成功
安装完成后，用以下命令验证：
superpowers list如果输出了一列技能名称和状态，说明安装成功。你还可以用superpowers check来验证技能文件是否有语法错误或逻辑冲突。
我建议在正式使用之前，先在一个测试项目里跑一遍。创建一个简单的Node.js项目，然后让Claude Code执行一个“添加健康检查端点”的任务。观察Claude Code是否自动加载了相关的API开发技能，以及生成的代码是否符合技能定义中的规范。
提示：如果你在Ubuntu上安装时遇到权限报错，不要直接用
sudo npm install -g，这会导致后续权限混乱。正确的做法是配置npm的全局目录到用户目录下，或者使用nvm管理Node版本。
4. 核心技能模块详解与实操要点
4.1 代码审查技能：让AI学会“挑自己的刺”
代码审查技能是superpowers里使用频率最高的模块之一。它的核心逻辑是：在AI生成代码之后，强制它切换到一个“审查者”的角色，按照预设的检查清单逐项验证。
默认的审查清单包含以下维度：
| 检查维度 | 具体内容 | 严重等级 |
|---|---|---|
| 安全性 | SQL注入、XSS、敏感信息硬编码 | 高 |
| 性能 | N+1查询、不必要的循环、内存泄漏 | 中 |
| 可维护性 | 函数长度、命名规范、注释完整性 | 中 |
| 错误处理 | 异常捕获、边界条件、降级策略 | 高 |
| 测试覆盖 | 单元测试、集成测试、边界用例 | 低 |
实操中我发现，这个技能最有用的地方是强制AI在输出代码后自动运行一次审查。你不需要手动触发，只要在技能配置里把auto_review设为true，每次代码生成完毕就会自动执行审查流程。审查结果会以注释的形式附加在代码后面，标注出需要修改的地方。
有一个细节值得注意：审查技能的严格程度是可以调节的。在.superpowers/config.yaml里有一个review_level参数，可选值有strict、moderate和loose。我建议新项目用strict，遗留项目用moderate，否则你会被大量的审查意见淹没。
4.2 单元测试生成技能：从“能跑”到“敢改”
单元测试是很多开发者的痛点——知道该写，但总是拖着不写。superpowers的测试生成技能试图解决这个问题，它的做法是：在你写完一个函数之后，自动分析函数的输入输出和分支逻辑，生成对应的测试用例。
这个技能的配置里有一个关键参数叫coverage_target，默认值是80%。它决定了AI生成测试用例的覆盖目标。如果你设成95%，AI会生成更多的边界用例，但也会花更多时间。我的经验是，核心业务逻辑设90%以上，工具函数设70%就够了。
测试生成技能还有一个很实用的功能：变异测试。它会故意修改你的源代码（比如把>改成>=），然后看测试用例是否能捕获这个变化。如果捕获不到，说明测试用例的质量不够。这个功能在默认配置里是关闭的，需要在技能文件中手动开启。
# .superpowers/skills/unit-test.yaml name: unit-test-generation coverage_target: 85 mutation_testing: true mutation_operators: - conditional_boundary - arithmetic_operator - return_value4.3 API开发技能：约束先于代码
API开发技能是我个人觉得设计得最巧妙的一个模块。它的核心思路是先定义契约，再实现逻辑。当你让AI开发一个新的API端点时，技能会强制它先输出接口定义（包括请求方法、路径、参数、响应格式），等你确认之后才开始写实现代码。
这个流程的好处是避免了“AI写了一堆代码但接口设计不合理”的情况。我踩过的坑是：有一次让Claude Code直接写一个用户注册接口，它把密码强度校验放在了数据库层，导致错误信息无法正确返回给前端。如果当时用了API开发技能，契约定义阶段就会明确“校验逻辑必须在业务层完成”。
API开发技能还内置了版本兼容性检查。当你修改一个已有接口时，它会自动对比新旧契约，标记出破坏性变更（比如删除了某个响应字段）。这个功能在维护公开API时特别有用。
4.4 数据库迁移技能：安全第一
数据库迁移是高风险操作，superpowers对这个技能的设计非常保守。默认情况下，任何迁移操作都需要二次确认。AI会先生成迁移脚本，然后暂停执行，等你手动确认后才继续。
迁移技能的核心检查项包括：
- 是否有
DROP或TRUNCATE操作（高风险，需要额外确认） - 是否添加了非空列但没有默认值（会导致现有数据插入失败）
- 是否修改了列类型（可能造成数据截断）
- 是否有对应的回滚脚本
我建议在技能配置里把require_rollback设为true，强制每次迁移都必须提供回滚方案。这个习惯在出问题的时候能救命。
注意：数据库迁移技能在Codex CLI和Claude Code上的行为略有不同。Codex CLI默认不会自动执行迁移命令，需要你手动运行；Claude Code在某些配置下会直接执行。建议在技能配置里明确设置
auto_execute: false，避免意外。
5. 与Claude Code和Codex CLI的深度集成
5.1 Claude Code的集成配置
Claude Code是目前对superpowers支持最完整的工具。集成方式有两种：一种是通过VS Code插件，另一种是纯CLI模式。
VS Code插件的配置相对简单。安装Claude Code插件后，在设置里找到claude-code.superpowers.path，填入.superpowers目录的路径。插件会自动加载技能文件，并在对话中根据上下文激活对应技能。你可以在插件的输出面板里看到技能激活的日志，方便调试。
CLI模式的配置需要手动编辑~/.claude/config.json文件，添加以下字段：
{ "superpowers": { "enabled": true, "skillsPath": "/absolute/path/to/.superpowers/skills", "autoActivate": true, "logLevel": "info" } }autoActivate设为true时，Claude Code会根据当前编辑的文件类型和对话内容自动匹配技能。如果你希望手动控制，设为false，然后在对话中用/skill命令手动激活。
5.2 Codex CLI的集成方式
Codex CLI的集成稍微复杂一些，因为它的配置体系跟Claude Code不同。你需要在~/.codex/config.yaml中添加superpowers的技能路径，并且确保Codex CLI的版本支持外部技能加载。
# ~/.codex/config.yaml skills: - path: /absolute/path/to/.superpowers/skills auto_load: true priority: highCodex CLI有一个很实用的命令/compact，可以在对话历史过长时压缩上下文。配合superpowers使用时，我建议在每次激活新技能之前先执行一次/compact，避免技能指令被淹没在冗长的对话历史里。
另外，Codex CLI的/model命令可以切换底层模型。如果你用的是本地模型（比如通过LM Studio加载的模型），需要注意技能文件的复杂度不要太高，否则本地模型可能无法正确解析。我的经验是，本地模型适合使用简单的技能定义，复杂的多步骤技能还是交给云端模型处理。
5.3 跨工具的技能同步
如果你同时使用Claude Code和Codex CLI，可以通过Git来同步技能文件。把.superpowers目录纳入版本控制，然后在两个工具里都指向同一个目录。这样你在一处修改技能定义，另一处也能立即生效。
不过要注意，两个工具对技能文件的解析可能有细微差异。比如Claude Code支持在技能定义中使用条件分支，而Codex CLI可能不支持。我建议在技能文件里避免使用过于复杂的逻辑，保持定义的简洁和通用性。
6. 常见问题与排查技巧实录
6.1 技能不生效的排查思路
这是最常见的问题。你配置好了技能文件，但AI的行为跟没加载技能一样。排查步骤按以下顺序进行。
第一步，检查技能文件路径是否正确。用superpowers list命令确认技能是否被正确识别。如果列表为空，说明路径配置有误。
第二步，检查技能文件的语法。YAML格式对缩进非常敏感，一个多余的空格就可能导致解析失败。用superpowers check命令做语法校验。
第三步，检查技能激活条件。有些技能定义了特定的触发条件，比如只在编辑特定文件类型时激活。如果你在.md文件里期待API开发技能生效，那肯定不会触发。
第四步，检查AI工具的日志。Claude Code和Codex CLI都有详细的日志输出，可以看到技能加载和激活的过程。如果日志里没有技能相关的记录，说明集成配置有问题。
6.2 技能冲突的处理
当你同时激活多个技能时，可能会出现指令冲突。比如代码审查技能要求“所有函数必须有注释”，而某个重构技能要求“删除冗余注释”。这种冲突会导致AI行为不稳定。
superpowers提供了一个冲突检测机制。在技能配置里可以定义exclusive_with字段，声明该技能与哪些技能互斥。当检测到冲突时，调度层会根据优先级选择激活哪个技能。
我的建议是，在项目初期不要加载太多技能。先启用最核心的三到四个，等团队适应了再逐步增加。技能太多不仅容易冲突，还会让AI的响应变慢。
6.3 性能问题的优化
加载superpowers之后，AI的响应时间可能会变长，因为每次生成代码之前都要走一遍技能定义的流程。如果你觉得太慢，可以从以下几个方面优化。
减少技能数量。只保留当前项目真正需要的技能，把其他的禁用掉。简化技能定义。把冗长的描述精简成关键步骤，去掉不必要的解释性文字。调整autoActivate策略。对于简单任务，手动激活技能比自动激活更快。
还有一个容易被忽略的点：技能文件的加载顺序。superpowers默认按字母顺序加载技能，但你可以通过priority字段调整。把高频使用的技能设为高优先级，可以减少调度层的匹配时间。
6.4 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| 技能列表为空 | 路径配置错误 | 检查skillsPath是否指向正确目录 |
| 技能加载报错 | YAML语法错误 | 用superpowers check校验 |
| AI不按技能执行 | 激活条件不匹配 | 检查技能触发条件，手动激活测试 |
| 响应速度明显变慢 | 技能过多或定义过长 | 精简技能集，优化定义 |
| 多个技能行为冲突 | 指令矛盾 | 设置exclusive_with或调整优先级 |
| 本地模型无法解析技能 | 模型能力不足 | 简化技能定义，或改用云端模型 |
提示：如果你在Windows上遇到“与64位版本不兼容”的报错，大概率是Node.js装成了32位版本。卸载后重新安装64位版本即可解决。这个问题在Claude Code和Codex CLI上都出现过。
7. 我的实操心得与进阶建议
7.1 从“能用”到“好用”的关键调整
刚开始用superpowers的时候，我犯了一个错误：把所有默认技能全部启用。结果AI每次生成代码都要走一遍完整的审查、测试、文档流程，速度慢得让人抓狂。后来我调整了策略，只保留三个核心技能：代码审查、单元测试和API开发。其他技能按需手动激活。这样既保证了代码质量，又不会拖慢日常开发节奏。
另一个心得是技能定义要迭代。不要指望一次写好的技能文件能一直用下去。我在用了两周之后，根据实际效果调整了审查技能的检查项，去掉了一些过于苛刻的规则，增加了一些项目特有的约束。技能文件应该像代码一样，持续维护和优化。
7.2 团队协作中的技能管理
如果你在团队里推广superpowers，建议把技能文件纳入代码仓库，跟项目代码一起做版本管理。这样每个团队成员用的都是同一套技能定义，AI生成的代码风格和质量标准才能统一。
我们还建立了一个技能评审流程：任何人修改技能文件都需要提交PR，由至少一个其他成员review。这个流程听起来有点重，但实际运行下来效果很好，避免了有人不小心把技能配置改坏导致整个团队的AI行为异常。
7.3 后续可以扩展的方向
superpowers的框架本身是开放的，你可以根据自己的需求扩展技能。我目前正在尝试的一个方向是将代码审查技能与CI/CD流水线集成。思路是在CI阶段自动运行superpowers的审查技能，把审查结果作为合并请求的评论输出。这样即使开发者本地没有配置superpowers，代码质量也能得到保障。
另一个方向是针对特定框架的技能包。比如React、Vue、Django这些主流框架，每个都有一些约定俗成的最佳实践。把这些实践写成技能文件，可以让AI在开发对应框架的项目时表现更好。我已经在整理一套React技能包，等成熟了再分享出来。
最后分享一个小技巧：如果你不确定某个技能是否适合当前项目，可以先用superpowers dry-run命令做一次模拟执行。它会展示技能激活后AI会执行哪些步骤，但不会真正修改代码。这个功能在调试技能定义时特别有用，能帮你快速发现逻辑问题。
