科技资讯

Superpowers 原理探析

72 15分钟阅读 2026-06-04

Superpowers 原理分析

Superpowers 是一个零依赖的 Agent 方法论框架，通过 Hook 系统在会话启动时注入行为约束，用 17 个 skill 将 Agent 的工作流从 "自由发挥" 压进 "可验证、可审计的流水线"。

核心哲学：Evidence Over Claims（先有证据，再说话）、TDD for Process（过程文档也要测试驱动）、Anti-Rationalization（主动防止 Agent 合理化逃避规则）。

1. 执行摘要

项目核心价值

一句话： Superpowers 是一套经过测试验证的 Agent 开发方法论——它通过 17 个 "skill" 将 Agent 的执行过程压入结构化流程（设计→计划→实现→验证→Review→收尾），确保每一步都可验证、可审计。

关键数据

17 个核心 skill，37 个 markdown 文件
零外部依赖（纯自实现）
支持 7 个 harness（Claude Code、Codex CLI、Codex App、Cursor、OpenCode、Gemini CLI、GitHub Copilot CLI）
当前版本 v5.1.0
项目 PR rejection 率 94%（严格的质量门槛）

解决的问题

Agent 在没有约束时的三种典型行为：

问题	症状	Superpowers 的对策
拍脑袋实现	直接开写代码，跳过需求澄清	`brainstorming`（硬门槛：未获设计批准不实现）
先写代码再补测试	测试沦为形式验证	`test-driven-development`（先写失败测试再写生产代码）
没验证就宣称完成	"应该没问题了"	`verification-before-completion`（必须看到最新验证输出）

2. 设计理念与核心原则

Superpowers 的设计哲学由四个相互支撑的核心原则构成。

2.1 Evidence Over Claims（先有证据，再声称）

所有结论必须有最新验证输出支撑。这个原则贯穿所有 skill：

BEFORE claiming any status or expressing satisfaction:
1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
5. ONLY THEN: Make the claim

verification-before-completion skill 中的铁律：

"If you haven't run the verification command in this message, you cannot claim it passes."

"Skip any step = lying, not verifying."

2.2 TDD for Process Documentation（过程文档也要测试驱动）

Superpowers 将 TDD（测试驱动开发）从代码扩展到过程文档：

TDD 概念	Skill 创建
测试用例	压力场景 + subagent
生产代码	Skill 文档（SKILL.md）
测试失败（RED）	Agent 在没有 skill 时违反规则
测试通过（GREEN）	Agent 在有 skill 时遵守规则
重构（REFACTOR）	关闭漏洞 + 保持合规
先写测试	先跑 baseline 场景，再写 skill

核心信条：

"If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing."

2.3 Anti-Rationalization（Agent 合理化防御）

Agent 在压力下会找借口逃避规则。Superpowers 通过三类机制主动预防：

显式计数器：列出常见借口并逐条反驳
红旗列表（Red Flags）：让 Agent 在开始合理化时自我检查
铁律声明：不留模糊空间

例如 using-superpowers 中的 Red Flags：

Thought	Reality
"This is just a simple question"	Questions are tasks. Check for skills.
"I need more context first"	Skill check comes BEFORE clarifying questions.
"Let me explore the codebase first"	Skills tell you HOW to explore. Check first.
"I remember this skill"	Skills evolve. Read current version.
"This doesn't need a formal skill"	If a skill exists, use it.
"I'll just do this one thing first"	Check BEFORE doing anything.
"This feels productive"	Undisciplined action wastes time.

2.4 Zero-Dependency 设计

整个项目不依赖任何第三方包。所有功能通过自实现工具链完成：

纯 shell 脚本（test-helpers.sh、bump-version.sh）
自实现 WebSocket 帧编解码（brainstorm-server 的 ws-protocol）
内联 frontmatter 解析（OpenCode 插件中的 extractAndStripFrontmatter）
无 npm install、无 requirements.txt、无外部 runtime 依赖

3. 架构概览

3.1 系统模块图

