Superpowers 源码解析：技能发现机制与开发流程约束

经常使用编码 Agent 后，真正让人疲惫的事情往往不是它不会写某段代码，而是它在需求还不明确时就开始实现，修改之后只运行最容易通过的测试，或者在长会话里重新做一遍已经完成的工作。模型有能力完成局部任务，并不意味着它会自动采用可靠的交付过程。

Superpowers 把需求澄清、设计、计划、测试、审查和交付组织成一组可组合技能。要用好它，需要理解技能如何进入上下文、不同阶段靠什么产物衔接，以及哪些规则只是模型需要遵守的指令，哪些已经变成脚本中的检查。[1]

本文面向已经使用过编码 Agent、了解 Git 与自动化测试的开发者。先沿源码认识组成与机制，再通过一个明确标注的教学案例走完整个过程。如果还在比较不同 Agent 的定位，可以先读 AI Agent 工作流实践；这里集中讨论 Superpowers 本身。

研究基线：Superpowers v6.4.1，提交 5bf4e78011075bcfc0dc295f0724994cd123ee71，资料核验日期为 2026-09-24。源码结论对应这个固定快照，不自动代表你已安装的副本。案例是设计演示，不是线上经验或已运行实验；文中不给出未经测量的效率提升比例。

补充调研：其他 AI Coding Skills 的比较于 2026-10-10 加入，依据各维护方当日可访问的主分支指令和官方文档。这部分不是与 Superpowers 同日的固定版本对照，也不是效果基准测试；使用时应重新核对实际安装版本。

先理解 Superpowers 解决的是哪一层问题

能写代码与能交付是两回事

考虑一个常见请求：“给订单接口加上幂等处理。”模型可能很快生成一个缓存键、一个查询和一个提前返回。代码在单次请求下看起来合理，但需求中的关键问题仍然悬空：键属于哪个用户？同键不同请求体怎么办？两个请求同时到达时谁获胜？订单已经落库而响应丢失时，重试应返回什么？

这些问题不是靠补全函数名解决的。它们要求开发者先定义行为，再选择实现，并用测试和审查检查结果。如果 Agent 直接越过这一步，即使后续每个工具调用都成功，也可能交付错误的产品行为。

Superpowers 的 README 将其定位为构建在可组合技能和初始引导之上的软件开发方法论。这里有两个同样重要的部分：一部分是工程方法的内容，另一部分是让 Agent 在合适时机找到并采用这些方法的接入机制。只有技能目录而没有有效发现，方法可能从不被读到；只有启动提示而没有具体过程，Agent 仍然不知道怎样落实。[1][4]

我把它理解成编码 Agent 的工程流程约束层。这个说法是对项目的分析，不是官方组件名称。它约束的对象是工作方式：先消除哪类不确定性，输出什么中间产物，什么证据才足以声明完成。它不会替代业务知识，也不会让不具备数据库知识的模型突然可靠地设计事务。

Skill、插件、宿主和工具分别负责什么

概念	在这里负责什么	不应混淆的边界
模型	理解请求、选择行动、生成代码和解释	生成的判断仍可能错误
宿主 Agent	管理会话、工具调用、权限、技能发现和子任务能力	不同宿主暴露的工具与生命周期不同
Skill	描述特定情境下的操作过程，附带脚本与参考资料	Markdown 中的强制措辞不是系统权限
插件	将技能、适配入口和资源组织为可安装单元	安装成功不等于每个技能都正确触发
工具与 MCP	提供读取文件、执行命令、访问服务等实际能力	工具可调用不代表当前任务已授权使用
项目规则	说明本仓库的命名、测试、目录与交付约束	不应为了遵循通用模板而破坏项目约定

Agent Skills 规范定义的是技能的目录、元数据和正文格式，OpenAI 官方文档则解释了 Codex 如何发现技能并按需读取内容。这两类资料共同说明：内容可以以相似形式分发，实际执行仍由宿主完成，不能从格式兼容直接推导所有平台行为相同。[19][20]

评价它时，先看交付证据

最容易观察到的是 Agent 宣布调用了几个技能、写了多少设计文档、启动了几个子 Agent。它们只是过程信号。更有意义的问题是：设计是否发现了隐藏约束，计划是否把接口说清楚，失败测试是否真的复现问题，完成报告能否指向当前代码的验证结果。

因此，本文不会把“按流程做过”当成“结果可靠”的同义词。Superpowers 的价值需要通过产物质量体现：每个阶段应该减少一种具体的不确定性，并留下下一阶段能使用的材料。阅读源码时，也应始终追问某条规则到底防止了什么失败，以及它还防不住什么。[6][12]

打开仓库：组件如何分工

从四类文件建立地图

下面是固定快照中与本文直接相关的目录摘录，不是完整文件清单：

superpowers/
├── .claude-plugin/                 # Claude 插件元数据
├── .codex-plugin/plugin.json       # Codex 插件入口
├── .cursor-plugin/                 # Cursor 适配入口
├── .opencode/                     # OpenCode 适配
├── hooks/
│   ├── hooks.json                 # Claude SessionStart 注册
│   └── session-start              # 读取并输出引导上下文
├── skills/
│   ├── using-superpowers/
│   │   ├── SKILL.md
│   │   └── references/            # 宿主相关工具说明
│   ├── brainstorming/
│   │   ├── SKILL.md
│   │   └── scripts/               # 可选视觉讨论工具
│   ├── subagent-driven-development/
│   │   ├── SKILL.md
│   │   ├── task-reviewer-prompt.md
│   │   └── scripts/               # workspace、brief、review package
│   └── executing-plans/
│       ├── SKILL.md
│       └── scripts/               # task-start、task-done
├── tests/                         # 插件程序及部分集成检查
├── docs/testing.md
└── RELEASE-NOTES.md

第一类是分发与适配文件：告诉宿主在哪里找到技能，以及是否注册生命周期钩子。第二类是技能内容：以 SKILL.md 为入口，说明触发条件、阶段产物、决策规则和常见错误。第三类是执行辅助材料：包括 prompt 模板、参考文件和脚本，把重复的交接或检查做成可复用资源。第四类是验证与演进记录：帮助判断行为约定是否有测试、何时发生过变化。[1][2][3][17][18]

图中分层是本文对源码职责的归纳。箭头表示信息与调用关系，不意味着仓库里存在一个同名的中央调度服务。

技能库不是互不相关的提示词

固定快照的 skills/ 下有 15 个直接包含 SKILL.md 的技能目录。可以按任务中的职责阅读它们，而不必按字母顺序记忆。[1]

技能	典型触发情境	关键产物或检查
using-superpowers	开始会话、判断适用技能	技能选择与读取，宿主适配
brainstorming	创建功能或改变行为之前	对目标的共同理解、对应规模的设计
writing-plans	已有设计，需要多步实施	文件、接口、测试和预期结果明确的计划
using-git-worktrees	需要隔离工作区	检测现有隔离、选择工作区、验证基线
executing-plans	选择 Native 执行计划	当前会话逐任务实现、测试日志与 ledger
subagent-driven-development	选择每任务独立实现和审查	brief、实现报告、审查包、进度记录
dispatching-parallel-agents	多个问题真正独立	每个问题域的独立任务及合并检查
test-driven-development	增加或修改程序行为	观察失败、最小实现、通过后重构
systematic-debugging	错误、测试失败或异常行为	根因证据、假设及验证
requesting-code-review	完成任务或准备集成	需求上下文、提交范围和审查结果
receiving-code-review	收到审查意见	对意见的技术核实、修复或有依据的反驳
verification-before-completion	准备声明完成或通过	与具体声明匹配的新鲜验证证据
finishing-a-development-branch	测试通过、准备交付分支	环境识别、集成选择和工作区处理
writing-skills	新建或修改技能	无技能基线、压力场景、行为回归
diagnosing-superpowers	会话重复工作、忽略计划或成本异常	带 path:line 引用的会话调查报告

表格中的“产物”有些是文件，有些是可观察行动。例如验证技能不需要发明一种新的报告格式；它要求声明与证据相符。单元测试通过只能支持被运行的测试通过，不能支持“线上问题彻底消失”。这类边界比技能名本身更值得记住。[12]

不同技能的关系既有前后衔接，也有横向约束。TDD 贯穿多个实现任务，不是流程末尾的一站；调试可能从任何失败处进入；完成验证适用于每一次结论。把这些关系画成一条没有反馈的流水线，会误导使用者以为只要按顺序调用一遍就结束了。

一个技能内部为什么同时有正文、参考文件和脚本

SKILL.md 适合放所有使用者都需要知道的核心过程。宿主工具映射放在 references/，是为了把平台差异留在边界。脚本负责容易机械化、值得统一实现的操作；例如生成任务 brief、收集提交差异、维护计划工作目录。[4][8][9]

