学不完，根本学不完-Superpowers使用指南

Superpowers 使用指南

基于 14 个 Superpowers Skill 的完整 SKILL.md 文档整理。所有流程均来自官方文档。

---

核心理念

Superpowers 不是工具集，而是一套纪律框架。它不提供具体怎么做（那是 mattpocock 和 Gstack 的事），而是定义什么时候做、按什么顺序做、以什么标准做。

14 个 Skill 通过铁律（Iron Law）机制强制执行，违反铁律的操作会被明确禁止。

---

铁律体系

Superpowers 的核心是 5 条铁律，贯穿所有 Skill：

铁律	所属 Skill	内容
Skill 优先	using-superpowers	在任何回复之前必须检查并调用相关 Skill
先思考再动手	brainstorming	没有经过头脑风暴和设计审批，绝不写代码
先测试再实现	test-driven-development	没有失败的测试，绝不写生产代码
先查根因再修复	systematic-debugging	没有根因调查，绝不修复 bug
证据先于断言	verification-before-completion	没有运行验证命令并确认输出，绝不声称完成

---

完整工作流链路

                   using-superpowers（每条链路都从这里开始）
                           │
            ┌──────────────┼──────────────┐
            ▼              ▼              ▼
      创造性工作        遇到 Bug        代码审查
            │              │              │
      brainstorming   systematic-    requesting-
            │         debugging     code-review
            ▼              │              │
      writing-plans        ▼              ▼
            │         test-driven-   receiving-
    ┌───────┴───────┐  development   code-review
    ▼               ▼       │
subagent-      executing-   ▼
driven-        plans    verification-
development       │      before-
    │              │      completion
    └──────┬───────┘
           ▼
    finishing-a-
    development-branch

支撑技能（贯穿全局）：

• using-git-worktrees — 工作空间隔离
• dispatching-parallel-agents — 并行任务分发
• writing-skills — 编写新 Skill（用 TDD 方法论）

---

场景一：从想法到代码（主工作流）

第 0 步：一切从这里开始

using-superpowers 是元技能，在任何对话开始时自动触发。它确保你在做任何事之前先检查并调用相关 Skill。

规则：

• 即使只是澄清问题，也要先检查 Skill
• 遇到 bug → 先调 systematic-debugging，不能直接提议修复
• 创造性工作 → 先调 brainstorming，不能直接写代码

红牌警告（以下想法意味着你在违规）：

你在想	你在违规
“这只是个简单问题”	问题也是任务，检查 Skill
“让我先探索代码库”	Skill 告诉你如何探索，先检查
“这个不需要正式 Skill”	如果有 Skill，就用它
“我记得这个 Skill”	Skill 会演进，读当前版本
“Skill 大材小用”	简单的事会变复杂，用它

第 1 步：头脑风暴

brainstorming 在任何创造性工作之前必须使用。

硬门：在呈现设计并获得用户批准之前，绝不调用实现 Skill、写代码、搭建项目或执行任何实现操作。

9 步清单：

1. 探索项目上下文 — 检查文件、文档、近期提交
2. 适时提供视觉伴侣 — 仅在问题确实需要用图说明时
3. 逐一询问澄清问题 — 推荐用选择题，了解目的/约束/成功标准
4. 提出 2-3 个方案 — 含权衡分析和推荐
5. 分章节呈现设计 — 架构、组件、数据流、错误处理、测试，每章需用户批准
6. 写设计文档 → 保存到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并提交
7. Spec 自审 — 检查占位符、矛盾、歧义、范围
8. 用户审查 — 让用户阅读 spec 文件后再继续
9. 转交实现 → 调用 writing-plans

YAGNI 原则：无情删除不必要的东西。即使是”简单”项目也不能跳过——未审查的假设在简单项目中造成的浪费最大。

第 2 步：编写实现计划

writing-plans 在有 spec 之后、写代码之前使用。

流程：

