Superpowers：AI Agent 系统化软件开发方法论

这不是一篇普通的工具介绍。这是一套强制 AI 在动手前先想清楚的纪律体系——14 个可组合的 skills，把 “收到任务就写代码” 的本能反应，改造成 “先设计、再计划、再执行、再验证” 的工程流程。读完这篇，你会理解为什么把这套方法叫做 Superpowers。

Superpowers 是什么

Superpowers 是一个AI 编程代理的软件开发方法论套件，以可组合的 skills 文件为载体，通过一套强制性的指令协议，把 AI 从"收到任务就写代码"的反应式代理，转变为"先设计、再计划、再执行、再验证"的系统化工程师。

它不是某个 IDE 的插件，也不是一个 CLI 工具——它是一个跨平台的行为框架，通过同一套 skills 目录同时支持 Claude Code、Codex、Cursor、OpenCode、Gemini CLI 和 GitHub Copilot CLI。

核心机制很简单：

Skills 是可组合的流程单元 — 每个 skill 是一个 Markdown 文件（SKILL.md），包含特定场景下的完整工作流
1% 规则强制调用 — 收到任何任务，先问自己"有没有 skill 适用？"，哪怕只有 1% 概率也必须调用
硬性门槛（HARD-GATE）阻止跳跃 — 未经设计批准，禁止写任何代码
全生命周期覆盖 — 从需求分析、设计、计划、执行、审查、验证到交付，每个阶段都有对应的 skill

skill 分为 6 大类，覆盖从需求分析到代码交付的完整开发生命周期：

分类	Skill	一句话定位
元技能	using-superpowers	入口技能，教你如何发现和强制调用其他 skills
	writing-skills	用 TDD 方法编写和迭代 skills 本身
设计层	brainstorming	任何创造性工作前的需求澄清与方案设计
计划层	writing-plans	将设计转化为可执行的、逐任务的实现计划
执行层	subagent-driven-development	推荐：每个任务派一个子代理 + 双层审查
	executing-plans	备选：在当前会话中按步骤执行计划
	dispatching-parallel-agents	多个独立问题并行派代理解决
	using-git-worktrees	强制使用 git worktree 进行工作区隔离
质量层	test-driven-development	写测试 → 看失败 → 写最小代码 → 重构
	systematic-debugging	四阶段系统化调试，先找根因再修复
	requesting-code-review	主动发起代码审查
	receiving-code-review	接收审查反馈时的技术严谨处理
	verification-before-completion	声称完成前必须运行验证命令
交付层	finishing-a-development-branch	开发完成后：合并 / PR / 保留 / 丢弃

Skills 工作流

整个体系形成一条强制性的"分析 → 设计 → 计划 → 执行 → 审查 → 验证 → 交付"流水线：

flowchart TD
    US[using-superpowers
入口：1%规则强制调用]
    US -- 新功能/修改 --> BR[brainstorming
需求→设计→方案]
    US -- Bug/异常 --> SD[systematic-debugging
四阶段找根因]
    SD --> M{多个独立根因?}
    M -->|是| DPA[dispatching-parallel-agents
并行代理分别调查]
    M -->|否| WGT
    DPA --> WGT

    BR --> WP[writing-plans
逐任务实现计划]
    WP --> WGT

    WGT[using-git-worktrees
强制隔离：不在main上开发]
    WGT --> SAD[subagent-driven-development
推荐：子代理+双层审查]
    WGT --> EP[executing-plans
当前会话执行]

    SAD --> RCR[requesting-code-review
每任务后：spec + quality]
    RCR --> RCV[receiving-code-review
收到外部反馈：验证→评估→实现]
    RCV --> VC[verification-before-completion
全部完成后：证据先于声称]
    EP --> VC
    VC --> FB[finishing-a-dev-branch
交付：合并/PR/保留/丢弃]

    style US fill:#e1f5fe
    style BR fill:#fff3e0
    style SD fill:#fff3e0
    style WGT fill:#f3e5f5
    style SAD fill:#e8f5e9
    style VC fill:#ffebee
    style FB fill:#e8eaf6

关键流程节点：

节点	硬性规则
设计门 (brainstorming 的 HARD-GATE)	未经设计+用户批准，禁止调用任何实现 skill、禁止写任何代码
计划门 (writing-plans)	每个任务必须拆到 2-5 分钟粒度，包含完整代码和命令
隔离门 (using-git-worktrees)	不在 main/master 分支直接开发；自动检测是否已在 managed worktree 中 [RELEASE-NOTES.md 13-15]
执行门 (subagent-driven-dev)	每个任务一个新鲜子代理 → spec 审查 → 代码质量审查 → 下一任务
验证门 (verification)	未运行验证命令就声称完成 = 撒谎
交付门 (finishing)	验证通过后，呈现 4 个选项（合并/PR/保留/丢弃）供用户选择

核心目的与关键原则

Superpowers 的根本目标是将 AI 编程代理从被动的代码编写者转变为系统化的工程师。它通过强制"后退一步"（step back）的方法论，在动手实现之前先梳理出规格说明并对设计进行签字确认，从而防止代理直接跳入代码 README.md 11-14。

