1. 拆解 superpowers：它到底想解决什么问题

第一次看到 “superpowers” 这个词，很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但如果你最近在关注 AI 辅助编程这个圈子，就会发现它其实是一个面向agentic skills framework的软件工程方法论实践集合。简单说，它试图回答一个很具体的问题：当我们把 Claude Code、Codex CLI 这类终端里的 AI 编程助手当成日常工具之后，怎么让它们不只是“能跑”，而是“跑得稳、跑得可复现、跑得能积累”？

我自己的理解是，superpowers 更像是一套围绕 AI 编程代理构建的“技能框架 + 工作流约定”。它不绑定某一个具体模型，也不要求你必须用某个特定平台。你可以把它看成一份写给开发者的操作手册：哪些任务适合交给代理去做，哪些必须自己盯着；上下文怎么组织，命令怎么拆解，失败之后怎么回滚，做完之后怎么把经验沉淀成下一次可以直接复用的技能模块。这些内容听起来有点抽象，但落到实际项目里，每一个点都对应着真实的痛点。

举个很常见的场景。你用 Claude Code 在终端里让它帮你重构一个模块，第一次它改得不错，第二次换个需求再让它改，它可能就把之前的结构又打乱了。问题不在于模型能力不够，而在于你没有给它一个稳定的“技能边界”和“验收标准”。superpowers 这类框架的价值，就是把这些边界和标准显式地写出来，让代理每次执行时都有据可依。它适合谁？我认为三类人最应该关注：一是已经把 AI 编程助手接入日常开发流程的工程师；二是正在搭建团队内部 AI 辅助规范的技术负责人；三是想从“会用”进阶到“用得好”的独立开发者。

2. 核心设计思路：为什么是技能框架而不是提示词合集

2.1 从“提示词工程”到“技能工程”的转变

早期大家用 AI 编程助手，习惯攒一堆提示词模板，遇到什么任务就翻出来改一改。这种做法在单次任务里有效，但一旦任务变多、协作变复杂，就会暴露两个问题：第一，提示词之间没有依赖关系，无法组合；第二，提示词没有版本管理，改坏了很难回退。superpowers 的思路是把“提示词”升级成“技能”。一个技能不只是几句话，它包含触发条件、输入输出约定、执行步骤、验收标准，甚至包括失败之后的降级方案。

这个转变背后的逻辑其实很朴素。你想想，一个刚入职的工程师，你不会只给他一句“把这个功能做了”，你会告诉他背景是什么、边界在哪里、做完怎么验证。技能框架就是把这种“带人”的方式标准化，只不过对象换成了 AI 代理。这样做的好处是，技能可以被复用、被测试、被迭代。今天你写了一个“数据库迁移”技能，明天遇到类似任务，直接调用就行，不需要重新组织语言。

2.2 为什么选择终端优先而不是 IDE 优先

从热词里能看到大量关于 Claude Code、Codex CLI、VS Code 配置的讨论。superpowers 的实践路径明显偏向终端优先。这不是说 IDE 不好，而是终端环境有几个天然优势：第一，命令和输出都是文本，容易被代理理解和记录；第二，终端里的操作更接近“原子步骤”，一个命令做一件事，方便拆解和回滚；第三，终端环境更容易做自动化串联，比如把格式化、测试、提交串成一条流水线。

我在实际使用中发现，终端优先还有一个隐性好处：它强迫你把任务想清楚。在 IDE 里点来点去，很多操作是隐式的；在终端里，你必须写出具体命令。这个“写出来”的过程，本身就是一次需求澄清。superpowers 把这一点放大，要求每个技能都明确写出执行命令和预期输出，这样代理执行时就不会“自由发挥”。

2.3 框架的边界：它不做什么

有一点需要提前说清楚，superpowers 不是模型，不是插件，也不是某个平台的专属功能。它不会帮你自动安装 Claude Code，也不会替你解决账号注册或者网络环境的问题。它是一层方法论，落在具体工具之上。你可以用 Claude Code 来执行它，也可以用 Codex CLI 来执行它，甚至可以用其他支持终端调用的模型来执行。它的价值在于“怎么组织工作”，而不是“用什么工具工作”。理解这一点很重要，否则你会在工具选型上浪费很多时间。

3. 核心细节解析：一个技能模块应该包含什么

3.1 技能描述与触发条件

一个可用的技能模块，第一件事是写清楚“什么时候用它”。这听起来简单，但很多人会忽略。比如你写了一个“修复测试失败”的技能，如果没有触发条件，代理可能在代码还没写完的时候就跑去修测试。触发条件应该尽量具体，包含前置状态和用户意图。例如：“当测试命令返回非零退出码，且用户明确要求修复测试时，加载本技能。”这种描述比“用于修复测试”要可靠得多。

触发条件还有一个作用是防止技能被滥用。AI 代理有时候会过度积极，看到一点相关信号就调用某个技能。明确的触发条件相当于一道闸门，只有满足条件才放行。我在自己的项目里会把触发条件写成类似配置的格式，方便代理解析，也方便自己复查。

