Superpowers 架构原理、源码剖析与工程实践

1. Superpowers 是什么

Superpowers 是一套面向 Coding Agent 的软件研发方法论和可执行技能框架。它通过“会话启动时注入总控规则 + 按场景加载技能 + 工具映射 + 辅助脚本 + 行为评测”，把需求澄清、设计、计划、TDD、调试、子代理协作、代码审查和分支收尾串成一条有约束的研发流水线。

它不是：

• • 一个新的大模型；
• • 一个独立 IDE；
• • 一个只包含提示词模板的仓库；
• • 一个替代 Git、测试框架或 CI 的构建系统；
• • 一个能保证模型永不犯错的形式化验证系统。

它解决的是 Coding Agent 常见的流程失控问题：

• • 没弄清需求就开始写代码；
• • 用猜测代替根因分析；
• • 先实现、后补测试；
• • 长任务压缩上下文后重复执行；
• • 子代理拿到过多无关上下文；
• • 只相信代理的“已完成”报告，不检查代码和测试；
• • 实现结束后没有明确的合并、PR、保留或清理路径。

可以把它理解为：

Superpowers= 行为协议（Skills）+ 会话引导（Bootstrap）+ 宿主适配（Harness Adapter）+ 状态与交接文件（Ledger / Brief / Report）+ 自动化脚本（Shell / JS / Python）+ 基础设施测试与行为评测（Tests / Evals）

其核心价值不是让模型“知道更多语法”，而是让模型在正确时间采用正确的工程过程。

2. 为什么 Coding Agent 需要方法论层

传统 IDE 工具通常是确定性的：格式化器输入固定，输出也固定。Coding Agent 则是概率系统。同一个请求在不同上下文、模型或轮次中，可能产生不同的计划和实现。

仅靠一句“请认真编码”无法稳定约束以下行为：

1. 1. 是否先理解需求；
2. 2. 是否真正查看现有代码；
3. 3. 是否选择了最小设计；
4. 4. 是否先观察测试失败；
5. 5. 是否查到根因后再修改；
6. 6. 是否在完成声明前运行了完整验证；
7. 7. 是否能在上下文压缩后恢复进度。

Superpowers 将这些行为写成可发现、可加载、可组合、可测试的技能。它本质上位于模型和工具之间：

flowchart LR     U[研发人员] --> H[Coding Agent Harness]     H --> B[Superpowers Bootstrap]     B --> D[技能发现与触发]     D --> S[具体 SKILL.md]     S --> M[大模型决策]     M --> T[文件 Git Shell 测试 子代理]     T --> E[代码与证据]     E --> M     M --> U

这里的 Harness 指承载模型、会话、工具和插件生命周期的宿主，例如 Claude Code、Codex、Cursor、OpenCode、Gemini CLI、Kimi Code、Pi 或 Hermes Agent。

3. 设计哲学

3.1 系统化优于临场发挥

遇到缺陷时，不直接尝试“看起来可能有效”的修改，而是依次完成复现、证据采集、模式比较、单一假设、最小实验和根因修复。

3.2 证据优于声明

“应该好了”“看起来没问题”都不是完成证据。测试通过需要本轮新鲜的测试输出，构建成功需要构建命令退出码为 0，需求完成需要逐项对照需求。

3.3 测试先于生产代码

框架把 RED-GREEN-REFACTOR 作为默认纪律：先写一个因缺少目标行为而失败的测试，确认失败原因，再写最小实现，最后在保持绿色的前提下重构。

3.4 降低复杂度

设计和计划强调 YAGNI、职责清晰、接口明确和可独立测试。计划记录实现者无法自行推断的决策，而不是提前把所有生产代码写进计划。

3.5 人类批准关键边界

框架不等于完全无人值守。设计、计划、破坏性操作、安全敏感操作、推送共享分支和发布等边界仍需要人类明确决策。

3.6 技能是行为代码

SKILL.md 虽然是 Markdown，但它改变 Agent 的决策路径，因此应像生产代码一样进行基线测试、修改、复测和回归评测。

4. 总体架构

Superpowers v6.4.2 可以分为六层。

典型调用链如下：

sequenceDiagram     participant Host as Harness     participant Adapter as 平台适配器     participant Boot as using-superpowers     participant Model as Coding Agent     participant Skill as 场景技能     participant Tool as 工具/子代理      Host->>Adapter: SessionStart / first LLM call     Adapter->>Boot: 读取 SKILL.md     Adapter->>Model: 注入 Bootstrap 与工具映射     Model->>Model: 判断是否存在适用技能     Model->>Skill: 按需加载完整技能     Skill->>Model: 提供流程、门禁与检查表     Model->>Tool: 浏览、编辑、测试或派发任务     Tool-->>Model: 返回代码、日志和证据     Model-->>Host: 汇报结果或请求关键批准

最关键的架构结论是：仅把 skills/ 复制到某个目录并不一定构成完整集成。真正的集成还要保证首轮会话自动加载 Bootstrap，使 Agent 在行动前主动检查技能。

5. 源码目录解析

superpowers/├── skills/                         # 15 个内置技能│   ├── using-superpowers/│   ├── brainstorming/│   ├── writing-plans/│   ├── executing-plans/│   ├── subagent-driven-development/│   ├── dispatching-parallel-agents/│   ├── test-driven-development/│   ├── systematic-debugging/│   ├── requesting-code-review/│   ├── receiving-code-review/│   ├── verification-before-completion/│   ├── using-git-worktrees/│   ├── finishing-a-development-branch/│   ├── writing-skills/│   └── diagnosing-superpowers/├── hooks/                          # 通用 SessionStart Hook├── .claude-plugin/                 # Claude Code 插件清单├── .codex-plugin/                  # Codex 插件清单├── .cursor-plugin/                 # Cursor 插件清单├── .kimi-plugin/                   # Kimi Code 清单及工具映射├── .muse-plugin/                   # Muse 原生插件定义├── .hermes-plugin/                 # Hermes Python 适配器├── .opencode/                      # OpenCode V1/V2 插件├── .pi/                            # Pi TypeScript 扩展├── docs/                           # 安装、移植、设计与实现记录├── scripts/                        # 打包、同步、版本管理、Shell 检查├── tests/                          # 各宿主的基础设施测试├── package.json                    # npm/Pi 元数据，版本 6.4.2├── gemini-extension.json           # Gemini CLI 扩展元数据├── README.md├── RELEASE-NOTES.md└── AGENTS.md                       # 项目贡献规则

