Superpowers (obra/superpowers) 技术

追随者永远是胜利者

388人浏览 · 2026-06-21 17:24:50

追随者永远是胜利者 · 2026-06-21 17:24:50 发布

Superpowers (obra/superpowers) 技术

文档层级定位：软件（Software）
Superpowers 是一个可安装的插件 + 技能库，是针对 AI 编程 Agent 的可执行框架，属于"软件"层级。但它同时承载了一套完整的方法论（技术层级）——面向 Agentic 软件开发的结构化工作流。两个维度本文均有覆盖。

0. 定位声明

适用版本：    Superpowers v6.0.0（2026 年 6 月发布，当前最新主版本）
              文档同时标注 v5.1.0（2026.05.04）等关键历史版本的变更对比
平台支持：    11 个 harness：Claude Code、Cursor、OpenCode、OpenAI Codex
              （CLI / App）、Gemini CLI、GitHub Copilot CLI、Factory Droid、
              Kimi Code、Pi、Antigravity（Google）
前置知识：    了解 Claude Code / AI 编程 Agent 的基本使用方式；
              理解 Git 工作区（worktree）概念；了解 TDD 基础思想；
              建议了解 Claude Code 原生 Subagent / Dynamic Workflows 概念
              （本文第 8 节会详细对比两者关系）
不适用范围：  本文不覆盖 superpowers-lab（实验性技能仓库）；
              不覆盖 prime-radiant-inc/superpowers-evals（独立评测仓库）；
              不适用于不支持 Skill tool 或 SessionStart Hook 的平台；
              不覆盖 Prime Radiant 的商业企业版定制特性（需联系
              sales@primeradiant.com 获取）

1. 一句话本质

Superpowers 是什么？

你的 AI 编程助手默认是个"听话但没主见的实习生"——你说什么它就做什么，缺乏方法论约束，往往跳过测试、省略规划、每次解决方式都不一样。

Superpowers 给它装了一套大脑操作系统：一组规则手册（称为 Skill），在助手每次启动时自动注入，强制它先想清楚再动手——先讨论需求、再写计划、再分批执行、全程 TDD，每个任务完成后还有一道"质检关卡"。

装上后，你什么都不用改，直接说"帮我实现这个功能"，它就会自动走完整套专业研发流程，能不间断工作数小时而不偏离方向。截至 2026 年 6 月，它已是 GitHub 上星标数 22 万+、全球排名前 20 的开源项目，并被 Anthropic 收录进官方插件市场。

2. 背景与根本矛盾

历史背景

2025 年，AI 编程 Agent（Claude Code、Cursor、Codex 等）的能力快速跃升，但研发团队很快发现：Agent 的能力上限很高，但行为下限极低。Jesse Vincent（fsck.com 博主，Keyboardio 创始人）将这套问题归因于"Agent 拥有执行力，但缺乏工程方法论的约束载体"，于 2025 年 10 月发布了 Superpowers 初版。

增长曲线（⚠️ 部分数据来自第三方观察站点，未经官方核实）：

时间节点	GitHub Stars	关键事件
2025-10（首发）	~7k-90k（首月暴涨）	初版发布，Hacker News 热议
2026-02	~57.5k	早期稳定增长期
2026-03-31（v5.0.7）	—	v5.0 重写技能系统，三月稳定迭代
2026-05-03	~177,000	五周内新增 6,000+ stars
2026-05-04（v5.1.0）	—	史上最大单次更新之一
2026-06（v6.0）	224,691+，约 2 万 forks，全球排名 #18	当前最新主版本

项目背后的运营主体是 Prime Radiant Inc.（Jesse Vincent 所在公司），目前提供企业级商业支持（联系 sales@primeradiant.com），并在公开招聘"Superpowers 社区工程师"全职岗位。项目本身仍是 MIT 开源协议，无付费门槛，可选支持渠道为 GitHub Sponsors。

根本矛盾（Trade-off）

维度	矛盾的两极	Superpowers 的取舍
自由 vs 纪律	Agent 自由发挥 vs 强制流程约束	选择强纪律：Skill 里写的是硬性规则，不是建议
速度 vs 质量	跳过 TDD 快速出码 vs RED-GREEN-REFACTOR 严格循环	选择质量优先，但 v6.0 起开始系统性压缩"质量税"（见第 5 节）
单一 Agent vs 多 Agent	一个会话做所有事 vs 每任务派发新 Subagent	选择隔离执行：保持 Orchestrator 上下文干净，每任务 fresh context
省钱 vs 省心	控制 token 成本 vs 多重审查带来的高质量	v6.0 起：用"单 Reviewer 双裁决+按需复核"取代"双 Reviewer 全量复核"，token 降约 50%
谁来"持有计划"	Agent 在对话中逐轮决定下一步 vs 把计划写成可重跑的代码	Superpowers 坚持"Agent 是编排者"，与 Claude Code 原生 Dynamic Workflows（计划写进代码）形成尚未完全调和的张力（详见第 8 节）

3. 核心概念与领域模型

3.1 关键术语表（含 v6.0 新增概念）