3.2 输入输出约定与验收标准

技能的执行结果必须可验证。superpowers 强调验收标准要前置，也就是说，在技能开始执行之前，就要定义好“什么样算完成”。比如一个“添加日志”的技能，验收标准可能是：指定模块的关键路径上出现日志语句，日志级别符合项目规范，运行测试时日志不导致失败。这些标准写出来之后，代理执行时就有了目标，你验收时也有了依据。

输入输出约定则是让技能之间可以串联。一个技能的输出，可能是另一个技能的输入。比如“生成迁移脚本”技能输出一个文件路径，“执行迁移”技能接收这个路径。如果没有约定，代理每次都要重新推断，容易出错。我通常会用简单的结构化文本描述输入输出，不追求复杂格式，够用就行。

3.3 执行步骤与回滚方案

执行步骤要拆到“可观察”的粒度。什么叫可观察？就是每一步执行完，你都能通过命令输出或者文件变化判断它是否成功。比如“修改配置文件”这一步，执行完应该能看到文件内容变化；“运行测试”这一步，执行完应该能看到测试结果。如果一步里包含太多操作，失败了很难定位。

回滚方案是很多人会漏掉的部分。AI 代理执行任务时，失败是常态，不是异常。没有回滚方案，一次失败可能留下半成品状态，影响后续操作。superpowers 的做法是要求每个技能在执行前记录当前状态，比如用版本控制做快照，或者把关键文件备份到临时目录。这样失败之后可以快速恢复，而不是手动一点点清理。

提示：回滚方案不需要很复杂，git stash 或者复制一份文件通常就够了。关键是要有，而不是追求完美。

4. 实操过程：从零搭建一个可用的技能工作流

4.1 环境准备与工具确认

在开始之前，你需要确认几件事。第一，你有一个可以执行终端命令的 AI 编程助手，Claude Code 或者 Codex CLI 都可以。第二，你的项目在版本控制之下，这是回滚的基础。第三，你清楚自己最常重复的任务是什么，这是你第一个技能模块的候选。

我不建议一上来就搭一个大而全的框架。先选一个你每周至少做三次的小任务，比如“格式化代码并运行 lint”或者“根据错误日志定位问题”。把这个任务写成技能模块，跑通一遍，再考虑扩展。这样做的原因是，小任务反馈快，你能迅速发现框架设计里的问题，调整成本低。

4.2 编写第一个技能模块

假设我们选的任务是“运行测试并汇总失败信息”。技能模块可以这样写：

## 技能：测试失败汇总 ### 触发条件 - 用户要求运行测试 - 当前目录存在测试配置文件 ### 输入 - 测试命令（默认：npm test） ### 执行步骤 1. 执行测试命令，捕获输出 2. 如果退出码为 0，报告“全部通过” 3. 如果退出码非 0，提取失败用例名称和错误摘要 4. 将失败信息写入 test-failures.md ### 验收标准 - test-failures.md 存在 - 文件中包含至少一个失败用例名称 - 文件内容不超过 200 行 ### 回滚方案 - 删除 test-failures.md

这个模块很简单，但它包含了触发条件、输入、步骤、验收和回滚。你可以把它放在项目根目录的 skills 文件夹里，然后在跟代理对话时明确说“加载测试失败汇总技能”。代理会按照这个结构执行，而不是自由发挥。

4.3 参数选择与命令拆解的实际考量

在执行步骤里，命令的写法很关键。以测试命令为例，不同项目的测试命令不一样，有的用 npm test，有的用 pytest，有的用 go test。如果你把命令写死，技能就无法复用。更好的做法是把命令作为输入参数，技能里只写“执行输入中指定的测试命令”。这样同一个技能可以适配不同项目。

另一个细节是输出处理。测试输出可能很长，直接全部塞给代理会占用大量上下文。我通常会在技能里加一步“提取关键信息”，比如只保留失败用例名称和错误类型，把完整输出写到文件里备查。这样代理看到的上下文更干净，判断也更准确。

4.4 实操现场记录：一次完整的技能执行

我拿一个真实的小项目试了一遍。项目是一个 Node.js 服务，测试用 Jest。我先把上面的技能模块放到 skills 目录，然后对 Claude Code 说：“加载测试失败汇总技能，测试命令是 npx jest。”代理先读取了技能文件，然后执行命令。第一次执行时，有两个用例失败。代理按照步骤提取了失败用例名称和错误摘要，写入了 test-failures.md。我检查了文件，内容符合验收标准。然后我修复了其中一个用例，再次执行技能，文件更新为只剩一个失败用例。整个过程没有出现代理乱改代码的情况，因为技能里没有授权它修改代码，它只做了汇总。

这次实操让我确认了一件事：技能模块的边界越清晰，代理的行为越可控。如果你在技能里写“修复失败的测试”，代理就会尝试改代码，风险立刻上升。所以第一个技能最好选只读操作，先建立信任，再逐步放开写操作。

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

