1. 从“superpowers”说起：一个让 AI 编码助手真正长出“工程肌肉”的技能框架

第一次看到 “superpowers” 这个词，是在几个做 AI 辅助开发的朋友群里。有人甩了张截图，说“这玩意儿装完之后，Claude Code 像换了个脑子”。我当时的第一反应是：又一个包装提示词的噱头。但耐着性子把它的设计思路翻完之后，我改主意了——它解决的是一个非常具体、非常痛的问题：AI 编码助手很聪明，但它不懂“工程规矩”。

你肯定有过这种体验：让 Claude Code 或者 Codex CLI 帮你写个功能，它三下五除二给你吐出一大段代码，跑起来也能用，但代码风格飘忽、没有测试、边界条件全靠运气、改两行就崩。问题不在模型能力，而在于它默认的“工作方式”是一次性生成，而不是工程化交付。superpowers 这个 agentic skills framework 要做的，就是给 AI 助手装上一套“软件开发的肌肉记忆”——需求先澄清、方案先设计、代码先测试、改完先验证。它本质上是一套软件开发的技能框架，把资深工程师的工作流拆成一个个可复用的 skill，让 AI 在每一步都按规矩来。

这篇文章适合三类人看：一是已经在用 Claude Code、Codex CLI 但觉得“差点意思”的开发者；二是想把这套方法论迁移到自己团队 AI 工作流里的技术负责人；三是刚接触 agentic 工具、想知道“除了聊天还能干嘛”的新手。我会把 superpowers 的核心设计、安装配置、实操流程、踩坑经验全部拆开讲，代码和命令都能直接抄。注意，本文讲的是方法论和工具使用，不涉及任何网络访问相关的操作，所有安装都基于官方公开渠道。

2. superpowers 到底解决了什么问题：AI 编码的“最后一公里”

2.1 为什么“能写代码”不等于“能交付代码”

我先说个真实场景。上个月帮一个朋友看他的小项目，他用 Claude Code 生成了一个用户注册模块，代码逻辑没问题，但打开一看：密码明文存了、没有输入校验、异常处理是空的、连个单元测试都没有。他跟我说“AI 写的，我也不太懂”。这就是典型的生成即完成的错觉。

AI 编码助手的能力边界很清楚：它擅长把“明确的意图”翻译成“可运行的代码”，但它不擅长主动补全工程约束。什么叫工程约束？就是那些“你不说它就不做，但做了才叫专业”的东西——错误处理、边界测试、日志、类型定义、依赖管理、代码分层。superpowers 的核心价值，就是把这些约束固化成 AI 必须走的流程。

它的设计逻辑我拆成三层来理解：

• 第一层是技能（skill）：每个 skill 是一个独立的、可复用的工作单元，比如“写测试”“做代码审查”“设计接口”。skill 不是提示词模板，而是带执行步骤和验收标准的流程定义。
• 第二层是编排（orchestration）：框架决定在什么阶段调用哪个 skill。比如接到一个新需求，先走“需求澄清”skill，再走“方案设计”skill，最后才进“编码”skill。
• 第三层是验证（verification）：每个 skill 执行完都有明确的产出物和检查点，AI 不能跳过验证直接进入下一步。

这三层叠起来，AI 的工作方式就从“一次性生成”变成了“分阶段交付”。这个转变听起来简单，但实际效果差别巨大——我实测下来，同一个需求，走 superpowers 流程产出的代码，返工率能降一半以上。

2.2 和直接写提示词的本质区别

有人会问：我直接在提示词里写“请先写测试再写代码”不就行了？我试过，不行。原因有两个。

第一，提示词是软的，流程是硬的。你在提示词里写“请写测试”，AI 可能写，也可能因为上下文太长忘了写。而 superpowers 把测试作为编码 skill 的前置依赖，不完成测试环节，编码环节根本不会启动。这是机制上的强制，不是靠 AI 自觉。

第二，提示词是一次性的，skill 是可积累的。你今天写一段提示词让 AI 做代码审查，明天换个项目又得重写。而 skill 是文件化的、可版本管理的、可跨项目复用的。你团队里沉淀下来的 skill 越多，AI 的“工程素养”就越高。这才是 agentic skills framework 真正的价值——它让 AI 的能力可沉淀、可传承。