什么是"后退一步"？

普通 AI 的行为是"反应式编码"——用户说"做个 Todo 列表"，AI 立刻开始写代码。这导致用户自己可能也没想清楚需求，AI 凭猜测实现，大概率返工。"后退一步"要求在动手前强制完成三个动作：

问清楚 — 通过 brainstorming 一次一个问题地澄清需求、约束、成功标准
想明白 — 提出 2-3 种方案，分析 trade-off，让用户选择
定下来 — 输出设计文档，获得用户签字确认后才能进入实现

brainstorming skill 中的 HARD-GATE 就是这道防线：未经设计 + 用户批准，禁止调用任何实现 skill、禁止写任何代码。哪怕用户说"就是个简单配置改一下"，也必须走这个流程。

这套方法论不是建议，而是强制协议。系统由 using-superpowers 元技能锚定：代理在任何任务之前必须检查相关技能，哪怕只有 1% 的概率适用也必须调用；这些技能是强制工作流，不是可选参考 README.md 170-172。

在此基础上，Superpowers 确立了四项工程原则：

原则	含义	代码中的实现
Test-Driven Development	先写测试、看它失败、再写最小代码通过它。如果你没看到测试失败，就不知道它测的是什么。	通过 `test-driven-development` skill 强制执行 RED-GREEN-REFACTOR 循环 README.md 164-165
Systematic over Ad-hoc	拒绝凭直觉猜修复。任何 bug 都必须经过复现→根因调查→假设验证→单点修复的科学流程。	用 `systematic-debugging` 的四阶段流程替代直觉 README.md 180-181
Complexity Reduction	不做多余的事。只实现当前明确需要的功能，不预支未来的复杂度。	强调 YAGNI（You Aren’t Gonna Need It）和 DRY（Don’t Repeat Yourself）README.md 15-16
Isolation & Safety	不在主分支上直接开发，每个任务在独立的工作区中进行，保证干净基线。	强制使用 git worktrees 进行工作区隔离和干净基线 README.md 158-159

每个 Skill 的深层思维与方法论

1. `using-superpowers` — 元技能入口：强制检查并调用适用的 workflow skill

核心思想：用外部规则覆盖本能。

LLM 的默认行为是"看到任务→凭直觉行动"。using-superpowers 要求在这个本能反应之前插入一个强制检查：“有没有 skill 适用？” 即使只有 1% 的概率，也必须调用。

具体方法——三层检查：

收到消息时：先问自己 “Might any skill apply?”（任何 skill 适用吗？）——不是"这个任务需要 skill 吗？“，而是"有没有 1% 的可能性”
进入 PlanMode 前：检查 “Already brainstormed?”（已经脑暴过了吗？）——防止重复脑暴或跳过脑暴
调用 skill 后：检查 “Has checklist?”（有检查清单吗？）——有就创建 TodoWrite 逐项执行

Red Flags —— 12 种自我欺骗想法：

想法	现实
“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 can check git/files quickly”	Files lack conversation context. Check for skills.
“Let me gather information first”	Skills tell you HOW to gather information.
“This doesn’t need a formal skill”	If a skill exists, use it.
“I remember this skill”	Skills evolve. Read current version.
“This doesn’t count as a task”	Action = task. Check for skills.
“The skill is overkill”	Simple things become complex. Use it.
“I’ll just do this one thing first”	Check BEFORE doing anything.
“This feels productive”	Undisciplined action wastes time. Skills prevent this.
“I know what that means”	Knowing the concept ≠ using the skill. Invoke it.

Skill Priority —— 多 skill 冲突时的决策顺序：

Process skills first（brainstorming, debugging）——决定 HOW to approach
Implementation skills second（frontend-design, mcp-builder）——决定 HOW to execute

例如：“Let’s build X” → brainstorming first, then implementation skills。

Skill Types —— 两种执行模式：

Rigid（TDD, debugging）：Follow exactly. Don’t adapt away discipline.
Flexible（patterns）：Adapt principles to context.

指令优先级：

用户显式指令（CLAUDE.md, GEMINI.md, direct requests）——最高
Superpowers skills —— 覆盖默认系统行为
默认系统提示 —— 最低

“Instructions say WHAT, not HOW. ‘Add X’ or ‘Fix Y’ doesn’t mean skip workflows.”

用户说"Add X"是在说 WHAT，不是 HOW。HOW 由 skill 决定。

2. `brainstorming` — 设计阶段：需求澄清、方案对比与设计文档输出（带 HARD-GATE）

核心思想：先理解，再构建；一个一个问题来。

brainstorming 不是"快速聊几句就开始写代码"，而是通过 9 个有序步骤，把模糊的想法转化为经过验证的设计文档。每一步都有明确的目标和产出。

九步 Checklist：