Agent Skills 规范和 Codex 文档都将这种方式描述为渐进披露：先暴露发现所需的元数据，再按需要读更详细的内容。[19][20]

但是，“放进参考文件”不是隐藏复杂性的万能方法。如果正文没有明确告诉 Agent 何时读取参考材料，重要约束可能永远到不了执行者；如果每项任务都要求读完所有材料，又会失去拆分的价值。因此，一个好的技能不仅需要内容正确，也需要清楚的读取路径。

如何读项目测试而不高估证明力

docs/testing.md 区分了插件程序测试与真实模型会话中的行为评估。前者可以检查 hook 输出、脚本、插件注册或服务端代码；后者观察 Agent 是否在特定场景中遵守流程。文档还指向外部的 superpowers-evals 实验室，不能因此假定主仓库下载后包含所有评估资源。[17]

两者证明的东西不同。JSON 格式测试能发现上下文输出损坏，却不能证明模型读到规则后一定执行；一次压力场景通过能提供行为证据，却不能保证换模型、换宿主或换任务仍然通过。甚至“能复述 SDD 流程”的测试，也不能替代“实际完成任务时执行了审查”的测试。

读发布说明中的评估结果时，要保留这个区分。维护者报告的样本观察可以解释某条规则为什么出现，但在缺少完整条件和独立复现时，不能拿来宣称自己的项目一定节省同样的费用或避免同样比例的错误。[17][18]

一次请求如何加载并触发技能

Claude Code：先注入使用技能的方法

在本文快照中，hooks/hooks.json 为 Claude Code 注册 SessionStart，匹配 startup|clear|compact，通过 hook 入口运行 session-start。主脚本定位插件根目录，读取 skills/using-superpowers/SKILL.md，将内容转义后输出为宿主可识别的 JSON。Claude 分支使用 hookSpecificOutput.additionalContext。[2][21]

这里注入的是引导技能，不是整个技能库。它告诉 Agent 在回复或行动前判断有没有适用技能，有则读取，并根据宿主加载相应参考文件。这样，启动层只承担“让后续方法能被找出来”的职责，具体工程过程仍然由目标技能提供。[4]

脚本还根据环境变量选择其他平台的输出形式。例如 Cursor 分支输出 additional_context。这些区别看起来只是字段命名，却是连接是否成立的关键。阅读适配层时应看具体条件分支，不能从某段注释或一个平台的成功日志推广到所有宿主。[2]

Codex：从原生技能发现开始

当前 .codex-plugin/plugin.json 的关键字段可摘录为：

{
  "name": "superpowers",
  "version": "6.4.1",
  "skills": "./skills/",
  "hooks": {}
}

这是源码中的字段摘录，不是让读者用这几行替换完整 manifest。它说明当前 Codex 入口暴露技能目录，同时显式声明空 hooks。[3]

RELEASE-NOTES.md 解释了这一细节的来历：此前移除 hooks 字段后，Codex 会回退自动发现仓库中的 Claude hook 配置，因此“字段缺失”没有达到“不要注册 hook”的目的。显式的 {} 是该版本用于避免回退发现的写法。[18]

OpenAI 官方文档说明 Codex 先看到技能名称和描述，选中技能后加载 SKILL.md，再按需读取参考文件或执行脚本。结合 manifest，可以理解当前项目在 Codex 中依赖原生技能发现的接入方式。不能因为 Claude 的路径中有 SessionStart，就推断当前 Codex 也必须启动相同脚本。[3][20]

这张图只概括接入路径和阅读顺序，不承诺原生发现一定在第一条消息触发某个技能。显式请求、描述匹配、宿主提供的元数据以及模型判断共同影响实际选择。

描述字段决定“能否被想到”，正文决定“怎么做”

Agent Skills 要求 SKILL.md 包含 YAML front matter，其中 name 和 description 是必填字段。规范给出名称与描述的格式限制，正文则承载技能指令；可选目录保存脚本、引用和资源。[19]

以 systematic-debugging 为例，它的描述把触发场景写成 bug、测试失败或异常行为，并强调在提出修复前使用。这样，即便用户只说“测试突然挂了”，发现阶段也有机会将它与请求匹配。正文进一步规定先读错误、稳定复现、检查最近变化和采集边界证据。[13]

writing-skills 对描述的建议更具体：描述应突出什么时候使用，不要把完整流程压缩进描述字段，否则模型可能只依据摘要行动而绕过正文。这是 Superpowers 的技能编写经验，不是所有技能标准都强制要求的额外字段规则。[16]

因此，当技能没有触发时，第一反应不应总是把正文写得更强硬。应先检查发现链路：宿主是否看到这个技能，名称是否冲突，描述是否覆盖实际说法，用户是否显式点名，模型有没有读取正确文件。如果正文从未进入上下文，添加更多正文规则没有作用。

工具适配必须以当前宿主为准

using-superpowers 的平台参考文件提供工具与环境差异说明。这让共同方法可以复用，例如都需要创建隔离工作区、派发任务、接收结果，但不要求所有宿主暴露同一种 API。[4]

最容易出错的是把一篇旧文章里的工具名或配置片段当成通用接口。子 Agent 的创建、后续消息和生命周期能力可能随宿主版本变化；有的环境允许独立上下文，有的环境只有串行执行。技能参考自己也强调，实际工具列表与旧表格冲突时，应以当前可用能力为依据。

在日常使用中，可以要求 Agent 先列出它实际读取的技能路径、版本来源和所需能力，再开始一个小任务。这比询问“你安装了 Superpowers 吗”更能验证真实接入：模型说自己知道项目，只能证明它能生成相关文字，不能证明当前会话已经加载正确资源。

从需求到交付：技能如何衔接

设计先解决目标，再决定需要多重的过程

当前 brainstorming 首先要求建立共同理解：为什么做这件事，谁会使用它，什么结果算成功。用户已经提供的信息应被准确复述，不需要为了完成问答仪式而再次询问。接下来按任务性质选择不同路径。[5]

路径	典型任务	需要确认的产物
Spike：探索	验证一种技术能否满足某个条件	要回答的问题和最小探测方案；结果是结论
Bounded：有限修改	已有流程中边界清楚的改动	简短的会话内设计
Architectural：结构性工作	新项目、新子系统或接口关系重构	书面 spec、实施计划及执行交接

这个划分的价值在于控制工作量。修改已有命令的一项标志，不必机械地写一套大型架构文档；但“做一个简单应用”也不能仅凭“简单”二字就假定边界清楚，因为现有仓库里可能根本没有相关流程可以参考。

三个路径都保留设计确认的含义：确认实际呈现过的目标与方案，而不是把“这个方向不错”扩展成对尚未出现的实现细节的认可。在真实宿主中，还要同时遵守当前用户授权和更高层指令；技能不能自行增加权限，也不能把原本有效的授权解释成不存在。[4][5]

对长期用户而言，更好的输入不是“随便做，别问”，而是提前写清哪些决定可以自主处理、哪些变化需要停下来。比如“可以调整内部函数划分，但不能改变公开响应字段；涉及数据库迁移时先给出迁移方案”。这样减少的是信息缺口，而不是单纯减少对话次数。

Spec 和 plan 是两种不同的交接

Spec 回答的是“我们要交付什么行为，为什么这样选择”；plan 回答的是“在哪些文件里，按什么顺序，把它实现并验证出来”。两者不能互相替代。只有 spec，执行者可能遗漏仓库的真实约束；只有 plan，执行者遇到计划错误时又不知道最终应服从什么目标。[6]

当前 writing-plans 的模板包含 Goal、Architecture、Tech Stack、Spec、Global Constraints 和 Review Focus。任务级别还包含 Files、Interfaces，以及按步骤展开的测试、实现和验证。Consumes 与 Produces 特别值得注意：独立执行者拿到自己的任务时，不能靠猜测推导前一任务的函数签名。[6]

例如，一项任务写“增加幂等记录存储”，另一项任务写“接入幂等处理”，仍然留下太多空白。至少应说明存储操作返回“首次创建”“已有相同请求结果”“相同键但载荷冲突”中的哪一种，以及事务由谁开启和提交。否则每个局部实现都可能自洽，连接起来却无法使用。

Review Focus 则补上另一类缺口：设计没有逐字枚举，但真实用户合理预期应该处理的输入或失败模式。它不是装饰性风险清单。技能要求把这些关注点落实到拥有相关代码的任务测试中，避免所有实现者都沿着同一份不完整计划忽略同一个问题。[6][18]

任务粒度也不是越细越好。技能将 task 定义为值得一次独立审查、拥有自身验证结果的交付单元；“建目录”“写一行配置”“改一个 import”通常只是步骤，不天然值得新建三个执行者。粒度过细会让上下文交接与审查的成本超过实际工作。[6][8]