术语	费曼式定义	正式定义
Skill	一份写给 AI 看的"标准操作手册"，告诉它在什么情况下必须做什么	存储在 SKILL.md 文件中的结构化指令，包含触发条件（YAML frontmatter）和执行规范（Markdown body）
Harness（宿主平台）	Skill 实际运行的"容器"，不同容器内置的工具不完全一样	Superpowers 支持的 AI 编程平台统称，当前共 11 个，每个 harness 各自维护一份 bootstrap + 工具映射文档
Bootstrap	“开机引导程序”，开机时注入的最小指令集	using-superpowers 技能内容，由 SessionStart Hook 直接注入上下文
Orchestrator（控制器）	主 Agent，负责读计划、派任务、审代码，但不自己写代码	使用 subagent-driven-development（SDD）技能管理整个实现过程的角色
task-reviewer-prompt.md（v6.0 新增）	一份"二合一质检单"，一次检查同时出具"是否符合需求"和"代码质量如何"两个结论	取代 v5.x 时代的 spec-reviewer-prompt.md + code-quality-reviewer-prompt.md 两份独立文件，单次 Reviewer dispatch 即可产出两个verdict
"无法从 diff 判断"裁决（v6.0 新增）	Reviewer 看完代码改动后说"这条需求涉及的代码我没看到改动，你自己再查查"	一种新增的审查结论类型，用于标记 Review 范围之外（未被改动的既有代码）才能验证的需求点，避免 Reviewer 强行猜测或漏判
task-brief / review-package（v6.0 新增）	把"这个任务要做什么"和"这次改了什么"写成文件，而不是粘贴一大段文字到 prompt 里	两个新脚本，分别把任务文本和审查 diff 写入文件供 Subagent 读取，避免"粘贴 diff 占满最贵的上下文"这一最大的 Reviewer 成本来源
`.superpowers/sdd/`（v6.0 新增）	SDD 过程中产生的"草稿纸"，放在一个 Git 会自动忽略、不会被提交的角落	任务简报、实现报告、审查 diff、进度台账（progress ledger）的存放目录，v6.0 之前曾尝试放在 `.git/sdd/` 但因 Claude Code 将 `.git/` 设为受保护路径而被拒绝写入，遂改为工作区内的自忽略目录
Progress Ledger（进度台账）（v6.0 新增）	一本"干到哪了"的流水账，让控制器哪怕"失忆"（context 丢失/compact）也能从台账接着干，而不是从头重做	记录每个任务完成状态和审查结果的持久化文件，存放于 `.superpowers/sdd/`
Dynamic Workflows（动态工作流）	Claude Code 原生功能：不再由 AI 一轮一轮决定下一步，而是先写一段 JavaScript 调度脚本，再让脚本去指挥一群 Subagent 干活	Anthropic 于 2026-05-28（随 Opus 4.8）推出的研究预览功能，单次运行最多调度 1,000 个 Subagent（同时并发上限 16 个），编排逻辑写进代码而非留在模型的上下文轮次里
Skill Priority	技能优先级，越具体越优先	同名 Skill 的覆盖顺序：project skills > personal skills > superpowers plugin skills（v6.0 起这一优先级机制保持不变）

3.2 领域模型（v6.0 架构图）

┌──────────────────────────────────────────────────────────────────┐
│                  Superpowers v6.0 领域模型                          │
│                                                                  │
│  ┌──────────────┐     SessionStart Hook (sync)                  │
│  │  AI Agent    │◄────────────────────────────────────────────┐ │
│  │  (主会话)    │  注入 using-superpowers bootstrap            │ │
│  └──────┬───────┘                                              │ │
│         │ 每次响应前检查 Skill                                   │ │
│         ▼                                                       │ │
│  ┌──────────────┐                                               │ │
│  │  Skill tool  │─────► 三层 Skill 搜索路径（含 11 个 harness     │ │
│  └──────────────┘       各自的工具映射 reference）：              │ │
│                         1. project skills（项目级）              │ │
│                         2. personal skills（个人级）              │ │
│                         3. superpowers skills（插件内置）◄──────┘ │
│                                                                  │
│  核心 Skill 触发链（线性工作流，结构未变）：                          │
│                                                                  │
│  brainstorming                                                   │
│       │ <HARD-GATE> + 内联自审（v5.1.0 起，不再派 Subagent 审 Spec） │
│       ▼                                                          │
│  using-git-worktrees                                              │
│       │ 优先检测既有隔离 → 用原生工具 → 最后才 fallback 到 git worktree│
│       │ Worktree 落地路径：项目内 .worktrees/（v6.0 起，废弃          │
│       │ 全局 ~/.config/superpowers/worktrees/）                    │
│       ▼                                                          │
│  writing-plans                                                    │
│       │ 内联自审（v5.1.0 起，~30 秒抓 3-5 个真实 bug，                │
│       │ 取代过去 ~25 分钟的 Subagent 审查回合）                       │
│       │ 在支持 Subagent 的平台上，强制走 subagent-driven-development │
│       │（不再提供 executing-plans 选项；后者仅保留给无 Subagent 能力   │
│       │ 的 harness 作为 fallback）                                  │
│       ▼                                                          │
│  ┌──────────────────────────────────────────────┐                │
│  │  subagent-driven-development（v6.0 重写）       │                │
│  │   ┌──────────────────────────────────────┐    │                │
│  │   │ Orchestrator 预检计划（Pre-flight）：    │   │                │
│  │   │ 提前发现计划内部矛盾/潜在审查会打回的问题 │   │                │
│  │   │   │                                    │   │                │
│  │   │   ▼                                    │   │                │
│  │   │ 写 task-brief 文件 → 派发 Implementer    │   │                │
│  │   │ Subagent（fresh context，必须明确         │   │                │
│  │   │ 指定模型，不允许"不指定→继承会话最贵模型"） │   │                │
│  │   │   ▼                                    │   │                │
│  │   │ 写 review-package 文件（diff 进文件，      │   │                │
│  │   │ 不再粘贴进 prompt）                       │   │                │
│  │   │   ▼                                    │   │                │
│  │   │ 单一 task-reviewer-prompt.md             │   │                │
│  │   │  → 一次产出两个裁决：Spec 合规 + 代码质量 │   │                │
│  │   │  → 或返回"无法从 diff 判断"，交还控制器自查│   │                │
│  │   │ （Reviewer 只读：不得 checkout/touch 工作区/│   │                │
│  │   │  分支；控制器不得"教 Reviewer 忽略某项发现"）│   │               │
│  │   │   ▼                                    │   │                │
│  │   │ 更新 Progress Ledger → 下一任务            │   │                │
│  │   └──────────────────────────────────────┘    │                │
│  │   全部任务完成后：单次"全分支"终审               │                │
│  │   （在最强模型上跑一次，取代逐任务反复全量复核）  │                │
│  └──────────────────────────────────────────────┘                │
│                                                                  │
│  贯穿实现全程：test-driven-development                            │
│       RED (写失败测试) → GREEN (最小实现) → REFACTOR                │
│                                                                  │
│  结尾：finishing-a-development-branch                              │
│       基于"创建者归属（Provenance）"的清理：只清理 .worktrees/        │
│       内由 Superpowers 自己创建的工作区，不动其他来源的目录            │
│       Forge-neutral：不再硬编码 gh pr create，按可用工具自适应推送   │
└──────────────────────────────────────────────────────────────────┘