Explore project context — 先看文件、文档、最近提交，了解当前项目状态
Offer visual companion（如需要）— 如果话题涉及视觉问题（mockup、布局、架构图），单独发一条消息提供浏览器可视化工具，不与其他内容合并
Ask clarifying questions — 一次只问一个问题，理解 purpose/constraints/success criteria
Propose 2-3 approaches — 提供带 trade-off 的多种方案，给出推荐和理由
Present design — 分节呈现（architecture、components、data flow、error handling、testing），每节后询问"这看起来对吗？"
Write design doc — 保存到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并提交到 git
Spec self-review — 自检：有无 TBD/TODO？内部矛盾？范围失控？歧义？
User reviews written spec — 请用户审查书面 spec，用户批准前不能继续
Transition to implementation — 唯一合法出口：调用 writing-plans 创建实现计划

HARD-GATE —— 绝对禁止：

“Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.”

在获得用户批准之前：禁止调用任何实现 skill、禁止写任何代码、禁止搭建项目、禁止任何实现动作。这适用于每一个项目，无论看起来多简单。因为简单项目是未检验假设造成最大浪费的地方。

Key Principles：

One question at a time — 不要一次问多个问题，避免用户认知过载
Multiple choice preferred — 优先用选择题（比开放式更容易回答）
YAGNI ruthlessly — 从所有设计中砍掉不必要的功能
Explore alternatives — 总是先提出 2-3 种方案再确定
Incremental validation — 分节呈现设计，逐节确认，及早发现方向偏差
Be flexible — 当某部分不清楚时，愿意回溯澄清
Decompose large projects first — 如果需求涉及多个独立子系统（如"做一个包含聊天、文件存储、计费、分析的平台"），先分解为子项目，再对每个子项目走独立的 spec → plan → implementation 循环，不要试图在一个 design doc 里吞下整头大象

Visual Companion 的使用规则：

提供浏览器可视化工具时，必须满足：

独立消息发送：不能和澄清问题合并，单独一条消息只提供 companion
per-question 决策：即使对方接受了 companion，每个问题单独判断——文本问题用终端，视觉问题用浏览器
终端用于：需求问题、概念选择、trade-off 列表、scope 决策
浏览器用于：mockup、wireframe、布局对比、架构图

3. `writing-plans` — 计划阶段：将设计文档拆解为可逐任务执行的详细实施计划

核心思想：假设执行者零上下文、品味可疑。

计划不是写给自己看的备忘录，而是写给一个"不了解代码库、测试设计能力一般"的执行者的操作手册。每个步骤必须包含实际内容，不能留任何"你自己看着办"的空间。

计划文档结构：

每个计划必须以固定 header 开头：

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

---

这个 header 内嵌了执行指令——计划文件自带"谁来执行、怎么执行"的元信息。Goal、Architecture、Tech Stack 三个字段不是装饰，它们确保执行者在零上下文的情况下也能理解"要做什么、怎么做、用什么做"。

每个任务的五要素：

Files：Create/Modify/Test 的确切路径（如 src/path/file.py:123-145）
步骤：用 checkbox (- [ ]) 语法，每个步骤 2-5 分钟
代码：完整的代码块，不是伪代码
命令：精确的命令和预期输出（如 pytest tests/path/test.py::test_name -v → Expected: PASS）
提交：git add ... && git commit -m "..."

Plan Failures —— 绝对禁止出现的写法：

禁止写法	为什么错误
“TBD” / “TODO” / “implement later”	计划不是待办清单，每个步骤必须可执行
“Add appropriate error handling”	“appropriate” 是什么？具体代码呢？
“Write tests for the above”（无实际测试代码）	执行者不知道测什么
“Similar to Task N”	执行者可能不按顺序读，必须重复完整代码
引用未定义的类型/函数/方法	执行者找不到定义

三来自审：

Spec coverage：spec 的每个需求，都能指向一个实现它的任务吗？
Placeholder scan：搜索计划中的 red flag 模式（TBD、TODO、无代码的测试步骤等）
Type consistency：Task 3 的 clearLayers() 和 Task 7 的 clearFullLayers() 不一致——这是 bug

执行选择：

计划完成后提供两种执行方式：

Subagent-Driven（推荐）——派子代理逐任务执行
Inline Execution——在当前会话中批量执行

“Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste.”

"零上下文、品味可疑"不是贬低执行者，而是一种防御性假设——计划必须精确到即使执行者完全不了解背景也能执行，因为子代理确实没有你的会话历史。

4. `executing-plans` — 执行阶段（降级）：无子代理时在当前会话中逐步执行计划

核心思想：没有子代理时的降级执行——先停下来质疑计划，不要直接开干。

当平台不支持子代理时，这个 skill 接管执行。但它不是"直接按步骤跑"，而是要求你先批判性地审查计划——因为你要对自己的执行负责，没有子代理替你背锅。

执行三步法：

Load and Review Plan — 先读计划，批判性地检查：有问题吗？有疑问吗？有 gap 吗？如果有，先向用户提出，而不是带着疑问开始执行
Execute Tasks — 逐任务执行，每个任务标记 in_progress → 按步骤执行 → 运行验证 → 标记 completed
Complete Development — 完成后调用 finishing-a-development-branch

什么时候必须停下来问：