每个技能至少包含一个 SKILL.md，常见结构为：

---name:systematic-debuggingdescription:Usewhenencounteringanybug,testfailure,orunexpectedbehavior,beforeproposingfixes---

Frontmatter 中：

• • name 是稳定技能标识；
• • description 主要用于发现和触发；
• • 正文才是完整执行协议；
• • 较长参考资料、脚本、提示模板可以放在同一技能目录下。

6. Bootstrap：让技能从“可用”变成“会被使用”

6.1 using-superpowers 的作用

using-superpowers 是总控技能。它要求 Agent 在任何回复或行动前先判断是否存在适用技能；即使只有很小概率适用，也应先加载技能确认，而不是凭记忆执行。

它还定义了技能优先级：流程技能先于实现技能。例如：

“实现一个新功能”  -> brainstorming  -> writing-plans  -> TDD / 执行技能“修复这个测试失败”  -> systematic-debugging  -> test-driven-development  -> verification-before-completion

这样可以避免模型一看见 React、数据库或 API 关键词，就直接跳到具体编码技术，而忽略需求和问题性质。

6.2 Claude Code、Cursor、Muse 等 Hook 路径

hooks/session-start 的主要逻辑是：

1. 1. 根据脚本位置计算插件根目录；
2. 2. 读取 skills/using-superpowers/SKILL.md；
3. 3. 对反斜线、引号、换行、回车和制表符做 JSON 转义；
4. 4. 包装为 <EXTREMELY_IMPORTANT> 上下文；
5. 5. 按宿主输出不同 JSON 字段。

平台输出差异包括：

hooks.json 将 Hook 绑定到 startup|clear|compact，意味着新会话、清空上下文以及压缩上下文后都可重新注入总控规则。

6.3 OpenCode 路径

.opencode/plugins/superpowers.js 同时适配 OpenCode V1 和 V2：

• • V1 通过配置 Hook 注册技能，并在消息转换阶段注入 Bootstrap；
• • V2 通过原生 Skill API 添加技能，通过会话上下文 Hook 注入 Bootstrap；
• • 插件跳过子会话，避免向委派出的工作代理重复注入控制器协议；
• • Bootstrap 按宿主版本缓存，减少每轮重复文件读取和解析；
• • 代码自行解析简单 YAML Frontmatter，维持零外部依赖。

OpenCode V1 与 V2 工具名不同，因此源码分别提供工具映射。例如 V1 的 bash、apply_patch、task，对应 V2 的 shell、patch、subagent。

6.4 Pi 路径

.pi/extensions/superpowers.ts：

• • 在 resources_discover 阶段暴露技能目录；
• • 在 session_start 和 session_compact 后标记需要注入；
• • 在 context 事件中把 Bootstrap 插入首个非压缩摘要消息之前；
• • 检查标记，防止重复注入；
• • 在 agent_end 后关闭本轮注入；
• • 明确说明 Pi 默认没有标准子代理和任务列表工具，不能虚构工具调用。

6.5 Hermes 路径

.hermes-plugin/__init__.py：

• • 兼容 Git Clone 和扁平复制两种安装布局；
• • 找不到 skills/using-superpowers/SKILL.md 时显式抛错，而非静默失效；
• • 遍历并注册全部技能；
• • 在第一次 pre_llm_call 中返回 Bootstrap 上下文；
• • 支持 skill_view("superpowers:skill-name")，失败时建议直接读取文件。

Hermes 缺少压缩后 Hook，因此超长会话压缩掉首轮上下文后，技能可能停止自动触发；官方 README 建议遇到此情况启动新会话。

6.6 自动触发为何重要

如果没有 Bootstrap，技能只是磁盘上的文档。模型未必知道何时加载，也可能在加载前已经修改代码。Superpowers 的验收思路是：在干净会话中发送“让我们做一个 React Todo List”，正常集成应在写代码前自动进入 brainstorming。

7. 技能发现、加载与组合

7.1 发现机制

宿主通常读取技能的 name 和 description，让模型根据当前任务判断是否加载。Superpowers 把 description 视为“触发条件”，而不是正文摘要。

错误写法：

description:用TDD开发，先写测试，再写实现，然后重构

这种描述可能让模型只执行摘要而跳过正文。

更好的写法：

description:Usewhenimplementinganyfeatureorbugfix,beforewritingimplementationcode

它只说明何时使用，迫使 Agent 读取正文来获得完整流程。

7.2 技能组合不是固定状态机

技能通过触发条件、前置技能和终止状态形成松耦合工作流。常见路径为：

flowchart TD     A[用户需求] --> B{任务性质}     B -->|新功能/行为变化| C[brainstorming]     B -->|缺陷/异常| D[systematic-debugging]     C --> E[设计批准]     E --> F[writing-plans]     F --> G{执行方式}     G --> H[subagent-driven-development]     G --> I[executing-plans]     H --> J[test-driven-development]     I --> J     D --> J     J --> K[requesting-code-review]     K --> L[verification-before-completion]     L --> M[finishing-a-development-branch]

实际路径由任务规模、宿主能力和用户选择共同决定。例如小型既有代码修改可在短设计获批后直接 TDD，不需要生成完整计划文件。

7.3 优先级与冲突

优先级通常是：