1. 宣布使用 writing-plans
2. 范围检查：如果 spec 覆盖多个独立子系统，建议拆分为独立计划
3. 文件结构映射：设计哪些文件创建/修改，各自负责什么
4. 写计划文档 → docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

计划文档格式：

• Header：Goal / Architecture / Tech Stack / Global Constraints
• 每个 Task：Files（create/modify/test）/ Interfaces（consumes/produces）/ 复选框步骤（含精确代码、命令和预期输出）

“不留占位符”规则：绝不写 TBD、TODO、”稍后实现”、”添加适当的错误处理”、”类似 Task N”。假设实现者技能熟练但对你的工具链和问题域一无所知。每个 task 是最小单位，有独立的测试周期。

执行交接：完成后提供两个选项：

• 推荐 → subagent-driven-development（同会话执行）
• 备选 → executing-plans（独立会话执行）

第 3 步：执行计划

方案 A：子 Agent 驱动（推荐）

subagent-driven-development 在子 Agent 可用时使用。

流程：

1. 预检：扫描计划一次，检查 task 之间的冲突和全局约束。一次性呈现所有冲突。
2. 为每个 task：
   • 运行 scripts/task-brief PLAN_FILE N 提取 task
   • 派遣实现子 Agent（使用 implementer-prompt.md 模板，子 Agent 应使用 test-driven-development）
   • 实现→测试→提交→自审
   • 生成审查包：scripts/review-package BASE HEAD
   • 派遣 task 审查子 Agent（使用 task-reviewer-prompt.md）
   • 如 Critical/Important 问题 → 派遣修复子 Agent → 重新审查
   • 标记完成
3. 全部完成后：派遣最终全分支代码审查
4. 调用 finishing-a-development-branch

持续执行：task 之间不停顿。只在阻塞、无法解决的歧义或完成时停止。

耐久性：进度写入 .superpowers/sdd/progress.md，跨上下文压缩也能恢复。

模型选择：机械任务用最便宜模型、协调用中档、架构/设计用最强。

红牌警告：禁止并行派遣多个实现子 Agent、禁止跳过 task 审查、禁止让实现者读整个计划（用 task-brief）、禁止替审查者预判发现。

方案 B：内联执行（无子 Agent 时）

executing-plans 在子 Agent 不可用时使用。

流程：

1. 加载并审查计划，批判性阅读，有疑虑就提出
2. 逐个执行 task：标记 in_progress → 严格按步骤执行 → 运行验证 → 标记完成
3. 全部完成后调用 finishing-a-development-branch

阻塞时停止：遇到阻塞、计划缺口、不清晰的指令或反复验证失败时停下来。绝不在 main/master 分支上开始实现。

第 4 步：测试驱动开发

test-driven-development 在实现任何功能或 bug 修复时使用。

铁律：没有失败的测试，绝不写生产代码。

红-绿-重构循环：

1. RED：写一个最小的失败测试
2. 验证 RED（强制）：跑测试，确认它因正确的原因失败（功能缺失，不是笔误）
3. GREEN：写最简单的代码让测试通过。不添加额外功能、不重构、不”改进”
4. 验证 GREEN（强制）：跑测试，确认通过且其他测试不受影响
5. REFACTOR：清理代码（消除重复、改进命名、提取助手），保持测试绿色，不添加行为
6. 重复：下一个行为的下一个失败测试

例外（需询问用户）：抛弃式原型、生成的代码、配置文件。

反模式警报（详见 testing-anti-patterns.md）：

• 测试 mock 的行为
• 为生产类添加仅测试用的方法
• 不理解依赖就 mock
• 事后补测试（回答”这做什么？”而非”这应该做什么？”）

第 5 步：代码审查

requesting-code-review 在以下情况触发：

• 强制：子 Agent 驱动的每个 task 完成后、主要功能完成后、合并到 main 前
• 可选：卡住时（新视角）、重构前（基线检查）、修复复杂 bug 后

流程：