情况	行动
遇到 blocker（缺失依赖、测试失败、指令不清）	STOP，不要猜
计划有 critical gaps	STOP，执行前必须先修复计划
不理解某条指令	STOP，要求澄清
验证反复失败	STOP，不要强行推进

“Tell your human partner that Superpowers works much better with access to subagents.”

这个 skill 的第一句话不是"开始执行"，而是告诉用户"没有子代理时质量会显著降低"。这是诚实——不假装降级模式能达到同样的质量。

5. `subagent-driven-development` — 执行阶段（推荐）：派子代理逐任务实现 + spec/quality 双层审查

核心思想：上下文隔离 + 连续执行 + 质量门控。

执行计划时，每个任务派一个全新的子代理（不带历史上下文），完成后经过两层审查（spec 合规 + 代码质量），通过后才进入下一任务。控制器以调度和协调为主，保留跨任务的协调上下文，为子代理提取并传递完整的任务文本（不让子代理自己读计划文件）。

Per-Task 循环：

读取任务文本 ──► 派实现子代理 ──► 实现子代理提问? ──► 回答后继续
                      │
                      ▼
              实现、测试、提交、自审
                      │
                      ▼
              派 spec reviewer ──► 合规? ──► 否 ──► 修复 ──► 重审
                      │                          │
                      是                         ▼
                      ▼                    派 code quality reviewer
              派 quality reviewer ──► 通过? ──► 否 ──► 修复 ──► 重审
                      │                          │
                      是                         ▼
                      ▼                    标记完成，下一任务
              TodoWrite 标记完成

Implementer 的四种状态：

状态	含义	处理方式
DONE	完成，无问题	进入 spec 审查
DONE_WITH_CONCERNS	完成但有疑虑	先读疑虑，关于正确性/scope 的先解决，观察性的记录后Proceed
NEEDS_CONTEXT	缺少信息	提供缺失上下文，重新派发
BLOCKED	无法完成	1) 上下文问题→提供更多上下文重派；2) 推理不足→换更强模型；3) 任务太大→拆分；4) 计划错误→上报人类

模型选择策略：

不是"全部最强模型"，而是按角色分配：

机械实现（1-2 文件，明确 spec）：便宜快速模型
集成与判断（多文件协调、模式匹配、调试）：标准模型
架构/设计/审查：最强模型

关键约束：

串行执行：禁止并行派多个实现子代理（会冲突）
连续执行：不在任务间暂停问"Should I continue?"——只有在 BLOCKED、ambiguity 或全部完成时才停止
审查顺序不能颠倒：必须先 spec 合规（做了正确的事），再 code quality（事做得正确）
不能让子代理读计划文件：控制器提取完整任务文本直接提供，节省上下文

“Core principle: Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration”

"新鲜上下文"解决的是上下文污染问题——子代理带着前面任务的假设和错误进入新任务；"双层审查"解决的是方向偏离问题——spec reviewer 防止多做/少做/做错方向，quality reviewer 防止代码质量差。两者缺一不可。

6. `dispatching-parallel-agents` — 执行阶段（并行）：对多个独立问题并行派发代理分别调查修复

核心思想：独立问题独立调查，并行加速。

当有多个互不相关的失败时（不同测试文件、不同子系统、不同 bug），逐个排查是浪费。每个问题可以独立理解、独立修复，应该并行派发代理。

四步模式：

Identify Independent Domains — 按"什么坏了"分组：File A 测的是 tool approval flow，File B 测的是 batch completion，File C 测的是 abort functionality → 三个独立域
Create Focused Agent Tasks — 每个代理拿到：Specific scope（一个文件/子系统）、Clear goal（让这些测试通过）、Constraints（不改其他代码）、Expected output（返回根因总结+修复内容）
Dispatch in Parallel — 同时派发
Review and Integrate — 回来后：读每个总结、检查冲突、跑完整测试集、集成所有变更

代理提示的三要素：

要素	❌ 反例	✅ 正例
聚焦	“Fix all the tests” — agent 会迷失	“Fix agent-tool-abort.test.ts” — 范围明确
自包含	“Fix the race condition” — 不知道在哪	粘贴错误消息和测试名称
明确输出	“Fix it” — 你不知道改了什么	“Return summary of root cause and changes”

什么时候不能用：

失败相关（修一个可能修全部）→ 先一起调查
需要理解完整系统状态 → 不能拆
探索性调试（还不知道哪坏了）→ 先定位
共享状态（代理会互相干扰）→ 不能并行

7. `test-driven-development` — 质量内嵌：强制 RED-GREEN-REFACTOR 测试驱动开发循环

核心思想：如果你没看到测试失败，你就不知道它在测什么。

TDD 不是"有测试就好"，而是严格的执行顺序：写测试 → 看它失败 → 写最小代码通过 → 重构。跳过任何一步，就不是 TDD。

铁律：NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

写代码之前先写了测试？删掉它，重新开始。不是"保留作为参考"，不是"适配一下"，不是"看一眼"——Delete means delete。

Red-Green-Refactor：