3.3 v6.0 Review 流程重写：为什么要改？

这是 v6.0 的"headline change"，值得单独展开费曼解释：

以前（v5.x 及更早）： 每个任务做完，派两个不同的 Subagent 分别审——一个专门看"做的对不对（合规）“，一个专门看"代码写得好不好（质量）”。两个 Reviewer 各自重新 git diff、各自重建上下文，成本高，而且控制器可以"教"某个 Reviewer 忽略某个问题、或者自己提前给问题定级，容易被"绕过"。

现在（v6.0）： 改成"一个 Reviewer，两个结论"——读一次 diff，同时给出"合规吗"和"质量如何"两个判断，省掉重复建上下文的成本。diff 和任务说明都提前写成文件交给 Reviewer 读，而不是粘贴进 prompt（粘贴 diff 是过去最贵的成本来源）。Reviewer 被设计成"只读、不可被说服"——不能 checkout 代码，不能被控制器要求"这条先别报"，遇到自己看不出来的情况（比如需求点落在没被改动的旧代码里）就老实说"我判断不了"，交还给控制器去人工核实。最后不再每个任务都全量复核一遍，而是全部任务做完后，在最强的模型上跑一次"全分支终审"。

量化效果（⚠️ 官方原话强调"这些数字不会在所有 harness 和工作负载上都成立"）： 在 Claude Code 和 Codex 上的内部评测中，v6.0 产出质量相近的结果，速度提升约 2 倍，token 消耗减少近 50%。

这套重写的产出过程本身也值得一提：Prime Radiant 团队曾短暂获得 Anthropic 一款内部研究工具（代号 “Fable”，后下架/未公开发布）的访问权限，用它跑了一整夜的"自动研究循环"——预先登记 25+ 个假设，逐一做实验验证（如"合并两个 Reviewer 是否能省 token"），并把过程记录在仓库的实验日志里。⚠️ 存疑：Fable 工具本身的能力边界和后续状态未公开，不构成 Anthropic 官方产品承诺。

4. 对比与选型决策

4.1 同类方案/相邻技术横向对比（v2 更新）

维度	Superpowers	Claude Code 原生 Dynamic Workflows	手写 CLAUDE.md	无约束 Agent
谁持有"计划"	Agent 逐轮决定（轮次留在上下文里）	一段可重跑的 JS 脚本持有计划（中间结果留在脚本变量里，不进上下文）	取决于用户每次怎么提示	无计划
并发规模	SDD 模式下任务间基本顺序执行，Subagent 之间彼此独立但不强调海量并行	单次运行最高 1,000 个 Subagent，16 个同时并发	N/A	N/A
是否支持任务中途追问	✅ SDD 中 Implementer 可向控制器提问、等待回答后继续	❌ 运行中不接受用户输入（只有权限确认弹窗会暂停）	N/A	N/A
强制工程纪律（TDD/规划）	✅ 核心卖点	❌ 不内置方法论，纯编排能力	⚠️ 完全自定义	❌
跨平台	11 个 harness	仅 Claude Code（CLI/Desktop/VS Code 扩展，及 API/Bedrock/Vertex/Foundry）	仅 CLAUDE.md 平台	全平台
官方/第三方	第三方开源项目（已进官方插件市场分发）	Anthropic 官方原生功能	N/A	N/A
成本特征	v6.0 后约为单 Agent 模式的 2-3x token（较 v5.x 的 3-5x 已显著下降）	“token 饥渴”，官方建议先用小范围任务校准消耗后再大规模启用	低	最低

4.2 选型决策树（v2：纳入 Dynamic Workflows 选项）

你在用 Claude Code / Cursor / Codex / OpenCode / Gemini CLI 等做软件开发？
│
├─ 是 → 任务规模如何？
│       │
│       ├─ 中小型功能开发，需要完整工程纪律（TDD/规划/质检）
│       │       → ✅ 使用 Superpowers（核心场景，SDD 编排）
│       │
│       ├─ 超大规模任务（数百文件迁移、全代码库审计、
│       │   需要多角度交叉验证的研究）且在 Claude Code 上
│       │       → 优先考虑原生 Dynamic Workflows（专为该场景设计，
│       │         省去 Agent 逐轮决策的 token 开销）
│       │       → ⚠️ 注意：截至 2026 年 6 月，社区内对"SDD 与
│       │         Dynamic Workflows 该如何配合"尚无官方定论
│       │         （见第 8 节），二者同时使用可能导致重复编排
│       │
│       └─ 快速脚本/一次性任务，不需要结构化流程
│               → ❌ Superpowers 会增加摩擦，直接用 Agent 原生能力
│
└─ 否 → ❌ Superpowers 当前不支持你的平台（需为 11 个 harness 之一）

4.3 技术栈位置（更新：与 Dynamic Workflows 并列）

用户意图
   │
   ├──► [Superpowers 方法论层] ──► Claude Code / Cursor / ... (平台层) ──► LLM
   │         │
   │         ├── brainstorming → writing-plans → subagent-driven-development → ...
   │         └── 强调：Agent 始终是编排者，逐轮决策
   │
   └──► [Claude Code 原生 Dynamic Workflows]（仅 Claude Code）──► LLM
             │
             └── 强调：编排逻辑写进可重跑的 JS 脚本，模型只负责"思考"那一部分

两条路径目前是平行存在、尚未官方整合的两种"给 Agent 装纪律/装规模"的方式（详见第 8 节）。

5. 工作原理与实现机制

5.1 静态结构：仓库组织（v6.0 更新）