用户直接要求 / 仓库 AGENTS.md 等项目规则    > 已加载技能    > Agent 默认习惯

技能之间冲突时，应优先采用决定“如何工作”的流程技能，再应用领域技能。若计划与规格冲突，SDD 以规格为约束依据，并把裁决写入账本。

8. 15 个内置技能全景

9. Brainstorming：从想法到经批准的设计

9.1 三类任务

v6.4.2 将工作分为三条路径：

分类标准不是“Agent 熟不熟悉”，而是仓库里是否已有明确流程、改动是否影响系统边界。发现隐藏复杂度时只能升级流程，不能为节省步骤而降级。

9.2 共享理解

在设计前需要确认：

• • 要解决的真实问题；
• • 谁会使用；
• • 成功标准；
• • 范围和约束；
• • 哪些是用户明确要求，哪些是 Agent 假设。

需求已经充分时，不应机械重复提问，而应复述理解并邀请纠正。

9.3 架构型任务流程

1. 1. 阅读项目文件、文档和最近提交；
2. 2. 一次问一个关键问题；
3. 3. 提出 2～3 种方案和取舍；
4. 4. 给出推荐方案并解释理由；
5. 5. 分节展示架构、组件、数据流、错误处理和测试；
6. 6. 获得设计批准后写入 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md；
7. 7. 自检占位符、矛盾、范围和歧义；
8. 8. 请用户审阅真实文件；
9. 9. 获批后才进入 writing-plans。

“我同意这个想法”不等于批准尚未生成的规格；“规格没问题”也不等于批准尚未生成的计划。这种分阶段批准防止 Agent 把模糊同意扩大解释为实施授权。

9.4 Visual Companion

Brainstorming 带有一个可选的浏览器视觉辅助工具，用于线框图、布局比较和架构图。它是按问题选择的工具，不是强制模式。

源码中的服务强调：

• • 仅在视觉表达明显优于文字时提出；
• • 用户同意后才打开浏览器；
• • 文本需求和概念选择仍通过普通对话；
• • 默认从远程加载 Prime Radiant 标识会携带版本信息；
• • 可用 SUPERPOWERS_DISABLE_TELEMETRY、DISABLE_TELEMETRY 或 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 关闭相关遥测。

10. Writing Plans：把设计转成可执行契约

10.1 计划的角色

计划面向“具备编码能力但不了解本项目决策”的执行者。它应记录：

• • 精确文件路径；
• • 接口名、参数和返回类型；
• • 来自规格的固定值；
• • 测试名称和关键断言；
• • 验证命令及成功标准；
• • 前后任务之间的接口依赖。

计划不应大段提前实现所有函数。v6.4.2 特别强化了“计划记录决策，不是代码转录稿”，并增加比例自检。

10.2 标准头部

计划通常保存到：

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

关键字段包括：

# Feature Implementation Plan**Goal:** 一句话目标**Architecture:** 2～3 句架构说明**Tech Stack:** 关键技术**Spec:** 对应设计规格路径## Global Constraints项目级版本、依赖、平台和命名约束## Review Focus规格暗示但现有任务测试尚未覆盖的高风险输入或失败模式

10.3 任务粒度

每个任务应形成可独立测试和审查的交付物。一个步骤只做一件有可检查结果的事：

写失败测试-> 运行并确认因目标行为缺失而失败-> 写最小实现-> 运行目标测试-> 运行项目测试套件-> 提交

Interfaces 区块说明本任务消费和生产什么，让后续执行者无需读取整份历史。

10.4 计划自检

完成计划后检查：

1. 1. 规格每项要求是否有归属任务；
2. 2. 每一步是否只产生一个合理动作；
3. 3. 跨任务类型、方法名和字段名是否一致；
4. 4. Review Focus 的风险是否落实为测试；
5. 5. 计划是否明显长于规格，代码块是否喧宾夺主。

随后由用户审阅计划，并在两种执行方式之间选择：

• • Subagent-driven：每任务新实现代理、每任务审查、最后全局审查；
• • Native：当前会话自行完成所有任务，最后只做一次独立全局审查。

11. TDD：行为验证的核心循环

11.1 铁律

没有先失败的测试，就不写生产代码。

完整循环是：

flowchart LR     R[RED 写最小失败测试] --> RF{确认按预期失败?}     RF -->|否| R     RF -->|是| G[GREEN 写最小实现]     G --> GF{目标测试与全套测试通过?}     GF -->|否| G     GF -->|是| X[REFACTOR 清理结构]     X --> GF     GF --> N[下一个行为]

11.2 为什么必须观察 RED

如果测试第一次运行就通过，可能意味着：

• • 测试覆盖的是已有行为；
• • 断言没有真正命中目标；
• • Mock 验证了 Mock 自己；
• • 测试未被发现或根本没有执行。

因此 RED 阶段不仅要“看到红色”，还要确认失败信息与缺失行为一致，而不是语法错误、路径错误或测试环境错误。

11.3 项目全套测试

目标测试通过只证明局部行为。v6.4.2 要求在任务完成前运行项目级测试命令，例如：

npm testpytestcargo testgo test ./...mvn test

任何失败都应在报告中按名称列出，包括并非本次变更引入的基线失败，不能选择性省略。

11.4 合理例外

丢弃型原型、生成代码和纯配置可能不适合严格 TDD，但技能要求先征得人类同意，不能由 Agent 自行把当前任务标记为例外。

12. Systematic Debugging：先证明根因，再修复

12.1 四阶段模型

12.2 多组件系统的证据链

对于 CI → 构建 → 签名，或 API → 服务 → 数据库之类的链路，应在每个边界记录输入、输出、环境和状态：

请求进入网关时是否完整？-> 服务收到的 Header 是否一致？-> DAO 实际绑定了什么参数？-> 数据库返回了什么？

先用一次观测定位故障层，再深挖该层。否则在所有层同时修改会破坏因果判断。