阶段	做什么	验证点
RED	写一个最小测试，展示应该发生什么	测试以预期方式失败（不是 typo，不是 error）
Verify RED	运行测试，确认失败	如果测试通过了 → 它在测已有行为，修复测试；如果报 error → 修复 error 再跑
GREEN	写最简单的代码让测试通过	只加必要代码，不预支功能，不重构
Verify GREEN	运行测试，确认通过	其他测试也通过了？输出干净无 warning？
REFACTOR	清理代码	保持测试 green，不加新行为

常见理性化借口（全部无效）：

借口	为什么错误
“太简单了不用测”	简单代码也会 break，写测试只要 30 秒
“写完再补测试”	测试后立即通过 = 证明不了它测了什么
“手动测过了”	手动是 ad-hoc，没记录、不能重跑、容易遗漏
“删除 X 小时工作是浪费”	沉没成本谬误。保留无验证代码 = 技术债务
“TDD 是教条，我是 pragmatic”	“Pragmatic” 捷径 = 生产环境调试 = 更慢
" spirit 不是 ritual"	违反字面 = 违反精神

关键洞察：顺序决定意义

Tests-after 回答"What does this do?"（它做了什么）
Tests-first 回答"What should this do?"（它应该做什么）

测试后写时，你的大脑已被实现"污染"——你只会测已想到的情况，miss 边界条件。测试先写强迫你在实现前探索边界，此时思维还没有被具体实现束缚。

8. `systematic-debugging` — 质量内嵌：四阶段科学调试法（调查→分析→假设→修复）

核心思想：没有根因调查，就没有修复。症状修复 = 失败。

调试不是"看到报错→改一行→看好了没"，而是四阶段科学方法，每阶段完成才能进入下一阶段。

Phase 1: Root Cause Investigation（必须先完成才能提修复）

Read Error Messages Carefully — 不要跳过错误和 warning，它们常包含精确解决方案；完整读 stack trace，记录行号、路径、错误码
Reproduce Consistently — 能可靠触发吗？具体步骤是什么？每次都会发生吗？如果不可复现 → 收集更多数据，不要猜
Check Recent Changes — git diff、最近提交、新依赖、配置变更、环境差异
Gather Evidence in Multi-Component Systems — 对每个组件边界：记录输入什么、输出什么、环境/配置是否传递、每层状态
Trace Data Flow — 错误值从哪来？谁传了坏值？一直往上追溯到源头，在源头修，不在 symptom 修

Phase 2: Pattern Analysis

找相似的正常代码 → 对比差异（列出每一个差异，不管多小）
读参考实现的每一行（不要 skimming）
理解依赖：需要什么组件、配置、环境、假设

Phase 3: Hypothesis and Testing

形成单一假设：“I think X is the root cause because Y”，写下来
做最小改动验证假设，一次只变一个变量
验证前不继续：工作 → Phase 4；不工作 → 新假设
不知道就说"I don’t understand X"，不要装懂

Phase 4: Implementation

写失败测试复现 bug（MUST have before fixing）
单一修复：只修根因，不做"while I’m here"的改进，不捆绑重构
验证：测试通过？其他测试没坏？问题真解决了？
修 3 次还不行 → STOP，质疑架构：这不是"还没找到正确的修复方法"，而是底层架构本身有问题。典型信号：每次修复在不同地方暴露新的共享状态/耦合问题；修复需要"大规模重构"才能实现；修复一处却在别处制造新症状。此时应与人类伴侣讨论架构层面的重构，而非继续尝试第 4 次修复。

Red Flags —— 这些想法意味着你在瞎猜：

“Quick fix for now, investigate later”
“Just try changing X and see if it works”
“Add multiple changes, run tests”
“Skip the test, I’ll manually verify”
“It’s probably X, let me fix that”
“I don’t fully understand but this might work”
“One more fix attempt”（已经试了 2+ 次）

伴侣信号解码：

伴侣说	你的问题
“Is that not happening?”	你没有验证就假设了
“Will it show us…?”	你应该加诊断日志
“Stop guessing”	你在没有理解的情况下提修复
“Ultrathink this”	不要修 symptom，质疑底层
“We’re stuck?”（沮丧）	你的方法不管用

9. `requesting-code-review` — 审查阶段：每任务完成后主动发起 spec + quality 代码审查

核心思想：Review early, review often —— 问题在扩散前捕获。

不是"全部做完再找人看看"，而是每个任务后都审。Task 1 的问题如果不及时捕获，会扩散到 Task 2、3、4，最终导致大规模返工。

什么时候必须审：

Mandatory：subagent-driven development 的每个任务后、完成 major feature 后、merge 到 main 前
Valuable：卡住时（新视角）、重构前（基线检查）、修了复杂 bug 后

三步请求法：

Get git SHAs — BASE_SHA=$(git rev-parse HEAD~1)、HEAD_SHA=$(git rev-parse HEAD)
Dispatch reviewer — 用 Task 工具派 general-purpose reviewer，填充 skills/requesting-code-review/code-reviewer.md 模板：DESCRIPTION（做了什么）、PLAN_OR_REQUIREMENTS（应该做什么）、BASE_SHA/HEAD_SHA（范围）
Act on feedback — Critical（立即修）、Important（继续前修）、Minor（记录后处理）

