Superpowers技能框架：让AI智能体按流程写代码的工程实践

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

第一次看到 “superpowers” 这个词，很多人会以为是某个超级英雄题材的游戏或者娱乐项目。但如果你最近在关注 AI 辅助编程这个圈子，尤其是在 Claude Code、Codex CLI 这些工具的讨论里频繁看到它，那它其实指向的是一个更有意思的东西——一套面向智能体（agent）的技能框架和软件开发方法论。简单说，它试图回答一个很实际的问题：当我们把越来越多的编码任务交给 AI 智能体去执行时，怎么让这些智能体不只是“能写代码”，而是“知道该怎么写、按什么流程写、写完怎么验证”。

这个问题的背景并不复杂。过去一两年，AI 编程工具的能力提升非常快，从最早的代码补全，到后来能理解整个文件、整个项目，再到现在能自主执行终端命令、读写文件、跑测试。工具本身越来越强，但很多人用下来的感受是：能力是有了，可产出质量忽高忽低。同一个需求，换个说法、换个时间，结果可能差很远。这不是模型不行，而是缺少一套稳定的“工作方法”。superpowers 想做的，就是把这套工作方法固化下来，变成智能体可以遵循的技能和流程。

它适合谁来了解？我觉得有三类人值得花时间研究。第一类是已经在用 Claude Code 或 Codex CLI 做日常开发的工程师，你会发现同样的工具，加上一套方法论之后，产出稳定性完全不一样。第二类是想把 AI 智能体引入团队流程的技术负责人，你需要的不只是“能用”，而是“可复现、可审查、可交接”。第三类是对 agentic skills framework 这个概念本身感兴趣的人，想搞清楚“技能框架”到底是怎么设计的、为什么这样设计。这篇文章我会围绕这几个方向，把 superpowers 的核心思路、关键细节、实操要点和我自己踩过的坑都摊开讲一遍。

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

2.1 从提示词工程到技能工程的关键转变

很多人接触 AI 编程的第一步是学“怎么写提示词”。网上有大量提示词模板，告诉你加一句“你是一个资深工程师”就能让输出变好。但用久了你会发现，提示词工程有个天花板：它太依赖单次对话的上下文，换个会话、换个任务，之前调好的提示词就失效了。而且提示词是“一次性”的，你没法把它沉淀成一个可复用、可组合、可版本管理的资产。

superpowers 的思路不一样。它把智能体需要具备的能力拆成一个个独立的“技能”（skill），每个技能有明确的触发条件、执行步骤和验证标准。这就像从“每次手写一封邮件”变成“建一套邮件模板库加发送规则”。技能是可以被智能体自动识别和调用的，不需要你每次手动提醒。这个转变的意义在于：你把经验从“对话里”搬到了“框架里”，它变得可积累、可迭代。

我自己的体会是，用纯提示词的时候，我脑子里得一直记着“这次要提醒它先读文件再改”“这次要让它跑完测试再提交”。用技能框架之后，这些约束变成了默认行为，我只需要关注任务本身。这个心智负担的降低，是实打实的。

2.2 技能框架的三个核心要素

拆开来看，一套能跑起来的技能框架至少需要三个东西。第一个是技能定义，也就是“这个技能是干什么的、什么时候用、具体怎么做”。第二个是触发机制，智能体怎么知道现在该调用哪个技能，是靠关键词匹配、任务类型判断，还是靠显式的流程编排。第三个是验证闭环，技能执行完之后，怎么确认结果是符合预期的，而不是“看起来对”。

这三个要素缺一不可。只有技能定义没有触发机制，技能就是摆设；只有触发没有验证，产出质量就没法保证。superpowers 在这三块上都有对应的设计，后面我会逐个展开。这里先建立一个整体认知：它不是让你写更长的提示词，而是让你把工作方法结构化。

2.3 为什么这套思路在 Claude Code 和 Codex CLI 上特别有意义