12.3 三次失败规则

若三个修复尝试都失败，问题可能不是某个局部条件，而是共享状态、边界或抽象本身错误。此时停止尝试第四个补丁，回到架构层与用户讨论。

12.4 配套技术

• • root-cause-tracing.md：从深层错误沿调用链反向追踪坏值来源；
• • defense-in-depth.md：确定根因后，在多个边界增加合理防御；
• • condition-based-waiting.md：用条件轮询代替随意 sleep；
• • find-polluter.sh：定位污染测试状态的用例。

13. 隔离开发：Git Worktree

using-git-worktrees 在执行计划前建立隔离环境，避免污染用户当前工作区。

流程包括：

1. 1. 判断当前是否已经处于隔离工作区；
2. 2. 优先使用宿主原生 Worktree 能力；
3. 3. 否则回退到 git worktree；
4. 4. 根据项目类型安装或准备依赖；
5. 5. 运行测试，确认基线干净；
6. 6. 报告工作区路径和基线状态。

隔离的价值不仅是 Git 分支分离，还包括：

• • 可以安全运行计划；
• • 便于比较任务前后的提交范围；
• • 子代理共享同一目标目录但不会改到主工作区；
• • 完成时能明确清理。

若测试基线已失败，应先报告既有失败，避免把它错误归因于新改动。

14. 两种计划执行引擎

14.1 Native：executing-plans

Native 模式由当前会话亲自完成所有任务。其优点是成本低、上下文切换少；缺点是每个任务没有独立审查者，直到最后才获得新鲜视角。

基本过程：

1. 1. 建立或确认隔离工作区；
2. 2. 为计划建立专属 SDD 工作目录；
3. 3. 读取规格和计划，做冲突预检；
4. 4. 按任务执行 TDD；
5. 5. 使用脚本记录任务开始、测试日志和完成提交；
6. 6. 全部任务结束后派发一次全分支审查；
7. 7. 处理审查问题；
8. 8. 进入分支收尾流程。

适合任务依赖紧密、预算有限、计划质量较高，或者宿主没有子代理能力的场景。

14.2 SDD：subagent-driven-development

SDD 模式的核心不是简单“多开几个 Agent”，而是通过隔离上下文和审查门禁管理长任务。

flowchart TD     A[读取规格和计划] --> B[创建计划专属账本]     B --> C[计划冲突预检]     C --> D[生成当前任务 Brief]     D --> E[派发新实现代理]     E --> F[实现 测试 提交 自检]     F --> G[生成 BASE..HEAD Review Package]     G --> H[独立任务审查]     H --> I{规格与质量均通过?}     I -->|否| J[修复与定向复审循环]     J --> I     I -->|是| K[账本标记任务完成]     K --> L{还有任务?}     L -->|是| D     L -->|否| M[全分支审查]     M --> N[清理计划工作区]     N --> O[分支收尾]

14.3 为什么每个任务使用新代理

• • 避免前序任务的猜测污染当前实现；
• • 控制每个代理看到的上下文规模；
• • 让任务 Brief 成为唯一需求来源；
• • 便于针对任务复杂度选择模型；
• • 审查者不会因为参与实现而产生确认偏差。

实现代理不应再派发自己的子代理，否则会形成递归委派、重复审查和成本失控。

14.4 为什么不并行实现相邻任务

即使计划任务看似独立，它们通常共享工作树、Git 索引、接口或测试环境。SDD 明确要求实现任务串行派发。真正独立的问题调查才适合 dispatching-parallel-agents。

若多个任务只是不同文件中的同形微改，可合并成一次批量派发并作为一个审查单元。

15. SDD 的持久状态设计

15.1 计划专属工作区

每份计划通过：

bash scripts/sdd-workspace PLAN_FILE

解析到类似目录：

<repo-root>/.superpowers/sdd/<plan-identity>/

其中保存：

progress.md             # 控制器恢复进度的账本task-N-brief.md         # 发给实现代理的精确需求task-N-report.md        # 实现代理完整报告review-*.md             # 提交范围、统计与 diff

计划使用独立目录，避免两个同名或连续计划误读彼此状态。

15.2 Ledger 为什么重要

上下文压缩可能让控制器忘记已经完成哪些任务。仅使用会话内 Todo 不够可靠；progress.md 与 Git 提交共同构成恢复依据。

首行记录计划身份：

# SDD ledger — plan: docs/superpowers/plans/example.md

账本还应记录：

• • 预检表；
• • 任务开始与完成；
• • 提交哈希；
• • 测试命令和结果；
• • 修复轮次；
• • 计划冲突裁决；
• • 暂存但未阻断的审查意见。

发生压缩后，应相信账本与 git log，而不是模型模糊的对话记忆。

15.3 Brief、Report 与 Review Package

task-brief 从计划中提取单个任务，避免把整份计划和累计历史反复粘贴给子代理。

实现代理将详细说明写到 report 文件，只在消息里返回状态、提交、测试摘要和关注点。这降低控制器上下文持续膨胀。

review-package 使用预先记录的 BASE 和当前 HEAD 生成：

• • 提交列表；
• • Diff Stat；
• • 带上下文的完整 Diff。

不能随意用 HEAD~1 代替 BASE，因为一个任务可能有多个提交，会漏掉前面的改动。脚本还会拒绝空范围或 HEAD 不是 BASE 后代的范围，防止审查一个实际上没有内容的 Diff。

15.4 实现代理状态协议

“重试同一提示”通常不能解决阻塞，必须改变信息、能力或任务结构。

15.5 修复循环和熔断

任务审查必须同时给出规格符合性和代码质量结论。未通过时：

• • 第 1～3 轮优先恢复原实现代理；
• • 第 4～5 轮使用更强的新代理；
• • 每轮修复后只对相关差异做定向复审；
• • 第 5 轮仍未收敛则触发熔断，由控制器逐项裁决。