审查上下文隔离：

审查者不继承你的会话历史。你只提供精心构造的 diff + 需求描述。这让审查者像第一次看到这个代码的人一样审视它——这正是人类审查者的视角。

10. `receiving-code-review` — 审查阶段：技术严谨地评估和处理外部代码审查反馈

核心思想：外部反馈 = 待评估的建议，不是待执行的命令。技术正确 > 社交舒适。

六步响应模式：

READ（完整读完，不反应）
→ UNDERSTAND（用自己的话重述，或问澄清）
→ VERIFY（对照代码库验证）
→ EVALUATE（对 THIS codebase 技术正确吗？）
→ RESPOND（技术确认或有理有据反驳）
→ IMPLEMENT（一次一项，每项测试）

禁止的回应：

❌ “You’re absolutely right!” / “Great point!” / “Thanks!” — 表演性，无技术信息量
❌ “Let me implement that now” — 还没验证就动手

正确的回应：

✅ 重述技术需求
✅ 问澄清问题
✅ 用技术推理反驳（如果建议错误）
✅ 直接改代码展示（行动 > 言语）

YAGNI 检查：

审查者说"完善实现"时，不要直接动手。先执行具体验证：

1	grep -r "endpointName" src/ tests/ --include=".ts" --include=".js"

没人调用 → 推回：“This endpoint isn’t called. Remove it (YAGNI)?”
有人调用 → 再实现完善版本

核心原则：你和审查者都向人类伴侣汇报。如果不需要这个功能，就不该加。

暗号机制：

当你觉得应该反驳但不确定时，可以说 “Strange things are afoot at the Circle K” ——向人类伴侣传递信号，不必在公开审查中直接对抗。*

这个 skill 建立了一个健康的审查文化——外部反馈是待评估的建议，不是待执行的命令。即使是经验丰富的审查者也可能不了解全部上下文。agent 被明确授权（甚至要求）在技术上有理有据地反驳。

“Signal if uncomfortable pushing back out loud: ‘Strange things are afoot at the Circle K’”

隐式沟通通道。当 agent 觉得应该反驳但不确定时，可以用这句暗号向人类伴侣传递信号，而不必在公开审查中直接对抗。这是一种保护机制——既维护了技术正确性，又避免了不必要的冲突。

11. `verification-before-completion` — 质量门禁：声称完成前必须提供新鲜验证证据

核心思想：未经验证就声称完成 = 不诚实。

铁律：NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

不是"我上次运行过测试"，而是"我在这条消息中运行了测试"。即使 5 分钟前通过，代码变了就不能引用上次结果。

五步法（Gate Function）：

IDENTIFY — 什么命令能证明这个声称？
RUN — 执行完整命令（fresh，不是部分）
READ — 读完整输出，检查 exit code，数失败数
VERIFY — 输出支持声称吗？不支持 → 报告实际状态+证据
ONLY THEN — 做出声称

Skip any step = lying, not verifying。

常见声称的验证标准：

声称	需要看到	不充分
“Tests pass”	测试输出：0 failures	上次运行的结果、“should pass”
“Build succeeds”	Build 命令 exit 0	Linter 通过 ≠ 编译通过
“Bug fixed”	原始症状的测试通过	代码改了 ≠ bug 修了
“Agent completed”	VCS diff 显示变更	Agent 报告"success"
“Requirements met”	逐行 checklist	测试通过 ≠ 需求全覆盖

回归测试的严格验证：

声称"bug 已修复"时，仅看测试通过是不够的。必须完成完整的 red-green 验证：

写测试 → 运行（通过）→ 撤销修复 → 运行（必须失败）→ 恢复修复 → 运行（通过）
跳过"撤销修复再验证失败"这一步 = 无法证明测试确实能捕获该 bug

语义全覆盖：

规则不仅适用于"tests pass"等明确声称，还包括 “Great!”、“Done!”、“Perfect!” 等暗示成功的情绪表达。ANY wording implying success without having run verification 都违反规则。

“From 24 failure memories: your human partner said ‘I don’t believe you’ - trust broken”

24 次失败记录中，伴侣说"I don’t believe you"。信任一旦因虚假声称破裂，就回不来了。

12. `finishing-a-development-branch` — 交付阶段：测试验证后提供合并/PR/保留/丢弃选项

核心思想：验证 → 检测环境 → 呈现选项 → 执行选择 → 清理。

不是"做完了， push 吧"，而是按状态机逐步收尾，每个步骤有明确前置条件。

Step 1: Verify Tests

先跑测试。如果失败 → 展示失败、停止，不进入 Step 2。

Step 2: Detect Environment

通过 GIT_DIR vs GIT_COMMON 判断当前状态：

状态	菜单	Cleanup
正常 repo	4 个选项	无 worktree
Named branch worktree	4 个选项	Provenance-based
Detached HEAD	3 个选项（无 merge）	外部管理，不清理

Step 3: Determine Base Branch

通过 git merge-base HEAD main（或 master）确定分支分岔点，或询问用户确认：