提示：不要把 superpowers 理解成“更长的提示词”。它的核心是流程编排和技能复用，提示词只是 skill 内部的一个组成部分。

2.3 适用场景与不适用场景

不是所有任务都值得上这套框架。我总结了一个简单的判断标准：

我的经验是：任务越复杂、越需要多人协作、越需要长期维护，superpowers 的价值就越大。反过来，如果你只是想让 AI 帮你写个正则表达式，那确实没必要。

3. 环境准备：Claude Code 与 Codex CLI 的安装配置

3.1 先搞清楚你要用哪个宿主工具

superpowers 本身是一个技能框架，它需要宿主工具来承载——也就是实际执行 AI 对话和代码操作的那个 CLI 或 IDE 插件。目前主流的有两个：Claude Code和Codex CLI。两者都能跑 superpowers，但体验有差异。

Claude Code 是 Anthropic 官方出的命令行工具，优势是和 Claude 模型深度集成，skill 的调用和上下文管理做得比较顺。Codex CLI 是另一套命令行工具，优势是模型选择更灵活，可以接不同的后端。我两个都用过，说下实际感受：

• 如果你主要用 Claude 系列模型，优先选 Claude Code，配置简单，skill 兼容性好。
• 如果你需要切换不同模型（比如某些任务用这个、某些任务用那个），Codex CLI 更合适。
• 如果你在 VS Code 里工作，两个都有对应的插件，Claude Code for VS Code 的体验更完整一些。

下面我分别讲安装。所有安装都基于官方公开的包管理渠道，不涉及任何特殊网络配置。

3.2 Claude Code 的安装与初始化

Claude Code 的安装依赖 Node.js 环境。先确认你的 Node 版本：

node -v npm -v

建议 Node 18 以上。如果版本太低，先升级 Node。然后安装 Claude Code：

npm install -g @anthropic-ai/claude-code

安装完成后，进入你的项目目录，运行：

claude

第一次运行会引导你做初始化配置。这里有个新手最容易卡住的点：它会要求你登录或配置 API 访问方式。如果你用的是官方订阅，按引导登录即可；如果你用的是第三方 API 或本地模型，需要额外配置。关于本地模型的接入，我在第 5 章会专门讲。

初始化完成后，你会看到 Claude Code 的交互界面。这时候输入/help可以看到所有可用命令。几个高频命令先记一下：

• /compact：压缩当前对话上下文，长会话必备
• /model：切换模型
• /resume：恢复之前的会话
• /clear：清空当前上下文

注意：如果你在安装过程中遇到 “your organization has disabled claude subscription access” 这类提示，通常是账号权限或组织策略问题，需要检查你的账号配置，而不是工具本身的问题。

3.3 Codex CLI 的安装与常见坑

Codex CLI 同样基于 Node.js。安装命令：

npm install -g @openai/codex

这里我要重点说一个很多人踩过的坑：node安装codex cli很慢。这不是你的网络问题，而是 npm 默认源在拉取某些依赖时确实慢。解决办法是配置国内镜像源：

npm config set registry https://registry.npmmirror.com

配完之后再装，速度会快很多。如果已经装了一半卡住，先卸载再重装：

npm uninstall -g @openai/codex npm install -g @openai/codex

安装完成后，运行codex进入交互界面。Codex CLI 的命令体系和 Claude Code 略有不同，常用的有：

• /compact：压缩上下文
• /model：切换模型
• /resume：恢复会话

如果你要删除 Codex CLI，用：

npm uninstall -g @openai/codex

3.4 VS Code 插件配置要点

如果你习惯在 VS Code 里工作，两个工具都有插件。Claude Code for VS Code 的配置相对简单，装完插件后在设置里填入你的 API 配置即可。有几个配置项值得注意：

• 模型选择：插件里可以指定用哪个模型，建议和 CLI 保持一致，避免行为差异。
• 上下文范围：插件默认会把当前打开的文件作为上下文，如果项目大，建议手动控制，不然 token 消耗很快。
• 终端集成：Claude Code 可以直接执行终端命令，这个功能在插件里也能用，但建议先在小项目里试，确认行为符合预期再放开。

