Superpowers 技术剖析：137K Stars 的 Agent 纪律框架

superpowers/
  skills/                    # 15 个 SKILL.md 文件 = 全部核心
    brainstorming/SKILL.md
    writing-plans/SKILL.md
    subagent-driven-development/SKILL.md
    test-driven-development/SKILL.md
    systematic-debugging/SKILL.md
    ...
  agents/                    # agent 实现
  commands/                  # CLI 命令
  hooks/                     # Git/开发 hooks
  scripts/                   # 工具脚本
  CLAUDE.md                  # Claude 专用配置
  GEMINI.md                  # Gemini 集成
  AGENTS.md

---
name: test-driven-development        # 连字符标识符
description: "Use when implementing any feature or bugfix, before writing implementation code"
---

**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development
**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging

# Claude Code（官方市场）
/plugin install superpowers@claude-plugins-official

# Claude Code（社区市场）
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Cursor
/add-plugin superpowers

# Codex CLI
# 获取并执行安装指令
Fetch https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# 更新
/plugin update superpowers

<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.
</HARD-GATE>

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
# 如果未被忽略：添加到 .gitignore，先提交，再继续

project=$(basename "$(git rev-parse --show-toplevel)")
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

# [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:** [一句话描述构建什么]
**Architecture:** [2-3 句话描述方法]
**Tech Stack:** [关键技术/库]

## Task N: [名称]

**Files:**
- Create: `src/foo.ts`
- Modify: `src/bar.ts` (lines 15-30)
- Test: `tests/foo.test.ts`