只有所有前进路径都依赖猜测、或涉及破坏性、安全敏感和外部副作用时才停下来询问用户。普通歧义由控制器依据规格裁决并写入账本，避免长任务无人值守时永久停滞。

16. 并行代理调度

dispatching-parallel-agents 适用于两个以上没有共享状态和顺序依赖的任务，例如三个不同测试模块分别失败，且根因彼此独立。

可并行：

Agent A：调查认证模块的 token 过期测试Agent B：调查报表模块的 SQL 排序错误Agent C：调查 CLI 的 Windows 路径测试

不应并行：

• • 多个代理同时修改同一文件；
• • B 依赖 A 新增的接口；
• • 原因尚未定位，多个失败可能来自同一根因；
• • 共享数据库或全局测试环境会互相污染。

高质量派发提示应包含：

1. 1. 单一、清晰的任务范围；
2. 2. 已知错误和复现方法；
3. 3. 允许修改与禁止修改的边界；
4. 4. 必须返回的证据；
5. 5. 不能满足时的报告方式。

并行结果返回后，控制器仍要检查重叠改动、整合冲突，并运行完整测试套件。

17. Code Review：独立验证而非礼仪

17.1 请求审查

requesting-code-review 用于完成任务、重要功能或合并前。审查者应获得明确需求和实际 Diff，而不是控制器整个对话历史。

任务级审查关注：

• • 是否完整满足本任务 Brief；
• • 是否违反规格或全局约束；
• • 测试是否验证真实行为；
• • 错误处理、边界条件和安全问题；
• • 是否引入不必要复杂度。

全分支审查则关注跨任务交互、总体架构、一致性和遗漏。

17.2 接收审查

receiving-code-review 反对表演式同意。收到建议后应：

1. 1. 阅读完整意见；
2. 2. 在代码库中验证意见是否成立；
3. 3. 不清楚时先澄清；
4. 4. 技术上正确则实现并验证；
5. 5. 与项目现实冲突时给出证据并合理反驳。

审查意见不是命令，尤其是外部审查者可能不了解现有兼容性、范围或用户决策。但也不能因措辞不友好而忽略正确问题。

17.3 严重级别

虽然不同审查模板可能采用不同标签，实践中可统一为：

• • Critical：数据丢失、安全漏洞、核心需求缺失，必须阻断；
• • Important：真实行为错误或高风险设计缺陷，通常必须修复；
• • Minor：可维护性或局部表达问题，不应掩盖正确性结论。

对规格没有明确提及的输入，审查者仍应按合理用户预期判断，不能把“规格没写”当成程序崩溃的许可。

18. 完成验证与分支收尾

18.1 Verification Gate

verification-before-completion 的门函数是：

IDENTIFY：哪条命令能证明声明？RUN：现在运行完整命令。READ：阅读全部输出、退出码和失败数。VERIFY：输出是否真的支持声明？CLAIM：只有支持时才给出完成结论。

不同声明需要不同证据：

18.2 分支收尾

finishing-a-development-branch 在实现和测试都完成后：

1. 1. 再次运行测试；
2. 2. 确认当前工作区、分支和基线；
3. 3. 判断基准分支；
4. 4. 向用户提供合并、推送并建 PR、原样保留等选项；
5. 5. 执行用户选择；
6. 6. 在安全条件满足时清理 Worktree。

若工作树存在未提交或未跟踪文件，不能强制移除。应列明文件并请求决定，避免 git worktree remove --force 造成数据丢失。

19. diagnosing-superpowers：诊断框架本身

当用户发现技能没有触发、计划被忽略、重复工作、成本异常或代理行为难以理解时，该技能分析当前或历史会话。

诊断强调：

• • 先界定用户认为“哪里不对”；
• • 找到实际会话记录，而不是依赖回忆；
• • 以 path:line 形式引用证据；
• • 构建技能时间线、计划遵循情况、重复工作、冲突和成本分析；
• • 把事实、推断和未知项分开；
• • 导出前按脱敏策略清理 Token、路径、个人信息和项目秘密；
• • 提交 GitHub Issue 前必须让用户审阅。

这相当于 Superpowers 的可观测性和事故复盘层。它不能恢复宿主从未持久化的会话，也不能证明缺失日志中的事件。

20. 技能开发：对提示协议做 TDD

20.1 技能测试映射

先观察基线失败很重要。如果 Agent 在没有技能时已经稳定做对，就无法证明新技能是必要的，也无法知道哪段文字真正影响了行为。

20.2 推荐目录

skills/my-skill/├── SKILL.md                 # 必需，触发条件与主流程├── references.md            # 可选，大型参考资料├── scripts/                 # 可选，可重复执行的确定性工具└── templates/               # 可选，交接或报告模板

20.3 Skill Discovery Optimization

技能发现优化包括：

• • description 以 Use when... 描述症状或触发条件；
• • 名称用动作导向、可搜索的短语；
• • 覆盖用户可能使用的错误、症状和工具关键词；
• • 高频加载技能保持精简；
• • 大段参考内容拆到独立文件；
• • 不在 description 中泄露完整工作流；
• • 用明确红线和反合理化表处理纪律型规则。

20.4 什么不适合写成核心技能

• • 单项目约定，应写入项目说明；
• • 一次性解决方案；
• • 可以用格式化器、Schema 或 CI 确定性执行的机械规则；
• • 只对单一业务领域有用的流程；
• • 没有行为评测证据的措辞大改。

如果规则能由程序强制执行，优先自动化；技能更适合需要模型判断的部分。

21. 测试与评测体系

Superpowers 区分两类测试。

21.1 插件基础设施测试

仓库 tests/ 中包含：