Native 与 SDD：选择上下文和审查成本

v6.4.1 中，executing-plans 表示 Native，也称 inline：当前会话自己逐项实施计划，保留进度和测试证据，最后进行一次整体审查。它不再是旧教程里“执行几项就固定停下来汇报”的模式。[7][18]

subagent-driven-development，下文简称 SDD，则由控制者派发新的实现者完成任务，再派发任务审查者。当前任务审查要求同时给出规格符合性和任务质量两个结论。不能把历史上的两阶段审查描述，未经核对就写成当前每项任务必定启动两个独立 reviewer。[8]

维度	Native	SDD
主要实现上下文	当前会话持续积累	每项任务新的实现者上下文
任务级独立审查	不为每项任务单独安排	每项任务交给独立审查者
最终审查	有工具时使用新的整体审查者	整体分支审查
进度恢复	计划专属 ledger 与 Git	同类 workspace、ledger 与任务报告
主要优势	交接少，已有理解可持续复用	任务之间隔离理解与审查盲点
主要代价	长会话可能积累偏差和上下文负担	每次派发与审查都要重新建立部分理解
适合的判断条件	任务明确、规模可控、当前上下文仍有效	需要逐任务检查，任务边界清楚且交付错误代价较高

这里的“成本”指结构性开销，不是保证某种模式永远便宜。一个能力不足的实现者多轮返工，可能比一个更强的执行者更贵；审查发现了重要问题，也可能使总返工更少。应结合真实任务和日志评估，而不是按子 Agent 数量推算收益。[8]

Native 在没有子 Agent 工具时允许执行者进行独立阶段的自审，但要求说明缺少新上下文审查这一事实。这样才能区分“做过审查”和“由另一个执行上下文审查过”，避免把两者包装成相同保证。[7]

SDD 并不等于把所有实现任务同时跑起来

当前 SDD 明确要求不要同时派发多个实现者，以避免冲突；它的重点是任务分解、独立上下文和审查交接。另一方面，dispatching-parallel-agents 处理的是可以独立调查的问题域，比如彼此不共享状态的几组故障。两者用途不同。[8]

判断能否并行，不能只看文件名不同。如果两项任务共同改变接口、共享测试数据库或依赖同一配置，它们仍可能相互干扰。反过来，两组只读调查即使看过同一个目录，也未必会产生状态冲突。应评估读写集合、接口依赖和环境资源，而不是笼统问“要不要多开几个 Agent”。

失败、审查与收尾是流程的一部分

实现过程中失败时，systematic-debugging 要求先调查根因，再分析模式、提出假设并验证。这里的关键是让修复建立在证据上，而不是多改几处直到测试碰巧变绿。测试隔壁模块失败也需要说明，不能只因为自己没有改那个文件就从报告中消失。[11][13]

审查意见到来后，receiving-code-review 要求先理解并核实。外部 reviewer 可能不知道兼容性约束，也可能提出实际正确的重要问题。执行者应该用代码和需求判断，既不盲目接受，也不因为“计划就是这么写的”拒绝修正。[14]

最后，finishing-a-development-branch 在运行完整测试套件后识别环境，再处理合并、PR 或保留分支。当前版本的默认选项不包含随手丢弃工作；删除分支或工作区也不应变成清理步骤中的隐含动作。[14][18]

图中只展开需要书面设计和计划的路径。小型有限修改和探索任务使用前述轻量产物，不需要为了匹配图形而补齐所有文档。这个流程由技能、模型和宿主协作维持，不是图里每条边都有一个程序在强制调度。

原理深挖：文字规则如何变成可检查的行为

三层约束承担不同责任

阅读技能中大量的 “MUST” 和 “HARD-GATE”，很容易产生一种错觉：既然写得这么强硬，Agent 就不可能跳过。实际应区分三层机制。

层次	例子	能做到什么	仍然防不住什么
文字约束	先复现、再修复；完成前读测试输出	给模型明确的选择规则和停止条件	模型误读、忽略或形式化执行
脚本检查	测试失败不写完成行；拒绝空审查范围	对具体输入执行确定性判断	检查对象选错、测试过弱、业务需求遗漏
宿主与基础设施	工具权限、沙箱、分支保护、CI	在系统边界限制或验证实际行动	被允许的行动在业务上仍可能错误

Superpowers 主要组织前两层，并依赖宿主提供第三层能力。要阻止未经授权的发布，不能仅在技能里加一句“禁止发布”，还应依赖宿主权限和实际发布流程；要保证接口兼容，也不能只看测试命令返回零，还要确认测试断言覆盖兼容性。[9][10][12]

这一划分并不贬低提示指令。很多工程判断无法提前写成完整程序，必须由模型理解上下文。但当某种失败可以机械识别，例如审查的是空提交范围，就值得交给脚本，而不必每次都期待 Agent 想起来检查。

“反合理化表”针对的是跳步骤的理由

using-superpowers、TDD、验证等技能中都能看到类似的表格：把“这件事很简单”“我已经知道该怎么做”“应该能通过”等常见理由，与需要执行的实际动作一一对应。[4][11][12]

它们试图解决的不是知识缺失，而是执行偏移。Agent 可能已经知道应该测试，却为了快速完成而把当前情况解释成例外。将这些理由预先写出来，可以让模型在产生类似判断时重新看到规则。

但措辞强度有收益上限。重复十遍“不要跳过”不一定比一条可检验条件更有效。比如“完成前必须验证”仍然抽象，而“运行项目测试命令，读取失败数量和退出码，只对已经证明的范围声明通过”提供了可以观察的动作。[12]

编写团队规则时，可以借鉴这种写法，但不应把所有可能行为都升级为绝对禁令。规则之间一旦互相矛盾，模型会花更多时间解释自己该服从哪条。更好的方式是明确适用情境、允许的例外和证据要求，并把冲突交由当前项目与用户授权处理。[4][16]

Ledger 把进度从记忆变成外部记录

长会话的一个失败模式是：执行者记得“大概完成了存储层”，却忘记具体提交、失败测试和剩余问题。上下文压缩之后，摘要可能保留了结果，丢失了结果成立的条件。

SDD 通过 sdd-workspace PLAN_FILE 为计划解析工作目录，默认位于 .superpowers/sdd/ 下。目录中保存 progress.md、任务 brief、报告和审查材料。Native 使用同类工作区和 ledger 格式，因此进度不是只存在于某个执行者的当前对话中。[7][8][9]

这里的身份设计很有启发性。单纯用 plan.md 作为目录名，会让 docs/alpha/plan.md 与 docs/beta/plan.md 冲突。脚本将计划路径写入 plan-path 标记；已有目录属于其他计划时，尝试加入父目录名，再用计数后缀消歧。不同计划不会因为同名而自然混用同一目录。[9]

这仍不是数据库级别的并发控制。旧的无标记目录存在被首次访问者认领的兼容路径，同一 worktree 中同时运行同一计划也会共享材料。正确结论是“计划归属更明确”，而不是“任何并发和历史残留都已被解决”。

恢复时应同时核对 ledger 和 Git：计划身份是否正确，完成项是否指向实际提交，未完成修复是否还有开放问题。ledger 是协作记录，可以被误写或删除；Git 记录代码变化，也不会自动证明测试曾覆盖正确行为。两者互相补充，不能把其中一个当作无条件真相。[7][8]

Brief 和 review package 控制交接信息量

task-brief 从计划中提取指定任务，避免控制者每次重新描述需求时发生遗漏或改写。脚本通过匹配 Task N 标题定位任务，并跳过代码围栏内的标题识别。因此，计划格式不只是为了阅读舒服，也是后续辅助工具的输入契约。[8]

这意味着任意改变模板标题可能产生实际后果。如果计划把所有任务写成“第一步”“第二步”，人类能够理解，提取脚本却未必找到。遇到这类错误时，不要让 Agent 继续凭记忆工作，应修正计划格式或明确采用等效的手动交接方式。

review-package 则把提交列表、变更统计和带上下文的差异放到文件里，让审查者一次读取。它要求 BASE 和 HEAD 可解析，BASE 是 HEAD 的祖先，而且范围内至少存在一个提交。空范围和非祖先范围返回错误，避免错误分支产生看似干净的审查包。[9]

为什么不能总用 HEAD~1？因为一个任务可能包含多个提交。只查看最后一项会遗漏早先真正的实现。任务开始时记录 BASE，比事后猜测更稳妥。整个分支的审查则需要适合该仓库的分叉基点，并确认目标分支没有选错。[8][14]

这些脚本改善了证据形态，却不负责证明材料完整：未提交的修改不在提交范围内，选错但合法的 BASE 也可能截断工作。因此审查前仍应检查工作区状态、任务范围与提交列表，而不是只看到脚本退出成功就宣布证据齐全。