1. 确定 BASE_SHA 和 HEAD_SHA
2. 派遣代码审查子 Agent（使用 code-reviewer.md 模板）
3. 按反馈行动：Critical → 立即修复 / Important → 继续前修复 / Minor → 记录稍后处理

receiving-code-review 在收到审查反馈时使用。

响应模式：

1. 完整阅读反馈，不反应
2. 用自己的话重述需求（或提问）
3. 对照代码库实际验证
4. 评估：在这个代码库中技术上是否合理？
5. 回应：技术性确认或有理由的反对
6. 逐项实现，每项单独测试

多项反馈的处理顺序：先澄清不清楚的 → 阻塞性（破坏/安全）→ 简单修复（笔误/import）→ 复杂修复（重构/逻辑）。

第 6 步：完成分支

finishing-a-development-branch 在实现完成、所有测试通过时使用。

流程：

1. 验证测试：运行测试套件。失败→停止。通过→继续。
2. 检测环境：正常仓库 / 命名分支 worktree / Detached HEAD
3. 确定 base 分支
4. 呈现 4 个选项（Detached HEAD 只有 3 个）：
   • 选项 1：本地合并回 base 分支
   • 选项 2：推送并创建 Pull Request
   • 选项 3：保持分支不动
   • 选项 4：丢弃此工作
5. 执行选择：按选定选项的预设工作流执行
6. 清理：仅选项 1 和 4。检查来源——Superpowers 管理的 worktree 由它清理，Harness 管理的由 Harness 清理

---

场景二：调试

systematic-debugging 在遇到任何 bug、测试失败或异常行为时使用。

铁律：没有根因调查，绝不修复。

四种强制阶段，按序完成：

Phase 1：根因调查（在任何修复之前）

1. 仔细读错误信息（堆栈、行号、错误码）
2. 确定复现（可靠触发器、精确步骤、每次都能复现？）
3. 检查近期变更（git diff、提交、新依赖、配置变更、环境）
4. 多组件系统：在每个组件边界插诊断日志
5. 追溯数据流（参考 root-cause-tracing.md 做反向追踪）

Phase 2：模式分析

1. 在同代码库中找正常工作的例子
2. 对比参考实现（完全读懂，不是略读）
3. 识别正常和异常的差异
4. 理解依赖（组件、设置、配置、假设）

Phase 3：假设与测试

1. 形成单一假设：”我认为 X 是根因，因为 Y”
2. 最小化测试——最小可能的改动，一次一个变量
3. 验证后再继续
4. 不确定时，说”我不理解 X”，寻求帮助

Phase 4：实现

1. 创建失败测试用例（调用 test-driven-development）
2. 实现单一修复（一次一个改动，不做”顺手”改进）
3. 验证修复（测试通过、无回归、问题解决）
4. 如果修复无效：
   • <3 次尝试 → 回到 Phase 1
   • ≥3 次修复失败 → 停止，质疑架构。和用户讨论后再尝试。模式表明架构问题。

---

场景三：并行任务

dispatching-parallel-agents 在 2+ 个独立任务时使用。

使用条件：

• 多个测试文件失败且根因不同
• 多个子系统独立出问题
• 每个问题无需其他问题的上下文就能理解
• 3+ 个独立问题域

流程：

1. 识别独立域：按出问题的组件分组
2. 创建聚焦的 Agent 任务：每个 Agent 有特定范围、清晰目标、约束条件和预期输出格式
3. 同一响应中并行派遣：多个派遣调用在同一回复中 = 并行执行
4. 审查与整合：Agent 返回后，逐个读摘要，验证修复不冲突，运行全量测试

---

场景四：验证与完成

verification-before-completion 在任何声称成功之前触发。

铁律：证据先于断言。

门函数：

1. 鉴别：什么命令能证明这个声称？
2. 运行：完整执行，新鲜完整的输出。
3. 读取：完整输出、检查退出码、数失败数。
4. 验证：输出是否确认了这个声称？
   • 否 → 陈述实际状态，附带证据。
   • 是 → 陈述声称，附带证据。