flowchart TD
    subgraph 配置层
        H["Hook 系统<br/>(hooks.json)"]
        P["Plugin 配置<br/>(plugin.json)"]
        S["本地设置<br/>(settings.json)"]
    end

    subgraph 引导层
        B["SessionStart Hook<br/>触发 bootstrap 加载"]
        U["using-superpowers<br/>(1% 规则：有1%可能就调用)"]
    end

    subgraph 技能层
        D["Discipline Skills<br/>(TDD, 验证, Review)"]
        T["Technique Skills<br/>(调试, Worktree, 并行)"]
        R["Reference Skills<br/>(工具映射, 平台适配)"]
    end

    subgraph 执行层
        SA["Subagent 架构<br/>(隔离上下文 / 状态报告)"]
        RV["两层 Review 流水线<br/>(Spec → Quality)"]
        VF["验证 Gate<br/>(先验证再声称)"]
    end

    subgraph 测试层
        FT["快速测试 ~2min<br/>(skill 内容验证)"]
        IT["集成测试 10-30min<br/>(真实会话执行)"]
        PT["协议测试<br/>(WebSocket 帧)"]
    end

    H -->|session-start| B
    B -->|注入 system prompt| U
    U -->|Skill 工具调用| D
    U -->|Skill 工具调用| T
    T --> SA
    D --> SA
    SA --> RV
    RV --> VF

    FT -.->|验证| D
    IT -.->|验证| SA

3.2 关键组件关系

┌──────────────────────────────────────────────────────────┐
│                      配置层                                │
│  hooks.json / hooks-cursor.json    plugin.json           │
│  .claude/settings.json             marketplace.json      │
└────────────────────────┬─────────────────────────────────┘
                         │ session-start 事件
                         ▼
┌──────────────────────────────────────────────────────────┐
│                      引导层                                │
│                                                          │
│  run-hook.cmd session-start                               │
│      │                                                    │
│      ▼                                                    │
│  using-superpowers/SKILL.md → "1% 规则" + Red Flags      │
│                                                          │
│  注入位置差异：                                            │
│  Claude Code → System Prompt                              │
│  OpenCode → First User Message（避免 token 膨胀）          │
└────────────────────────┬─────────────────────────────────┘
                         │ 用户消息到达 → Skill 判定
                         ▼
┌──────────────────────────────────────────────────────────┐
│                      技能执行层                             │
│                                                          │
│  1. brainstorming（设计前置）                               │
│  2. writing-plans（计划编写）                                │
│  3. subagent-driven-development（实现 + 两层 Review）      │
│  4. requesting-code-review（发起 Review）                  │
│  5. verification-before-completion（验证）                 │
│  6. finishing-a-development-branch（收尾）                 │
└──────────────────────────────────────────────────────────┘

4. 技能清单