task-done：一个小脚本的保证与限制

Native 的 task-done 接收计划、任务号、BASE 和测试命令。它在计划工作区保留完整测试日志，打印尾部；命令失败时退出，不追加完成记录；成功时写入包含提交范围、命令和输出摘要的完成行。[10]

它确实把“测试失败却记录完成”这一类错误挡在正常脚本路径上，但不知道命令是否选对，也不会解释断言语义。传入一个无意义但返回成功的命令，同样可能得到完成行。即使传入真正的测试命令，测试可能只检查格式而没有检查核心行为。

此外，源码是按具体命令控制流运行的：例如它读取日志中的最后一个非空行，空日志路径是否符合预期，应看实际运行结果，不能把代码注释扩展为对所有命令的保证。学习这种辅助工具，最有用的方式是同时读输入、失败分支和成功条件，而不是只记住命令名字。

因此，完成声明仍应受 verification-before-completion 约束：先确定要证明的命题，再选择匹配的命令，读取输出并判断证据范围。脚本把证据落盘，执行者对证据是否支持结论负责。[10][12]

修复循环为什么需要边界

审查不一定一次通过，反复审查也不一定收敛。当前 SDD 将一轮定义为修复派发加一次限定范围的复审，任务级最多五轮：前三轮优先继续原实现者，后两轮换新的、更有能力的实现者；达到上限后由控制者对开放问题作出记录明确的判断。[8]

限定范围很重要。复审应检查原问题是否解决，以及修复差异有没有引入新问题，不应每轮都把全仓库重新当成首次审查。否则命名偏好、结构建议和新发现不断进入循环，任务可能永远无法结束。

达到上限也不等于问题消失。控制者需要记录哪些意见被采纳、哪些延期、哪些判断有争议，以及判断错误会造成什么后果。Native 的最终修复路径与 SDD 不完全相同，不能把 SDD 的每任务五轮机制套到 Native 上。[7][8]

从机制设计看，Superpowers 不只规定“做得更仔细”，也在限制无止境地花费预算。读者需要评价这些边界是否适合自己的风险级别，并保留独立 CI、人工审查等项目要求；技能内部的一条完成记录不能替代团队的合并标准。

贯穿实践：给已有订单服务增加幂等处理

先约定案例范围

下面是用于解释工作流的教学设计，不是可直接部署的订单系统，也没有在本文中运行真实数据库实验。假设已有一个 Python 订单服务，使用关系型数据库，订单创建只包含同一数据库内的写入，不调用外部支付或库存服务。测试命令采用 pytest，示例路径由案例约定，不对应 Superpowers 自身代码。

需求约定为：POST /orders 必须携带幂等键；键的唯一范围是认证租户、接口和键值的组合。首次成功请求返回 201 与订单结果；相同语义载荷的重复请求重放相同状态码和业务结果；同键不同语义载荷返回 409，不创建新订单。未通过认证或参数校验的请求不占用幂等键。这些状态码和行为都是本例设计选择，不是 Superpowers 提供的业务标准。

“语义载荷相同”也需要定义。本例先校验请求，再把影响订单行为的字段规范化并记录其版本与规范化内容；JSON 字段顺序等不影响业务的差异不构成冲突。若实现为了索引或比较额外使用摘要，应保留明确的比较规则，不能把随意序列化后的字符串哈希当成完整业务定义。

键在教学范围内不自动过期。生产设计若需要清理，必须另行说明保留窗口、迟到重试、敏感载荷保存和删除策略。暂不讨论清理不是说清理不重要，而是避免在幂等语义尚未定义时同时引入另一组生命周期问题。

第一次输入：让 Agent 理解你要保护什么

可以直接使用下面这种自然语言请求，不依赖宿主专用 Slash Command：

已有订单服务需要增加幂等请求处理，请先使用 brainstorming。
目标是防止客户端超时重试造成重复订单，不改变原有订单字段。
同租户、同接口、同幂等键且语义载荷相同，应返回同一业务结果；
同键不同载荷应拒绝。订单与幂等记录使用同一数据库。
请先阅读现有接口、事务代码和测试，说明并发及响应丢失时的行为，
给出设计与非目标。内部代码组织可自行决定，数据库迁移先说明影响。

应观察到的不是一大段通用幂等知识，而是 Agent 将设计关联到现有代码：认证在何处完成，事务由谁控制，响应如何序列化，测试数据库能否模拟并发。它应区分用户已经明确的条件和从仓库推测出的前提。[5]

如果现有代码已经有唯一业务请求号，也许只需扩展现有机制；如果接口跨多个外部系统，本例的单数据库前提就不成立，需要重新界定设计。此时停止盲目沿原方案实现，是发现范围变化，而不是工作流失败。

设计片段：把事务边界写清楚

本例选择的设计是：在单个事务中尝试占用唯一键、创建订单、保存可重放结果，最后一起提交。幂等记录具有数据库唯一约束；发生唯一键竞争后，失败请求必须在当前数据库允许的事务状态下重新读取获胜结果，不能假定捕获一次异常后原事务仍然可用。

事务内首次路径（教学设计）
1. 校验并规范化请求，确定租户 + 接口 + 幂等键。
2. 开始事务，尝试插入唯一的幂等记录。
3. 只有取得该键的请求才能创建订单。
4. 将规范化请求和响应状态、业务结果写入幂等记录。
5. 提交订单与幂等记录，再发送响应。

竞争或重复路径
1. 遵守数据库的回滚 / 重试要求，读取已提交的获胜记录。
2. 相同语义载荷：重放已保存结果。
3. 不同语义载荷：返回冲突，不执行订单创建。
4. 等待竞争事务超时：返回明确的可重试错误，不绕过唯一约束。

这段设计把几个容易遗漏的失败窗口暴露出来。提交前进程失败，订单与幂等记录都不应留下已提交的部分结果；提交成功但响应丢失，重试应读取已保存结果。唯一约束负责争用同一键，事务负责绑定多项写入，两者不能互相替代。

事务机制的具体实现仍需针对所用数据库验证。唯一冲突发生在语句执行还是提交阶段、等待如何结束、隔离级别下能否读到获胜记录，都影响适配代码。这也是设计必须指向项目实际存储层的原因，而不是让 Agent 从教程里复制一个 try/except。

如果加入外部扣款，数据库回滚不会撤销已经发生的外部动作，就要重新设计外部幂等协议、事件交付或补偿流程。此处不扩展成分布式事务教程，但必须明确当前保证不覆盖那个场景。

计划片段：围绕可验证交付物拆分

依据 writing-plans 的思路，完整计划需要实际文件、接口、测试内容和命令。下面仅展示三个任务的交付边界，不是可直接交给执行者的完整实施计划。[6]

任务	本任务负责	输入与输出契约	验证重点
Task 1	幂等记录持久化与事务适配	消费规范化请求；产生取得键、已存在结果或载荷冲突的明确结果	唯一约束、事务回滚、竞争后读取
Task 2	接入订单创建与响应重放	消费 Task 1 的精确接口；保证原响应字段兼容	首次请求、同键重放、异载荷拒绝、租户隔离
Task 3	失败窗口与并发集成验证	使用真实测试数据库与服务边界	双请求竞争、提交前失败、提交后响应丢失

为什么不先建一个“幂等框架”，再接入所有接口？因为用户只要求保护订单创建，而且不同接口的语义载荷和重放政策可能不同。先完成一个行为完整的用例，比抽象出还没有消费者的通用框架更能减少不确定性。

计划还应该把“规范化算法属于谁”“事务由哪一层开始”“结果类型名字是什么”写入 Interfaces。举例说，Task 1 产生 ReplayResult，Task 2 就不能自己假定它叫 ExistingOrder，再让集成测试替模糊交接付费。

Review Focus 可以关注认证租户参与唯一范围、同键异载荷、请求字段顺序、事务超时和响应丢失。其中能明确测试的内容，应回填到对应任务；不能只列为“最终 reviewer 留意”。如果这些测试已经全部覆盖，Review Focus 应如实说明，不为了凑满条目重复同一问题。[6]

执行输入：保留自主权，也保留边界

当实际设计和完整计划已经审阅，可以使用第二段输入：

设计和实施计划已审阅，采用 Native 执行。
请逐项完成计划，使用项目已有测试命令；普通内部实现选择自行处理。
计划与设计冲突时，以设计目标和仓库约束为依据，记录决定及影响。
每个任务保留测试证据和完成状态，恢复会话时先检查 ledger 与提交。
涉及不兼容接口变更或设计未覆盖的数据迁移时停止并说明影响。
完成后提交需求覆盖、验证结果和仍然存在的限制。

按照当前 Native 技能，执行者读取任务 brief、记录 BASE、实施测试与修改、比较命令输出和 Expected，最后通过 task-done 记录结果。[7][10]