5. 只有这时：才能做出声称。

触发条件（包括但不限于）：

• 声称”完成了”/“修好了”/“通过了”
• 准备提交/创建 PR/声明任务完成
• “太好了！”/“完美！”/“搞定了！”等满足表达
• “应该”/“大概”/“看起来”等模糊词
• 委派给 Agent 后相信其成功报告

---

场景五：工作空间隔离

using-git-worktrees 在开始需要隔离的功能开发或执行实现计划时使用。

流程：

1. 检测已有隔离：检查是否已在链接 worktree 中，是则跳过
2. 优先使用平台原生工具（如 EnterWorktree）
3. Git Worktree 回退方案（无原生工具时）：
   • 选目录（优先：明确指令 > .worktrees/ > worktrees/ > 默认 .worktrees/）
   • 验证目录在 gitignore 中
   • git worktree add "$path" -b "$BRANCH_NAME" 并 cd
4. 项目设置：自动检测并运行 setup（npm install / cargo build / pip install / go mod download）
5. 验证干净基线：运行测试确保工作空间干净

---

场景六：编写新 Skill

writing-skills 在创建新 Skill、编辑已有 Skill 或部署前验证 Skill 时使用。

TDD 方法论应用于文档编写：

RED 阶段——写失败测试（基线）

• 创建压力场景（纪律类 Skill 需 3+ 种组合压力）
• 不加载 Skill 运行场景，逐字记录基线行为
• 识别合理化和失败的规律

GREEN 阶段——写最小 Skill

• 针对那些合理化写 SKILL.md
• Frontmatter：name（仅字母、数字、连字符）、description（”Use when…”开头，第三人称，仅触发器，不写工作流摘要，最长 1024 字符）
• 完整场景前先微测试措辞（每变体 5+ 次重复，始终包含无指引对照组）
• 加载 Skill 运行场景，验证 Agent 现遵循规则

REFACTOR 阶段——封堵漏洞

• 识别测试中的新型合理化
• 添加显式反制（纪律类 Skill）
• 构建合理化表和红牌列表
• 反复测试直到无懈可击

部署

• 提交 Skill 到 git 并推送

前置要求：必须理解 test-driven-development。

---

Skill 依赖关系总图

                    using-superpowers（元技能，总是最先调用）
                            │
         ┌──────────────────┼──────────────────┐
         ▼                  ▼                  ▼
    brainstorming    systematic-         dispatching-
         │           debugging          parallel-agents
         ▼               │
    writing-plans         ▼
         │           test-driven-
    ┌────┴────┐      development
    ▼         ▼           │
subagent-  executing-     │
driven-    plans          │
development  │            │
    │         │           │
    ├─────────┘           │
    ▼                     │
requesting-code-review    │
    │                     │
    ▼                     │
receiving-code-review     │
    │                     │
    ▼                     │
finishing-a-              │
development-branch        │
                          │
         ┌────────────────┘
         ▼
  verification-before-completion（最后一道门）

全局支撑：

• using-git-worktrees — 在执行实现计划之前创建隔离工作空间
• writing-skills — 用 TDD 方法编写新 Skill

---

Superpowers 与其他框架的关系

维度	Superpowers	mattpocock/skills	Gstack
定位	流程纪律框架	工程执行工具	全生命周期平台
关注	何时做、按什么顺序做	怎么做具体的事	从想法到上线的完整流程
特色	铁律强制执行	盘问驱动 + 领域建模	基础设施 + 自动化
协同	Skill 调用入口（检查并路由）	Superpowers 流程中的执行环节	可与 Superpowers 互补使用

实际情况：using-superpowers 确保你在开始工作前检查所有可用 Skill——包括 mattpocock 和 Gstack 的。而 Superpowers 自己的 14 个 Skill 定义了从想法到代码的纪律边界，mattpocock 和 Gstack 在边界内提供具体执行能力。