来源：/skills/*/SKILL.md 的 frontmatter（name / description）

分类说明

按 writing-skills 中的定义，skill 分为四类：

类型	定义	测试方式
Discipline	规则约束类，不遵守会导致流程失效	压力场景 + 多压力叠加
Technique	具体方法步骤类，教会 Agent 怎么做	应用场景 + 边界情况
Pattern	思维模型类，教会 Agent 怎么想	识别 + 应用 + 反例
Reference	文档/API 参考类，供 Agent 查阅	检索 + 用例覆盖

完整清单

Skill	用途（中文）	类型
`brainstorming`	创造性工作前的需求澄清与设计批准。在实现任何功能/组件/修改行为前必须先跑。	Discipline
`dispatching-parallel-agents`	有 2 个以上互不依赖、无共享状态、无顺序依赖的任务时并行推进。	Technique
`executing-plans`	有实现计划时在单独会话中串行执行。	Technique
`finishing-a-development-branch`	实现完成且测试通过后，决定如何集成（merge/PR/keep/discard）。	Technique
`receiving-code-review`	收到 Review 反馈时的处理流程：先验证再采纳，不"表演式同意"。	Discipline
`requesting-code-review`	发起代码审查，通过 git SHA 给 reviewer 精准上下文。	Technique
`subagent-driven-development`	当前会话中执行实现计划的推荐方式（每任务 subagent + 两层 Review）。	Technique
`systematic-debugging`	bug/测试失败/非预期行为的系统化根因调查（4 阶段）。	Discipline
`test-driven-development`	先写失败测试，再写最小实现，再重构的 TDD 流程。	Discipline
`using-git-worktrees`	创建隔离工作区用于开发（优先原生隔离，其次 git worktree）。	Technique
`using-superpowers`	入口 skill：在任何回复前先判定是否需要调用其他 skill。	Discipline
`verification-before-completion`	声称完成前的验证约束：必须看到最新验证输出。	Discipline
`writing-plans`	将 spec 转化为可执行的任务清单（每任务含文件、测试、命令、预期输出）。	Technique
`writing-skills`	创建/编辑/验证 skill：TDD 流程创作技能。	Technique

5. 工作流程

5.1 总览

flowchart TD
  A[会话开始] --> B["using-superpowers: 先做 skill 判定
(在任何回复/澄清前)"]

  B --> C{是否进入 PlanMode/创造性工作?}
  C -->|是| D["brainstorming: 澄清需求/方案对比/设计
(硬门槛：未获设计批准不实现)"]
  D --> E["写 spec 文档 + 自检 + 用户 review gate"]
  E --> F["writing-plans: 写实现计划
(任务拆分+命令+代码+测试+提交)"]

  F --> G{执行方式?}
  G -->|推荐| H["subagent-driven-development:
每任务 1 个实现子代理 +
两段 review(规格->质量)"]
  G -->|备选| I["executing-plans:
本会话按计划逐条执行+检查点"]

  H --> J["requesting-code-review:
阶段性/任务后/合并前 review"]
  I --> J

  J --> K["verification-before-completion:
任何“完成/通过/修复”声明前必须跑验证"]
  K --> L["finishing-a-development-branch:
测完->识别环境->给出选项(merge/PR/keep/discard)->清理"]

  C -->|否| M{是否 bug/失败/非预期?}
  M -->|是| N["systematic-debugging:
先找根因(Phase1-3)再修(Phase4)"]
  N --> O["test-driven-development:
Red->Green->Refactor"]
  O --> J
  M -->|否| P[可能并行的独立任务]
  P --> Q["dispatching-parallel-agents:
2+独立任务并行推进"]

5.2 关键硬门槛

规则	Skill	禁止的行为
先判定 skill，再任何回复	`using-superpowers`	先回答、先澄清、先读代码
创造性工作先设计	`brainstorming`	未经设计批准就实现
先写失败测试后写生产代码	`test-driven-development`	先写实现再补测试
先根因调查后修复	`systematic-debugging`	"先改一改试试"
先验证再声称完成	`verification-before-completion`	没证据就宣称完成、跳过验证步骤

5.3 典型路径：新功能开发

using-superpowers（判定 skill）
  → brainstorming（设计前置，硬门槛）
    → writing-plans（写实现计划）
      → subagent-driven-development（实现 + 两层 Review）
        → requesting-code-review（每次 Review）
          → verification-before-completion（验证）
            → finishing-a-development-branch（收尾）

5.4 典型路径：Bug 修复

using-superpowers（判定 skill）
  → systematic-debugging（Phase 1-3：根因调查）
    → systematic-debugging Phase 4 → test-driven-development（修复）
      → requesting-code-review（Review）
        → verification-before-completion（验证）
          → finishing-a-development-branch（收尾）

5.5 执行层：两条路线对比

维度	subagent-driven-development（推荐）	executing-plans（备选）
执行场景	当前会话、任务相对独立	单独会话、串行执行
每任务处理	实现 subagent → spec review → code review	按计划逐条执行 + 检查点
上下文	full task text 粘贴（subagent 不读文件）	读计划文件
Review	内置两层 Review	按计划要求
状态跟踪	TodoWrite	TodoWrite
失败处理	循环修复直到通过	按计划要求

6. 关键特性

6.1 强制 Skill 调用机制

"1% 规则"：using-superpowers 中明确声明：

"If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill."

"IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT. This is not negotiable. This is not optional. You cannot rationalize your way out of this."

这段强硬声明 + 12 条 Red Flags 构成了行为约束的"强制执行层"。Agent 无法在调用 Skill 工具前回答任何用户问题。

6.2 两层 Review 流水线

与大多数代码审查流程不同，Subagent 实现后经历 两层独立审查：

Spec Compliance Review（规格审查）：审查者不信任 implementer 的报告，独立阅读代码核对需求
Code Quality Review（质量审查）：在规格审查通过后，检查代码质量、测试完整性

审查模板开头的心理暗示：

"The implementer finished suspiciously quickly. Their report may be incomplete, inaccurate, or optimistic. You MUST verify everything independently."

6.3 Subagent 上下文隔离

Subagent 不继承主会话上下文。每个 subagent 获得一个自包含 prompt：

完整的任务描述（从计划粘贴，不要求 subagent 读取文件）
场景上下文（位置、依赖、架构信息）
自我审查要求（在报告前自检）

四种状态报告系统：

状态	含义	后续操作
DONE	完成	进入规格审查
DONE_WITH_CONCERNS	完成但有疑虑	处理疑虑后审查
NEEDS_CONTEXT	缺少上下文	提供更多信息，重新调度
BLOCKED	无法完成	分析原因（太难、太大、计划有误）

Subagent 被鼓励在遇到困难时升级而非硬撑：

"It is always OK to stop and say 'this is too hard for me.' Bad work is worse than no work."

6.4 TDD for Skills

每个 skill 通过 TDD 流程创建，确保它们实际改变 Agent 行为而非停留在文本层面。详见第 8 节：测试策略。

7. 实现细节

7.1 Hook 系统

Hook 系统是 Superpowers 的"触发器"，确保 using-superpowers 在会话开始时自动加载。

7.1.1 Hook 配置

Claude Code 格式（hooks/hooks.json）：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
            "async": false
          }
        ]
      }
    ]
  }
}

Cursor 格式（hooks/hooks-cursor.json）：

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "command": "./hooks/run-hook.cmd session-start"
      }
    ]
  }
}

7.1.2 触发流程

会话启动 / /clear / /compact
       │
       ▼
SessionStart Hook 匹配（matcher: "startup|clear|compact"）
       │
       ▼
run-hook.cmd session-start 执行（async: false，阻塞执行）
       │
       ▼
using-superpowers bootstrap 注入到 system prompt / 首条用户消息
       │
       ▼
Agent 收到第一条用户消息
       │
       ▼
"1% 规则"判定 → 调用 Skill 工具 → 加载 SKILL.md

关键设计点：

matcher: "startup|clear|compact" —— 会话启动、清空、压缩后都触发
async: false —— 阻塞执行，bootstrap 必须在 agent 推理前加载
${CLAUDE_PLUGIN_ROOT} —— 指向插件安装目录的环境变量

7.1.3 不同 Harness 的 Hook 差异

Harness	配置文件	触发机制	注入位置
Claude Code	hooks.json	SessionStart + matcher	System Prompt
Cursor	hooks-cursor.json	sessionStart	System Prompt
Codex CLI	hooks.json	SessionStart + additionalContext	System Prompt
OpenCode	.opencode/plugins/superpowers.js	messages.transform	首条用户消息

OpenCode 的特殊处理（.opencode/plugins/superpowers.js）：

使用 experimental.chat.messages.transform 钩子将 bootstrap 注入用户消息（而非系统消息），原因：

避免系统消息每轮重复导致的 token 膨胀（见 #750）
解决多系统消息对 Qwen 等模型的兼容性问题（见 #894）

同时实现模块级缓存 _bootstrapCache（undefined→未加载，null→文件缺失），避免每步都读取磁盘：

let _bootstrapCache = undefined;

const getBootstrapContent = () => {
  if (_bootstrapCache !== undefined) return _bootstrapCache;
  // ...读文件、解析 frontmatter...
  _bootstrapCache = `<EXTREMELY_IMPORTANT>...${content}...</EXTREMELY_IMPORTANT>`;
  return _bootstrapCache;
};

7.2 SKILL.md 规范

7.2.1 Frontmatter

---
name: skill-name-with-hyphens
description: Use when [specific triggering conditions and symptoms]
---

关键约束：

字段	约束
`name`	只允许字母、数字、连字符
`description`	以 "Use when..." 开头，描述触发条件（而非技能内容）
`description`	不超过 1024 字符
`description`	第三人称

重要经验： description 不应总结工作流。测试发现，当 description 包含工作流摘要时，Agent 会跳过完整的 SKILL.md 直接按 description 执行——导致丢失关键步骤（如只做一次 review 而非两次）。

# ❌ BAD：总结了工作流程
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ✅ GOOD：只描述触发条件
description: Use when executing implementation plans with independent tasks in the current session

7.2.2 CSO（Claude Search Optimization）

让 Agent 在推理时能搜索到正确的 skill：

Rich Description：回答 "我现在应该读这个 skill 吗？"
Keyword Coverage：用 Agent 会搜索的词（错误信息、症状、工具名）
Descriptive Naming：主动语态、动词优先（condition-based-waiting 而非 async-test-helpers）
Token Efficiency：高频 skill < 200 词，其余 < 500 词

7.2.3 文件组织结构

├── self-contained skill/
│   └── SKILL.md          # 所有内容内联

├── skill with tool/
│   ├── SKILL.md          # 概览 + 模式说明
│   └── example.ts        # 可复用的工具/代码

├── skill with reference/
│   ├── SKILL.md          # 概览 + 工作流
│   ├── api-reference.md  # API 文档（100+ 行）
│   └── scripts/          # 可执行工具

7.3 Subagent 架构

7.3.1 实现子代理 prompt 模板

每个实现子代理收到自包含的 prompt（不继承会话上下文）：

Task tool (general-purpose):
  description: "Implement Task N: [task name]"
  prompt: |
    ## Task Description
    [FULL TEXT of task from plan - paste it here, don't make subagent read file]

    ## Context
    [Where this fits, dependencies, architectural context]

    ## Your Job
    1. Implement exactly what the task specifies
    2. Write tests (following TDD if task says to)
    3. Verify implementation works
    4. Commit your work
    5. Self-review (see below)
    6. Report back

    ## When You're in Over Your Head
    STOP and escalate when:
    - Task requires architectural decisions
    - You can't understand the codebase
    - You're uncertain about correctness

    ## Report Format
    - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
    - What you implemented
    - Test results
    - Files changed
    - Self-review findings

7.3.2 升级规则

原因	处理方式
上下文不够	提供更多信息，同模型重新调度
任务太复杂	使用更高能力模型重新调度
任务太大	拆分为更小子任务
计划本身有误	升级到人类

7.3.3 隔离的优势

消除上下文污染：每个 subagent 从干净状态开始
降低 token 开销：不需要传递完整会话历史
确定性：subagent 基于"你要做什么"而非"你从哪里来"做判断
安全网：允许 subagent 说"我不行"（BLOCKED 不会被惩罚）

7.4 Review 流程

7.4.1 规格审查（Spec Compliance Reviewer）

审查者模板的开头：

CRITICAL: Do Not Trust the Report The implementer finished suspiciously quickly. Their report may be incomplete, inaccurate, or optimistic. You MUST verify everything independently.

DO NOT: Take their word, trust their claims, accept their interpretation.

DO: Read the actual code, compare to requirements line by line, check for missing pieces and extra features.

审查输出：

✅ Spec compliant
❌ Issues found: [file:line 引用]

7.4.2 质量审查（Code Quality Reviewer）

只在规格审查通过后执行，检查：

单一职责：每个文件一个清晰的责任
接口定义：有明确的 interface
文件大小：新建文件是否已经过大
测试质量：是否验证实际行为而非 mock 行为

7.4.3 发起 Review

通过 requesting-code-review skill，使用 git SHA 给精准上下文：

DESCRIPTION: [task summary]
PLAN_OR_REQUIREMENTS: Task N from [plan-file]
BASE_SHA: [commit before task]
HEAD_SHA: [current commit]

7.4.4 接收 Review

通过 receiving-code-review skill：

先理解/复述 reviewer 的反馈
对照代码事实验证
逐条实现并测试
必要时基于技术理由反驳（不表演式同意）

8. 测试策略

8.1 TDD for Skills 流程

创建/修改 skill 必须遵守 RED→GREEN→REFACTOR：

RED：运行压力场景（无 skill）
  → 记录 agent 的 baseline 行为 verbatim
  → 识别合理化借口

GREEN：编写最小 skill
  → 运行相同场景（有 skill）
  → 验证 agent 遵守规则

REFACTOR：关闭漏洞
  → 识别新的合理化借口
  → 添加显式计数器
  → 重新测试直到无漏洞

Iron Law: NO SKILL WITHOUT A FAILING TEST FIRST.

写 skill 前没有测试？删除 skill。重新开始。

8.2 压力场景类型

类型	描述	对应 skill 类型
学术问题	问规则是什么？	适用于所有 discipline skill
压力场景	给时间紧迫信号	适用于 discipline
多压力叠加	time + sunk cost + exhaustion 同时施加	适用于 discipline
应用场景	能否应用技术正确？	适用于 technique
边界情况	处理边缘场景	适用于 technique
识别场景	能否识别模式适用？	适用于 pattern
反例测试	知道何时不适用？	适用于 pattern
检索场景	能否找到正确信息？	适用于 reference
用例覆盖	常见场景都有覆盖？	适用于 reference

8.3 测试分类

类型	耗时	验证目标	工具
快速测试	~2 分钟	Skill 加载、内容验证、需求检查	`run-skill-tests.sh`
集成测试	10-30 分钟	真实 Agent 会话、subagent 调度、文件生成、测试通过、git 提交	`test-subagent-driven-development-integration.sh`
协议测试	秒级	WebSocket 帧编解码、握手、边界	`ws-protocol.test.js`

集成测试的输出示例（简化）：

=== Verification Tests ===
Test 1: Skill tool invoked...          [PASS]
Test 2: Subagents dispatched...         [PASS] 7 subagents
Test 3: Task tracking...               [PASS] TodoWrite used 5 times
Test 4: Spec review before code review...[PASS]
Test 5: Implementer self-review...      [PASS]
Test 6: Files created...               [PASS] src/math.js, test/math.test.js
Test 7: Tests pass...                  [PASS]
Test 8: Git commits...                 [PASS] 3 commits

==========================================
STATUS: PASSED

8.4 Token 分析

通过 analyze-token-usage.py 分析 session 的 token 成本和缓存效率：

Agent           Description                  Input     Output     Cache       Cost
--------------------------------------------------------------------------------------
main            Main session (coordinator)     27      3,996   1,213,703  $   4.09
3380c209        implementing Task 1             2        787      24,989  $   0.09
34b00fde        implementing Task 2             4        644      25,114  $   0.09
3801a732        spec review Task 1              5        703      25,742  $   0.09
4c142934        code review Task 2              6        854      25,319  $   0.09
--------------------------------------------------------------------------------------
TOTALS: Messages 41, Cost: $4.67

典型数据： 一个完整的多任务 subagent 工作流成本约 $4-5**，每个 subagent 约 **$ 0.05-0.15。

8.5 Rationalization Table

每个 discipline skill 都有一个 Rationalization Table，列出测试中 Agent 实际说出的借口：

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |

8.6 测试基础设施

tests/
├── claude-code/
│   ├── test-helpers.sh                    # 共享测试工具
│   ├── test-subagent-driven-development-integration.sh
│   ├── analyze-token-usage.py             # Token 分析工具
│   └── run-skill-tests.sh                 # 测试运行器
├── brainstorm-server/
│   ├── server.test.js                     # 服务器行为测试
│   ├── ws-protocol.test.js                # WebSocket 协议测试
│   └── package.json
└── skill-triggering/
    └── run-test.sh                        # 自然语言触发测试

9. 平台兼容性

9.1 支持的 Harness

Harness	集成方式	特殊适配
Claude Code	原生 plugin + hooks.json	基于 SessionStart matcher 触发
Codex CLI	plugin.json + hooks.json	支持 additionalContext
Codex App	原生 skill 支持	无需工具映射
Cursor	hooks-cursor.json	Windows UTF-8 BOM 处理（run-hook.cmd）
OpenCode	superpowers.js plugin	用户消息注入 + 模块级缓存
Gemini CLI	activate_skill + GEMINI.md	自动加载 tool mapping
GitHub Copilot CLI	hooks + references/copilot-tools.md	完整工具映射表

9.2 工具映射

不同 harness 的工具名不同，Superpowers 在 references/ 目录中维护映射：

概念	Claude Code	Copilot CLI	OpenCode
加载 skill	`Skill`	`skill`	`skill`
子代理	`Task`	`task` (agent_type)	@mention
任务跟踪	`TodoWrite`	`sql` (todos table)	`todowrite`
读文件	`Read`	`view`	原生工具
写文件	`Write`/`Edit`	`create`/`edit`	原生工具
执行命令	`Bash`	`bash`	原生工具

9.3 Bootstrap 注入差异

Harness	注入位置	缓存策略
Claude Code	System Prompt	无缓存（每轮自带）
Codex CLI	System Prompt	无缓存
OpenCode	First User Message	模块级 `_bootstrapCache`
Gemini CLI	System Prompt	无缓存

9.4 配置结构

Claude Code Plugin（.claude-plugin/plugin.json）：

{
  "name": "superpowers",
  "version": "5.1.0",
  "skills": "./skills/"
}

Marketplace（.claude-plugin/marketplace.json）：

{
  "name": "superpowers-dev",
  "plugins": [{"name": "superpowers", "source": "./"}]
}

本地启用（~/.claude/settings.json）：

{
  "enabledPlugins": {"superpowers@superpowers-dev": true}
}

10. 示例

10.1 TDD for Skills 完整流程：创建 brainstorming skill

目标：创建一个让 Agent 在动代码前先做方案讨论的 skill。

RED 阶段——运行压力场景（无 skill）：

用户: "帮我做一个任务管理应用"
Agent: "好的，我马上开始写代码，先初始化项目和安装依赖..."

Baseline 结果：Agent 直接进入编码，没有需求澄清、没有方案讨论、没有设计文档。

记录下 Agent 的典型行为：

跳过了需求澄清阶段
自己做了技术选型假设（React + TypeScript + 特定库）
对不确定的需求做了默认假设

GREEN 阶段——编写 brainstorming skill：

SKILL.md 包含：

硬性约束：在实现任何创造性工作前必须调用
特定流程：澄清上下文 → 逐个问题澄清 → 提 2-3 方案 → 设计批准
Red Flags：防止 Agent 说 "这只是一个简单问题"
Rationalization Table：防止 Agent 绕过设计阶段

再次运行场景（有 skill）：

用户: "帮我做一个任务管理应用"
Agent: "在开始实现之前，让我先通过 brainstorming 来澄清需求。
首先，这个应用的目标用户是谁？..."

REFACTOR 阶段：

测试发现 Agent 在某些场景下仍回避 brainstorming
添加 "I know what that means"（知道概念≠使用 skill）到 Red Flags
添加 "This feels productive"（无纪律的动作也浪费时间的辩解）
重新测试直到 Agent 在所有场景下都遵守

10.2 Subagent 工作流完整示例

计划：实现一个简单的数学库（2 个任务）

Task 1: Create Add Function → 实现 add(a, b)，测试 test/math.test.js
Task 2: Create Multiply Function → 实现 multiply(a, b)

执行流水线：

Step 1: Controller 读取计划一次（不重复读）
──────────────────────────────────────────
Step 2: Dispatch subagent("Implement Task 1")
  → 实现 add 函数
  → 写测试并验证通过
  → git commit
  → 自评: 完成
  → Report: DONE
──────────────────────────────────────────
Step 3: Dispatch spec reviewer("Review Task 1")
  → 独立阅读代码（不信任 implementer 报告）
  → 对照需求逐行检查
  → Report: ✅ Spec compliant
──────────────────────────────────────────
Step 4: Dispatch code reviewer("Review Task 1")
  → 检查代码质量、命名、测试完整性
  → Report: ✅ Quality OK
──────────────────────────────────────────
Step 5: Dispatch subagent("Implement Task 2")  → DONE
Step 6: spec review → ✅
Step 7: code review → ✅
──────────────────────────────────────────
Step 8: Dispatch final global reviewer
  → 整体代码质量检查
  → Report: ✅ All OK
──────────────────────────────────────────
Step 9: → finishing-a-development-branch

10.3 压力场景：Time + Sunk Cost 复合压力

输入给 Agent：

// 这个项目已经做了两个月，客户明天交付，我已经连续加班两周了。
// 现在有个排序 bug，先用 hotfix 顶着，有空再好好修。

无 skill 的 Agent（baseline）：

理解了，我用 setTimeout 加一个临时补丁，让排序在数据量小时
跳过错误。后续再重构。

——跳过了系统化调试，直接打补丁。

有 systematic-debugging skill 的 Agent：

我理解你很急，但根据 systematic-debugging 流程，我需要先调查：
Phase 1: 复现问题，找到根因
Phase 2: 分析模式
Phase 3: 单一假设验证
Phase 4: 再进入修复

先让我确认：
1. 排序失败的具体输入是什么？
2. 是稳定复现还是偶发？
3. 有日志或报错信息吗？

——坚持了先找根因再修复的流程。

11. 限制与未来计划

11.1 已知问题和限制

问题	影响	当前处理
Windows UTF-8 BOM	Cursor 的 hooks-cursor.json 需要额外包装	`run-hook.cmd` 包装器
OpenCode 消息注入	每次 agent step 重载消息数组，bootstrap 可能重复注入	模块级缓存 + 去重检查（EXTREMELY_IMPORTANT 标记）
Hook ordering 依赖	SessionStart hook 必须在 agent 推理前完成	使用 `async: false` 阻塞执行
Skill 内容膨胀	skill 越长，agent 越容易 "skip content"	通过 CSO token efficiency 约束
跨模型兼容性	Qwen 等多系统消息破坏问题	OpenCode 转为用户消息注入
无持久化状态	不追踪跨会话的 skill 使用记录	当前为设计决策（保持简单）

11.2 Breaking Changes 历史（v5.x）

版本	变更
v5.1.0	移除旧版 slash commands（/brainstorm、/execute-plan、/write-plan）
v5.1.0	Code reviewer agent 合并到 skill 模板中
v5.1.0	Worktree skills 重写（原生工具优先、保留前确认、origin 清理）
v5.1.0	OpenCode bootstrap 缓存优化（#1202）
v5.0+	所有 skill 迁移到 SKILL.md + frontmatter 格式

11.3 未来方向

更多 harness 支持（后续的 IDE/CLI 工具）
新 skill 开发（当前 17 个，社区持续贡献）
技能测试自动化的改进（更快的测试反馈循环）
更好的跨会话 skill 使用追踪（当前无持久化状态）

12. 参考资源

关键文件索引

skills/
├── using-superpowers/SKILL.md           # 引导 skill（入口：1% 规则 + Red Flags）
├── writing-skills/SKILL.md              # Skill 编写规范（TDD for Skills）
├── brainstorming/SKILL.md               # 设计前置（硬门槛）
├── subagent-driven-development/
│   ├── SKILL.md                         # Subagent 工作流
│   ├── implementer-prompt.md            # 实现子代理模板
│   ├── spec-reviewer-prompt.md          # 规格审查模板
│   └── code-quality-reviewer-prompt.md  # 质量审查模板
├── systematic-debugging/SKILL.md        # 系统化调试（4 阶段）
├── test-driven-development/SKILL.md     # TDD（Red→Green→Refactor）
└── verification-before-completion/SKILL.md  # 验证 Gate

hooks/
├── hooks.json             # Claude Code hook 配置
├── hooks-cursor.json      # Cursor hook 配置
└── run-hook.cmd           # Hook 执行包装器（Windows）

tests/
├── claude-code/
│   ├── test-helpers.sh           # 共享测试工具
│   ├── test-subagent-driven-development-integration.sh  # 集成测试
│   └── analyze-token-usage.py    # Token 分析工具
├── brainstorm-server/
│   ├── server.test.js            # 服务器测试
│   └── ws-protocol.test.js       # WebSocket 协议测试
└── skill-triggering/
    └── run-test.sh               # 自然语言触发测试

.opencode/plugins/superpowers.js   # OpenCode 插件（消息注入 + 缓存）
docs/testing.md                    # 测试方法文档
CLAUDE.md                          # 贡献者指南（AI agent 必读）

链接

README.md — 项目概述
CLAUDE.md — 贡献者指南
docs/testing.md — 测试方法
docs/README.opencode.md — OpenCode 集成
skills/using-superpowers/SKILL.md — 入口 skill
skills/writing-skills/SKILL.md — Skill 编写规范
hooks/hooks.json — Hook 配置
.opencode/plugins/superpowers.js — OpenCode 插件源码

社区

GitHub: github.com/obra/superp…
License: MIT