深入 Superpowers 源码（三）：四大核心工作流技能详解

mokingone
0 阅读14分钟

深入 Superpowers 源码（三）：四大核心工作流技能详解

这是 Superpowers 源码学习系列第三阶段的学习笔记，深入剖析 brainstorming、writing-plans、subagent-driven-development、test-driven-development 四大核心技能的设计哲学与实现细节。

前言

Superpowers 是一套为 Claude Code 设计的技能系统，它让 AI 助手能够遵循严格的工程实践，如 TDD、代码审查、迭代规划等。

在前两阶段中，我们理解了它的插件架构、Hook 系统和技能设计模式。本阶段深入核心工作流技能——这是 Superpowers 的"心脏"，定义了从需求到代码的完整工程流程。

📁 本文学习目录

skills/brainstorming/              # 头脑风暴
├── SKILL.md                      # 核心流程
├── visual-companion.md           # 可视化助手
└── scripts/
    └── server.cjs                # WebSocket 服务器

skills/writing-plans/             # 编写计划
└── SKILL.md

skills/subagent-driven-development/  # 子代理驱动开发
├── SKILL.md
├── implementer-prompt.md         # 实现者模板
├── spec-reviewer-prompt.md       # 规格审查模板
└── code-quality-reviewer-prompt.md  # 质量审查模板

skills/test-driven-development/   # 测试驱动开发
└── SKILL.md

一、Brainstorming：设计优先于实现

核心理念

HARD-GATE：任何代码实现前，必须先有设计文档并获得用户批准。

这不是"建议"，是铁律。为什么？"简单项目不需要设计"恰恰是未审视假设导致浪费的主因。

一个 todo list、一个单函数工具、一个配置修改——都需要设计。
设计可以简短（真正简单的项目几句话即可），但必须呈现并获得批准。

完整流程

flowchart TD
    A[探索项目上下文] --> B{涉及视觉问题?}
    B -->|是| C[提供 Visual Companion]
    B -->|否| D[提问澄清需求]
    C --> D
    D --> E[提出 2-3 个方案]
    E --> F[逐节呈现设计]
    F --> G{用户批准?}
    G -->|否| F
    G -->|是| H[编写设计文档]
    H --> I[Spec 审查循环]
    I --> J{审查通过?}
    J -->|否| K[修复问题]
    K --> I
    J -->|是| L[用户审查文档]
    L --> M{用户确认?}
    M -->|否| H
    M -->|是| N[转 writing-plans]

关键设计原则

1. 一次一个问题

不要一次性抛出多个问题，这会让用户不知所措：

❌ 错误：这个功能的目标用户是谁？预期日活多少？需要支持哪些平台？优先级如何？

✅ 正确：这个功能的主要目标用户是谁？（A. 企业用户 B. 个人用户 C. 两者都有）

2. 设计隔离与清晰边界

每个单元应该能回答：

  • 它做什么？
  • 如何使用它？
  • 它依赖什么？

如果有人需要阅读内部实现才能理解一个单元，说明边界有问题。

3. 探索替代方案

永远提出 2-3 个方案，而非只给一个"最佳答案"。展示权衡，给出推荐和理由。

Visual Companion：零依赖 WebSocket 服务器

当涉及视觉内容（UI 原型、架构图、布局对比）时，Brainstorming 技能可以启动一个浏览器端的可视化助手。

实现亮点（scripts/server.cjs）：

// 完整 RFC 6455 WebSocket 协议实现
// 无任何外部依赖，只用 Node.js 内置模块

const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';

function encodeFrame(opcode, payload) {
  const fin = 0x80;
  const len = payload.length;
  // ... 帧编码逻辑
}

工作原理：

  1. 启动 HTTP + WebSocket 服务器
  2. 监听目录中的 HTML 文件变化
  3. 你写 HTML → 用户浏览器自动刷新显示
  4. 用户点击选择 → .events 文件记录交互

使用决策：每个问题独立判断

问题类型推荐渠道
UI 原型、布局对比、架构图浏览器
需求澄清、概念选择、权衡讨论终端

