Superpowers 实现原理深度解析：如何把工程纪律变成 Agent 的默认行为

**版本基线：**本文以 Superpowers 官方正式版 v6.1.1（2026-07-02）的代码、README.md、RELEASE-NOTES.md 和 skills/*/SKILL.md 为准。

**项目数据：**截至 2026 年 7 月 11 日，Superpowers 在 GitHub 上已获得约 25.2 万 Star 、2.2 万次 Fork。官方 GitHub 仓库。

Superpowers 由 Jesse Vincent （GitHub 用户名 obra）发起。Jesse 是一位长期从事软件工程与开发者工具工作的创业者，曾创办 Best Practical，并创建了开源工单系统 Request Tracker。进入 AI 编程时代后，他反复观察到一种落差：模型明明"知道"需求澄清、测试驱动开发、系统化调试和代码评审，却常常在真实任务中跳过这些步骤，直接开始写代码。提示词一长、上下文一复杂，这种行为还会变得更加不稳定。

因此，Jesse 没有再造一个代码生成器，而是将自己与编程 Agent 协作时采用的工程流程，整理为一套开源的 Agentic Skills（面向 Agent 的技能化工作流）框架与软件开发方法论。

先给出全文结论：Superpowers 的核心，不是增强模型的代码知识，而是把软件工程纪律封装成可加载、可执行、可验证、可恢复的 Skill 协议，让 Agent 不只是"会写代码"，而是"会按工程流程交付"。

它要解决的，因此也不是"如何让模型写出代码"，而是一个更具工程挑战的问题：

如何把成熟的软件工程纪律内化为 Agent 的默认工作方式，并使其能够在 Claude Code、Cursor、Codex、OpenCode 等不同宿主中稳定复用？

Superpowers 的回答可以压缩为三点：用平台无关的 Skill 定义方法论，用宿主适配与模型编排把方法论注入任务，再用测试、Git、代码评审和状态文件把执行过程变得可检查、可追溯、可恢复。

为证明这个结论，全文按四个并列问题展开：它改变了什么、它如何运行、它为何相对可靠、它又沉淀出哪些可复用原则。

篇章	回答的问题	对应内容
第一篇：它改变了什么	Superpowers 改变了什么，为什么这样设计？	开发流程、技能体系、设计哲学
第二篇：它如何运行	Skill 怎样进入宿主并组织一次开发任务？	系统架构、Skill 加载、bootstrap、入口检查与流程分流、主工作流
第三篇：它为何可靠	自然语言流程为什么有效，又有哪些边界？	行为约束、TDD 与评测、跨平台适配、可靠性边界
第四篇：它沉淀出什么原则	这套实现能抽象出哪些通用原则？	七条 Agent 工程原则与全文结论

1. 第一篇：建立整体认知------从开发流程到技能体系

本篇先给结论：Superpowers 改变的首先不是 Agent 的知识上限，而是任务的默认推进顺序。 一个需求不再从自然语言直接跳到代码，而是先经过设计、计划、隔离实现、测试、评审、验证和交付。

下面按三个层次展开：先看一个需求如何沿流程推进，再看 14 个 Skill 如何覆盖生命周期，最后回到设计哲学，解释它为什么要把行为稳定性放在代码生成能力之前。

1.1 一个需求如何沿着 Superpowers 流转

假设用户提出："给现有系统增加通知功能。"普通 Agent 很可能先搜索代码、选择一个库，然后直接修改实现。Superpowers 则会把这个模糊想法推进为一条有明确门禁和证据的工程流水线：

text 复制代码

提出想法
  → brainstorming：澄清目标、比较方案、形成并批准设计
  → writing-plans：把设计拆成带文件路径、测试与命令的任务
  → using-git-worktrees：确认或创建隔离工作区
  → subagent-driven-development / executing-plans：逐任务执行
  → test-driven-development：每项功能先红、再绿、后重构
  → requesting-code-review：检查规格符合度与实现质量
  → verification-before-completion：用刚刚重新运行的测试和构建结果证明任务完成
  → finishing-a-development-branch：决定合并、提 PR、保留或丢弃

这条流水线的关键不在于步骤更多，而在于每个阶段都有明确的输入、输出和门禁。以通知功能需求为例，整个过程会这样推进：

**澄清目标并批准设计。**先确认通知的触发事件、展示范围、已读规则、失败补偿等需求边界，再比较同步写入、异步投递、是否需要消息队列等方案；只有用户批准设计后，才能进入实现。
**把设计拆成执行计划。**将已批准的设计细化为带文件路径、实现步骤、测试方法和验证命令的小任务，减少执行时的临场猜测。
**隔离工作环境。**确认或创建独立 worktree（Git 的隔离工作目录），并验证基线状态，避免当前任务污染主工作区或受既有改动干扰。
**按计划逐项实现。**由子 Agent 或当前会话依次完成任务，在清晰的任务边界内提交、检查和纠偏，避免一次性修改失控。
**用 TDD 约束编码。**每项功能都先编写会正确失败的测试，再实现最少代码使其通过，最后在测试保护下重构。
**检查规格与质量。**Reviewer 对照任务说明和实际 diff，检查实现是否漏做、误做、超出范围，或存在设计与代码质量问题；重要问题必须修复并复审。
**用最新结果验证完成。**重新运行与任务相关的测试和构建命令，并结合输出、退出码和 Git 状态判断是否满足规格；没有最新证据，就不能声称任务完成。
**由用户决定交付方式。**验证通过后，向用户提供合并、创建 PR、保留分支或丢弃改动等选项，再根据选择安全处理分支和工作区。

因此，Superpowers 带来的"超能力"并不是让模型突然掌握更多 API，而是通过逐阶段收敛、门禁和外部证据，把容易失控的自然语言对话转化为可检查、可恢复、可复核的软件工程过程。

1.2 14 个 Skill 如何覆盖开发生命周期

Superpowers v6.1.1 的 skills/ 目录包含 14 个核心 Skill。它们不是彼此孤立的提示词，而是按软件生命周期相互衔接的行为协议。

1.2.1 入口与元能力

Skill	作用
`using-superpowers`	总入口。在采取任何行动前检查适用 Skill，建立"先选流程、再做事情"的纪律。
`writing-skills`	指导如何用类似 TDD 的方式创建、测试和改进 Skill，本质上是框架的自举能力。

1.2.2 需求与计划

Skill	作用
`brainstorming`	把模糊想法变成经用户批准的设计：澄清问题、比较方案、控制范围并形成规格。
`writing-plans`	把设计编译成可执行计划，明确任务边界、文件路径、接口、测试、命令与预期结果。

1.2.3 执行与任务编排

Skill	作用
`subagent-driven-development`	由控制器逐任务派发实现者和评审者，通过 brief、report、review package 与进度 ledger 完成交接。
`executing-plans`	在同一执行会话中按批次落实既有计划，并在批次之间设置检查点。
`dispatching-parallel-agents`	当多个问题彼此独立时并行派发子代理，减少不必要的串行等待和上下文干扰。

1.2.4 质量保障

Skill	作用
`test-driven-development`	强制 RED → Verify RED → GREEN → Verify GREEN → REFACTOR，确保测试真正约束实现。
`systematic-debugging`	面对故障先复现、收集证据和验证根因，再实施修复，避免连续猜测式补丁。
`verification-before-completion`	声称完成前重新运行能够证明结论的命令，以实际输出替代"应该没问题"；这里的 verification 可以理解为"用最新工具结果完成收尾验证"。
`requesting-code-review`	组织评审材料并请求独立 Reviewer 检查实现。
`receiving-code-review`	要求对评审意见进行技术核验后再修改，避免盲从或表面接受。

1.2.5 工作区与交付

Skill	作用
`using-git-worktrees`	检测并建立隔离工作区，运行基线验证，避免新任务污染当前 checkout。
`finishing-a-development-branch`	测试通过后显式选择合并、创建 PR、保留或丢弃，并安全清理工作区。

从角色上看，using-superpowers 负责在任务起点做 Skill 检查与流程分流；设计和计划类 Skill 负责定义"做什么"；执行类 Skill 负责组织"谁来做、按什么粒度做"；质量类 Skill 负责建立证据门禁；Git 类 Skill 负责隔离与交付。14 个 Skill 合起来，覆盖的是一条端到端开发生命周期，而不只是编码环节。

看清技能体系之后，还需要回答一个更根本的问题：为什么项目要用如此完整的流程约束 Agent？答案不在于模型缺少编码知识，而在于它很难在复杂任务中持续执行自己已经知道的工程纪律。

1.3 从行为稳定性问题理解四条设计哲学

大模型通常能够编写局部代码，但完成一个真实软件任务还需要一整套过程：

先理解用户意图和成功标准；
比较多个方案，而不是抓到第一个想法就实现；
把设计写成可检查的规格；
把规格拆成低歧义、可验证的任务；
先看到测试正确失败，再写最小实现；
检查实现是否符合规格，是否多做或漏做；
在宣布完成前，重新运行测试、构建等验证命令，确认最终产出符合预期；
明确决定合并、提 PR、保留还是丢弃分支。

Agent 的问题通常不是"不知道这些概念"，而是在时间压力、长上下文或高度自信时跳过它们。它会用看似合理的理由直接行动，例如"先看一下文件""这个改动很简单""测试应该能过"。

Superpowers 因而不以增加知识为第一目标，而是改变默认行为顺序：

text 复制代码

普通 Agent
收到任务 → 立即探索或编码 → 事后补流程

Superpowers Agent
收到任务 → 先判断适用 skill → 建立过程 → 产生证据 → 再推进

官方 README 将其概括为：技能是 mandatory workflows, not suggestions。这里的 mandatory 是方法论要求；它的实际可靠性来自 bootstrap、强约束文案、检查清单、子代理复核和工具证据的共同作用。

1.3.1 四条设计哲学

1. Test-Driven Development（测试驱动开发）

Agent 容易先写实现，再补一个只会证明现有代码正确的测试。Superpowers 要求严格执行 RED → Verify RED → GREEN → Verify GREEN → REFACTOR：先通过正确的失败证明测试能够捕获目标问题，再编写最小实现使其通过。这样，测试不只是交付后的装饰，而是定义行为、约束实现并提供正确性证据的工具。

2. Systematic over ad-hoc（系统化优先于临时应对）

面对故障时，Agent 容易根据表面症状连续尝试补丁，每次修改都引入新的变量，却没有建立对根因的解释。systematic-debugging 要求先稳定复现、收集证据、定位故障边界并验证根因假设，再实施修复。其重点不是让 Agent 更快地产生改动，而是让每一步都缩小问题空间，避免"碰巧修好"或掩盖深层问题。

3. Complexity reduction（降低复杂度）

Agent 容易为了可能出现的未来需求提前设计抽象层、扩展点和通用框架，也容易把大量计划、代码和历史对话塞进同一上下文。Superpowers 以 YAGNI（You Aren't Gonna Need It，只实现当前确实需要的功能）限制实现范围，并通过小任务、文件化交接和隔离子代理控制认知负担。减少不必要的代码与上下文，既能降低缺陷概率，也让实现和评审更容易聚焦。

4. Evidence over claims（证据优先于声明）

语言模型很容易把"看起来正确""应该能通过"表达成已经完成，但这种自信并不能证明实际状态。Superpowers 要求用测试输出、构建结果、review package、Git diff、退出码以及完成前的重新验证支撑结论。能够由工具确认的事实必须交给工具确认，把"模型认为正确"转化为"外部证据支持正确"。

第一篇由此建立了三个层次的整体认知：端到端流程展示 Superpowers 怎样工作 ，技能地图说明流程由哪些能力组成 ，四条设计哲学解释项目为什么这样设计。接下来进入实现内部，沿一次任务的真实运行顺序，分析这些方法如何被表达、注入、选择和执行。

2. 第二篇：拆解运行机制------从系统架构到工作流执行

本篇先给出技能层、宿主适配层、模型编排层、证据与状态层组成的系统全景，再沿"Skill 描述与加载 → bootstrap 注入 → 任务起点的 Skill 检查与流程分流 → 主工作流执行"的链路逐层展开。

2.1 四层系统架构：技能、适配、编排与证据

2.1.1 第一层：平台无关的技能库

skills/ 是方法论的单一事实来源，包含 14 个核心技能：

类别	Skill
设计与规划	`brainstorming`、`writing-plans`
执行	`subagent-driven-development`、`executing-plans`、`dispatching-parallel-agents`
测试与调试	`test-driven-development`、`systematic-debugging`、`verification-before-completion`
评审	`requesting-code-review`、`receiving-code-review`
Git 工作流	`using-git-worktrees`、`finishing-a-development-branch`
元能力	`using-superpowers`、`writing-skills`

每个技能目录至少有 SKILL.md，还可以带：

Prompt 模板，例如 implementer-prompt.md、task-reviewer-prompt.md；
参考文档，例如 testing-anti-patterns.md；
可执行脚本，例如 SDD 的 task-brief、review-package；
可视化工具，例如 brainstorming 的 visual companion。

技能正文使用"调用技能""派发子代理""创建任务""读取文件"等动作语义，而不是把流程绑定到某个平台的工具函数名。

2.1.2 第二层：宿主平台适配要解决什么

这一层先不展开具体实现，而是先把适配层要解决的问题说清楚。不同宿主的适配方式虽然不同，但最终都绕不开两个核心问题：

宿主怎样发现 skills/；
using-superpowers 怎样在任务开始时成为有效指令。

Superpowers 优先使用宿主原生能力，常见实现可以归纳为两类：

适配机制	代表宿主	技能发现	bootstrap 生效方式
Shell Hook	Claude Code、Cursor	插件约定或 manifest 注册 `skills/`	会话启动时运行脚本，将 `using-superpowers` 注入上下文
进程内插件	OpenCode	插件 API 注册技能路径	在消息生命周期中插入 bootstrap，并负责缓存和去重

其他宿主虽然在 manifest 字段、事件名称和工具映射上有所差异，但都围绕这两个不变量展开：让技能可发现，并在 Agent 第一次行动前建立技能检查规则。这里先把问题边界立住；具体到 Skill 如何被宿主发现，会在 2.2 节展开；具体到 bootstrap 如何在会话启动时把规则注入上下文，则放到 2.3 节详细说明。

2.1.3 第三层：模型驱动的语义编排

宿主可以确定性地注册和呈现技能，但"当前任务与哪个 description 匹配"仍由模型判断。例如：

text 复制代码

"增加通知功能"
→ brainstorming 描述命中创意或行为变更

"修复偶发认证失败"
→ systematic-debugging 命中 bug 调试场景

"实现这个已经批准的多步骤规格"
→ writing-plans 或计划执行技能命中

技能之间通过正文中的 REQUIRED SUB-SKILL、流程终态和场景触发继续编排，不存在一个把全部步骤写死的中央 DAG 引擎。

2.1.4 第四层：确定性证据与恢复状态

自然语言负责过程选择，工具负责事实确认。系统重点记录并验证：

测试先失败、后通过的真实输出；
每任务 commit 范围和完整 diff；
实现报告、任务简报、评审包等文件化交接；
.superpowers/sdd/progress.md 持久化进度；
Git worktree 的实际隔离状态；
完成前重新运行的验证命令。

这形成完整闭环：

text 复制代码

识别情境 → 加载 Skill → 执行动作 → 生成证据
    ▲                                  │
    └──── 不符合要求：修复并重新验证 ────┘

四层架构说明了系统由什么组成，但还没有回答"流程是如何真正跑起来的"。第二篇的核心结论是：Superpowers 不是一个写死步骤的中央状态机，而是一套由宿主、模型、Skill 和工具共同执行的分层协议。

下面将继续展开它如何把"何时使用"和"怎样执行"编码进 SKILL.md，以及宿主和模型如何逐步加载这些内容。

2.2 Skill 如何被描述、匹配与按需加载

一个 Skill 从仓库文件变成 Agent 当前任务中的执行规则，需要依次经过三个环节：先用元数据声明"我是谁、何时适用"，再由模型根据任务语义判断是否命中，最后加载正文及其配套资源。Superpowers 将这三个环节分开，是为了同时兼顾触发准确性、执行完整性和上下文成本。

2.2.1 Frontmatter 声明触发条件，正文定义执行协议

每个 SKILL.md 都分为元数据与正文两部分。Frontmatter（前置元数据块）位于 Markdown 文件开头，由一对 --- 包围，通常以 YAML 格式记录文件的结构化元信息；后面的 Markdown 正文则承载完整工作流。

典型结构如下：

markdown 复制代码

---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code
---

# Test-Driven Development (TDD)

...

三部分各自承担不同职责：

name：提供稳定、唯一的 Skill 标识，供宿主发现和调用；
description：描述适用场景，供模型判断当前任务是否需要该 Skill；
正文：定义命中之后必须执行的步骤、门禁、检查项和异常处理方式。

writing-skills 要求 frontmatter 至少包含 name 和 description 两个字段，整体不超过 1024 字符，名称只能使用字母、数字和连字符。这些限制使元数据保持简短、规范，适合作为常驻的技能索引。

2.2.2 `description` 负责召回，不负责讲解流程

模型在尚未加载正文时，主要依据 description 判断 Skill 是否适用。因此，description 应准确描述任务类型、可观察症状和触发时点，例如：

text 复制代码

Use when implementing any feature or bugfix, before writing implementation code

它不应写成"先写测试、再实现、最后重构"这样的流程摘要。否则模型可能把摘要误当成完整指令，不再加载正文中的 RED 验证、GREEN 验证和偏离处理等关键约束。官方将这种元数据取代正文的现象称为 Description Trap。

因此，两者的边界是：description 只回答"什么时候应该使用"，正文负责回答"使用之后具体怎么做"。前者需要提高正确 Skill 的召回率，后者才保证工作流的完整性。

2.2.3 命中后再逐层加载，控制上下文成本

明确上述分工后，Skill 的加载链路就很清楚了。宿主首先只向模型暴露体积较小的 name 和 description；模型结合当前任务判断命中后，才加载对应的完整 SKILL.md；正文引用的参考文档、Prompt 模板或脚本，则等执行到相关步骤时再读取。

text 复制代码

第一层：name + description       发现候选 Skill、判断是否适用
  → 第二层：完整 SKILL.md        获取工作流、门禁与检查项
    → 第三层：参考、模板或脚本   执行具体步骤时按需读取

这种渐进式加载避免让 14 个 Skill 的全文长期占据上下文，也减少无关规则之间的注意力干扰。换言之，元数据承担低成本路由，正文与配套资源承担按需执行。

2.2.4 由主协调者选择流程，任务子代理只履行契约

上述匹配与加载机制主要服务于主协调者。using-superpowers 在入口处要求主协调者检查适用 Skill、选择流程并维护全局状态，但它同时规定：如果当前 Agent 是为一个边界明确的任务而派发的 subagent，就跳过这项入口检查。

这是因为子代理接收到的 task brief 已经是主协调者完成流程选择后的结果。若子代理再次依据"1% 规则"从头匹配 Skill，就可能重新启动 brainstorming、规划或子代理调度，进而造成递归编排和职责越界。

text 复制代码

主协调者：理解全局任务 → 匹配 Skill → 选择流程 → 维护状态
任务子代理：读取派发契约 → 完成局部任务 → 返回结果与证据

至此，SKILL.md 已经定义了"如何被识别、何时命中、命中后如何执行"。但这些文件仍只是仓库中的静态内容：宿主还必须先注册技能目录，并在 Agent 第一次行动前让总入口规则进入会话。下一节将沿这个边界进入 bootstrap 适配机制。

2.3 bootstrap 如何把技能纪律注入 Cursor

不同宿主的 API 各不相同，但 bootstrap 适配中最有代表性的两种机制是 Shell Hook 和进程内插件。前者由宿主在会话启动时执行外部脚本，后者直接参与消息生命周期。

2.3.1 注入发生在什么时点：`session-start` Hook

在 Cursor 里，Superpowers 不是等模型"自己想起来"先检查 Skill，而是在会话启动时就把 using-superpowers 的规则注入上下文。这个入口由根目录下的 hooks/session-start 脚本承担。

它要完成五件事：

根据脚本位置定位插件根目录；
读取 skills/using-superpowers/SKILL.md 的完整内容；
组装一段额外上下文，明确说明 using-superpowers 已经加载，其他 Skill 需要按需再调用；
对内容做 JSON 转义，确保可以被宿主稳定消费；
按 Cursor 的协议输出到标准输出，交给会话启动流程注入。

这里最关键的点是时机：注入必须发生在 Agent 第一次行动之前。只有这样，"先检查是否需要某个 Skill"才不是一句建议，而是当前会话一开始就已经在场的工作规则。

2.3.2 注入内容长什么样：Cursor 消费的 JSON 契约

对 Cursor 来说，session-start 脚本最终产出的不是任意文本，而是宿主约定的 JSON 结构：

text 复制代码

{ "additional_context": "..." }

也就是说，脚本真正做的事情不是"执行 Skill"，而是把一段额外上下文交给 Cursor，再由 Cursor 把它拼进当前会话。这个上下文至少要包含两层意思：

using-superpowers 的完整规则已经进入当前对话；
其他 Skill 不需要预先全部加载，而是由后续任务语义按需触发。

这种设计有两个直接收益。

第一，入口规则常驻，而不是等模型自行回忆。模型在收到用户请求时，面对的起点就已经不是"自由发挥"，而是"先按 using-superpowers 检查流程"。

第二，只有总入口常驻，其他 Skill 继续按需加载。这样既保住了纪律约束，又避免把 14 个 Skill 的全文一次性塞进上下文，造成不必要的 token 占用和注意力干扰。

2.3.3 为什么这种机制能稳定生效：去重、重建与恢复

把规则注入一次并不难，难的是在真实会话里持续有效。Cursor 场景下，bootstrap 机制要同时处理三个稳定性问题。

**1. 不能重复叠加。**同一段 bootstrap 如果在一次会话中被重复注入，模型看到的就会是多份近似规则，既浪费上下文，也可能放大注意力噪音。因此脚本输出必须严格遵守宿主契约，让一次生命周期事件只对应一次注入。

**2. 会话重建后要能恢复。**用户重新开始会话时，Agent 不应退回到"裸奔"状态，而应再次拿到 using-superpowers 这条总入口规则。对这类依赖会话状态的系统来说，恢复机制不是锦上添花，而是纪律能否持续存在的前提。

**3. 上下文压缩后要保留关键规则。**长会话里最容易丢失的，往往不是局部实现细节，而是最上层的行为纪律。把 bootstrap 放在会话启动钩子上，本质上就是把"恢复入口规则"这件事交给宿主生命周期，而不是交给模型记忆力。

因此，从 Cursor 的视角看，bootstrap 机制的实质并不复杂：宿主在会话开始时执行脚本，脚本读取 using-superpowers，按 JSON 契约输出额外上下文，Cursor 再把这段上下文注入当前对话。复杂之处不在"能不能注入"，而在"能否始终在正确时点、按正确格式、以可恢复的方式注入"。

bootstrap 到这里完成的是"让总入口规则先在场"。但它仍然不替模型决定当前具体该调用哪个 Skill。真正接过下一棒的，是 using-superpowers 本身：它负责在任务起点完成 Skill 检查，并把任务分流到合适的过程型工作流。

2.4 `using-superpowers` 如何在任务起点完成 Skill 检查与流程分流

2.4.1 "1% 规则"为什么要优先保证召回

using-superpowers 要求：只要认为某个 Skill 有 1% 的可能适用，就必须调用检查。这个阈值有明确的成本逻辑：

多加载一次错误 Skill，通常只浪费少量上下文；
漏掉 brainstorming、debugging 或 TDD，可能使整个任务从一开始走错。

因此系统主动偏向高召回率：先加载，再判断是否真的适用。

2.4.2 为什么 Skill 检查必须先于任何动作

规则覆盖的不只是编码，还包括回答、澄清、探索代码库和检查文件。原因是"先了解一点情况"很容易成为直接实现的入口。

using-superpowers 还设置了 plan mode 前置门：如果尚未 brainstorm，就必须先调用 brainstorming，不能直接进入宿主自己的 plan mode。

2.4.3 它如何把任务分流到过程型 Skill

当多个 Skill 同时命中时：

text 复制代码

过程型 Skill → 决定怎样处理任务
实现型 Skill → 指导某一技术领域的具体实现

例如"构建 X"先进入 brainstorming，"修复 bug"先进入 systematic-debugging。这避免 Agent 在问题尚未定义时就开始优化局部代码。

2.4.4 Red Flags 如何阻断"先做一点再说"的合理化

using-superpowers 列出"问题太简单""先看文件""我记得这个 Skill""先做一件小事"等常见念头，并明确把它们定义为 rationalization。

这不是单纯在强调语气，而是把压力测试中反复出现的逃逸路径，整理成可识别的症状。一旦模型产生这些念头，就应当停止并回到 Skill 检查。

2.4.5 它如何处理用户目标与 Skill 规则的优先级

using-superpowers 明确规定：

text 复制代码

用户指令（项目说明文件与直接请求）
        > Superpowers Skills
        > Agent 默认行为

所以 Skill 不是覆盖用户意图的最高权力。用户可以明确要求跳过某个流程；但"增加 X""修复 Y"只定义目标，不自动等于允许跳过 TDD、设计或评审。

这一轮 Skill 检查与流程分流完成的结果，是为当前任务选择正确的过程型 Skill。接下来这些 Skill 会继续调用彼此，把一个想法依次推进为设计、计划、隔离实现、测试证据、独立评审和最终交付。

2.5 主工作流如何把设计推进到交付

主线不是中央状态机，但官方 Skill 之间形成了明确协议：

text 复制代码

brainstorming
  → writing-plans
    → using-git-worktrees（执行时确认隔离）
      → subagent-driven-development 或 executing-plans
        → test-driven-development
          → per-task task review
            → whole-branch review
              → finishing-a-development-branch

2.5.1 `brainstorming`：设计批准前禁止实现

brainstorming 要求按顺序完成九项任务：

探索项目文件、文档和近期提交；
只有视觉问题真正出现时，才即时提供 visual companion；
一次只问一个澄清问题；
给出 2---3 个方案、权衡和推荐；
分段展示设计并逐段确认；
保存到 docs/superpowers/specs/YYYY-MM-DD--design.md 并提交；
内联自审占位符、矛盾、歧义和范围；
要求用户审阅已经写入文件的规格；
规格批准后，只能转入 writing-plans。

终态不是"开始编码"，而是调用 writing-plans。这构成严格设计门：在用户批准前，不调用实现 Skill、不写代码、不搭脚手架。

该 Skill 还要求先判断范围。如果需求包含多个相对独立子系统，应先拆为多个子项目，每个子项目独立经历 spec → plan → implementation。

2.5.2 `writing-plans`：将规格编译成自包含任务

计划默认保存到：

text 复制代码

docs/superpowers/plans/YYYY-MM-DD-<feature>.md

每个计划包含：

Goal、Architecture、Tech Stack；
Global Constraints：从规格逐字复制的全局约束；
文件职责和结构映射；
每任务精确文件路径；
Interfaces：任务消费和产出的签名；
失败测试、运行命令、预期失败；
最小实现、通过命令和预期结果；
commit 步骤。

任务边界不应机械理解为越小越好。合适的任务是拥有自己的测试循环，并值得接受一次独立 Reviewer gate 的最小单元。配置、脚手架和文档应并入真正需要它们的交付任务。

计划完成后由当前 Agent 做内联 Self-Review，检查规格覆盖、占位符和类型一致性，不再派发独立计划 Reviewer。

2.5.3 `using-git-worktrees`：先检测、再原生、最后 Git 回退

该算法严格分三步：

text 复制代码

Step 0：检测是否已经隔离
Step 1a：优先使用宿主原生 worktree 工具
Step 1b：没有原生工具时才调用 git worktree

检测通过比较 git rev-parse --git-dir 与 --git-common-dir，同时使用 superproject 检查避免把 submodule 误判为 linked worktree。

如果已经位于 linked worktree，就直接复用；如果处于普通 checkout 且用户没有预先声明偏好，创建前必须询问同意。用户拒绝时可以原地工作。

手工 Git 回退默认使用项目根目录 .worktrees/，但优先尊重用户设置和现有 .worktrees/ / worktrees/。创建前必须用 git check-ignore 确保目录被忽略；若未忽略，先更新 .gitignore 并提交。

若 sandbox 阻止创建，Skill 明确降级为报告原因并在当前目录工作，而不是反复对抗宿主。

最后自动执行项目初始化并运行基线测试。基线失败时必须报告并询问是否继续，不能把已有红灯冒充新代码造成的问题。

2.5.4 `test-driven-development`：RED 本质上是测试有效性的证据

铁律保持不变：

text 复制代码

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

完整循环包含五个门：

**RED：**为一个行为写最小测试；
**Verify RED：**运行并确认测试因功能缺失而失败，而不是语法或环境错误；
**GREEN：**只写刚好让测试通过的实现；
**Verify GREEN：**确认目标测试和其他测试通过，输出无错误警告；
**REFACTOR：**只在绿灯下清理，不增加行为。

"先看它失败"证明测试确实具备检测能力。测试若一开始就通过，可能只覆盖已有行为；若报错而不是断言失败，则测试环境仍不可信。

若实现先于测试，Skill 要求删除并重来，不允许保留作参考。允许偏离 TDD 的情形只有 throwaway prototype、生成代码和配置文件，而且必须先询问用户。

2.5.5 `subagent-driven-development`：文件化执行协议

SDD 的核心不只是"每任务一个新子代理"，而是一个控制器、实现者、任务评审者和最终评审者组成的协议。

text 复制代码

Controller
  ├─ 维护计划、全局约束、todo 与持久化 ledger
  ├─ 为每任务生成 task brief
  ├─ 派发 Implementer
  ├─ 生成 review package
  ├─ 派发一个 Task Reviewer，返回两个 verdict
  └─ 全部完成后派发 Whole-Branch Reviewer

2.5.5.1 执行前：Pre-Flight Plan Review

在 Task 1 前，Controller 先扫描任务之间的矛盾，以及计划要求与评审准则直接冲突的内容。所有发现一次性提交用户裁决，避免执行中逐个打断。

2.5.5.2 每任务：最小上下文交接

执行协议不把整个计划和会话历史粘贴给子代理，而是使用脚本生成文件：

scripts/task-brief PLAN_FILE N：提取第 N 个任务；
Implementer 把详细报告写入对应 report file；
scripts/review-package BASE HEAD：生成包含 commit 列表、stat 和上下文 diff 的唯一文件；
Reviewer 读取 brief、report 和 review package。

这样大块材料不会永久占用 Controller 上下文，也不会在后续每轮反复计费。

2.5.5.3 一个 Reviewer，两个独立结论

每个任务只派发一个 task-reviewer-prompt.md，但它必须给出两个 verdict：

**Spec compliance：**有没有漏做、多做或违反精确约束；
**Task quality：**代码、测试、结构和可维护性是否合格。

这是一种一次读取 diff、同时返回两项独立门禁的设计。Critical 或 Important 问题必须修复并重新评审；Reviewer 无法从 diff 判断的要求使用"Cannot verify from diff"升级给 Controller 核验。

2.5.5.4 实现者状态协议

Implementer 返回四类状态：

状态	Controller 行为
`DONE`	生成 review package 并进入评审
`DONE_WITH_CONCERNS`	先判断顾虑是否影响正确性或范围
`NEEDS_CONTEXT`	补充缺失上下文后重新派发
`BLOCKED`	补上下文、升级模型、拆任务或升级给用户

不得让同一模型在条件不变时盲目重试。

2.5.5.5 持久化进度：防止 compaction 后重复执行

Todos 不足以跨上下文压缩恢复。SDD 使用：

text 复制代码

.superpowers/sdd/progress.md

记录完成任务、commit 和评审状态。压缩或恢复后，Controller 以 ledger 和 git log 为事实来源，从第一个未完成任务继续，避免重新派发已完成任务。

2.5.5.6 最终整分支评审

所有任务通过后，再以 MERGE_BASE..HEAD 生成全分支 review package，使用最强可用模型做一次 broad review。若发现多个问题，应把完整列表交给一个 Fix subagent，避免每个问题重复构建上下文和运行测试。

2.5.6 `finishing-a-development-branch`：完成代码与集成决策分离

执行完成后先验证测试，再根据当前是否有正常分支、worktree 是否由 Superpowers 管理等事实提供合并、创建 PR、保留或丢弃选项。

清理采用 provenance 原则：只自动清理能够确认由 Superpowers 创建、位于项目约定目录中的 worktree；宿主外部管理的 worktree 或 detached HEAD 环境交还宿主原生控制。这样可以避免误删用户工作区。

第二篇至此完成了运行机制的拆解：四层架构定义职责边界，SKILL.md 提供触发索引与执行协议，bootstrap（即会话启动时的规则注入过程）负责把总入口规则注入 Cursor，using-superpowers 负责在任务起点完成 Skill 检查与流程分流，主工作流再把流程落实为动作与产物。不过，"流程能够运行"还不等于"流程足够可靠"。第三篇将继续回答自然语言规则如何形成约束、如何经过评测、如何跨宿主保持一致，以及其确定性边界在哪里。

3. 第三篇：建立工程可靠性------从行为约束到系统边界

本篇按照"形成约束 → 测试约束 → 迁移约束 → 界定约束"的顺序展开：先解释自然语言 Skill 如何形成行为约束，再说明这些约束如何被评测、迁移与校正，最后交代它们的真实边界。

3.1 自然语言 Skill 如何产生行为约束

3.1.1 规则必须变成可观察动作

"保证质量"无法核验；下面的动作序列可以：

text 复制代码

写失败测试 → 运行并观察失败 → 写最小实现
→ 运行并观察通过 → 生成 diff → 独立评审 → 修复后复审

强 Skill 的共同点，是把价值观转换成有顺序、有证据、可判断是否遗漏的动作。

3.1.2 禁止规则只适合纪律逃逸

writing-skills 提出一个重要区分：指导形式必须匹配失败类型。

基线失败	合适形式
Agent 明知规则却在压力下跳过	禁止事项、Red Flags、合理化反驳
输出形状错误或冗长	正向 recipe / output contract
固定字段遗漏	结构化模板中的 REQUIRED slot
行为依赖条件	基于可观察 predicate 的条件规则

对输出形状问题堆叠"不要做 X"可能适得其反，因为模型会继续与禁止规则协商；直接定义输出由哪些部分按何顺序组成，更容易稳定收敛。

3.1.3 Evidence over claims

verification-before-completion 要求在声称完成前：识别能证明结论的命令、立即运行、读取完整输出和退出码，然后只陈述输出支持的事实。

text 复制代码

"应该已经通过"
        ↓
"刚执行了 X，退出码为 0，N 项测试通过"

这是一套声明协议：没有新鲜证据，就没有完成声明。

把价值观改写成动作、模板、门禁和证据，可以提高单次执行的稳定性；但 Skill 文案本身也可能存在遗漏、歧义和可被合理化绕过的漏洞。因此，下一步不是继续加强语气，而是把 Skill 当作行为代码，通过 TDD 和评测持续验证。

3.2 Skill 如何通过 TDD 和评测持续改进

writing-skills 把 Skill 开发映射为 TDD：

软件 TDD	Skill 开发
测试用例	新鲜上下文中的行为场景
生产代码	`SKILL.md`
RED	无 Skill 时出现目标失败
GREEN	加载 Skill 后行为符合要求
REFACTOR	堵住漏洞、精简文案并保持通过

3.2.1 先建立无指导基线

如果 control group 本来就不出现目标失败，就没有证据说明需要新增指导。Skill 作者必须先观察 Agent 在没有 Skill 时怎样失败，并记录其原始合理化语言。

3.2.2 不同 Skill 类型使用不同测试

**纪律型：**叠加时间、沉没成本、权威和疲劳压力，观察是否违规；
**技术型：**让 Agent 在新问题和边界条件中实际应用方法；
**模式型：**测试能否识别适用与不适用场景；
**参考型：**测试能否检索并正确使用具体信息。

知识问答只证明"会背"，不能证明"会在压力下执行"。

3.2.3 完整场景前先做 wording micro-test

完整场景测试前，应先低成本比较措辞：

每次使用全新上下文；
始终包含 no-guidance control；
每个变体至少运行 5 次；
人工阅读每个命中，排除模板回显等假阳性；
把结果方差当成指标------五次产生五种理解，说明文案仍不具约束力。

Micro-test 验证措辞，完整压力场景验证实际纪律，两者不能互相替代。

3.2.4 官方评测边界

插件基础设施测试位于 tests/；Skill 行为测试使用独立的 superpowers-evals drill 框架。贡献指南不鼓励随意增加新 Skill，且 Skill 修改必须在所有支持宿主上可工作。

这说明 Skill 文案被视为需要跨模型、跨宿主回归验证的行为代码，而不是普通说明文档。

评测证明的是一套 Skill 在给定场景和模型中的行为表现。要让同一套方法论进入 Claude Code、Cursor、Codex、OpenCode 等宿主，还需要把稳定的动作语义与不断变化的平台 API 分离，避免每增加一个宿主就复制并分叉全部 Skill。

3.3 跨平台适配如何共享语义、隔离差异

3.3.1 为什么 Skill 不绑定工具名

核心 Skill 使用"派发子代理""创建 todo""读取文件""调用技能"等动作。宿主适配层再映射到本地能力。

例如 Codex 的参考文件只保留真正需要特别说明的差异：启用 multi-agent 后使用 spawn_agent、wait_agent、close_agent；worktree Skill 先用只读 Git 命令检测 Codex App 的隔离和 detached HEAD 状态。

v6.1.0 已删除多个没有宿主特异信息的冗长工具映射。原因是现代 Agent 能直接理解通用动作，没有必要长期支付重复映射的 token 成本。

3.3.2 为什么角色随 Skill 分发

requesting-code-review/code-reviewer.md、subagent-driven-development/implementer-prompt.md 和 task-reviewer-prompt.md 都是自包含模板。Controller 将具体任务、文件路径和约束填入模板，再派发通用子代理。

这样无需宿主预注册名为 superpowers:code-reviewer 的全局 Agent；角色定义和 Skill 一起版本化、测试和分发。

3.3.3 能力缺失时如何降级

完整体验需要文件操作、Shell、技能加载、任务跟踪和子代理。若宿主缺少可选能力：

无子代理工具：改为当前会话执行，或明确报告能力缺失；
无任务列表工具：使用计划文件或 repo-local TODO.md；
无独立 Skill 工具但有原生技能发现：按宿主约定读取 SKILL.md；
worktree 被 sandbox 拒绝：报告后在当前目录工作。

原则是显式降级，绝不虚构不存在的工具。

共享动作语义、隔离宿主差异，使同一套 Skill 可以跨平台迁移；显式降级则保证能力不足时系统不会伪装成功。但跨平台可运行仍不等于每一步都能被代码强制保证。第三篇的核心结论是：Superpowers 的可靠性不来自自然语言本身，而来自外围工程机制------测试、评测、状态持久化、角色分离与多层护栏。

最后需要划清硬事实与软决策的边界，并观察多层护栏如何对冲模型的不确定性。

3.4 可靠性边界：硬事实、软决策与多层护栏

3.4.1 可由代码和工具确认的事实

插件 manifest 注册了哪些 skills 和 hooks；
bootstrap 是否被插入消息；
去重 marker 是否存在；
测试退出码和输出；
Git 分支、worktree、commit 与 diff；
brief、report、review package 和 progress ledger 的内容。

3.4.2 仍依赖模型的决策

当前场景是否匹配某个 description；
规格是否完整、架构是否合理；
是否准确执行自然语言步骤；
Reviewer 是否发现所有实质问题；
测试集合是否真的覆盖用户需求。

3.4.3 多层对冲

风险	对冲机制
任务前忘记检查 Skill	`using-superpowers`、宿主 bootstrap 或原生触发
压缩后遗忘	Claude/Pi 等在 compact 后恢复，SDD 使用 ledger
模型合理化跳步	1% 规则、Red Flags、硬门和 checklist
子代理上下文污染	每任务新子代理、task brief 文件
大量 diff 占满主上下文	review package 文件交接
实现偏离规格	一个 Task Reviewer 给出两个独立 verdict
修复后未确认	Review loop 与覆盖测试证据
重复执行已完成任务	`.superpowers/sdd/progress.md` + `git log`
误建或误删 worktree	先检测、优先原生、创建需同意、按 provenance 清理
声称完成却无证据	`verification-before-completion`

可靠性来自这些机制叠加，而不是某一段强硬文案单独保证。

第三篇由此给出了完整的可靠性链路：可观察动作让自然语言规则形成约束，TDD 与评测持续检验约束，跨平台分层让约束可迁移，多层护栏则在硬事实和软决策之间控制风险。这些做法并不只适用于 Superpowers，还可以进一步抽象为通用的 Agent 工程原则。

4. 第四篇：回到 Agent 工程------可复用原则与核心结论

前三篇分别回答了 Superpowers 改变什么、依靠什么运行、为什么相对可靠。本篇先给结论：Superpowers 最有价值的地方，不只是仓库里那 14 个 Skill，而是它沉淀出了一套可迁移的 Agent 工程原则。

下面将跳出具体仓库，把这些实现选择收束为其他 Agent 系统也可以复用的设计原则，并在结语中回扣全文。

4.1 可以抽象出的七条 Agent 工程原则

4.1.1 原则一：方法论与宿主适配必须分层

skills/ 保存稳定动作语义，宿主插件只负责发现、注入和少量工具翻译。这样平台变化不会迫使全部 Skill 分叉。

4.1.2 原则二：优先使用宿主原生能力

原生 Skill discovery、worktree 和生命周期事件通常比自建兼容层更可靠。Codex 删除多余 Hook、Worktree Skill 优先原生工具，都是这一原则的体现。

4.1.3 原则三：上下文也是需要管理的资源

缓存 bootstrap、删除冗余映射、使用 task brief 和 review package 文件、限制子代理上下文，都是在减少长期上下文驻留成本和注意力污染。

4.1.4 原则四：关键状态必须能跨压缩恢复

会话记忆不是持久化存储。重要进度应写入 ledger 和 Git，关键规则应在宿主生命周期允许时重新注入。

4.1.5 原则五：实现和复核必须解耦

实现者的自审不能代替独立评审。Reviewer 读取实际 brief、report 和 diff，并分别判断规格与质量。

4.1.6 原则六：指导形式要与失败类型匹配

纪律逃逸用禁令和 Red Flags；输出结构问题用正向契约；字段遗漏用模板；条件行为用明确 predicate。不是所有问题都适合"更强硬地说不要"。

4.1.7 原则七：用工具证明能机械确认的事实

模型负责语义和判断，测试、Git、文件和退出码负责事实。凡是可以运行命令确认的，不应只靠语言声明。

4.2 结语

回到开篇提出的问题：Superpowers 要解决的，不是模型是否"知道"软件工程方法，而是这些方法能否在真实任务中成为稳定、可复用、可验证的默认行为。全文从四个层次给出了答案。

**第一篇建立整体认知。**一个需求不再从自然语言直接跳到代码，而是沿设计、计划、隔离实现、TDD、评审、验证和交付逐步推进。14 个 Skill 覆盖这条开发生命周期，背后共同遵循系统化、TDD、降低复杂度和证据优先四条设计哲学。Superpowers 改变的首先不是 Agent 的知识上限，而是它处理任务的默认顺序。

**第二篇拆解运行机制。**系统由技能层、宿主适配层、模型编排层、证据与状态层共同组成：SKILL.md 用 description 提供触发索引、用正文定义执行协议；bootstrap 借助宿主原生机制注册技能并把总入口规则注入 Cursor；using-superpowers 负责在任务起点完成 Skill 检查与流程分流；各过程 Skill 再把任务推进为可检查的动作、文件和工具结果。它不是一个写死全部步骤的中央 DAG，而是一套由宿主、模型、Skill 和工具共同执行的分层协议。

**第三篇建立工程可靠性。**自然语言本身并不确定，可靠性来自外围工程机制：把原则改写成可观察动作和门禁，用 TDD 与压力评测检验 Skill 文案，通过平台无关的动作语义跨宿主复用，再用测试、Git、评审包、进度 ledger 和完成前验证对冲模型的不确定性。代码和工具可以确认事实，模型仍负责语义判断；多层护栏可以降低风险，但不能把概率系统伪装成确定性程序。

**第四篇回到 Agent 工程。**从 Superpowers 可以抽象出一组更普遍的原则：方法论与宿主适配分层，优先利用宿主原生能力，把上下文视为受限资源，把关键状态持久化，让实现与复核解耦，使指导形式匹配失败类型，并用工具证明一切可以机械确认的事实。这些原则适用于任何希望把"模型能力"转化为"稳定工程行为"的 Agent 系统。

因此，Superpowers 的完整实现脉络可以浓缩为：

text 复制代码

整体认知：开发流程 + 技能体系 + 设计哲学
    ↓
运行机制：四层架构 + Skill 加载 + bootstrap + Skill 检查与流程分流 + 主工作流
    ↓
工程可靠性：行为约束 + TDD 与评测 + 跨平台适配 + 多层护栏
    ↓
Agent 工程原则：分层、原生能力、上下文管理、状态恢复、独立复核与外部证据

Superpowers 不维护自建的统一技能加载核心，而是利用宿主原生能力发现技能、注入 bootstrap 和执行工具。它共享的是 skills/ 中的平台无关动作语义与工程纪律，隔离的是插件 API、生命周期事件和工具名称等宿主差异。

Superpowers 的核心创新，不是用一段更强硬的 Prompt 命令 Agent 守纪律，而是把工程方法做成可发现、可组合、可测试、可恢复、可验证，并能被多种宿主原生执行的行为协议。

4.3 参考资料

README：github.com/obra/superp...
Release Notes：github.com/obra/superp...
using-superpowers：github.com/obra/superp...
brainstorming：github.com/obra/superp...
writing-plans：github.com/obra/superp...
test-driven-development：github.com/obra/superp...
subagent-driven-development：github.com/obra/superp...
using-git-worktrees：github.com/obra/superp...
SessionStart Hook：github.com/obra/superp...
Cursor 插件清单：github.com/obra/superp...
OpenCode 插件：github.com/obra/superp...
新宿主移植指南：github.com/obra/superp...

Superpowers 实现原理深度解析：如何把工程纪律变成 Agent 的默认行为