如果改用 SDD，同一任务需要交给新的实现者，并带上任务 brief、前序接口、决策和报告路径；完成后将 brief、报告与差异交给 reviewer。控制者不应把整段历史对话原样复制过去，也不应为了缩短提示而漏掉租户范围这种全局约束。[8]

无论选择哪种方式，工作区的隔离需要实际确认。Git worktree 能让不同分支拥有不同工作目录，但不会自动隔离数据库、端口、进程和外部服务。两个 worktree 的测试如果连接同一个可写数据库，仍然可能互相污染。[22]

测试首先证明“真的会错”

本例的测试矩阵如下。表中的预期是设计要求，并非已经运行得到的结果。

测试情境	应观察的结果	单纯检查 HTTP 成功码为何不够
首次合法请求	创建一笔订单并保存重放结果	还要检查持久化关联
同键同载荷重试	返回同一订单，订单数量不增加	两次成功也可能创建两笔订单
同键异载荷	冲突且没有第二笔订单	可能错误返回旧结果而掩盖请求冲突
不同租户使用同键	各自独立，不能读到对方结果	成功码无法证明隔离
两个并发请求	只有一个创建动作，另一个重放或按协议重试	串行测试无法覆盖争用
提交前异常	没有已提交的部分订单或成功记录	返回错误仍可能留脏数据
提交后响应丢失	重试恢复已提交结果，不再创建	客户端失败不意味着服务端回滚

示例命令可以是 pytest tests/integration/test_order_idempotency.py -q，前提是完整计划已经建立该文件和对应测试环境。它只说明运行某个集成测试文件；项目全套验证仍应使用仓库规定的命令。不能把案例中的路径粘贴到任何项目就期待得到同样结果。

按照 TDD，需要先看到一个与目标行为相关的失败。例如重复调用后数据库有两笔订单，才真正暴露了缺少幂等保护。导入错误、数据库没启动或断言写错同样会让命令失败，但并没有证明业务测试有效。[11]

通过之后还要思考反事实：如果去掉唯一约束或在重放分支误执行一次创建，哪条测试会失败？如果说不出来，测试可能只是重复实现细节。这里的反事实检查不是要求无边界地增加测试，而是用来判断现有测试是否真能保护预期行为。[11][16]

遇到失败时，提供事实而不是指定猜测性修复

第三段输入适合测试失败后使用：

并发幂等测试失败：两个请求返回不同订单号，数据库中有两笔订单。
单请求和串行重试测试通过。请使用 systematic-debugging，
先检查复现条件、事务边界和唯一约束是否真实生效，比较最近修改。
先给出证据支持的根因，再做最小修复，并说明哪条回归测试保护它。
不要通过降低并发度、增加固定 sleep 或删除断言让测试表面通过。

执行者应先查实际数据库 schema、事务日志和测试连接，而不是立刻加锁。可能的原因包括迁移没有应用、键范围写错、测试使用了不同数据库，或者业务调用绕过了事务。症状相同，不代表修复也相同。[13]

在审查阶段，还可以故意检查计划的盲区：如果计划只写了“重复请求返回之前结果”，实现者对同键异载荷也返回旧订单，reviewer 应指出这违背了业务上的冲突语义。若规格明确要求冲突，这是漏实现；若规格没有说明，则需要依据用户预期澄清设计并补上测试，不能以“没有写”为由自动认定安全。[6][14]

完成报告要能逐项对照目标

第四段输入用于收尾：

请按已确认设计逐项核对，不只汇报“测试通过”。
列出首次请求、重放、异载荷、租户隔离、并发和失败恢复各自的证据。
给出实际运行命令、结果、对应提交或工作区状态，区分实测与推断。
说明没有覆盖的行为、迁移要求和已延期问题；不要把未运行检查写成通过。

理想报告中，每个结论都有不同的证据。例如重放语义对应集成测试，公共响应兼容性对应既有测试，数据库约束对应迁移与真实 schema 检查。构建成功证明包能构建，不证明并发正确；代码审查看起来合理，也不能替代特定失败窗口的运行验证。[12]

最终还应回到设计前提：这个案例仅覆盖同一数据库事务中的订单创建，没有证明跨支付系统的幂等，没有评估长期清理策略，也没有提供吞吐数据。明确边界让后续工作有可靠起点，比一个过于宽泛的“生产可用”标签更有帮助。

经常使用时最容易踩的坑

更新了项目，不代表当前会话已经使用新规则

使用时间越长，越容易同时存在手动安装目录、插件缓存、项目级副本和旧教程。版本问题不只是“版本号老一点”，也可能是核心流程已经变了：当前设计有三种规模路径，Native 执行持续推进，SDD 的审查结构与旧版介绍不同。[5][7][8][18]

排查时应记录实际加载路径、manifest 版本以及读取到的正文。只看 GitHub 主分支不能证明当前会话版本；只看到某个文件夹也不能证明宿主选中了它。升级之后应在新会话中用小任务验证发现和行为，再投入长时间任务。

重复安装同名技能也不能简单靠“哪个目录更靠近项目”猜优先级。应查当前宿主规则与实际加载证据，定位旧副本后再决定如何处理。不要让 Agent 因为看到两个目录就递归删除其中一个；里面可能有你维护的本地修改。

安装之后，验证一条最小路径

研究基线的 README 为 Claude Code 推荐通过官方插件市场安装：在 Claude Code 交互界面输入以下命令，不是在普通 Shell 里执行。[1]

/plugin install superpowers@claude-plugins-official

Codex App 的路径是在 Plugins 中查找并安装 Superpowers；Codex CLI 的 README 路径是进入 /plugins 搜索 Superpowers 并选择安装。市场可见性和宿主版本可能变化，因此遇到界面不同应回看当前官方入口，不凭旧博客拼凑安装脚本。[1][20]

安装后用一个只需读取的小请求检查：“请说明本会话可用的 Superpowers 技能、实际读取路径，以及设计阶段会怎样处理一个已有函数的有限修改。”然后观察它是否真的读取正确内容。不要一开始就以改整个项目作为安装验证；失败时很难区分发现问题和任务本身的问题。

这一步还应检查能力是否满足后续计划。没有可用子 Agent 工具时，不应在输出中伪造派发记录；没有可写隔离目录时，也不能只宣布已经创建 worktree。所有“已完成的准备”都应有可观察依据。[7][12]

将症状映射到证据，比叠加规则更有效

症状	优先查什么证据	下一步处理
技能从未触发	可见元数据、加载路径、描述与实际请求	先修发现或匹配，再改正文
总是加载旧流程	插件版本、手动副本和当前读文件记录	清楚区分来源后再升级或去重
不断重复确认	用户已批准的具体产物、当前阶段	指出已授权范围，补齐真正缺少的信息
worktree 放错位置	已有 worktree、仓库约定、分支状态	优先识别现有隔离，遵守项目路径
脚本 Permission denied	实际文件权限、解释器、内部调用链	检查分发包与辅助脚本，不盲目批量 chmod
审查说没有变化	BASE、HEAD、分支、未提交差异	修正证据范围，不能接受空审查
测试绿色但需求遗漏	运行命令和实际断言、需求映射	补能捕获行为错误的测试
压缩后重复实现	plan 身份、ledger、实际提交和修复轮次	从首个未完成项恢复
reviewer 反复提新建议	原问题列表、复审范围、严重性	限定复审，记录延期与裁决
两个 Agent 互相覆盖	文件、接口、数据库和进程的共享状态	重新划分任务或串行执行
费用明显异常	实际轮次、重复读写、重复派发及计费记录	先定位成本来源，再决定执行模式
要向维护者发会话资料	具体证据范围、脱敏结果、导出文件清单	检查后再决定分享，不上传整段原始会话

这些建议综合来自工作区、执行、验证和会话诊断机制，属于本文的排查组织方式，不是项目提供的统一命令。[8][9][12][15][18]

特别要注意路径规则冲突。Superpowers 示例常使用 docs/superpowers/ 保存设计和计划，但项目可能要求工作材料放入其他目录。用户与项目明确约定应被保留。相反，某些辅助脚本默认的工作区路径写在代码里，不会因为自然语言说“换个目录”就自动改变；使用前要确认是否支持覆盖，必要时采用经确认的等效工作方式。[4][6][9]

排查 Superpowers 本身，也需要可核查的证据

新增的 diagnosing-superpowers 面向会话行为异常：重复工作、没有遵守计划、技能没有触发，或耗时和费用超出预期。它先明确具体会话、预期与实际现象，再定位 transcript，要求发现附带 path:line 引用。[15]

这里一个重要约束是区分证据与归因。看到任务被执行两次，可以报告重复派发发生在哪一段；但仅凭这件事，还不能断言是某个技能缺陷导致，也可能是计划身份、宿主上下文或用户新指令造成的。该技能将取证报告和后续项目缺陷判断分开。