• • Hook JSON 和 SessionStart 输出；
• • OpenCode V1/V2 技能注册、Bootstrap 缓存和子会话跳过；
• • Pi 扩展生命周期；
• • Hermes 注册和首轮注入；
• • Kimi、Codex、Devin、Antigravity 等清单；
• • SDD 工作区、任务 Brief、Review Package；
• • Brainstorming 可视化服务的认证、生命周期、WebSocket 和 Windows 行为；
• • Shell Lint、版本同步和辅助脚本。

这些测试验证“插件能加载和接线”，不等价于验证模型一定遵守技能。

21.2 Agent 行为评测

行为评测已迁移到独立的 superpowers-evals。其思路是驱动真实 Coding Agent CLI，在压力场景中观察：

• • 技能是否被正确触发；
• • Agent 是否试图绕过门禁；
• • 有无技能时结果是否显著不同；
• • 不同模型和宿主是否一致；
• • 修改是否引入行为回归；
• • 结果是否满足场景验收条件和确定性后检查。

因此，基础设施测试通过只说明“文档可见”，行为评测才说明“文档改变了决策”。

22. 多 Harness 适配策略

不同 Coding Agent 的差异主要集中在四类接口：

1. 1. 插件发现和安装格式；
2. 2. 会话启动、恢复和压缩 Hook；
3. 3. Skill 注册或按需读取方式；
4. 4. 文件、Shell、任务列表和子代理工具名。

Superpowers 不强求所有宿主提供同名工具，而是在 Bootstrap 或引用文件中提供语义映射。

移植到新 Harness 的最低验收要求：

• • 技能目录被宿主发现；
• • 首轮自动注入 using-superpowers；
• • 压缩或恢复后按需重新注入；
• • 子会话不会误拿控制器 Bootstrap；
• • 工具映射准确，不能要求不存在的工具；
• • 通过“React Todo List 自动触发 brainstorming”的端到端测试；
• • 有真实会话记录证明集成有效。

23. 安装与验证

以下命令基于 v6.4.2 README，平台命令可能随宿主版本变化，安装前应再次查看对应官方说明。

23.1 Claude Code

/plugin install superpowers@claude-plugins-official

也可先添加项目 Marketplace，再安装：

/plugin marketplace add obra/superpowers-marketplace/plugin install superpowers@superpowers-marketplace

23.2 Codex App / CLI

Codex App 在 Plugins 侧栏的 Coding 分类中安装；Codex CLI 使用：

/plugins

然后搜索 superpowers 并选择安装。

23.3 Cursor

/add-plugin superpowers

23.4 Gemini CLI

gemini extensions install https://github.com/obra/superpowersgemini extensions update superpowers

23.5 Kimi Code

在 /plugins Marketplace 中安装，或：

/plugins install https://github.com/obra/superpowers

23.6 OpenCode

OpenCode 使用自己的插件安装流程，应参考仓库 .opencode/INSTALL.md，不能假设安装了其他 Harness 的版本就会自动共享。

23.7 Pi

pi install git:github.com/obra/superpowers

23.8 Hermes Agent

hermes plugins install obra/superpowers --enable

23.9 验证安装

启动全新会话，输入一个明确的新项目请求，例如：

Let's make a react todo list

预期现象：Agent 在写代码或脚手架之前识别为架构型创造任务，并启动需求澄清或 brainstorming。如果直接生成代码，应依次检查：

1. 1. 插件是否安装在当前 Harness；
2. 2. 技能是否被发现；
3. 3. SessionStart/首轮 Hook 是否运行；
4. 4. Bootstrap 是否出现在会话上下文；
5. 5. 是否在旧会话中安装但未重启；
6. 6. 上下文压缩后宿主是否支持再次注入。

24. 一个完整使用案例

假设用户提出：“为订单服务增加可配置的支付重试策略。”

24.1 设计阶段

Agent 使用 brainstorming：

• • 明确重试是为应对网络失败还是业务拒绝；
• • 确认幂等键和重复扣款风险；
• • 确认退避算法、最大次数和可观测性；
• • 比较应用内重试、消息队列重试和工作流引擎方案；
• • 形成规格并由用户审阅。

24.2 计划阶段

writing-plans 可能拆为：

1. 1. 定义 RetryPolicy 值对象及验证；
2. 2. 在支付网关外增加可测试重试执行器；
3. 3. 接入幂等键；
4. 4. 添加配置解析；
5. 5. 添加指标、日志和集成测试。

每个任务声明输入输出接口，且 Review Focus 包含超时、不可重试错误、重复请求和配置越界等风险。

24.3 执行阶段

选择 SDD 后：

• • 控制器创建计划专属账本；
• • Task 1 Brief 交给新实现代理；
• • 实现代理先写无效次数配置的失败测试；
• • 观察 RED 后写最小值对象；
• • 运行项目全套测试并提交；
• • 控制器用 BASE…HEAD 生成审查包；
• • 独立审查者检查规格和代码质量；
• • 问题修复并复审后才进入 Task 2。

24.4 收尾阶段

全部任务后进行全分支审查，重新执行构建和测试，再让用户选择本地合并、推送 PR 或保留分支。任何“已完成”结论都附当前验证证据。

25. 安全边界与风险

25.1 Prompt Injection

技能、仓库文档、Issue 和网页内容都可能含有指令。应区分：

• • 用户和系统授予的权限；
• • 项目内可信操作规范；
• • 仅作为数据阅读的第三方文本。

技能不能扩大用户授权。即使计划写着“发布到生产”，如果用户没有授权外部发布，也必须停下确认。

25.2 Shell 与文件风险

• • 不使用未解析的宽泛变量做递归删除；
• • 不在主分支直接执行大规模变更；
• • 清理 Worktree 前检查未跟踪文件；
• • 评审脚本使用明确 BASE 和 HEAD；
• • 下载或运行第三方脚本前核对来源与内容；
• • 不把秘密写入任务 Brief、报告或会话诊断包。

25.3 子代理权限

子代理应遵循最小上下文和最小权限原则：