Claude Code 和 Codex CLI 这类工具和普通聊天式 AI 最大的区别，是它们能直接操作你的文件系统和终端。这意味着智能体的行为会产生真实后果——改错文件、跑错命令、提交错误代码，都是真实发生的。在这种场景下，“让智能体按流程办事”就不是锦上添花，而是刚需。

举个例子，一个没有流程约束的智能体，可能在你让它“修复这个 bug”的时候，直接改了三四个文件，然后告诉你“已修复”。但你不知道它改了什么、为什么这么改、有没有引入新问题。而一套技能框架会强制它先复现问题、再定位原因、再最小化修改、最后跑测试验证。这个流程本身就是质量保障。所以 superpowers 这类框架在 Claude Code、Codex CLI 生态里讨论度高，不是偶然，是因为这些工具的能力越强，对方法论的依赖就越深。

3. 核心细节解析：技能是怎么定义和触发的

3.1 技能定义的粒度怎么把握

设计技能时最容易犯的错，是粒度失控。太粗，一个技能包揽“开发一个功能”，那它本质上还是提示词，没有可操作性；太细，每个小动作都拆成技能，智能体光在技能之间切换就耗尽了上下文。我的经验是，一个技能对应“一个可独立验证的工作单元”比较合适。比如“复现一个 bug”“写一个单元测试”“重构一个函数”“审查一次代码变更”，这些都是有明确输入、明确产出、可以独立判断成败的单元。

判断粒度是否合适，有个简单的测试：你能不能在不看技能内部实现的情况下，仅凭技能名字和描述，就知道它什么时候该被调用、调用完你会得到什么。如果答案是肯定的，粒度基本没问题。如果描述里出现“以及”“同时”“顺便”这类词，通常说明该拆了。

3.2 触发机制：让智能体自己知道该用什么技能

触发机制是技能框架里最容易被低估的部分。很多人设计了一堆技能，但智能体根本不知道什么时候用，结果还是靠人手动指定。好的触发机制应该让智能体在面对任务时，能自动匹配到相关技能。

常见的做法有三种。第一种是基于任务描述的关键词和语义匹配，智能体分析当前任务，判断涉及哪些技能领域。第二种是基于流程阶段的显式编排，比如“开发流程”技能内部规定了先调用“需求澄清”再调用“方案设计”再调用“编码实现”。第三种是基于上下文的隐式触发，比如检测到当前目录有测试文件，就自动加载“测试相关”技能。

实际操作中，这三种往往是混用的。我自己的项目里，流程编排负责主干，语义匹配负责分支，上下文触发负责补充。这样既保证了主流程稳定，又保留了灵活性。需要注意的是，触发机制不能设计得太“聪明”，否则智能体会过度调用技能，反而拖慢速度。宁可触发条件明确一点，也不要让它猜。

3.3 验证闭环：怎么判断技能执行到位了

验证闭环是区分“玩具框架”和“生产框架”的分水岭。一个技能执行完，怎么知道它做对了？最直接的方式是定义可检查的产出标准。比如“写单元测试”这个技能，产出标准可以是：测试文件存在、测试能跑通、覆盖了指定的函数、断言数量合理。这些标准可以被自动检查，也可以被人工快速审查。

更进阶的做法是引入对抗性验证。也就是让另一个智能体或者另一个技能来“挑刺”，专门找产出里的问题。这在代码审查场景里特别有用。我自己试过让一个技能负责写代码，另一个技能专门负责找边界条件遗漏，效果比单个技能反复自我检查要好得多。当然，这会增加 token 消耗和执行时间，需要根据任务重要性来权衡。

提示：验证标准一定要在技能定义阶段就写清楚，不要等到执行完再想“怎么算做完了”。事后补标准，往往会变成“怎么都能算做完”。

4. 实操过程：从零搭一套能跑的技能框架

4.1 环境准备与工具选型