obra/superpowers/
├── .claude-plugin/
│   └── marketplace.json          # Claude Code 插件市场元数据
├── hooks/
│   ├── hooks.json                # SessionStart hook 注册（async: false）
│   └── session-start.sh          # Bootstrap 注入脚本（dual-emit JSON，
│                                  # 同时兼容 Claude 的 hookSpecificOutput
│                                  # 和 Cursor 等平台的 additional_context）
├── skills/                       # 技能库主目录（⚠️ 存疑：历史上曾短暂
│   │                              # 拆分到独立仓库 obra/superpowers-skills，
│   │                              # 但截至 2026 年 6 月主仓库内仍直接维护
│   │                              # skills/ 目录，具体演进路径未完全公开核实）
│   ├── brainstorming/
│   │   └── SKILL.md
│   ├── test-driven-development/
│   │   ├── SKILL.md
│   │   └── testing-anti-patterns.md
│   ├── subagent-driven-development/
│   │   ├── SKILL.md
│   │   ├── task-reviewer-prompt.md       # v6.0 新增，取代下面两个文件
│   │   ├── spec-reviewer-prompt.md       # v6.0 起废弃
│   │   └── code-quality-reviewer-prompt.md # v6.0 起废弃
│   ├── requesting-code-review/
│   │   ├── SKILL.md
│   │   └── code-reviewer.md      # v5.1.0 起自包含（不再依赖外部 named agent）
│   ├── writing-plans/
│   │   └── SKILL.md
│   ├── using-git-worktrees/
│   │   └── SKILL.md
│   ├── finishing-a-development-branch/
│   │   └── SKILL.md
│   ├── using-superpowers/        # Bootstrap 技能（核心）
│   │   ├── SKILL.md
│   │   └── references/           # v6.0：每个 harness 一份工具映射文档
│   │       ├── codex-tools.md
│   │       ├── copilot-tools.md
│   │       ├── gemini-tools.md
│   │       ├── pi-tools.md
│   │       └── antigravity-tools.md
│   └── writing-skills/           # 元技能：如何写 Skill
│       └── SKILL.md
├── docs/
│   ├── README.opencode.md
│   ├── README.codex.md
│   └── porting-to-a-new-harness.md   # v6.0 新增：移植到新平台的指南
├── .superpowers/sdd/              # 运行时生成（git-ignored 工作区草稿）
│   ├── task-briefs/
│   ├── implementer-reports/
│   ├── review-diffs/
│   └── progress-ledger.json
└── RELEASE-NOTES.md

已移除的目录/机制：

agents/ 目录及 agents/code-reviewer.md（v5.1.0 移除，Superpowers 现在零具名 Agent，所有 Subagent 均为 general-purpose dispatch + 提示词模板）
~/.config/superpowers/worktrees/（全局 worktree 目录，v6.0 移除，worktree 改为落地在项目内）
旧版 /brainstorm、/write-plan、/execute-plan Slash 命令（v5.1.0 移除，统一通过 Skill 直接调用，如 superpowers:brainstorming）
evals 子模块（v6.0 不再随插件一起分发，独立仓库 prime-radiant-inc/superpowers-evals，避免拖垮普通用户的插件安装）

5.2 动态行为：Session 初始化时序（机制未变，细节更新）

用户启动 Claude Code Session
        │
        ▼
Claude Code 触发 SessionStart 事件
        │
        ▼
hooks/hooks.json → 同步执行 session-start.sh (async: false)
        │
        ├── 1. 检查 Superpowers 是否已安装，如需更新则 git pull
        ├── 2. 读取 skills/using-superpowers/SKILL.md 内容
        ├── 3. 通过 escape_for_json() 安全转义后注入 session 上下文
        └── 4.（v6.0 新增）针对不同 harness dual-emit：
              同时输出 hookSpecificOutput（Claude Code 格式）和
              additional_context（Cursor 等其他平台格式），
              避免重复注入两份上下文
                    │
                    ▼
        Agent 第一次响应前，using-superpowers 内容已在 context 中
                    │
                    ▼
        Agent 收到用户消息 → 先检索相关 Skill →
        在支持 Subagent 的平台（Claude Code、Codex 等）上
        writing-plans 之后强制进入 subagent-driven-development，
        不再像早期版本那样把"SDD 还是 executing-plans"留给 Agent 选

5.3 动态行为：v6.0 完整开发工作流时序（更新版）

用户："帮我实现用户登录功能"
        │
        ▼
[brainstorming skill 触发]
  Agent: 提出澄清问题 → 逐段展示设计方案 → 内联自审（无需派 Subagent）
  <HARD-GATE>: 用户未确认设计 → 不得进入 writing-plans
        │  用户: "设计方案确认，开始吧"
        ▼
[using-git-worktrees skill 触发]
  优先检测：是否已经在 harness 管理的隔离工作区里？
    是 → 直接复用，不重复创建
    否 → 检查有无原生隔离工具 → 都没有 → fallback 到
         git worktree add（落地到项目内 .worktrees/，并校验已被 gitignore）
        │
        ▼
[writing-plans skill 触发]
  生成实现计划 + 内联自审（~30 秒抓 3-5 个真实 bug，
  如出生点位置错误、API 不匹配、随机种子 bug、网格索引错误）
        │
        ▼
[subagent-driven-development skill 触发，v6.0 重写]
  Pre-flight：控制器先通读整个计划，找出内部矛盾和
              "审查时大概率会被打回"的隐患，一次性提出
        │
        ▼
  循环（每个任务）：
    ├── 写 task-brief 文件
    ├── 派发 Implementer Subagent（fresh context，显式指定模型）
    │         │
    │         ▼ [test-driven-development skill 在 Subagent 内触发]
    │     RED → GREEN → REFACTOR → commit → 自报实现结果到文件
    │     （TDD 场景下需附带 red/green 证据）
    │         │
    ├── 写 review-package 文件（diff 落盘，不进 prompt 正文）
    ├── 派发单一 task-reviewer Subagent（只读，不可被说服跳过问题）
    │     → 返回 Spec 合规 + 代码质量 两个裁决
    │     → 或返回"无法从 diff 判断"，交还控制器人工核实
    └── 更新 Progress Ledger → 下一个任务
        │  所有任务完成
        ▼
  单次"全分支终审"（最强模型跑一遍，而非逐任务重复）
        │
        ▼
[finishing-a-development-branch skill 触发]
  基于 Provenance 的清理（只清理自己创建的 .worktrees/ 内容）
  → Forge-neutral 推送（不再硬编码 gh pr create）

5.4 关键设计决策（v2：新增三个 v6.0 决策）

决策 1：Skill body 描述触发条件，不描述工作流（沿用自 v1）