Ubuntu 和 Mac 上的配置流程基本一致，主要差异在 Node 环境的安装方式。Ubuntu 上建议用nvm管理 Node 版本，Mac 上用brew更省事。Windows 用户要注意，某些版本可能存在兼容性问题，如果遇到 “与64位版本不兼容” 的提示，优先检查 Node 和 npm 的位数是否匹配。

4. superpowers 的核心机制：技能框架是怎么运转的

4.1 skill 的文件结构与组织方式

superpowers 的 skill 本质上是结构化的 Markdown 文件，放在项目的特定目录下。一个典型的 skill 文件包含几个部分：

# Skill: 编写单元测试 ## 触发条件 当需要为新功能或修改的功能编写测试时 ## 前置依赖 - 已完成需求澄清 - 已确定接口定义 ## 执行步骤 1. 读取目标函数的签名和文档 2. 识别所有输入边界和异常路径 3. 为每个边界生成测试用例 4. 运行测试并确认全部通过 ## 验收标准 - 测试覆盖率不低于 80% - 所有边界条件都有对应用例 - 测试可独立运行，不依赖外部状态

这个结构的关键在于前置依赖和验收标准。前置依赖确保 skill 不会在错误的时机被调用，验收标准确保执行结果可检查。这两点是把“提示词”升级成“流程”的核心。

我建议你在组织 skill 时遵循一个原则：一个 skill 只做一件事。不要写“写代码并测试并部署”这种大杂烩，拆成“写代码”“写测试”“部署”三个独立 skill，编排层负责把它们串起来。这样每个 skill 都容易维护、容易复用、容易替换。

4.2 编排层如何决定“下一步做什么”

编排层是 superpowers 的“大脑”。它根据当前任务的状态，决定调用哪个 skill。这个决策逻辑通常基于两个输入：任务类型和当前进度。

举个例子，当你给 AI 一个“实现用户登录功能”的任务时，编排层的决策链大致是：

1. 任务类型是“新功能开发”，进入开发流程
2. 当前进度是“零”，先调用“需求澄清”skill
3. 需求澄清完成后，调用“方案设计”skill
4. 方案确认后，调用“接口定义”skill
5. 接口定义完成后，调用“编写测试”skill
6. 测试通过后，调用“编写实现”skill
7. 实现完成后，调用“代码审查”skill

每一步的产出物都是下一步的输入，形成一条可追溯的交付链。这个链条的价值在于：任何一步出问题，你都能定位到具体环节，而不是面对一坨“AI 生成的代码”无从下手。

4.3 验证机制：让 AI 不能“糊弄过去”

验证机制是我认为 superpowers 最被低估的部分。大多数 AI 工具的问题是：AI 说“完成了”，但你不知道它到底完成了没有。superpowers 通过强制产出物检查来解决这个问题。

每个 skill 执行完，必须产出可验证的结果。比如“编写测试”skill 的产出物是测试文件和测试运行报告，“代码审查”skill 的产出物是审查意见列表。编排层会检查这些产出物是否存在、是否符合验收标准，不符合就打回重做。

这个机制的实际效果是：AI 没法用“我觉得可以了”来蒙混过关。它必须拿出实际的东西。我实测下来，这个约束能显著减少“看起来完成了但实际不能用”的情况。

提示：验证标准要写得具体、可量化。“代码质量好”不是标准，“函数复杂度不超过 10、无重复代码块”才是标准。

5. 实操全流程：从零跑通一个 superpowers 项目

5.1 项目初始化与 skill 目录搭建

假设你有一个新项目，想用 superpowers 来管理 AI 的开发流程。第一步是建立 skill 目录结构。我常用的结构是这样的：

project/ ├── .superpowers/ │ ├── skills/ │ │ ├── requirement-clarify.md │ │ ├── design.md │ │ ├── write-test.md │ │ ├── implement.md │ │ └── review.md │ └── config.yaml ├── src/ └── tests/

.superpowers/skills/放所有 skill 文件，config.yaml放编排配置。config 里主要定义两件事：流程顺序和每个阶段的验收标准。

workflow: - name: requirement-clarify next: design - name: design next: write-test - name: write-test next: implement - name: implement next: review - name: review next: done