一个问题"关于 UI"不等于必须用浏览器。"什么样的导航结构更合适？"是概念问题，用终端。"这两个布局哪个更好？"是视觉问题，用浏览器。

Spec Review Loop

设计文档写完后，不是直接给用户，而是先经过子代理审查：

设计文档 → 派遣 spec-document-reviewer 子代理
              ↓
         有问题？ → 修复 → 重新派遣
              ↓
         通过（最多 3 次迭代）→ 用户审查

这确保设计文档质量，减少用户来回修改的次数。

二、Writing-Plans：任务拆解的艺术

核心理念

假设执行者对你的代码库一无所知，且品味存疑。

写计划时要详尽到：哪些文件需要修改、测试命令是什么、期望输出是什么、代码片段完整给出。

任务粒度：2-5 分钟一个动作

### Task 1: 用户登录验证

**Files:**
- Create: `src/auth/validator.py`
- Modify: `src/auth/service.py:45-78`
- Test: `tests/auth/test_validator.py`

- [ ] **Step 1: 写失败的测试**

```python
def test_validate_email_format():
    result = validate_email("invalid-email")
    assert result.is_valid == False
  • Step 2: 运行测试确认失败

Run: pytest tests/auth/test_validator.py -v Expected: FAIL with "validate_email not defined"

  • Step 3: 写最小实现代码
def validate_email(email: str):
    return ValidationResult(is_valid="@" in email)
  • Step 4: 运行测试确认通过

Run: pytest tests/auth/test_validator.py -v Expected: PASS

  • Step 5: 提交
git add tests/auth/test_validator.py src/auth/validator.py
git commit -m "feat(auth): add email validation"


### 计划文档头部模板

每个计划**必须**以这个头部开始：

```markdown
# [功能名称] 实施计划

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 一句话描述这个计划要构建什么

**Architecture:** 2-3 句话说明架构思路

**Tech Stack:** 关键技术/库列表

---

文件结构先行

在定义任务之前，先确定文件结构：

  • 每个文件单一职责，清晰边界
  • 改动频率相似的文件放一起
  • 遵循项目既有模式（不要单方面重构）

这决定了任务拆解的方式——每个任务应该产生独立可理解的变更。

Plan Review Loop

计划写完后同样要经过子代理审查：

计划文档 → 派遣 plan-document-reviewer 子代理
              ↓
         有问题？ → 修复 → 重新派遣
              ↓
         通过 → 执行移交

执行移交选项

计划通过后，提供两种执行方式：

方式适用场景特点
Subagent-Driven（推荐）任务独立的计划每任务派新子代理，任务间自动审查
Inline Execution当前会话内执行批量执行，检查点人工审查

三、Subagent-Driven Development：子代理驱动开发

核心理念

每任务派新子代理 + 两阶段审查 = 高质量、快迭代

为什么用子代理？

问题子代理方案
上下文污染子代理不继承会话历史，你精确构建它需要的信息
任务聚焦每个任务独立上下文，不会混淆
并行安全子代理不会互相干扰
保留协调能力你的上下文用于协调，不被实现细节占满

完整工作流程

flowchart TD
    A[读取计划] --> B[提取所有任务]
    B --> C[创建 TodoWrite]
    C --> D{还有任务?}
    D -->|是| E[派遣 implementer 子代理]
    E --> F{有疑问?}
    F -->|是| G[回答问题]
    G --> E
    F -->|否| H[实现、测试、提交、自我审查]
    H --> I[派遣 spec reviewer]
    I --> J{符合规格?}
    J -->|否| K[修复规格差距]
    K --> I
    J -->|是| L[派遣 code quality reviewer]
    L --> M{代码质量 OK?}
    M -->|否| N[修复质量问题]
    N --> L
    M -->|是| O[标记任务完成]
    O --> D
    D -->|否| P[派遣最终代码审查]
    P --> Q[finishing-a-development-branch]

两阶段审查：先规格，后质量