为什么这样： 避免 description 字段被 Agent 当作执行规范直接套用，跳过读取完整 SKILL.md。
代价： description 对人类的可读性下降。

决策 2：Subagent 完全隔离，不继承 Orchestrator 上下文（沿用自 v1）

为什么这样： 避免历史噪音干扰任务聚焦，保持执行结果可预测、可重现。
代价： Orchestrator 需要显式构造每个 Subagent 的上下文。

决策 3（v5.1.0 新增）：把"审查"从派 Subagent 改为"内联自审"，仅限 brainstorming 和 writing-plans 阶段

为什么这样： 团队做了跨 5 个版本（v3.6.0~v5.0.4，每版 5 次试验）的回归测试，发现"有没有派 Subagent 复核 brainstorm/计划"对最终质量（任务规模、数量、质量分）没有可测量的差异，但派 Subagent 复核会多花约 25 分钟。于是改为控制器自己花 30 秒读一遍、自己挑错。
代价： 这一决策只适用于"设计/计划"这种偏静态、可由模型自检的产物；对"代码实现是否真的做对了"这种需要独立视角交叉验证的环节（即 SDD 的任务级 Review），团队保留了独立 Subagent 复核机制——说明团队对"什么时候省审查、什么时候不能省"做了精细区分，而不是一刀切。

决策 4（v6.0 新增）：Review 从"双 Subagent 各自全量复核"改为"单 Subagent 双裁决 + 末尾一次终审"

为什么这样： 实测发现旧机制的两大成本：(1) 两个 Reviewer 各自要重新跑 git 命令重建 diff 上下文，是审查阶段里最贵的单项开销；(2) 控制器有"调教 Reviewer"的能力（比如要求某个发现"最多算 Minor"），实测中真的有控制器这么做并让缺陷漏过。新设计用文件化 diff 交付解决成本问题，用"Reviewer 只读 + 不可被控制器指挥忽略发现"解决可信度问题。
代价： Reviewer 拿到的是静态文件快照，如果某个需求点落在 diff 之外的既有代码里，Reviewer 没法验证——这正是新增"无法从 diff 判断"裁决的原因，把这部分判断责任明确转交回控制器，而不是让 Reviewer 硬猜。

决策 5（v6.0 新增）：要求每次 Subagent dispatch 必须显式指定模型

为什么这样： 实测中发现，如果不强制指定，控制器会习惯性地不点名模型，而"不点名"在很多 harness 里的默认行为是继承当前会话最贵的模型——曾有一次运行因此把全部 26 个 Reviewer 都跑在了顶级模型上，造成不必要的成本。强制显式指定，把模型选择这一决策权从"隐式继承"改为"控制器必须主动做出的判断"。
代价： 增加了控制器侧的认知负担（每次 dispatch 都要想清楚"这个任务配得上哪个模型档位"），但避免了成本失控的尾部风险。

6. 使用实践与故障手册

6.1 安装方式（v2 更新：新增官方市场渠道）

Claude Code（推荐，二选一）：

# 方式一：通过 Anthropic 官方插件市场（自 2026-01-15 起上架，推荐）
/plugin install superpowers@claude-plugins-official

# 方式二：通过 Superpowers 自家市场
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

安装后重启 Claude Code，验证：

新建会话后直接问："你有哪些 superpowers？"
Agent 应能列出 skills 并主动提及 Superpowers

Cursor：

通过 Cursor 插件市场命令安装：/add-plugin superpowers
（注意：旧文档中的 /plugin-add 命令已随 Cursor 2.5 更名为 /add-plugin）

OpenCode（已升级为 git 包式安装，不再需要手动 symlink）：

// opencode.json
{
  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
}

若之前用 git clone + symlink 的旧方式安装过，需先手动清理：

rm -f ~/.config/opencode/plugins/superpowers.js
rm -rf ~/.config/opencode/skills/superpowers
rm -rf ~/.config/opencode/superpowers

Kimi Code（v6.0 新增支持）：

从 Kimi 自带的插件市场安装，或直接从仓库安装（含独立的 plugin manifest）

Pi（v6.0 新增支持）：

Pi 原生支持 Skill，无需兼容层（compatibility shim），
通过 session-start 扩展自动注册 skills 并注入 bootstrap

Antigravity（Google，v6.0 新增支持）：

直接安装插件，从第一条消息起即自动 bootstrap
（已通过"用 React 做一个 Todo List"标准验收测试）

Codex / Gemini CLI / GitHub Copilot CLI / Factory Droid：

均通过各自平台的 .codex/INSTALL.md、.gemini/INSTALL.md 等说明文档
按平台规范手动接入；详见 docs/porting-to-a-new-harness.md（v6.0 新增）

6.2 核心 Skill 速查（v2 更新）

Skill 名称	触发场景	v6.0 关键变化
`brainstorming`	开始任何新功能构建前	沿用 HARD-GATE，复核改为内联自审（v5.1.0 起）
`using-git-worktrees`	设计确认后	检测优先级变为"既有隔离 > 原生工具 > git worktree 兜底"；worktree 落地路径改为项目内
`writing-plans`	有已确认的设计后	复核改为内联自审；不再提供 SDD/executing-plans 二选一（有 Subagent 能力则强制 SDD）
`subagent-driven-development`	有实现计划时（任务独立，平台支持 Subagent）	v6.0 全面重写：单 Reviewer 双裁决、Pre-flight 检查、文件化交付、强制指定模型、终审取代逐任务复核
`executing-plans`	仅用于不支持 Subagent 的 harness	现在明确告知用户"在支持 Subagent 的平台上效果更好"
`test-driven-development`	实现任何功能/修复任何 Bug	规则未变，新增对 testing-anti-patterns 参考文档的内部链接修复
`requesting-code-review`	任务间隙请求复核	现已自包含（persona + checklist + dispatch 模板合一），不再依赖外部具名 Agent；移除"每 3 个任务暂停一次"的旧节奏，改为"自然检查点"+ 持续执行
`finishing-a-development-branch`	分支开发完成后	Provenance 清理（只清理自建 worktree）；Forge-neutral（不再硬编码 `gh pr create`）

6.3 自定义 Skill 开发（机制未变）