这个配置告诉编排层：接到新任务后，按这个顺序走。每个 skill 完成后自动进入下一个，除非验收不通过。

5.2 需求澄清 skill 的实际执行

需求澄清是整条链的起点，也是最容易被跳过的一步。很多人觉得“需求很清楚啊，直接写就行了”，但实际执行下来，这一步能省掉后面大量的返工。

我写的需求澄清 skill 大致是这样的：

# Skill: 需求澄清 ## 目标 把模糊的需求转化为明确的、可验证的功能描述 ## 执行步骤 1. 用一句话复述需求，确认理解无误 2. 列出所有不确定的点，逐条向用户确认 3. 明确输入、输出、边界条件 4. 明确不做什么（范围外事项） 5. 输出需求文档，等待用户确认 ## 验收标准 - 需求文档包含明确的输入输出定义 - 所有歧义点都已澄清 - 用户明确确认

实际跑的时候，AI 会先复述你的需求，然后抛出一堆问题：“用户登录失败时返回什么？”“密码错误几次锁定？”“是否需要记住登录状态？”这些问题你平时可能想不到，但都是实现时必须回答的。这一步的价值就是把“实现时才发现的坑”提前到“动手前就填平”。

5.3 测试先行：让 AI 先写测试再写实现

测试先行是 superpowers 流程里最“反直觉”但最有效的一环。大多数人让 AI 写代码的顺序是“先实现，再补测试”，但 superpowers 强制反过来：先写测试，测试通过后再写实现。

为什么？因为测试是对需求的可执行验证。你先写测试，等于先把“什么叫完成”定义清楚了。AI 写实现的时候，目标就变成了“让这些测试通过”，而不是“写一段看起来对的代码”。这个目标转变，能极大减少“代码能跑但不符合需求”的情况。

实际操作时，write-test skill 会：

1. 读取需求文档和接口定义
2. 为每个功能点生成测试用例
3. 运行测试，确认全部失败（因为实现还没写）
4. 输出测试报告

第 3 步很关键——测试必须先失败。如果测试一开始就通过，说明测试写错了，或者测的是已有功能。这个“红-绿-重构”的节奏，是测试驱动开发的核心，superpowers 把它固化进了流程。

5.4 实现与审查：闭环是怎么形成的

测试写完后，进入 implement skill。这时候 AI 的任务很明确：写最少的代码让所有测试通过。这个约束很重要，它防止 AI 过度设计、写一堆用不上的代码。

实现完成后，自动进入 review skill。代码审查不是走过场，它有具体的检查项：

审查不通过就打回上一步，直到全部通过。这个闭环跑下来，产出的代码质量比我手动写再让 AI 补测试要高不少。核心原因是：每一步都有明确的验收标准，AI 没有“差不多就行”的空间。

6. 进阶玩法：本地模型接入与多模型切换

6.1 用本地模型跑 Claude Code 的思路

有些场景下，你可能想用本地模型来跑 Claude Code，比如数据敏感、或者想省 API 成本。Claude Code 支持通过配置接入本地模型服务，前提是你本地有一个兼容的模型服务在跑。

配置的核心是指定模型服务的地址和模型名称。具体配置方式因版本而异，但思路是一致的：在 Claude Code 的配置文件里，把模型端点指向本地服务的地址。这里我不展开具体配置细节，因为不同版本的配置项可能变化，建议以官方文档为准。

需要提醒的是：本地模型的能力和云端模型有差距，尤其是在复杂推理和长上下文处理上。superpowers 的流程对模型的指令遵循能力要求比较高，如果本地模型跟不上，skill 的执行质量会打折扣。我的建议是：简单任务用本地模型，复杂任务还是用云端模型。

6.2 多模型切换的实操技巧

Codex CLI 在多模型切换上更灵活。你可以通过/model命令在会话中切换模型，也可以在不同项目里配置不同的默认模型。

我的使用策略是这样的：

• 需求澄清和方案设计：用推理能力强的模型，这一步质量决定后面所有环节
• 写测试和写实现：用代码能力强的模型，速度也要考虑
• 代码审查：用另一个模型，避免“自己审自己”的盲区