阶段一：Spec Compliance Review（规格合规审查）

目的：验证实现者构建了"被要求的东西"——不多不少。

审查者的原则：不要信任实现者的报告！

❌ 不要：
- 相信他们"实现了"
- 接受他们对需求的解释
- 跳过代码直接看报告

✅ 要：
- 阅读实际代码
- 逐行对比需求和实现
- 检查遗漏和多余

阶段二：Code Quality Review（代码质量审查）

目的：验证实现是"良好构建的"——干净、可测试、可维护。

注意：必须在规格审查通过后才能进行！

模型选择策略

不是所有任务都需要最强模型。用"最小可用模型"节省成本、提高速度：

任务类型推荐模型原因
机械实现（1-2 文件，规格清晰）快速廉价模型只需按指令执行
集成判断（多文件协调、调试）标准模型需要一定推理能力
架构设计、复杂审查最强模型需要深度理解

子代理状态处理

实现者子代理会返回四种状态：

状态含义处理方式
DONE完成工作进入规格审查
DONE_WITH_CONCERNS完成但有疑虑先读疑虑，再决定是否处理
NEEDS_CONTEXT缺少信息提供缺失信息，重新派遣
BLOCKED无法完成评估阻碍：提供上下文 / 换更强模型 / 拆分任务 / 上报人工

重要：永远不要忽略 BLOCKED 或强行用相同模型重试。如果子代理说卡住了，必然有东西需要改变。

实现者 Prompt 模板核心要点

## Before You Begin

如果你对需求、方法、依赖、假设有任何疑问——**现在问**。
在开始工作前提出所有顾虑。

## Your Job

明确后：
1. 实现任务指定的内容
2. 写测试（任务要求 TDD 则遵循）
3. 验证实现工作正常
4. 提交工作
5. 自我审查
6. 汇报

## When You're in Over Your Head

停下来并说"这对我来说太难了"是可以的。
糟糕的工作比不工作更糟。你不会因为升级问题受罚。

**何时升级：**
- 任务需要架构决策
- 无法理解代码库
- 不确定方法是否正确
- 计划没预料的重构
- 读了很多文件仍然困惑

关键铁律

❌ 禁止：
- 并行派遣多个实现子代理（会冲突）
- 跳过任一阶段审查
- 规格审查通过前开始代码质量审查
- 忽略子代理疑问
- 审查发现问题后不重新审查
- 用自我审查替代正式审查

✅ 必须：
- 回答子代理疑问后再让其继续
- 发现问题 → 修复 → 重新审查
- 按顺序：实现 → 规格 → 质量

四、Test-Driven Development：测试驱动开发

铁律

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

如果没看到测试失败，你不知道它是否测试了正确的东西。

先写代码再测试？删除。重新开始。

没有例外：
- 不要保留作为"参考"
- 不要在写测试时"改编"它
- 不要看它
- 删除意味着删除

Red-Green-Refactor 循环

flowchart LR
    R[RED<br/>写失败测试] --> VR{验证失败?}
    VR -->|否| R
    VR -->|是| G[GREEN<br/>最小代码]
    G --> VG{验证通过?}
    VG -->|否| G
    VG -->|是| F[REFACTOR<br/>清理]
    F --> VG2{仍通过?}
    VG2 -->|否| F
    VG2 -->|是| N[Next<br/>下一测试]
    N --> R

RED 阶段要求：

# ✅ 好：清晰命名，测试真实行为，一件事
def test_retries_failed_operations_3_times():
    attempts = 0
    def operation():
        attempts += 1
        if attempts < 3:
            raise Error('fail')
        return 'success'
    
    result = retry_operation(operation)
    assert result == 'success'
    assert attempts == 3

# ❌ 坏：模糊命名，测试 mock 不是代码
def test_retry_works():
    mock = Mock()
    mock.side_effect = [Error(), Error(), 'success']
    retry_operation(mock)
    assert mock.call_count == 3

GREEN 阶段要求：

只写让测试通过的最小代码。不添加功能，不重构，不"改进"。