- [ ] Step 1: Write failing test
  ```typescript
  // 完整测试代码，不是伪代码

**粒度**：每步 = 2-5 分钟的单一动作。

**禁止 Placeholder**（完整清单）：

- "TBD"、"TODO"、"implement later"、"fill in details"
- "Add appropriate error handling" / "add validation" / "handle edge cases"
- "Write tests for the above"（没有实际测试代码）
- "Similar to Task N"（重复代码——执行者可能不按顺序读 task）
- 描述做什么但不展示怎么做的步骤
- 引用未在任何 task 中定义的类型/函数/方法

**自审三步**：
1. Spec 覆盖率：每个需求都映射到了 task？
2. Placeholder 扫描：搜索上述红旗模式
3. 类型一致性：后续 task 中的类型/方法签名是否与前面 task 匹配？

### Stage 4：Subagent 驱动执行（推荐模式）

**前置条件**：有完整计划 + 任务大部分独立 + 有 subagent 支持

**核心模式**："每 task 一个新鲜 subagent + 两阶段 review（先 spec 合规，后代码质量）"

**完整流程**：

**上下文隔离**：Subagent **只收到** task 描述和必要上下文。**没有**完整对话历史，**没有**前序 task 的执行记录。这是刻意的架构——防止上下文污染。

**审查者也是隔离的**：reviewer subagent **永远看不到** implementer 的会话历史（防止偏见）。使用独立的 prompt 模板：
- `./implementer-prompt.md`
- `./spec-reviewer-prompt.md`
- `./code-quality-reviewer-prompt.md`

**模型分层策略**：

| 任务类型 | 推荐模型 |
|---------|---------|
| 机械性（1-2 文件，清晰 spec） | 便宜/快速模型 |
| 集成性（多文件协调） | 标准模型 |
| 架构/设计/审查 | 最强模型 |

**"Never" 清单**（精确）：
- 未经用户同意就在 main/master 上开始实现
- 跳过任一审查阶段（spec 合规 或 代码质量）
- 带着未修复的问题继续
- 并行分派多个 implementer（冲突风险）
- 让 subagent 自己去读 plan 文件（直接提供完整文本）
- 跳过场景设置上下文
- 忽略 subagent 的提问
- spec 合规还没通过就开始代码质量审查
- 当前 task 还有未关闭的 review issue 就跳到下一个

### Stage 5：TDD（贯穿所有阶段）

**铁律**（原文）：

> Write code before the test? Delete it. Start over.
> **No exceptions:** Don't keep it as "reference." Don't "adapt" it while writing tests. Don't look at it. Delete means delete.

**RED-GREEN-REFACTOR**：

1. **RED**：写一个**最小的**失败测试。要求：测试一个行为、清晰命名、真实代码（mock 仅在不可避免时使用）
2. **验证 RED（强制，不可跳过）**：运行测试。确认：**失败**（不是 error）、失败消息符合预期、因为功能缺失而失败（不是拼写错误）。如果通过了？你在测试已有行为——修改测试。如果 error？修复 error 重跑。
3. **GREEN**：写**最简代码**让测试通过。不加功能、不重构、不"改进"。
4. **验证 GREEN（强制）**：确认测试通过、其他测试仍然通过、输出干净无 warning。
5. **REFACTOR**：仅在 green 之后。消除重复、改善命名、提取 helper。保持测试绿色。不加行为。

**合理化对照表**（13 条，部分摘录）：

| 借口 | 现实 |
|------|------|
| "太简单不需要测试" | 简单的代码也会坏。测试只要 30 秒。 |
| "之后再写测试" | 立即通过的测试什么都证明不了。 |
| "删掉 X 小时的工作太浪费了" | 沉没成本谬误。保留未验证代码才是技术债。 |
| "先留着当参考，再用 TDD 写" | 你会"参考"着改它。那就是 test-after。Delete means delete。 |
| "TDD 会拖慢我" | TDD 比 debug 快。Pragmatic = test-first。 |

**13 个红旗信号**（任何一个出现 = 删除代码，从头来过）：
- 先写了代码再测试
- 测试立即通过
- 合理化"就这一次"
- "这种情况不一样因为..."
- "已经花了 X 小时，删掉太浪费"

### Stage 6：Code Review

**分派审查**：用 `superpowers:code-reviewer` subagent，使用精确构造的上下文，**不传递你的会话历史**。

**审查模板的五个必填字段**：

**三级严重性**：

| 级别 | 效果 |
|------|------|
| **Critical** | 立即阻断，必须修复 |
| **Important** | 阻断下一个 task，必须在继续前解决 |
| **Minor** | 记录备查，不阻断进度 |

**接收 Review 反馈**（`receiving-code-review` skill）：

六步流程：**完整阅读** → 用自己的话复述需求 → 对照实际代码库验证 → 评估技术正确性 → 回应（确认或有理有据地反驳）→ 逐项实现并测试

**禁止的回应**（原文）：

- "You're absolutely right!"
- "Great point!"
- "Thanks for catching that!"

这些是表演性语言。正确格式："Fixed. [具体描述]"——技术事实，不是社交表演。

**什么时候该反驳**：建议会破坏功能、违反 YAGNI、技术上对你的 stack 不正确、或与已有架构决策冲突时。

### Stage 7：收尾

1. **运行测试套件**。失败 → 停止，不继续
2. **确定 base branch**（main/master）
3. **展示精确四个选项**：
   - Merge 到 base branch
   - Push 并创建 PR（`gh pr create`）
   - 保留 branch 原样
   - 丢弃（需要用户输入 "discard" 确认）
4. **执行选择**。Merge 后重新跑测试验证。
5. **清理 worktree**：选项 1、4 移除；选项 2、3 保留

---

## 六、Systematic Debugging（单独拆解）

**铁律**：`NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST`

**四个阶段**（必须按序完成）：

**Phase 1：根因调查**（在提出任何修复之前必须完成）
- 读完整错误信息（不要跳过 stack trace、行号、错误码）
- 稳定复现（不能复现就不能修）
- `git diff` 检查最近变更
- 多组件系统：在每个组件边界记录日志（入口和出口）
- 从故障点**反向**追踪数据流到原始来源

**Phase 2：模式分析**
- 在代码库中找到同类**正常工作的代码**
- **完整阅读**参考实现（"Don't skim -- read every line"）
- 列出工作代码和故障代码之间的**所有**差异
- 理解依赖关系

**Phase 3：假设与测试**
- 形成**单一**明确假设："我认为 X 是根因，因为 Y"
- 最小变更测试（一次只改一个变量）
- 不行？形成**新**假设。**不要在旧修复上叠加新修复**

**Phase 4：实现**
- 先写失败测试（调用 TDD skill）
- 实现单一修复——**不搂草打兔子**（no "while I'm here" improvements）
- 验证

**3 次修复失败 = 硬门控**：

> "If 3+ Fixes Failed: Question Architecture."
> 指标：每次修复暴露新的耦合/共享状态，修复需要"大规模重构"，每次修复在别处产生新症状。
> **必须和人类讨论后才能继续。**

**效果数据**：系统方法 15-30 分钟解决，首次修复成功率 ~95%。随机修复 2-3 小时，成功率 ~40%，常引入新 bug。

---

## 七、并行 Agent 分派

`dispatching-parallel-agents` skill 处理真正独立的并行任务。

**隔离规则**：
- 每个 agent 只获得领域特定信息（无共享会话上下文）
- 自包含 prompt，含所有必要背景
- 每个 agent 一个问题域
- 明确边界："don't change other code"

**协调序列**：
1. 识别独立领域
2. 创建聚焦任务
3. 并发分派
4. Agent 并行工作（执行期间无协调）
5. 编排者审查摘要
6. 验证无冲突
7. 运行完整测试套件
8. 集成变更

**关键约束**："Don't use when failures are related"——必须是真正的独立性。

---

## 八、Skill 开发方法论（Meta-Skill）

`writing-skills` 把 TDD 方法论应用于 skill 本身：

**铁律**：`NO SKILL WITHOUT A FAILING TEST FIRST`

**RED**（基线）：
- 创建 3+ 个压力场景
- **不加载** skill 运行
- 逐字记录 agent 的行为和合理化借口
- 识别失败模式

**GREEN**（写 skill）：
- 写**最少**内容，仅针对基线失败
- 用**同一组**场景 + skill 重跑
- 验证 agent 现在遵守

**REFACTOR**（堵漏洞）：
- 识别测试中出现的**新**合理化借口
- 添加显式对抗措施
- 从所有迭代中构建合理化对照表
- 创建红旗清单
- 重测直到无漏洞

这就是为什么每个纪律 skill 都有那么详尽的"合理化对照表"和"红旗清单"——它们是实际测试中 agent 真的尝试跳过步骤时说的话，被记录下来并堵死了。

---

## 九、Skill 依赖图

**Skill 分类**：
- **刚性/强制执行**：TDD、Systematic Debugging（硬门控 + 删除策略）
- **结构化/自适应**：Brainstorming（清单驱动 + 门控审批）
- **咨询性**：Code Review（报告发现，人类决策）

---

## 十、案例：Chardet 7.0.0

Dan Blanchard 用 Superpowers 引导 Claude Code 完成了 chardet Python 库（字符编码检测）的**完全重写**。2026 年 3 月 4 日发布。

**流程**：brainstorming → writing-plans → subagent-driven-development（全程 TDD）→ 两阶段审查

**结果**：

| 指标 | 数值 |
|------|------|
| 准确率 | **96.8%**（vs chardet 6.0 的 94.5%，vs charset-normalizer 的 89.1%） |
| 速度 | **41x faster**（mypyc 编译），28x（纯 Python），7.5x faster than charset-normalizer |
| 编码覆盖 | 99 种编码，6 个时代（MODERN_WEB / LEGACY_ISO / LEGACY_MAC / LEGACY_REGIONAL / DOS / MAINFRAME） |
| 检测管道 | 12 阶段（BOM → UTF-16/32 → 转义序列 → 二进制检测 → markup charset → ASCII → UTF-8 验证 → 字节有效性 → CJK 门控 → 结构探测 → 统计评分 → 后处理） |
| 语言检测 | 49 种语言，90.5% 准确率 |
| 测试套件 | **2,161 文件**，99 种编码——TDD 方法论的直接产物 |
| 导入内存 | 96 bytes |
| 运行时依赖 | **零** |
| 协议 | LGPL → MIT |

---

## 十一、vs Deep Agents：不同层面的解决方案

| 维度 | Superpowers | Deep Agents |
|------|-------------|-------------|
| **本质** | 纯 Markdown prompt 工程 | Python/JS SDK + 中间件管道 |
| **运行时** | 无（依赖宿主 agent） | LangGraph |
| **模型绑定** | 无（任何能读 Markdown 的 LLM） | 无（但默认 Claude Sonnet） |
| **核心机制** | 硬门控 + 反合理化表 + 两阶段审查 | planning tool + filesystem + subagent + context compaction |
| **上下文管理** | subagent 隔离（由宿主 agent 实现） | 内置 SummarizationMiddleware |
| **持久化** | 依赖宿主 agent 的文件系统 | 6 种可插拔后端 |
| **可编程性** | 写新 SKILL.md | 写中间件/自定义后端 |
| **解决的问题** | Agent 纪律——防止跳步、偷懒、合理化 | Agent 能力——planning、文件、subagent、上下文压缩 |
| **Stars** | 138K | 19.6K |

**它们不互斥**。Superpowers 的 SKILL.md 可以加载到 Deep Agents 的 skills 系统里。一个管纪律，一个管能力。

---

## 十二、工程师踩坑提醒

1. **description 写错 = skill 永远不触发** — 这是最常见的坑。description 只描述触发条件，不概括流程
2. **不是所有 agent 都支持 subagent** — 没有 subagent 支持时退回 `executing-plans`，效果会打折
3. **Brainstorming 的 hard gate 是认真的** — 如果你想跳过设计直接写代码，Superpowers 会物理阻止你
4. **TDD 的 "delete" 是字面意思** — 先写了代码？不是"参考一下"，是真的删掉重来
5. **Reviewer 看不到 implementer 的上下文** — 这是特性不是 bug，但意味着 review prompt 必须自包含
6. **3 次修复失败 = 架构讨论** — 不是"再试一次"，是"停下来质疑整个方案"
7. **Token 预算很紧** — 高频 skill <200 词。如果你的自定义 skill 太长，agent 性能会退化
8. **Skills 按关键词触发** — 用错误消息、症状词（"flaky"、"hanging"）、工具名作为 description 关键词，而非抽象概念

---

## 参考来源

- [obra/superpowers — GitHub](https://github.com/obra/superpowers)
- [Superpowers: Skills Framework Reshaping AI Dev — Termdock](https://www.termdock.com/en/blog/superpowers-framework-agent-skills)
- [chardet 7.0.0 Release Notes](https://github.com/chardet/chardet/releases/tag/7.0.0)
- [agentskills.io Specification](https://agentskills.io/specification)
- [Individual SKILL.md files from the repository](https://github.com/obra/superpowers/tree/main/skills)