它还区分了调查、导出和对外提交：分析会话不等于可以把会话打包发出去。资料可能包含源码、工具结果和用户输入；即使经过自动脱敏，仍需要检查。实践中先用能够支撑问题的最小证据范围，通常也更方便维护者理解。[15]

遥测范围要读实现，不要扩大也不要淡化

README 说明可选 visual companion 会加载 Prime Radiant 的远程 logo，并附带 Superpowers 版本用于粗略统计。检查 server.cjs 可以看到，品牌图片 URL 加了 ?v= 参数；设置禁用变量后不生成这张远程图片。源码识别 SUPERPOWERS_DISABLE_TELEMETRY，也识别 README 所列的另外两个退出变量。[1]

例如，在启动会继承该环境变量的宿主或视觉工具之前设置：

export SUPERPOWERS_DISABLE_TELEMETRY=1

这只说明该视觉工具的品牌图片请求机制，不应写成“所有 Superpowers 会话都会上传内容”，也不能推导整个宿主不存在其他网络请求。环境变量还必须真的传入相关进程；在另一个终端设置，并不会自动修改已经启动的桌面应用环境。

不让方法论变成额外的负担

高频使用者最需要管理的是适用范围。对只读解释、机械文档修正和探索问题，应选择相应的工作方式；对行为修改和高风险交付，则需要更强证据。不要为了让日志看起来完整，把所有任务都套成一次大型软件项目。[5]

同样，不应把上游的每一条强制措辞原样提升为团队所有任务的最高规则。项目已有 CI、审批和发布流程时，技能应该帮助 Agent 遵循它们，而不是另起一套相互矛盾的要求。实际授权、宿主规则与项目规范的关系要清楚，例外要有具体理由，而不是让模型偷偷跳过。

与其他 AI Coding Skills 比较：哪些可以替代，哪些适合补充

先核实名字，再比较职责

同样被叫作 Skill，可能分别指方法论、工作流入口、编码规则、浏览器工具或分发平台。把它们放在同一份“热门技能清单”里，容易误以为功能重复或互为替代。下面只将能够定位维护方和具体指令的项目作为比较对象，不以 GitHub 星数、安装量或名称相似性推断工程质量。

项目或名称	已核实的来源	更准确的定位
think、check	tw93/Waza	方案形成与交付检查的可组合工作流
grill-me、grill-with-docs	mattpocock/skills	前者调用需求澄清，后者同时维护领域文档
implement、implement-spec	mattpocock/skills	单项实施入口与基于依赖图的并行实施编排
handoff	mattpocock/skills	面向下一会话的精简交接文档
ponytail	DietrichGebert/ponytail	贯穿编码过程的最小改动规则

这些条目有明确实现，不必将 ponytail 只写成搜索关键词，也不必将 handoff、check 仅描述成通用自定义脚本。尤其是 Matt 的 grill，应区分用户入口 grill-me、grill-with-docs 与底层 grilling，否则容易忽略组合调用和环境调查要求。[23][24][25][26][27][30][31]

总体差异：完整流程与单项约束不是一回事

维度	Superpowers v6.4.1	Waza	Matt Pocock Skills	Ponytail
核心关注	设计、实施、审查和交付的衔接	独立工作流中的工程判断	可组合的编排入口与基础技能	用最少新增复杂度完整解决任务
需求与方案	brainstorming 按任务规模形成设计	think 给出推荐方向与决策完备计划	grilling 消除决策分支，按需形成 Spec 或 Ticket	质疑不必要功能与抽象
实施方式	Native 或逐任务 SDD	由具体工作流与宿主能力决定	implement 直接实施，implement-spec 并行调度	不提供完整任务编排
测试约束	先观察失败，再最小实现，绿色后重构	check 要求真实验证证据	当前 tdd 先约定测试边界，逐测试实施	非平凡新增逻辑保留小测试或自检
主要取舍	阶段衔接完整，也有交接与审查开销	按需组合，需要明确授权边界	灵活组合，但部分入口依赖其他技能或子 Agent	简化实现，不能替代完整验收

这张表是本文根据指令结构做的归纳，不是维护方共同定义的分类，也不证明某个项目更快或更省 Token。Superpowers 当前已有有限修改和探索路径；Matt 的某些技能包含 worktree、并行派发和 PR 操作。因此，不能简单把两者分别贴成“重型”和“轻型”。[5][7][8][23][24][27][28][31]

维护者是谁：项目方法往往带着作者的工程背景

这四个项目的共同点是个人方法论色彩很强，并不是由同一个基金会统一设计的标准。比较它们时，除了看技能正文，也应该知道谁在持续维护，以及这些人的长期工程经验来自哪里。

项目	主要维护者	背景与项目气质
Superpowers v6.4.1	Jesse Vincent（GitHub 用户 obra）和 Prime Radiant 团队	Jesse Vincent 是资深 Perl 程序员和创业者，做过 Request Tracker（RT），参与过 Perl 生态，并与 Kaia Dekker 共同创办 Keyboardio；目前通过 Prime Radiant 推进 AI agent 工具。Superpowers 因此更像一套完整的软件工程方法论：需求澄清、设计、计划、TDD、子 Agent、Code Review 和交付验证彼此衔接。[1][36]
Waza	Tw93（tw93/Waza）	Tw93 将自己定位为 Product Engineer，长期做易用的开源工具和独立产品，代表项目包括 Kaku、Pake、Mole、Kami；技术栈横跨 Rust、Swift、Shell 和 TypeScript。Waza 的气质是轻量、直接、可组合，把工程习惯拆成 think、hunt、check、ui 等各自只有一个主要职责的技能。[37][23][24]
Matt Pocock Skills	Matt Pocock（mattpocock/skills）	Matt Pocock 是 TypeScript 教育者和工程师，创建了 Total TypeScript，曾参与 XState 等 TypeScript 生态项目，也有 Vercel 和 Stately 相关经历。他的技能库重点不是替用户接管流程，而是把需求访谈、领域语言、架构、TDD、Debug、Code Review 和 issue/ticket 工作流整理成可组合的工程实践。[38][39]
Ponytail	Dietrich Gebert（DietrichGebert/ponytail）	公开资料显示，Dietrich Gebert 是 Trimble Transportation 的 Lead GenAI Engineer，也是 Ponytail 的作者。项目把企业软件、DevOps、安全和生成式 AI 工程经验浓缩成“像一个懒但资深的工程师”这一规则：优先复用现有能力，减少不必要代码，但不省略测试、安全、错误处理和可访问性。[40][31]

因此，四者可以粗略地这样理解：Superpowers 偏完整流程和团队交付纪律；Waza 偏独立开发者的轻量工程习惯；Matt Pocock Skills 偏 TypeScript 工程教育与软件设计；Ponytail 偏 YAGNI、最小改动和避免过度工程。这些归纳是基于仓库说明和公开履历的分析，不代表维护者对彼此项目的共同分类，也不等于效果排名。

这里的 Waza 特指 tw93/Waza。另有一个同名的 Microsoft Waza，它是用于评估 AI agent skills 的 Go CLI/framework，并不是本文比较的 coding skills 集合；同名项目不能直接合并判断维护背景。

think：约束方案质量与实现交接

Waza 的 think 面向架构设计、方案对齐、头脑风暴，以及缺少可执行计划的实现请求。它排除常规 bug 修复和小改动；没有实施授权时，停在规划阶段，已经获得明确授权时，不重复索要批准。关键指令可以提炼为：

• 先读取项目规则、历史决策和真实配置；当前代码与文档优先于模型记忆。
• 优先研究框架官方方案，困难问题进一步查成熟项目的实际实现。
• 给出推荐方向与最小方案，说明成本、风险、收益和主动牺牲的能力。
• 明确最脆弱的假设、失败方式，以及新增依赖、状态和抽象是否值得。
• 交接计划不能留下未决方向或占位符，必须覆盖范围、接口、验证、回滚和交付。

它更接近一次方案评审；Superpowers brainstorming 则先建立目标和成功标准的共同理解，再按任务规模决定产物。两者可以服务同一阶段，但重复执行两套完整问答未必增加有效信息。[23][5][6]

grilling：用决策树消除隐含选择

Matt 的 grill-me 调用 grilling，grill-with-docs 则同时调用 domain-modeling，用于沉淀领域术语和 ADR。底层澄清流程的关键指令是：

• 将需求组织成决策树，先解决前置决策，再询问后续分支。
• 每轮只问当前已具备前提的问题，为每个问题给出推荐答案，回答后重算下一轮。
• 能从环境获取的事实自行调查；方向性选择和需要用户判断的取舍不能擅自代答。
• 所有分支明确、用户确认共同理解后，才开始行动。