“This branch split from main - is that correct?”

Step 4: Present Options

不要加解释，直接呈现：

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

选项本身应该自解释。如果需要解释，说明措辞需要改进。

Step 5: Execute Choice

选项	Merge	Push	Keep Worktree	Cleanup Branch
1. Merge locally	✓	—	—	✓
2. Create PR	—	✓	✓	—
3. Keep as-is	—	—	✓	—
4. Discard	—	—	—	✓ (force)

选 2（PR）→ 不清理 worktree（用户需要它来迭代 PR feedback）
选 4（Discard）→ 要求输入 “discard” 确认

Step 6: Cleanup

Provenance-based：只清理 superpowers 自己创建的 worktree（在 .worktrees/、worktrees/、~/.config/superpowers/worktrees/ 下）；harness 创建的绝不碰。

来源归属（Provenance）。 worktree 清理不是"看到 worktree 就删"，而是先检查谁创建的。只有 superpowers 自己创建的（在特定路径下）才清理；harness（如 Claude Code 自身）创建的 workspace 绝不触碰。这防止了 phantom state——harness 看不到的清理操作会导致状态不一致。

13. `using-git-worktrees` — 环境隔离：强制在非 main 分支的独立 worktree 中开发

核心思想：不在 main 上开发，不在脏环境中工作。

四步隔离法（实际步骤编号为 0, 1, 3, 4）：

Step 0: Detect Existing Isolation — 先检查 GIT_DIR != GIT_COMMON（排除 submodule 误判）。如果已在 worktree 中 → 跳过创建，直接报告状态
Step 1: Create Isolated Workspace — 优先用平台原生工具（如 EnterWorktree，Step 1a）；无原生工具时走 git worktree fallback（Step 1b），按优先级选目录：.worktrees/ > worktrees/ > ~/.config/superpowers/worktrees/，并用 git check-ignore 确认目录被 ignore
Step 3: Project Setup — 自动检测并运行项目依赖安装（npm install、cargo build、poetry install 等）
Step 4: Verify Clean Baseline — 跑测试验证干净基线。如果测试失败 → 报告失败并询问是否继续，而不是默默带着 pre-existing issues 开工

Baseline Test：

创建后跑测试验证干净基线。如果测试失败 → 报告失败并询问是否继续，而不是默默带着 pre-existing issues 开工。

Never fight the harness：

如果平台已经提供了隔离（如 Claude Code 的 worktree），不要用自己的机制和它冲突。

14. `writing-skills` — 元技能：用 TDD 方法迭代编写和验证 skill 流程文档

核心思想：写 skill = 把 TDD 应用于流程文档。

TDD	Skill 创建
测试用例	压力场景 + 子代理
生产代码	SKILL.md
RED（失败）	Agent 无 skill 时违反规则
GREEN（通过）	Agent 有 skill 时遵守规则
Refactor	关闭漏洞

TDD for Skills 三步：

RED（Baseline） — 先不写 skill，直接给 agent 压力场景，观察它怎么失败。记录：做了什么选择？用了什么借口？什么压力触发了违规？
GREEN（写 Skill） — 针对那些具体的失败写 skill。不是泛泛而谈，而是解决观察到的具体理性化
REFACTOR（关漏洞） — Agent 找到新借口？加显式 counter。重测直到 bulletproof

Iron Law：NO SKILL WITHOUT A FAILING TEST FIRST

先写 skill 再补测试？删掉，重来。你会不自觉地写 agent 已经能通过的测试， miss 真正需要教的东西。

CSO（Claude Search Optimization）：

description 只写触发条件，不写流程摘要——实验发现：description 总结流程会导致 Claude 只读 description 跳过正文
❌ BAD: "Use for TDD - write test first..." → Claude 只做一次 review
✅ GOOD: "Use when implementing any feature or bugfix, before writing implementation code" → Claude 读完整 skill

对抗理性化的四层防御：

Close Every Loophole — 不是"删掉"，而是"删掉。不要保留为参考。不要适配。不要看。Delete means delete"
“Violating the letter = violating the spirit” — 切断"我在 follow spirit"的借口
Rationalization Table — 把测试中发现的每个借口列入表格：借口 vs 现实
Red Flags List — 让 agent 能自检是否在理性化

Skill Types：

Technique：具体步骤（condition-based-waiting, root-cause-tracing）
Pattern：思维方式（flatten-with-flags, test-invariants）
Reference：API/工具文档

Token Efficiency：

getting-started skills：<150 词
频繁加载 skills：<200 词
其他 skills：<500 词

技巧：把详细内容移到工具 help、用 cross-reference（REQUIRED SUB-SKILL: Use superpowers:test-driven-development）、压缩例子、消除冗余。

STOP：创建 Skill 后必须完成的部署流程

写完任何一个 skill 后，必须停止并走完整部署 checklist，不要批量创建多个 skill 而不逐个验证。部署未测试的 skill = 部署未测试的代码。