5.1 代理不按技能执行怎么办

这是最常见的问题。原因通常有三个：第一，触发条件写得太模糊，代理觉得当前场景不匹配；第二，技能文件没有被正确加载，代理根本不知道有这个技能；第三，代理的上下文里已经有其他指令，优先级冲突。排查顺序建议从加载开始，确认代理能读到技能文件；然后检查触发条件，看是否过于严格或过于宽松；最后检查对话历史，看是否有冲突指令。

我自己的经验是，在对话开头明确说“本次对话只使用以下技能”，比让代理自己判断要可靠。代理的判断能力在复杂场景下并不稳定，显式指定能减少很多意外。

5.2 技能执行到一半失败怎么恢复

如果技能有回滚方案，直接执行回滚，然后重新加载技能。如果没有回滚方案，先手动恢复到执行前的状态，再补上回滚方案。这里的关键是不要在半成品状态上继续叠加操作，那样只会让问题更复杂。我踩过一次坑：代理修改了配置文件之后失败，我没有回滚就直接让它重试，结果配置文件里出现了重复内容，排查了很久。从那以后，我要求每个写操作技能必须先做备份。

5.3 多个技能之间如何避免冲突

当你有多个技能时，冲突主要出现在两个方面：文件操作重叠和上下文占用。文件操作重叠可以通过约定目录来避免，比如每个技能只操作自己负责的目录。上下文占用则需要控制技能输出的信息量，尽量让技能输出结构化摘要，而不是原始日志。我通常会把技能输出限制在 50 行以内，超出部分写到文件里，代理只读摘要。

下面这张表整理了我遇到过的典型问题和处理方式，可以直接对照排查：

5.4 关于工具链选择的几点个人建议

Claude Code 和 Codex CLI 我都用过一段时间。Claude Code 在理解复杂技能描述方面表现更稳，适合执行步骤较多的技能；Codex CLI 在命令执行和文件操作上更直接，适合步骤简单的技能。如果你刚开始搭建，我建议先用一个工具跑通流程，不要同时折腾多个。等技能模块稳定了，再考虑跨工具复用。

另外，关于本地模型接入，热词里提到不少相关讨论。我的看法是，本地模型适合对隐私要求高、任务相对固定的场景。如果你的技能模块需要频繁调用外部命令和读写文件，本地模型的工具调用能力需要仔细验证。不要因为“本地”就默认它更可控，实际表现取决于具体模型和配置。

6. 技能框架的扩展与长期维护

6.1 从单技能到技能库的演进路径

当你有了三五个稳定运行的技能之后，就可以考虑把它们组织成技能库。技能库的核心是索引和分类。索引让代理能快速找到需要的技能，分类让人类维护者能快速定位。我自己的做法是按任务类型分目录，比如“代码质量”“测试”“部署”“文档”，每个目录下放对应的技能文件。然后在根目录放一个 index.md，列出所有技能的名称、触发条件和文件路径。

这个演进路径不需要一步到位。你可以先手动维护索引，等技能数量超过二十个再考虑自动化生成。过早自动化会增加维护成本，而且你还不清楚自己的分类习惯。

6.2 技能版本管理与迭代

技能也是代码，应该纳入版本管理。每次修改技能，都要写清楚改了什么、为什么改。我通常会在技能文件顶部加一个变更记录，格式很简单：日期、修改人、修改内容。这样当技能行为发生变化时，能快速定位到是哪次修改导致的。

迭代技能时，建议保留旧版本一段时间。新版本可能在某些场景下表现不如旧版本，保留旧版本可以快速切换。我一般会保留最近三个版本，超过三个再清理。

6.3 团队协作中的技能共享

如果团队多人使用同一套技能库，需要约定一些规则。第一，技能文件命名要统一，建议用“动词-名词”格式，比如“run-tests”“fix-lint”。第二，修改技能需要经过评审，避免个人偏好影响团队。第三，技能库要有明确的负责人，负责合并冲突和清理过期技能。

团队协作里最容易出问题的是“私有技能”和“公共技能”的边界。我的建议是，任何技能在稳定运行两周之后，都应该考虑是否提升为公共技能。长期停留在私有状态，会导致重复建设和知识孤岛。

6.4 技能框架的长期价值在哪里

用了一段时间之后，我最大的体会是：技能框架的价值不在于让 AI 做更多事，而在于让 AI 做的事更可预期。可预期意味着你可以放心地把重复任务交出去，把精力留给真正需要判断力的工作。这个转变不会一夜发生，但随着技能库的积累，你会发现自己跟代理的协作越来越顺，返工越来越少。

最后分享一个小技巧：每隔一段时间，回顾一下你的技能库，把那些超过一个月没用的技能归档。技能库不是越大越好，保持精简才能让代理快速定位。我现在的技能库维持在十五个左右，每个都经过多次迭代，用起来很稳。