<!-- ~/.claude/skills/my-custom-skill/SKILL.md -->
---
name: my-custom-skill
description: Use when doing [具体触发条件，不写流程]
---

# My Custom Skill

[你的规范内容：何时做什么，必须遵守的规则，checklist，等]

优先级规则未变： 个人 Skill（~/.claude/skills/）会覆盖同名 Superpowers Skill；项目级覆盖个人级。

⚠️ 注意（v2 新增提示）： 官方仓库目前不太接受新增 Skill 的外部贡献，且明确要求任何 Skill 改动必须在全部 11 个支持的 harness 上都验证通过。如果你只是想为自己项目定制行为，建议走"项目级/个人级 Skill 覆盖"路线，而不是直接向主仓库提 PR。

6.4 故障手册（v2：新增 v6.0 相关故障）

【故障 1：Agent 忽略 Skill，直接开始写代码】（沿用自 v1）
- 现象：说"帮我实现 X"，Agent 直接给代码，没有进入 brainstorming 流程
- 根本原因：SessionStart Hook 未成功执行，或使用了旧版 Read tool 而非 Skill tool
- 应急：
  1. 检查插件版本是否为 v6.0.0+
  2. 手动触发："请先使用 superpowers:brainstorming 再帮我规划这个功能"
     （v5.1.0 起必须用完整命名空间调用，纯 "brainstorm" 会报 "Unknown skill"）

【故障 2（v6.0 新增）：进度台账丢失】
- 现象：长时间运行的 SDD 任务中途中断，重新进入后控制器从头开始，
        看不到之前的进度记录
- 根本原因：.superpowers/sdd/ 是 Git 工作区内的"自忽略"草稿目录，
            如果运行过 git clean -fdx，会把这个目录一并清空
- 预防：避免在 SDD 运行期间或刚结束后执行 git clean -fdx
- 应急：通过 git log 查看历史 commit 中是否有可恢复的进度信息
        （官方说明明确指出："recover from git log if that happens"）

【故障 3（v6.0 新增）：Worktree 路径在升级后"消失"】
- 现象：升级到 v6.0 后，过去存放在
        ~/.config/superpowers/worktrees/ 的工作区找不到了
- 根本原因：v6.0 移除了全局 worktree 目录机制，worktree 改为
            落地在项目内的 .worktrees/（或已有的 worktrees/）
- 应急：手动迁移历史 worktree 内容到项目目录，或直接重新创建

【故障 4（v6.0 新增）：finishing-a-development-branch 误删了不该删的 worktree】
- 现象（历史 bug，v6.0 已修复）：执行 "Option 2"（清理）时连带删除了
        不是 Superpowers 自己创建的工作区
- 根本原因：v6.0 之前没有"创建者归属（Provenance）"判断逻辑
- 现状：v6.0 起已修复，清理逻辑现在只针对 .worktrees/ 内由
        Superpowers 自己创建的内容生效

【故障 5：PR 被仓库以"疑似 AI 生成的低质量内容"拒绝】
- 现象：向 obra/superpowers 主仓库提交 PR，被快速 close
- 根本原因：官方审计过去 100 个已关闭 PR，发现 94% 的拒绝率
            源于"agentic slop"——Agent 没读 PR 模板、开重复 PR、
            编造问题描述、把 fork/特定领域改动错误地上推到主仓库
- 预防：v6.0 起，PR 和 issue 模板新增"披露字段"，要求注明
        本次贡献使用的模型、harness、版本和已安装插件，
        或注明"由人工手写"；同时 PR 现在必须针对 dev 分支，而非 main

【故障 6：在 Claude Code 上同时触发了 Superpowers 的 SDD 
          和原生 Dynamic Workflows，行为混乱/重复编排】
- 现象：开启 ultracode 模式或显式要求"用 workflow"后，
        SDD 和原生 Workflow 编排器互相冲突，
        比如 SDD 期望 Implementer 能中途提问，
        但 Workflow 运行期间不接受任何用户输入
- 根本原因：截至 2026 年 6 月，社区 issue #1647 中明确指出
            两个编排层"目前没有谁该赢的规则"，且这是一个
            仍在讨论中、未关闭的开放问题
- 应急：当前建议手动二选一——做结构化的中小型功能开发用
        Superpowers SDD；做超大规模、无需中途交互的批量任务
        （如代码库审计、大规模迁移）才考虑原生 Dynamic Workflows，
        不要在同一个任务里同时依赖两者（详见第 8 节）

6.5 边界条件与局限性（v2 更新）

Context Window 压力： 依然存在，但 v6.0 的文件化 diff 交付机制已显著降低了"粘贴大段 diff 占满上下文"这一历史痛点。⚠️ 存疑：具体 token 节省比例随项目改动量大小波动，官方仅给出"约 50%"的总体评测均值。
Subagent 并发限制： Superpowers 本身的 SDD 模式偏顺序执行，与 Claude Code 原生 Dynamic Workflows 的"16 路并发、上限 1,000 个 Subagent"规模不在一个量级，两者解决的是不同形状的问题（见第 4.1 节对比表）。
强 TDD 模式不适用于所有场景： 同 v1 版本结论，建议用项目级 Skill 覆盖来调整约束强度。
API 调用成本： v6.0 后约为单 Agent 模式的 2-3 倍（较 v5.x 的 3-5 倍已下降，但仍显著高于无结构化流程的直接调用）。
新平台支持的成熟度不均： Pi、Antigravity、Kimi Code 是 v6.0 才新增的 harness，集成深度和社区验证案例数量明显少于 Claude Code/Cursor/Codex，⚠️ 存疑：这三个平台上的长期稳定性尚缺乏足够公开案例佐证。
第三方质量评分工具给出的分数仅供参考： 曾有社区评测工具对 using-superpowers 这一核心 Skill 打出 68/100（D 档）的分数，主要扣分点在于写作风格（如 “EXTREMELY-IMPORTANT” 全大写 + “not negotiable” 这类"营销腔"被认为不够简洁）。⚠️ 存疑：此类自动化评分工具的方法论本身未经过广泛交叉验证，分数仅作为风格参考，不代表 Skill 的实际有效性。

7. 核心 Skill 深度解析（v1 内容保留，新增 v6.0 视角）