当前原版要求通过 subagent 调查环境事实。因此，不能因为名字叫“追问”就认定它不需要子 Agent。单 Agent 使用者可以借鉴决策树方法，但需要明确采用适配后的流程，而不是声称原版已原样执行。与 Superpowers 的开放式目标澄清相比，它更强调系统地穷尽决策分支。[25][5]

implement 与 implement-spec：执行入口和并行调度

implement 从已明确的 Spec 或 Ticket 开始：引用不清楚就询问，调用 tdd 实施，经常运行类型检查与局部测试，结束时运行完整套件，再调用 code-review 并提交当前分支。这不是只负责写代码的提示词，也不能忽略它间接引入的审查和 Git 动作。[26][29]

implement-spec 的核心约束则是：

• 将 Ticket 视为有依赖的任务图，只启动前置工作已完成的任务。
• 每个实现者使用独立分支和 worktree，以集成分支为共同基线。
• 用 Spec、Ticket、研究材料和提交引用交接，而不是反复复制整段对话。
• 已完成任务汇入集成分支后，启动新解锁的任务；最后整体审查并处理 PR、Ticket 与工作区。

这与 Superpowers SDD 的差别不是“谁会使用子 Agent”，而是并行调度与逐任务审查的组织方式不同。本文固定版本的 SDD 明确禁止同时派发多个实现者；implement-spec 则将可并行任务的依赖调度作为核心。独立 worktree 也不会自动隔离数据库、端口和外部服务。[27][8][22]

Matt 当前 tdd 还有一个容易被概括遗漏的差异：先与用户约定公共行为接口和测试边界，再按一个测试、一段最小实现的纵向切片推进；它明确将重构放到审查阶段。Superpowers 则允许在绿色阶段重构。两者都强调先观察有效失败，但不能仅凭共同的 TDD 标签认定全部指令相同。[28][11]

ponytail：少写代码，但不能少交付行为

Ponytail 的 “Ladder of Laziness” 可以理解为解决方案的优先顺序：不必要就不做，先找仓库已有实现，再找标准库或平台能力、已安装依赖、易读的一行代码，最后才新增最小自定义实现。其他关键约束包括：

• 不增加无人要求的抽象、包装层、配置项和未来可能用到的代码。
• 修改前检查受影响的调用方、测试、配置与导出，不能只处理当前打开的函数。
• 非平凡新增逻辑留下小测试或断言自检，结束时说明未检查项与风险。
• 不能省掉安全校验、防数据丢失的错误处理、可访问性或用户明确要求。
• 激活后持续影响会话，直到用户关闭。

它适合补充任何实施流程，却不能替代需求澄清、并发验证或完整交付。“最小”应指满足行为约束的最小改动，不是把必要错误处理或测试删掉。[31]

check、code-review 与 handoff：检查范围和交接证据

技能	关键指令	与 Superpowers 的关系
Waza check	先看工作区与项目规则，保护用户改动；审查默认只报告；检查范围偏移、过度设计与安全问题；发现要有位置和触发条件；没有本次证据不声称通过	与审查、完成验证及收尾部分重叠
Matt code-review	固定比较基线；两个独立 subagent 分别检查仓库规范和 Spec；结果按审查轴分别呈现；代码异味仅作启发式线索，项目规范优先	不能套成 Superpowers v6.4.1 每任务固定双 reviewer
Matt handoff	压缩为下一会话能继续工作的文档；引用已有 Spec、ADR、Issue 与 diff，不重复正文；按后续目标列出技能；脱敏后写入临时文件	补充会话交接，不替代 ledger 与 Git 核对

handoff 不是完整上下文的无损转储。它主动保留必要状态并引用权威材料；原版使用系统临时目录，项目另有工作目录规则时应适配。check 中包含发布相关检查，也不意味着用户请求“检查一下”便授权修复、提交或发布。[24][29][30][8][12][14]

Superpowers 的关键指令速查

前文已经展开源码机制，这里只保留最影响执行选择的约束：

技能	最关键的行为要求
using-superpowers	回复或行动前检查适用技能；先读规则再行动；流程技能优先；当前用户与项目约束不能被通用模板覆盖
brainstorming	先理解目标和成功标准；复用用户已给出的信息；按任务规模选择产物，不机械制造长文档
writing-plans	写清具体文件、接口、输入输出、测试和预期结果；每个 task 是有独立验收意义的交付单元
test-driven-development	先看到测试因正确原因失败，再写最小实现；绿色后重构，结束前验证
systematic-debugging	先复现和收集根因证据，再单独验证假设；多次修复失败时重新检查架构假设
verification-before-completion	确定证明命令，实际运行并读完整输出；只对证据覆盖的范围声明通过
executing-plans / SDD	按计划实施并留下可恢复记录；SDD 保留逐任务独立审查，Native 减少任务级交接

这些是对固定版本指令的归纳，实际使用应阅读完整技能及其适用条件。Skill 中写了 “MUST” 不代表宿主权限、CI 或业务正确性已经由程序保证。[4][5][6][7][8][11][12][13]

官方技能库、审查插件和分发平台处于不同层

Vercel 的准确仓库地址是 vercel-labs/agent-skills，不只是组织首页；其技能提供 React、Next.js、组合模式和界面规范等领域知识。Anthropic 可确认的来源是 anthropics/skills 和官方插件目录，不应把尚未确认的 anthropics/claude-code-community-skills 当作官方仓库。skills.sh 是技能发现和安装生态，不能与完整开发方法论直接比较。[32][33][35]

Anthropic 官方 code-review 插件以 GitHub PR 为对象，使用多 Agent 审查和置信度筛选，并把构建、类型检查交给其他流程。因此，code-review 这个名字本身不代表固定的“对抗性审查”机制，更不保证一定覆盖死锁、并发和所有边界行为。[34]

原清单中的 context-gatherer、repo-map、agile-spec、adr-writer、playwright-evaluator、e2e-runner 和 mcp-db-inspector，在未绑定具体维护方与版本前，应视为待核实名称或能力类别，而非已确认的热门项目。浏览器执行、仓库索引和数据库查询可以补充流程，但工具能返回截图不等于数据已正确落库，只读意图也应由实际权限保障。

组合原则：保留一个主流程，补上缺失能力

基于这些指令结构，本文建议先确定一个主流程，再添加领域知识或缺失检查，不将多套完整规划、执行和审查链全部叠加。否则可能重复澄清、产生不同的阶段产物，并在 Git 或工作目录处理上形成冲突。这是组合风险判断，不是性能实验结论。

可以用 Superpowers 组织交付，吸收 Ponytail 的最小改动原则，并在跨会话时使用精简 handoff；也可以由开发者明确调度 Waza 和 Matt 的独立技能。但只要某个入口会继续调用其他技能，就需要顺着调用链确认子 Agent、测试、提交与发布要求，不能仅凭入口正文很短认定整体过程轻量。[4][26][29][30][31]

不使用 subagent 时，Superpowers Native 有明确的能力降级说明；Matt 当前 grilling、implement-spec 和双轴 code-review 则不能未经适配原样执行。这里的选择应基于实际能力和风险，不应把“不使用子 Agent”当成永远更好或更差。[7][25][27][29]

如何扩展与评价自己的技能

从重复出现的失败开始

值得写成技能的，通常不是“这次任务我做了什么”，而是“以后遇到同类条件时应该怎样做”。例如，团队反复在 API 修改中漏查向后兼容性，就可以形成一个读取接口定义、消费者和契约测试的检查流程；某次修复的日志则更适合留在问题记录里。[16]

一个技能的最小结构是名称、描述和正文。脚本只有在需要重复执行机械工作时才加入；参考资料只有在正文不适合承载时才拆分。不要为了看起来像完整项目而预先建立大量空目录。[19]

下面是描述字段的教学示例，不是一份已经完成测试的可安装技能：

name: checking-api-compatibility
description: Use when changing a public API response, request schema, or error contract that existing clients depend on.

正文接着需要说明如何发现消费者、什么变化算不兼容、运行哪些项目检查、没有证据时如何报告。对于不同仓库，命令可以由项目配置提供；不能让一个全局技能固定假设所有项目都使用同一个测试框架。

把技能开发视作行为测试

writing-skills 将 TDD 的思想用于过程文档：先设计场景，观察没有技能时的失败，再写最小规则改善行为，最后在新的压力场景中检查是否复发。[16]

例如，给 Agent 一个看似简单的响应字段重命名任务，并施加“只剩一点时间”的压力。基线要记录它是否检查了消费者、是否运行契约测试、是否把不兼容修改误称为重构。加入技能后，再观察相同维度，而不是只检查它有没有说出技能名称。