# ✅ 好：刚好足够通过
async def retry_operation(fn):
    for i in range(3):
        try:
            return await fn()
        except:
            if i == 2:
                raise

# ❌ 坏：过度工程
async def retry_operation(fn, options=None):
    max_retries = options?.max_retries or 3
    backoff = options?.backoff or 'linear'
    # ... 一堆没用到的功能

为什么顺序重要？

"我之后写测试验证它工作"

测试在代码后写会立即通过。立即通过证明不了任何事：

  • 可能测试了错误的东西
  • 可能测试了实现而非行为
  • 可能漏掉了你忘记的边界情况
  • 你从未看到它捕获 bug

测试优先强迫你看到测试失败，证明它确实在测试某些东西。

"我已经手动测试了所有边界情况"

手动测试是临时的：

  • 没有记录测试了什么
  • 代码改变时无法重新运行
  • 压力下容易忘记情况
  • "我试过没问题" ≠ 全面

常见理性化借口表

借口现实
"太简单不需要测试"简单代码也会出错。测试只需 30 秒。
"我之后补测试"测试立即通过说明不了任何问题。
"之后测试效果一样"之后测试回答"这做了什么"，测试优先回答"这应该做什么"。
"已经手动测试过"临时 ≠ 系统。没记录，不能重跑。
"删除 X 小时的工作是浪费"沉没成本谬误。保留未验证的代码才是技术债。
"保留作参考，重新写测试"你会改编它。那还是测试后写。
"TDD 会拖慢我"TDD 比调试快。务实 = 测试优先。
"测试困难 = 设计不清晰"听测试的。难测试 = 难使用。

Red Flags：出现这些必须重新开始

- 代码先于测试
- 实现后补测试
- 测试立即通过
- 无法解释为什么测试失败
- "稍后添加测试"
- "就这一次"的合理化
- "我已经手动测试过"
- "之后测试达到同样目的"
- "重要的是精神不是仪式"
- "保留作参考"或"改编现有代码"
- "已经花了 X 小时，删除是浪费"
- "TDD 是教条，我务实"
- "这不同因为..."

所有这些意味着：删除代码。用 TDD 重新开始。

五、技能协作链路：从需求到代码

四大核心技能不是独立的，它们组成一条完整的工作流链路：

flowchart LR
    A[brainstorming<br/>头脑风暴] -->|设计文档| B[writing-plans<br/>编写计划]
    B -->|实施计划| C[subagent-driven-development<br/>子代理驱动开发]
    C -->|TDD| D[finishing-a-development-branch<br/>完成开发分支]
    
    subgraph 循环
        E[test-driven-development<br/>测试驱动开发]
    end
    
    C -.-> E

链路详解

1. Brainstorming → Writing-Plans

输入：用户需求/想法
输出：设计文档（docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md）
关键检查点：用户批准设计文档

2. Writing-Plans → Subagent-Driven

输入：设计文档
输出：实施计划（docs/superpowers/plans/YYYY-MM-DD-<feature>.md）
关键检查点：计划文档审查通过

3. Subagent-Driven → TDD

输入：实施计划（每个任务独立）
输出：实现代码 + 测试代码
关键检查点：两阶段审查（规格 → 质量）

每个子代理内部遵循 TDD 循环，确保代码质量。

实际案例演示

假设用户需求："添加用户登录功能"

Step 1: Brainstorming

Claude: 我理解你想添加用户登录功能。让我先了解项目结构。
[读取项目文件]

Claude: 我看到这是一个 Spring Boot 项目，使用 JWT 认证。
有几个问题想确认：

1. 登录方式支持哪些？
   A. 用户名+密码
   B. 手机号+验证码
   C. 两者都支持

用户: A，用户名+密码

Claude: 了解。关于密码存储：
   A. BCrypt 加密
   B. 其他加密方式

用户: A

[继续提问...]
[提出 2-3 个方案...]
[逐节呈现设计...]