7.1 test-driven-development Skill 的设计哲学（机制未变）

核心洞察： "事后写测试"和"TDD"解决的是完全不同的问题。

	事后测试	TDD (RED-GREEN)
回答的问题	“这段代码做了什么？”	“这段代码应该做什么？”
偏见来源	测试被实现污染	测试先行，迫使边界条件提前发现
证明能力	代码跑起来了	测试本身是有效的（你见过它失败）
Bug 预防	验证你记得的 edge case	发现你没想到的 edge case

7.2 writing-skills：TDD for Documentation（机制未变，新增度量手段）

v6.0 在原有"用 Subagent 压测找出理由化路径"的方法论基础上，新增了两条面向 Skill 作者的具体指导：

“匹配形式与失效模式”（Match the Form to the Failure）：一个简表，帮作者判断该用哪种写法——“别做 X"这种平铺直叙的禁令，对付的是纪律性滑坡（比如想跳过测试）；但如果问题出在"产出物的形状不对”（比如格式总是写错），平铺禁令没用，得换成一个具体的"范例"来引导。
“微测试措辞法”（Micro-Test Wording）：一种低成本验证某句措辞是否有效的办法——在"有无该指导"两种条件下各跑几次采样，逐条人工对比结果，把"跑几次结果就不一样"本身当作一个警示信号（说明这句措辞不够稳定）。

7.3（v2 新增）Review 流程的"防被说服"设计

v6.0 的 task-reviewer 被明确设计为"对借口免疫"：

实测发现，过去会出现 Implementer 在报告里写"我这里故意没抽象，是有意为之"，结果真的说服了 Reviewer 放过一个本该被标记的真实问题。新版本要求 Reviewer 对实现者的"自我辩护"保持怀疑，并且 Reviewer 本身被设计成只读——连 git checkout 这种"顺手"的操作都不允许，因为曾经出现过 Reviewer 跑 git checkout 导致后续提交被孤立（orphan）的真实事故。

这与第一版文档第 7.2 节提到的"反理由化（Anti-Rationalization）"语言设计一脉相承——只是这次"被说服的对象"从 Agent 本身的纪律，扩展到了"Reviewer 会不会被另一个 Agent 的话术绕过"这一新维度。

8. 演进方向与未来趋势（v2 重点更新）

8.1 与 Claude Code 原生 Dynamic Workflows 的关系：尚未解决的核心张力

这是当前（2026 年 6 月）Superpowers 生态中最值得关注的演进方向，因此单独展开。

背景： 2026 年 5 月 28 日，Anthropic 随 Claude Opus 4.8 一同推出了 Claude Code 的 Dynamic Workflows（研究预览）——一种全新的编排范式：Claude 不再在对话轮次里逐步决定下一步该干什么，而是先写一段 JavaScript 脚本，把"分支、循环、中间结果"都放进代码里，再让这段脚本去调度一群 Subagent（单次最多 1,000 个，16 个同时并发）。这与 Superpowers 的核心设计哲学——“Agent 始终是编排者，逐轮决策，最大化保留中途人工介入和追问的能力”——构成了直接的方法论分歧。

社区已经注意到这个问题： Superpowers 仓库的 issue #1647（提出于约 2026 年 5-6 月之交，截至本文撰写时仍为开放状态）明确列出了二者冲突的四个具体表现：

编排权之争：Dynamic Workflows 想把任务整体编码成一个后台脚本，而 SDD 规定的是"顺序 Task() 派发 + 逐任务复核"，没有任何文档说明两者同时触发时谁该让步。
并行 vs 顺序的根本分歧：Workflows 是为大规模并行设计的；SDD 则是刻意保持顺序执行的——"把计划当 workflow 跑"本身就和 SDD 的设计初衷相矛盾。
中途不可交互：Workflows 运行期间不接受任何用户输入（只有工具权限确认弹窗可以暂停），这直接废掉了 SDD 里"Implementer 遇到不确定的地方可以向控制器提问"这一关键环节——Agent 只能依赖一开始给定的上下文往下走。
没有插拔接口：Skill 是纯 Prose（自然语言指令），不是可编程组件，SDD 那套"顺序、靠问答推进、靠状态判断重新派发"的循环逻辑，没法直接套进"运行中不能给输入"的 Workflow 模型里。

issue 中讨论的三种应对方案（截至目前均未定案）：

方案 A：在 subagent-driven-development 文档里加一条简短的决策规则——什么情况下该留在 SDD 里，什么情况下该把某个阶段交给 Workflow，让两个编排者"配合而非竞争"。
方案 B：新增一个 Claude-Code-专属、实验性、需手动开启的 workflow-driven-development Skill——作为 SDD 的"workflow 原生版兄弟"，把"Spec + 代码质量复核"做成对抗式验证阶段，循环直到通过，但要明确告知用户代价（运行中不能追问、上下文必须前置准备好）。
方案 C（已被否决）：直接给 SDD/executing-plans 加一个"workflow 后端"——这个方案被认为不可行，因为 Skill 是纯 prose，没有可插拔的接口点，而且强行适配会让 SDD 失去（而非获得）能力，比如失去中途问答这个核心特性。

对使用者的实际影响： 在官方给出明确指引之前，建议按本文第 4.2 节决策树的建议手动二选一，避免在同一任务里让两套编排逻辑互相打架、重复消耗 token。这也是观察 Superpowers 项目未来走向的一个关键信号——它选择"和 Dynamic Workflows 配合"还是"在某些场景被边缘化"，很大程度上取决于 issue #1647 最终走向哪个方案。

8.2 平台覆盖持续扩张

2026 年内，支持平台数量从年初的 4 个（Claude Code、Cursor、Codex、OpenCode）扩展到 6 月的 11 个，新增 Gemini CLI、GitHub Copilot CLI、Factory Droid、Kimi Code、Pi、Antigravity。docs/porting-to-a-new-harness.md 的发布也标志着"移植到新 harness"这件事本身已经标准化、文档化——团队总结出"每个集成需要的三个组件，以及一条做不到就全盘失败的铁律：必须在 Session 启动时加载 bootstrap"。

8.3 治理与可信度建设