• • 只提供当前任务需要的路径和约束；
• • 明确禁止推送、发布和破坏性动作；
• • 实现代理不自行递归派发；
• • 控制器独立验证其 Diff 和测试；
• • 并行代理不能共享可冲突的写入目标。

25.4 遥测与隐私

可视化伴侣默认加载远程品牌资源时会携带版本信息。虽然项目说明不发送提示词或项目详情，安全敏感环境仍应关闭非必要网络流量，并在企业代理、离线构建和数据分级政策下进行审查。

25.5 供应链

安装插件等同于允许其技能和 Hook 影响 Agent 行为。企业使用时应：

• • 固定版本或提交哈希；
• • 审查清单、Hook 和脚本；
• • 建立内部镜像；
• • 对升级运行回归评测；
• • 监控安装目录和发布来源变化。

26. 工程最佳实践

26.1 团队落地

建议从一个低风险仓库试点：

1. 1. 选择有可靠测试套件的服务；
2. 2. 固定 Superpowers 和 Harness 版本；
3. 3. 记录无框架时的交付周期、返工和缺陷；
4. 4. 引入 Brainstorming、TDD、验证门禁；
5. 5. 再引入 Worktree 和 SDD；
6. 6. 收集成本、轮次、审查发现和回滚率；
7. 7. 根据数据决定哪些任务使用 Native，哪些使用 SDD。

26.2 选择 Native 还是 SDD

26.3 控制上下文成本

• • 把完整 Diff 写入文件，不粘贴到控制器对话；
• • 子代理只读当前 Brief，不读整份计划；
• • 报告写文件，消息只返回摘要；
• • 同形微任务批量派发；
• • 选择能以较少轮次完成任务的模型，而非只看单 Token 价格；
• • 使用账本恢复，不重新调查已经完成的任务。

26.4 计划质量

• • 规格定义“要实现什么”，计划定义“如何分解和验证”；
• • 接口名称、类型和固定值只定义一次；
• • 每项风险有归属测试；
• • 不写 TBD、“处理边界情况”等不可验证表述；
• • 不把计划写成整份代码；
• • 用户必须审阅实际计划文件，而不是只批准口头摘要。

26.5 证据管理

每个任务至少保留：

• • RED 失败原因；
• • GREEN 测试结果；
• • 项目全套测试结果；
• • 提交范围；
• • 审查结论；
• • 未解决问题及其裁决。

这套证据既服务当前交付，也服务上下文恢复和事后诊断。

27. 常见问题与解决方案

27.1 技能已安装但不自动触发

可能原因：只有技能文件，没有启动 Bootstrap；插件装在另一个 Harness；当前会话未重启；压缩后没有重注入。

处理：检查清单和 Hook，开新会话执行 React Todo 验收用例，确认首轮上下文含 using-superpowers。

27.2 Agent 对简单请求也执行很重的流程

可能原因：任务分类错误，或旧版本只使用单一路径。

处理：按 v6.4.2 的 Spike、Bounded、Architectural 分类；既有代码中的小改动使用短设计，但仍保留批准门禁。

27.3 Agent 一直提问，不开始执行

检查是否缺少某一阶段的明确批准，或者计划严重不完整。对普通实施歧义，执行控制器应做可逆裁决并记录；只有破坏性、安全敏感、外部副作用或所有路径都靠猜测时才应停下。

27.4 TDD 测试一开始就通过

说明测试没有证明新行为。检查测试是否真正运行、是否命中了生产入口、目标行为是否已存在、Mock 是否遮蔽了真实代码。修正测试直到它因预期原因失败。

27.5 单测通过但项目仍不能构建

单测、Lint 和构建证明的是不同属性。运行仓库定义的完整测试和构建命令，不能从一个命令外推另一个结论。

27.6 子代理重复做已经完成的任务

通常是上下文压缩后只依赖会话记忆。检查计划专属 progress.md 与 git log，恢复到第一个没有完成标记的任务。

27.7 Review Package 为空

检查 BASE 是否记录在实现前、HEAD 是否为其后代、代理是否提交到了正确分支。不要改用 HEAD~1 掩盖问题。

27.8 多个代理互相覆盖代码

实现任务不应并行写同一工作树。停止并行，实现任务改为串行；只将真正独立的调查交给并行代理。

27.9 修复循环迟迟不收敛

前三轮补充上下文并恢复原代理，后两轮升级模型；五轮后逐项裁决。若连续三次根因修复尝试失败，应重新审视架构，而不是继续打补丁。

27.10 Worktree 无法删除

先查看未提交和未跟踪文件。不要强制删除；让用户决定提交、移动、保留还是明确丢弃。

27.11 诊断包可能泄露秘密

导出前执行脱敏审计，检查访问令牌、Cookie、密钥、内部 URL、用户名、绝对路径、客户数据和私有代码。用户审阅后才能上传。

27.12 技能规则与项目规范冲突

用户直接要求和项目级说明优先。记录冲突和采用的规则；不要静默混合两个不兼容流程。

28. 局限性

1. 1. 技能是自然语言协议，无法像类型系统一样绝对强制模型行为；
2. 2. 效果依赖模型指令遵循能力和 Harness 是否正确注入；
3. 3. SDD 会增加模型调用、审查次数和成本；
4. 4. 严格 TDD 不适合所有探索性任务，需要正确分类；
5. 5. 多 Harness API 变化可能让适配代码失效；
6. 6. 测试通过不能证明需求本身正确；
7. 7. 评审 Agent 也会误判，必须保留人类最终责任；
8. 8. Ledger 目录是 Git 忽略的临时状态，git clean -fdx 可能删除它；
9. 9. 某些 Harness 不支持压缩后 Hook、子代理或任务列表，能力会降级；
10. 10. 流程纪律能降低风险，但不能替代安全审计、性能测试和生产观测。

29. 与其他方案的区别