Claude: 设计文档已写入 docs/superpowers/specs/2026-03-24-user-login-design.md
请审阅，确认后我们开始编写实施计划。

Step 2: Writing-Plans

Claude: 我正在使用 writing-plans 技能创建实施计划。
[分析设计文档]
[确定文件结构]
[编写详细任务...]

Claude: 计划已保存到 docs/superpowers/plans/2026-03-24-user-login.md

计划包含 5 个任务：
1. 创建 LoginRequest/Response DTO
2. 实现 LoginService
3. 添加 JWT 生成
4. 创建 LoginController
5. 集成测试

执行方式：
1. Subagent-Driven（推荐）- 每任务派子代理，自动审查
2. Inline Execution - 当前会话执行

你选择哪种？

Step 3: Subagent-Driven Development

Claude: 使用 Subagent-Driven Development 执行计划。
[创建 TodoWrite 追踪 5 个任务]

=== Task 1: 创建 LoginRequest/Response DTO ===

[派遣 implementer 子代理]

Implementer: 我有个问题：DTO 应该放在哪个包下？
  A. com.example.auth.dto
  B. com.example.dto

Claude: A，和其他认证相关的类放一起。

Implementer: 明白。正在实现...
- 创建 LoginRequest.java
- 创建 LoginResponse.java
- 测试通过
- 已提交
- 自我审查：无问题

[派遣 spec reviewer 子代理]

Spec Reviewer: ✅ 规格合规 - 所有要求已实现，无额外内容

[派遣 code quality reviewer 子代理]

Code Reviewer: 
优点：命名清晰，符合规范
问题（重要）：缺少字段校验注解

[implementer 修复]

Implementer: 已添加 @NotBlank 注解

[Code Reviewer 重审]

Code Reviewer: ✅ 批准

=== Task 1 完成 ===

[继续 Task 2...]

六、关键设计洞察

1. 为什么是"两阶段"审查？

一个阶段不够吗？不够：

审查类型关注点发现的问题
规格合规是否构建了被要求的东西遗漏需求、多余功能、理解偏差
代码质量是否构建得良好代码坏味道、测试不足、性能问题

先确保"做了对的事"，再确保"把事做好了"。顺序不能乱——代码质量再高，如果规格不符，也是白搭。

2. 为什么子代理要"重新审查"？

审查发现问题 → 修复 → 必须重新审查。

为什么？因为修复可能引入新问题，或者"修复"根本没修复。只有审查者确认才算通过。

3. 为什么 TDD 必须"看到失败"？

测试立即通过 ≠ 测试有效

可能的情况：

  • 测试了错误的行为
  • 测试了实现细节而非公共接口
  • 测试里写死了结果

只有看到测试因为正确的原因失败，才能确信它在测试正确的东西。

4. 为什么 Visual Companion 是"可选"的？

因为不是所有问题都适合可视化：

问题类型适合渠道
"这个按钮放哪里？"浏览器（布局对比）
"这个功能的目标用户是谁？"终端（概念讨论）
"这两种架构哪个更好？"浏览器（架构图）
"性能优先还是可维护性优先？"终端（权衡讨论）

每个问题独立决策，不让工具决定方法。

七、总结

Superpowers 的四大核心工作流技能体现了严格的工程哲学：

技能核心原则关键实践
Brainstorming设计优先于实现HARD-GATE、一次一问、设计隔离
Writing-Plans细节决定成败2-5 分钟粒度、完整代码、精确命令
Subagent-Driven隔离上下文、双重把关每任务新代理、两阶段审查
TDD没有失败就没有成功Red-Green-Refactor、看到失败

这些不是独立的技巧，而是相互支撑的体系：

需求 → [设计] → [计划] → [实现] → [审查]
              ↓
          TDD 贯穿始终

核心思想：慢即是快。前期投入设计、计划、测试的时间，会在后期节省大量调试和返工的成本。

参考资料

本文是 Superpowers 源码学习系列第三阶段笔记。后续阶段将继续深入子代理系统、测试系统、跨平台支持等内容。

avatar
文章
阅读
粉丝