随着项目影响力扩大，"低质量 AI 生成 PR 淹没仓库"成为真实的工程治理问题（94% 拒绝率）。v6.0 引入的"贡献者必须披露生成方式"机制，某种程度上是行业内较早的一次公开应对——这一治理模式未来是否会被其他大型开源 Agent 项目效仿，值得持续关注。

9. 面试高频题（v2：保留 v1 核心题，新增 v6.0 相关题）

【基础理解层】（考察概念掌握）

Q：Superpowers 中的 Skill 和普通的 system prompt 有什么区别？
A：普通 system prompt 在整个会话中静态存在，一次性注入所有内容。
   Skill 是按需加载的——只有 Skill tool 识别到触发场景时才读取对应 Skill。
   此外，Skill 有三层优先级（project > personal > plugin），支持局部覆盖，
   system prompt 则是单层全局生效。
考察意图：理解"按需加载"和"分层覆盖"是否清晰。


【原理深挖层】（考察内部机制理解）

Q：v6.0 把"两个 Reviewer 分别审"改成"一个 Reviewer 出两个裁决"，
   这个改动具体省在哪里？有没有什么副作用是需要额外机制弥补的？
A：省的地方主要有两处：一是省掉了第二个 Reviewer 重新拉取/重建 diff
   上下文的开销（这是过去最贵的单项成本）；二是把 diff 和任务文本
   从"粘贴进 prompt 正文"改成"写入文件供读取"，进一步压缩了
   单次 dispatch 的 token 消耗。
   副作用：单一 Reviewer 只能看到 diff 范围内的改动，如果某个需求点
   恰好落在没被改动的既有代码里，Reviewer 没法验证。为此新增了
   "无法从 diff 判断"这一裁决类型，把这部分判断责任明确转交回
   控制器人工核实，而不是让 Reviewer 在信息不足的情况下强行下结论。
考察意图：理解成本优化与判断完整性之间的权衡，以及"明确转交不确定性"
   这种设计模式（而不是让系统假装自己什么都能判断）。

Q：为什么 v6.0 要求每次 Subagent dispatch 必须显式指定模型，
   而不是让系统自动选一个合理的默认值？
A：实测中发现"不指定"在很多 harness 里的默认行为是"继承当前会话
   正在用的模型"，而控制器往往在用顶级模型，于是"不指定"实质上
   变成了"默认用最贵的模型"——曾经因此出现过一次运行把全部 26 个
   Reviewer 都跑在了顶级模型上。强制要求控制器每次显式做出选择，
   本质上是把一个容易被忽略的隐式决策，转成一个不可回避的显式决策点，
   用"增加一点认知负担"换"避免成本失控的尾部风险"。
考察意图：识别"隐式默认值"在系统设计中的隐藏成本，理解
   "强制显式化"作为一种工程对策的适用场景。


【生产实战层】（考察工程经验）

Q：如果你的团队同时在用 Superpowers 和 Claude Code 的
   原生 Dynamic Workflows，应该怎么决定什么时候用哪个？
A：核心判断维度有两个：(1) 任务规模——Dynamic Workflows 是为
   "单个上下文装不下的超大规模任务"设计的（数百文件迁移、全代码库
   审计、需要多角度交叉验证的研究），SDD 则更适合中小型、需要
   完整工程纪律（TDD/规划/质检）的常规功能开发；(2) 是否需要
   中途人工介入——Workflows 运行期间不接受用户输入，只能在
   一开始把上下文准备充分；SDD 则保留了 Implementer 中途
   向控制器提问的能力。
   实践建议：截至目前官方未给出整合方案（参见 issue #1647），
   建议团队内部明确约定"这个任务该走哪条路"，避免在同一任务里
   同时触发两套编排逻辑，造成重复的、互相打架的调度开销。
考察意图：考察候选人是否能跟踪一个开源项目的最新动态、
   理解两种编排范式的本质差异，并能给出务实的工程决策建议，
   而不是简单地"两个都用"。

Q：Superpowers 在 v5.1.0 把 brainstorming/writing-plans 阶段的
   "Subagent 复核"改成了"内联自审"，但在 SDD 的任务级 Review
   阶段却坚持保留独立 Subagent 复核。这种"区别对待"说明了什么
   设计原则？
A：团队做过严格的回归测试（5 个版本 × 每版 5 次试验），证明对于
   "设计/计划"这类偏静态、模型自己就能审视的产物，独立 Subagent
   复核带来的质量提升在统计上不可测量，只是徒增约 25 分钟开销。
   但对"代码实现是否真的做对了"这种需要独立视角才能避免"自己批
   自己作业"式偏见的环节，独立视角的价值是真实存在的，因此保留。
   这说明的核心原则是：**是否要为质量付出额外成本，应该用实证
   （而非"听起来更严谨"的直觉）来决定**，并且要按环节精细区分，
   而不是对所有"审查"环节一刀切地省或一刀切地保留。
考察意图：考察候选人是否理解"用数据驱动设计决策"而非"凭印象做架构"
   的工程文化，以及能否识别"看似相似的两个环节，背后的价值来源
   可能完全不同"这一更深层的设计洞察。

官方文档：

GitHub 主仓库：https://github.com/obra/superpowers
Release Notes：https://github.com/obra/superpowers/blob/main/RELEASE-NOTES.md
v6.0.0 Release：https://github.com/obra/superpowers/releases/tag/v6.0.0
v5.1.0 Release：https://github.com/obra/superpowers/releases/tag/v5.1.0
Prime Radiant 官方博客（Superpowers 6 发布说明）：
https://primeradiant.com/blog/2026/superpowers-6.html
评测框架仓库：https://github.com/prime-radiant-inc/superpowers-evals
Claude Code Dynamic Workflows 官方文档：
https://code.claude.com/docs/en/workflows
Anthropic 官方博客（Dynamic Workflows 发布）：
https://claude.com/blog/introducing-dynamic-workflows-in-claude-code

社区讨论：

SDD 与 Dynamic Workflows 整合方案讨论（issue #1647）：
https://github.com/obra/superpowers/issues/1647
using-superpowers Skill 第三方质量评分报告（issue #202）：
https://github.com/obra/superpowers/issues/202