两者可以组合。例如团队可用 LangGraph 构建企业 Agent 控制平面，同时把 Superpowers 技能作为 Coding Worker 的行为协议。

30. 二次开发建议

30.1 增加企业专属技能

不要直接修改核心技能来塞入业务规则。更稳妥的方式是建立独立插件：

company-engineering-skills/├── skills/│   ├── deploying-to-company-k8s/│   │   ├── SKILL.md│   │   └── references/│   └── handling-company-incidents/│       └── SKILL.md├── hooks/└── plugin manifest

核心 Superpowers 负责通用研发过程，企业插件负责内部平台、合规和领域知识。

30.2 增加新 Harness

建议实现顺序：

1. 1. 研究宿主插件和生命周期接口；
2. 2. 注册 skills/；
3. 3. 实现首轮 Bootstrap；
4. 4. 处理清空、恢复和压缩；
5. 5. 避免对子代理重复注入；
6. 6. 编写准确工具映射；
7. 7. 添加清单和版本同步；
8. 8. 写基础设施测试；
9. 9. 跑端到端自动触发验收；
10. 10. 保存真实会话记录。

30.3 版本升级

升级前比较：

• • RELEASE-NOTES.md；
• • 技能触发描述；
• • Hook 输出格式；
• • 宿主工具映射；
• • SDD 辅助脚本参数；
• • 插件清单和最低宿主版本。

升级后至少重跑安装验收、关键业务场景和本地定制技能评测。

31. 源码阅读路线

推荐按以下顺序阅读，避免一开始陷入平台细节：

1. 1. README.md：项目定位和主流程；
2. 2. skills/using-superpowers/SKILL.md：总控触发协议；
3. 3. skills/brainstorming/SKILL.md：需求到设计；
4. 4. skills/writing-plans/SKILL.md：设计到任务；
5. 5. skills/test-driven-development/SKILL.md：实现纪律；
6. 6. skills/systematic-debugging/SKILL.md：缺陷处理；
7. 7. skills/subagent-driven-development/SKILL.md：长任务编排；
8. 8. SDD 的 scripts/ 和提示模板：状态及交接；
9. 9. skills/verification-before-completion/SKILL.md：完成证据；
10. 10. hooks/session-start：通用 Bootstrap；
11. 11. .opencode/plugins/superpowers.js、.pi/extensions/superpowers.ts、.hermes-plugin/__init__.py：平台实现差异；
12. 12. tests/：作者认为什么行为必须稳定；
13. 13. RELEASE-NOTES.md 与 docs/superpowers/specs/：设计演进和缺陷背景。

阅读技能时始终区分四种内容：触发条件、硬门禁、建议性启发、宿主适配说明。

32. 快速检查表

安装检查

• • [ ] 插件版本已固定并记录
• • [ ] Skills 能被宿主发现
• • [ ] 新会话自动注入 Bootstrap
• • [ ] 压缩或恢复路径经过验证
• • [ ] 工具映射符合当前宿主
• • [ ] 子会话不会误加载控制器协议

需求与计划

• • [ ] 已区分 Spike、Bounded、Architectural
• • [ ] 目的、用户、约束和成功标准明确
• • [ ] 架构型任务已有用户审阅的规格
• • [ ] 计划记录接口与测试，而非复制全部代码
• • [ ] Review Focus 已落到具体测试

执行

• • [ ] 主工作区被隔离
• • [ ] 先观察 RED，再编写实现
• • [ ] 每个任务有可恢复账本记录
• • [ ] 子代理只收到必要 Brief
• • [ ] Review Package 使用真实 BASE…HEAD
• • [ ] 任务级和全局审查没有混淆

完成

• • [ ] 运行了本轮新鲜的完整测试
• • [ ] 构建、Lint 和测试分别验证
• • [ ] 逐项核对需求
• • [ ] 未跟踪文件得到保护
• • [ ] 合并、推送、发布由用户授权
• • [ ] 最终报告区分已完成、已验证和遗留风险

33. 总结

Superpowers 的核心不是某一句神奇 Prompt，而是把 Coding Agent 的研发行为拆成可发现、可组合和可评测的协议：

先理解，再设计；先批准，再计划；先失败，再实现；先找根因，再修复；先审查和验证，再宣称完成；用文件和 Git 保存事实，不依赖模型记忆。

从架构上看，Bootstrap 解决“技能何时生效”，SKILL.md 解决“应该如何行动”，Harness Adapter 解决“不同宿主怎样执行”，Ledger/Brief/Report 解决“长任务怎样恢复和交接”，测试与评测解决“系统是否真的按预期工作”。

对于个人开发者，它是一套减少 Agent 返工和幻觉式完成声明的工作习惯；对于团队，它更接近可版本化、可审计的 AI 研发流程层。最有效的落地方式不是一次性启用所有复杂流程，而是在稳定测试和版本固定的前提下，从需求澄清、TDD 和完成验证开始，再逐步引入 Worktree、SDD 和企业自定义技能。

参考资料

1. 1. obra/superpowers 仓库：https://github.com/obra/superpowers
2. 2. v6.4.2 Release：https://github.com/obra/superpowers/releases/tag/v6.4.2
3. 3. 项目 README：https://github.com/obra/superpowers/blob/v6.4.2/README.md
4. 4. Release Notes：https://github.com/obra/superpowers/blob/v6.4.2/RELEASE-NOTES.md
5. 5. Skills 源码：https://github.com/obra/superpowers/tree/v6.4.2/skills
6. 6. SessionStart Hook：https://github.com/obra/superpowers/blob/v6.4.2/hooks/session-start
7. 7. 新 Harness 移植说明：https://github.com/obra/superpowers/blob/v6.4.2/docs/porting-to-a-new-harness.md
8. 8. 测试说明：https://github.com/obra/superpowers/blob/v6.4.2/docs/testing.md
9. 9. Agent Skills 规范：https://agentskills.io/specification