还应准备不会触发的反例：纯粹解释接口文档，未改变任何契约，不应该凭空开启一轮代码修改；内部局部变量更名也不应自动当成公开 API 迁移。只看正例会让技能越来越容易触发，却越来越不适合日常使用。

为减少偶然性，应保持模型、宿主、项目快照和任务条件尽量一致，保留每次运行记录，并承认样本量有限。一次成功说明一个场景里发生了改善，不构成“这个技能永远有效”的证明。跨模型或升级后，关键场景需要重新检查。[16][17]

同时评价正确性与过程成本

评价问题	适合观察的证据	常见误用
需求是否交付	需求覆盖表、行为测试、真实审查发现	用代码行数代表产出
是否减少错误	同类任务中的缺陷与返工记录	把任务难度不同的两次运行直接比较
是否更易恢复	中断后能否定位首个未完成任务	只检查是否存在 ledger 文件
是否值得多 Agent	发现的重要问题、交接与修复成本	把 Agent 数量当作严谨程度
是否降低人工负担	需要人类解决的决策数量与性质	认为任何提问都是负担
是否控制费用	实际 token、计费与耗时记录	从价格表推算没有记录的总账单

把这些量放在一起，才能看到真实取舍。例如更多需求澄清可能延长前半段会话，却减少错误实现；减少子 Agent 可能降低派发开销，却增加最后才发现问题的成本。没有真实对照时，应把这些描述为可能的机制，而不是已发生的收益。

给长期用户的源码阅读路线

第一遍只读 README、using-superpowers 和 Agent Skills 规范，建立“分发—发现—按需读取”的基本结构。第二遍顺着一个真实任务读 brainstorming、writing-plans 与一种执行模式，记录每个阶段的输入、输出和停止条件。[1][4][19]

第三遍再读 sdd-workspace、task-brief、review-package 和 task-done。不要仅看正常路径，重点看身份冲突、空输入、错误退出和证据范围。你会发现项目已经把一部分常见误操作转成代码，也会看到剩余判断仍然交给执行者。[9][10]

第四遍读 writing-skills、测试说明与发布记录，理解规则为什么演进。阅读时应特别留意文档之间的版本差异：编写技巧中的历史案例未必描述当前执行模式。发生冲突时，具体行为以固定版本的对应技能和实现为依据，历史案例只用于解释经验来源。[16][17][18]

最后，把学习结果应用到一个你熟悉的小项目：先写清交付目标，选择合适流程，检查真实产物。你不需要记住所有技能的每条规则，但应该能够识别什么时候缺了设计、什么时候计划不再可信、什么时候“已完成”还没有证据。

Superpowers 最值得学习的地方，是将原本隐含的工程习惯变成能被读取、交接和检查的工作材料。用得成熟时，关注点会从“Agent 有没有调用技能”转向“这一步消除了什么不确定性，留下的证据是否足够支持下一步”。这也是从频繁使用走向真正理解的分界。

参考资料

原始研究资料中的 Superpowers 项目作者为 Jesse Vincent / Superpowers contributors，来源为 GitHub，固定于 v6.4.1 / 5bf4e78011075bcfc0dc295f0724994cd123ee71（2026）。参考组 1–22 的访问日期为 2026-09-24；补充比较的参考组 23–35 作者见各条，访问日期为 2026-10-10，链接指向核验时的主分支或滚动页面，未来内容可能变化。外部文档不补写不明确的出版年份。

以下共 35 个参考组：原有 22 组中，18 组是 Superpowers 的一手实现证据，4 组来自外部官方文档；新增 13 组用于其他 Skills 的比较。不同源码文件用于支持不同结论，不代表来自同等数量独立机构的交叉验证。每组附带的相关文件用于补全同一论点，不额外计数。

1. README：定位、安装、遥测。项目组成、各宿主入口与遥测声明；不能证明普遍提效。关联源码：skills/brainstorming/scripts/server.cjs。
2. SessionStart hook。读取 bootstrap 与 JSON 输出；结合 hooks/hooks.json 核验注册时机。关联源码：hooks/hooks.json。
3. Codex 插件 manifest。skills 入口与显式空 hooks；不能代表本机安装版本。
4. using-superpowers。技能选择、优先级、子任务 bootstrap 豁免。关联源码：skills/using-superpowers/references/codex-tools.md。
5. brainstorming。三种任务路径与设计阶段产物、审批边界。
6. writing-plans。计划格式、接口契约、Review Focus 和执行交接。
7. executing-plans。Native 模式、任务完成条件与最终审查。
8. subagent-driven-development。控制者、实现者、审查者、修复循环与断路处理。关联源码：skills/dispatching-parallel-agents/SKILL.md；skills/subagent-driven-development/scripts/task-brief；skills/subagent-driven-development/task-reviewer-prompt.md。
9. 计划工作区与审查包。计划身份、同名冲突隔离；结合 review-package 分析范围检查。关联源码：skills/subagent-driven-development/scripts/review-package。
10. Native task-done。运行传入命令、保留日志、成功后追加 ledger 的实现边界。关联源码：skills/executing-plans/scripts/task-start。
11. test-driven-development。先观察失败，再最小实现，再运行验证；不能据此推断收益比例。关联源码：writing-good-tests.md。
12. verification-before-completion。完成声明与新鲜证据的对应关系。
13. systematic-debugging。根因调查、模式分析、假设实验和实施。
14. 审查、隔离与收尾技能组。审查请求与证据交接；关联 receiving-code-review、using-git-worktrees、finishing-a-development-branch。关联源码：skills/receiving-code-review/SKILL.md；skills/using-git-worktrees/SKILL.md；skills/finishing-a-development-branch/SKILL.md。
15. diagnosing-superpowers。基于 transcript 的 path:line 取证、报告与导出边界。
16. writing-skills。描述字段、压力场景、无技能基线与行为回归。
17. Testing Superpowers。程序测试与行为评估分层、外部 eval lab 和运行边界。
18. Release Notes。版本变化；评估数字只作为维护者报告，不能冒称独立复现。
19. Agent Skills — Specification。SKILL.md 格式与渐进披露；格式兼容不等于各宿主行为一致。
20. OpenAI — Customization / Skills。Codex 的元数据发现、按需加载及全局/项目技能位置。
21. Anthropic — Hooks reference。Claude Code SessionStart 与上下文输出协议；不能泛化到 Codex。
22. Git project — git-worktree。linked worktree、共享仓库关系和清理语义；worktree 不等于权限沙箱。
23. tw93 / Waza, think。方案授权、官方实现调查、最小方案、脆弱假设与决策完备交接。
24. tw93 / Waza, check。工作区保护、范围与风险审查、验证证据和发布授权边界。
25. Matt Pocock, grilling。决策树、依赖就绪问题、环境事实调查与行动确认。关联入口：grill-me；grill-with-docs。
26. Matt Pocock, implement。Spec/Ticket 获取、TDD、完整测试、审查和提交。
27. Matt Pocock, implement-spec。依赖图、独立 worktree、并行实施、集成分支和收尾。
28. Matt Pocock, tdd。公共接口测试边界、逐测试纵向切片与重构阶段；应区分具体指令和 README 简述。
29. Matt Pocock, code-review。规范与 Spec 双轴独立审查、比较基线和项目规则优先。
30. Matt Pocock, handoff。精简交接、已有材料引用、后续技能建议与脱敏。
31. Dietrich Gebert, Ponytail。Ladder of Laziness、影响范围、最小改动和不可省略的质量边界。
32. Vercel Labs, Agent Skills。领域技能目录及适用范围；不据此推断实际性能收益。
33. Anthropic, Skills。官方技能示例库及其与工具、宿主的边界。
34. Anthropic, 官方 code-review 插件指令。GitHub PR、多 Agent 审查、置信度筛选和不承担的检查范围。
35. Vercel, skills.sh。技能发现、安装与分发生态；榜单不作为工程质量或效率证明。
36. Jesse Vincent / obra 与 Prime Radiant, Superpowers README 与 Jesse Vincent 公开资料。项目维护者、Prime Radiant、Request Tracker、Perl 与 Keyboardio 背景；职业经历的交叉核验见 Keyboardio About Us 与 Jesse Vincent GitHub profile。
37. Tw93, GitHub profile 与 Waza README。Product Engineer 自述、Kaku/Pake/Mole/Kami 等项目及 Waza 的技能定位。
38. Matt Pocock, Total TypeScript 与 Matt Pocock GitHub profile。TypeScript 教育者、工程师和 Total TypeScript 作者背景。
39. Matt Pocock, Skills for Real Engineers。技能库的定位、工程经验来源和技能分类；项目履历的补充核验见 LinkedIn profile。
40. Dietrich Gebert, Ponytail GitHub profile 与 公开职业资料。Ponytail 作者身份及 Lead GenAI Engineer 经历；职业信息以公开搜索结果和个人职业页面为准。