这个策略的核心是让不同模型发挥各自优势，同时通过“换模型审查”来引入不同的视角。实测下来，换模型审查能发现不少同模型审查漏掉的问题。

6.3 第三方 API 接入的注意事项

如果你用的是第三方 API 服务，有几个点要注意：

• 兼容性：确认 API 的接口格式和 Claude Code / Codex CLI 兼容，不兼容的话需要中间层转换
• 上下文长度：第三方服务的上下文窗口可能和官方不同，配置时要对应调整
• 稳定性：第三方服务的响应稳定性直接影响 skill 执行，建议先小规模测试

注意：接入任何第三方服务前，先确认其合规性和数据安全策略，避免敏感代码外泄。

7. 常见问题与排查技巧实录

7.1 安装与配置类问题速查

7.2 skill 执行中的典型故障

故障一：skill 不触发。通常是触发条件写得太窄，或者编排配置里没把 skill 挂上。排查方法是手动调用 skill，看是否能执行。能执行说明是编排问题，不能执行说明是 skill 文件本身有问题。

故障二：skill 执行到一半卡住。最常见的原因是上下文超限。长会话里，前面的内容把上下文占满了，后面的 skill 没有足够空间执行。解决办法是用/compact压缩上下文，或者把大任务拆成小任务。

故障三：验收标准总是通不过。要么是标准定得太高，要么是 skill 的执行步骤不够具体。我的经验是：验收标准要可量化，执行步骤要可操作。“写好代码”不是标准，“函数不超过 50 行、有类型标注、有错误处理”才是。

7.3 我踩过的三个坑

第一个坑：skill 写得太细。一开始我把每个操作都写成一个 skill，结果编排层要调几十个 skill，光切换开销就很大。后来我改成按阶段划分，一个阶段一个 skill，内部步骤在 skill 里描述，效率高很多。

第二个坑：忽略上下文管理。superpowers 的流程比较长，一个完整流程跑下来，上下文消耗很大。我后来养成了习惯：每个阶段结束后手动/compact一次，保持上下文清爽。

第三个坑：验收标准形同虚设。早期我写的验收标准太模糊，AI 随便糊弄一下就过了。后来我把标准改成必须产出具体文件或具体数据，比如“测试报告里必须包含覆盖率数字”，效果立刻不一样。

7.4 性能与成本优化建议

superpowers 的流程比直接对话消耗更多 token，这是必然的——它做了更多的事。但有几个优化空间：

• 按需启用：不是所有任务都走完整流程，简单任务可以跳过部分 skill
• 上下文复用：相似的 skill 之间共享上下文，避免重复读取
• 模型分级：不同阶段用不同档位的模型，贵的模型用在关键决策上
• 缓存机制：对重复执行的结果做缓存，避免重复计算

我实测下来，合理配置后，superpowers 的 token 消耗大约是同任务直接对话的 1.5 到 2 倍，但返工率降低带来的时间节省，远超这个成本。

8. 把 superpowers 用成自己的东西

superpowers 这套框架最有意思的地方，不是它自带的那些 skill，而是它提供了一种把工程经验固化成 AI 可执行流程的方法。你团队里那些“老司机才知道”的规矩——比如“改数据库必须写迁移脚本”“接口必须版本化”“日志必须带 trace id”——都可以写成 skill，让 AI 每次都遵守。

我自己在实际使用中的体会是：skill 的质量比数量重要得多。与其写二十个半吊子 skill，不如把三五个核心 skill 打磨到“AI 执行完你完全放心”的程度。我现在项目里常驻的 skill 就五个：需求澄清、方案设计、测试先行、实现、审查。这五个跑顺了，AI 产出的代码质量已经能稳定在一个可接受的水平。

最后分享一个小技巧：定期回顾 skill 的执行记录。看看哪些 skill 经常被打回、哪些验收标准从来没触发过。经常被打回的 skill 说明步骤不够清晰，从来没触发过的标准说明定得太松。根据这些记录迭代 skill，比一次性写完就不管，效果好得多。这个框架后续还可以往“团队共享 skill 库”的方向扩展——把每个人沉淀的 skill 汇总起来，新项目直接复用，这才是 agentic skills framework 真正的长期价值。