阶段	检查项
RED（Baseline）	创建压力场景（3+ 组合压力），无 skill 运行，记录基线行为和理性化借口
GREEN（写 Skill）	YAML frontmatter 完整（name、description）、description 以 “Use when…” 开头、只描述触发条件不描述流程、关键词覆盖、一个优质示例
REFACTOR（关漏洞）	识别新理性化借口、添加显式 counter、构建理性化表格、创建 Red Flags 列表、重测至 bulletproof
Quality Checks	小流程图仅用于非显而易见的决策、快速参考表、常见错误章节、无叙事故事、支持文件仅用于工具或重型参考
Deployment	提交到 git 并推送到 fork（如已配置）

Skill Types 与测试策略：

不同类型 skill 需要不同测试方法：

Discipline-Enforcing（如 TDD、verification）：用学术提问 + 压力场景测试，验证 agent 在最大压力下是否遵守规则
Technique（如 condition-based-waiting）：用应用场景 + 变体场景测试，验证能否正确应用技术
Pattern（如 reducing-complexity）：用识别场景 + 反例测试，验证能否正确识别何时适用
Reference（如 API 文档）：用检索场景 + 应用场景测试，验证能否找到并正确应用信息

四、多平台架构与实现细节

Superpowers 使用单一数据源（skills/ 目录），但通过平台特定的 hooks 和配置文件与各种 AI 环境进行独特集成。

平台集成映射

平台	集成机制	关键配置文件
Claude Code	Native marketplace / hooks	`.claude-plugin/plugin.json`
Cursor	Marketplace / hooks	`hooks-cursor.json`
OpenCode	JS plugin / prompt transform	`opencode.json`
Codex	Marketplace / Mirror tooling	`sync-to-codex-plugin` 脚本
Gemini CLI	Extension system	`gemini extensions install`
Copilot CLI	Plugin marketplace	`references/copilot-tools.md`

工具映射层

Skills 使用 Claude Code 的工具名（如 Skill、Task、TodoWrite）。对于其他平台，Superpowers 提供工具映射层：

Skill 引用	Copilot CLI 等价物
`Read`（文件读取）	`view`
`Skill` 工具	`skill`
`Task` 工具	`task` with `agent_type: "general-purpose"`
`TodoWrite`	`sql` with built-in `todos` table

v5.1.0 Named Agent 合并

从 v5.1.0 开始，系统移除了命名代理（如 superpowers:code-reviewer），改为使用自包含的 Task-dispatch 模型 [RELEASE-NOTES.md 8]：

合并：角色和检查清单（如代码审查）现在直接存放在 skill 目录内（如 skills/requesting-code-review/code-reviewer.md）[RELEASE-NOTES.md 48-50]
通用分发：Skills 现在分发 Task (general-purpose) 并附带特定提示模板，而非依赖外部代理定义 [RELEASE-NOTES.md 8, 51]

环境检测

Skills 如 using-git-worktrees 和 finishing-a-development-branch 包含环境检测逻辑（检查 GIT_DIR != GIT_COMMON），以确保在已处于 managed worktree 中时不会执行冗余操作 [RELEASE-NOTES.md 13-15]。

五、总结：Superpowers 的设计哲学

纪律 > 聪明：用强制流程防止 LLM 凭直觉跳过关键步骤
上下文隔离：子代理、worktree、独立审查——都是为了防止上下文污染
增量验证：每个阶段都有检查点和用户确认，不假设理解正确
反理性化：系统性地识别和封堵 LLM 找借口绕过规则的行为
证据文化：验证先于声称，测试先于实现，基线测试先于 skill 发布
人机协作：“your human partner” 是 deliberate 的称呼——强调 agent 是辅助者，人是决策者

Superpowers 是什么

Skills 工作流

核心目的与关键原则

每个 Skill 的深层思维与方法论

1. using-superpowers — 元技能入口：强制检查并调用适用的 workflow skill

2. brainstorming — 设计阶段：需求澄清、方案对比与设计文档输出（带 HARD-GATE）

3. writing-plans — 计划阶段：将设计文档拆解为可逐任务执行的详细实施计划

4. executing-plans — 执行阶段（降级）：无子代理时在当前会话中逐步执行计划

5. subagent-driven-development — 执行阶段（推荐）：派子代理逐任务实现 + spec/quality 双层审查

6. dispatching-parallel-agents — 执行阶段（并行）：对多个独立问题并行派发代理分别调查修复

7. test-driven-development — 质量内嵌：强制 RED-GREEN-REFACTOR 测试驱动开发循环

8. systematic-debugging — 质量内嵌：四阶段科学调试法（调查→分析→假设→修复）

9. requesting-code-review — 审查阶段：每任务完成后主动发起 spec + quality 代码审查

10. receiving-code-review — 审查阶段：技术严谨地评估和处理外部代码审查反馈

11. verification-before-completion — 质量门禁：声称完成前必须提供新鲜验证证据

12. finishing-a-development-branch — 交付阶段：测试验证后提供合并/PR/保留/丢弃选项

13. using-git-worktrees — 环境隔离：强制在非 main 分支的独立 worktree 中开发

14. writing-skills — 元技能：用 TDD 方法迭代编写和验证 skill 流程文档