要实操这套东西，你需要先有一个能执行终端命令、读写文件的 AI 编程环境。Claude Code 和 Codex CLI 是目前比较主流的选择。Claude Code 的优势是和文件系统、终端的集成比较自然，适合做需要多步骤操作的任务；Codex CLI 在命令执行和脚本化方面有它的特点。两者都可以作为技能框架的运行载体。

安装和配置这块，不同平台差异不小。macOS 和 Ubuntu 上的安装流程相对顺畅，Windows 上偶尔会遇到兼容性提示，这个后面在问题排查里会细说。配置的核心是让工具能访问你的项目目录，并且有权限执行必要的命令。我建议一开始在一个独立的测试项目里折腾，不要直接在你的主力代码库上试，避免误操作。

工具选型上还有一个考虑：你是用官方提供的模型，还是接入第三方模型。这个选择会影响技能框架的稳定性，因为不同模型对技能定义的理解能力有差异。我的建议是先用官方模型把框架跑通，确认流程没问题之后，再考虑替换模型来降低成本或满足特定需求。

4.2 定义你的第一批技能

不要一上来就设计几十个技能，那样你根本维护不过来。从三到五个核心技能开始，覆盖你最常做的工作流。比如一个典型的开发流程可以拆成：需求澄清、方案设计、编码实现、测试验证、代码审查。这五个技能就能覆盖大部分日常任务。

每个技能的定义建议包含这几个字段：技能名称、适用场景、输入要求、执行步骤、产出标准、常见陷阱。执行步骤要写成有序列表，每一步都要具体到“读哪个文件”“跑哪个命令”“输出什么格式”。产出标准要可检查，最好能自动化验证。常见陷阱这部分特别重要，它相当于把你的经验教训固化下来，让智能体不重复踩坑。

写技能定义的时候，语言要直接、无歧义。避免“尽量”“适当”“合理”这类模糊词，换成具体的数量、格式、条件。比如不要写“写足够的测试”，要写“为每个公开函数至少写一个正常路径测试和一个异常路径测试”。

4.3 把技能串成流程

单个技能能干活，但真正的效率提升来自技能之间的串联。你需要定义技能之间的调用关系和传递的数据。比如“方案设计”技能的输出，应该作为“编码实现”技能的输入；“编码实现”的产出，应该自动触发“测试验证”技能。

串联方式有两种。一种是线性流程，适合步骤固定的任务，比如“修 bug”就是复现、定位、修复、验证一条线走到底。另一种是条件分支，根据中间结果决定下一步走哪个技能，比如测试通过就走审查，不通过就回到编码。实际项目里，主干用线性，分支用条件，组合起来就能覆盖大部分场景。

串联的时候要注意上下文传递。技能之间传递的不只是文本，还包括文件路径、命令输出、错误信息这些结构化数据。如果传递不完整，下游技能就会“缺信息”，导致执行偏差。我一般会在流程定义里明确每个技能需要哪些输入、产出哪些输出，形成一个简单的数据契约。

4.4 跑通第一个完整任务

理论说再多不如跑一遍。选一个你熟悉的小任务，比如“给现有函数补一个边界条件处理”，然后让技能框架完整跑一遍。观察几个点：智能体有没有自动识别出该用哪些技能、技能之间的衔接顺不顺、产出是否符合验证标准、有没有出现意料之外的操作。

第一次跑大概率不会完美。可能会发现某个技能触发条件太宽，导致不该用的时候也用了；或者某个验证标准太松，明显有问题的产出也通过了。这些都是正常的，记录下来，逐个调整。我的经验是，跑通三个不同类型的任务之后，框架基本就稳定了。之后每遇到一个新场景，就补充或调整技能，框架会越用越顺手。

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

5.1 技能不触发或者乱触发怎么办

这是最常见的问题。技能不触发，通常是触发条件写得太窄，或者任务描述里缺少关键信息。排查方法是把任务描述和技能触发条件对照着看，找出匹配失败的地方。如果是语义匹配，可以适当放宽关键词范围；如果是流程编排，检查一下流程入口条件是不是太严格。

乱触发则相反，通常是触发条件太宽泛。比如一个“重构”技能，如果触发条件只是“涉及代码修改”，那几乎所有编码任务都会触发它。解决办法是增加排除条件，或者把技能拆得更细，让每个技能的适用范围更明确。我一般会维护一个“触发日志”，记录每次任务实际触发了哪些技能，定期回顾，把误触发和漏触发都修掉。

5.2 智能体执行到一半“跑偏”了

这种情况通常发生在长流程任务里。智能体执行到某个技能时，突然开始做技能定义之外的事情，或者跳过了某个必要步骤。原因可能是上下文太长导致它“忘了”流程，也可能是某个技能的产出不符合下游预期，导致下游技能自行“发挥”。

应对方法有几个。一是把长流程拆成更短的段落，每个段落结束后做一次状态检查。二是在关键技能后面加“确认点”，要求智能体显式确认当前状态再继续。三是缩短单次执行的上下文，把不相关的信息清理掉。我自己最常用的是第二种，虽然会多花一点时间，但能大幅降低跑偏概率。

5.3 验证环节形同虚设

验证标准写了，但实际执行时智能体总是“自己宣布通过”。这通常是因为验证标准不够具体，或者验证步骤没有被真正执行。解决办法是把验证做成一个独立技能，由它来检查产出，而不是让执行技能自己检查自己。独立验证技能应该有明确的检查清单和判定逻辑，检查结果要输出成结构化格式，方便追溯。

另一个技巧是引入“反例测试”。也就是故意构造一些应该被验证拦住的产出，看验证技能能不能识别出来。如果拦不住，说明验证标准有漏洞，需要补强。这个做法有点像给验证逻辑做单元测试，虽然多花点功夫，但能显著提升框架的可靠性。

5.4 跨平台和工具兼容性问题速查

这张表是我自己遇到过的典型问题汇总，实际排查时可以先对照着看，能省不少时间。需要强调的是，不同工具和平台的报错信息差异很大，遇到没见过的错误，先看日志，再看官方文档，最后再去社区搜，这个顺序效率最高。

注意：任何时候都不要在技能定义或配置里硬编码敏感信息，比如密钥、令牌。用环境变量或者独立的配置文件来管理，并且确保这些文件不会被提交到版本库。

6. 我踩过的坑和几条实在建议

先说一个我印象最深的坑。早期我设计技能的时候，总想把所有情况都覆盖到，结果技能定义写得极其复杂，光一个“编码实现”技能就有二十多条步骤。实际跑起来，智能体要么记不住这么多步骤，要么在某个步骤上卡住导致整个流程停滞。后来我把这个技能拆成了“接口设计”“核心逻辑实现”“错误处理”三个独立技能，每个只保留五到七步，反而跑得更顺。这个教训是：技能框架的复杂度要匹配智能体的实际处理能力，不是越全越好。

第二个坑是过度依赖自动化验证。有一段时间我完全信任验证技能的判断，结果有一次它把一个有明显性能问题的实现判定为“通过”，因为我的验证标准里只检查了功能正确性，没检查复杂度。从那以后，我在关键技能里都会加一条“人工复核”的触发条件，重要产出必须经过人工确认才能进入下一阶段。自动化是提效手段，不是免责手段。

第三个建议是关于技能库的维护。技能不是写完就完了，随着项目演进和工具更新，技能定义也需要调整。我现在的做法是每个月回顾一次技能库，把不再适用的技能归档，把频繁出问题的技能重写，把新出现的场景补成新技能。这个维护成本不高，但不做的话，框架会慢慢“腐烂”，最后又退回到手动提示词的状态。

最后分享一个我觉得特别有用的小技巧：给每个技能加一个“失败案例”字段，记录这个技能在什么情况下会失败、失败时是什么表现。这个字段在排查问题时价值极高，因为很多时候你不是不知道技能该怎么用，而是不知道它什么时候会不灵。有了失败案例，你就能提前预判风险，而不是等出了问题再回头找原因。