深入 Superpowers 源码（四）：子代理系统设计与实现

深入 Superpowers 源码（四）：子代理系统设计与实现

这是 Superpowers 源码学习系列第四阶段的学习笔记，深入剖析子代理系统的设计哲学、代理定义结构、Prompt 模板设计以及状态处理机制。

前言

在前三阶段中，我们学习了 Superpowers 的核心架构、技能系统设计和四大工作流技能。本阶段深入子代理系统——这是实现"高质量、快迭代"的关键技术支撑。

子代理系统的核心思想：每任务派新子代理 + 两阶段审查。这听起来简单，但背后有精心的设计考量。

---

📁 本文学习目录

agents/                            # 代理定义
└── code-reviewer.md              # 代码审查代理

skills/subagent-driven-development/
├── SKILL.md                      # 子代理调度流程
├── implementer-prompt.md         # 实现者指令模板
├── spec-reviewer-prompt.md       # 规格合规审查模板
└── code-quality-reviewer-prompt.md  # 代码质量审查模板

skills/requesting-code-review/
└── code-reviewer.md              # 代码审查模板

---

一、代理定义：极简的配置，丰富的能力

目录结构

Superpowers 的代理定义非常精简：

superpowers/agents/
└── code-reviewer.md    # 唯一的代理定义文件

代理定义结构

---
name: code-reviewer
description: |
  使用场景描述（触发条件）
  包含示例（<example>标签）
model: inherit          # 继承父会话模型
---
代理职责和能力定义...

关键点：

字段	作用	说明
name	代理标识符	用于调用时引用
description	触发条件	描述何时使用此代理，包含示例
model	使用的模型	inherit 继承父会话，或指定具体模型

code-reviewer 的职责定义

代理定义的正文描述了代理的职责和能力：

1. 计划对齐分析
   - 对比实现与原始计划
   - 识别偏差（合理的改进 vs 有问题的偏离）
   - 验证所有功能已实现

2. 代码质量评估
   - 模式和约定遵循
   - 错误处理、类型安全
   - 命名、可维护性
   - 测试覆盖和质量
   - 安全漏洞、性能问题

3. 架构和设计审查
   - SOLID 原则
   - 关注点分离、松耦合
   - 与现有系统集成

4. 文档和标准
   - 注释和文档完整性
   - 编码标准遵循

5. 问题识别和建议
   - 分类：Critical / Important / Minor
   - 具体示例和可操作建议

6. 沟通协议
   - 先肯定优点，再指出问题
   - 显著偏差 → 要求确认
   - 计划问题 → 建议更新

设计洞察： 代理定义不是配置文件，而是"角色说明书"。它定义了代理的身份、职责、工作方式和沟通风格。

---

二、子代理提示模板：精确控制上下文

子代理系统的核心是三套 Prompt 模板，分别用于实现者、规格审查者和质量审查者。

模板文件结构

skills/subagent-driven-development/
├── implementer-prompt.md           # 实现者模板
├── spec-reviewer-prompt.md         # 规格合规审查模板
└── code-quality-reviewer-prompt.md # 代码质量审查模板

2.1 实现者模板

核心结构：

## Task Description
[从计划中粘贴完整任务文本 - 不让子代理读文件]

## Context
[场景设定：任务位置、依赖、架构上下文]

## Before You Begin
如果有疑问（需求、方法、依赖、假设）→ 现在问

## Your Job
明确后：实现 → 测试 → 验证 → 提交 → 自我审查 → 汇报

## Code Organization
- 每个文件单一职责
- 遵循计划定义的文件结构
- 现有代码库遵循已有模式

## When You're in Over Your Head
停止并说"这对我来说太难了"是可以的

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

## Self-Review
**完整性：** 全部实现？遗漏需求？边界情况？
**质量：** 最佳工作？命名清晰？代码整洁？
**纪律：** YAGNI？只构建请求的？遵循模式？
**测试：** 测试真实行为？TDD？全面？

## Report Format
Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
实现内容 / 测试结果 / 文件变更 / 自我审查发现 / 问题或疑虑

设计要点：

1. 不让子代理读文件：直接提供完整任务文本，避免文件读取带来的上下文噪音
2. 场景设定：提供任务在整体架构中的位置，帮助子代理理解"为什么"
3. 升级机制：明确告诉子代理"卡住了可以求助"，而不是硬撑

2.2 规格合规审查模板

核心原则：不要信任实现者的报告！

## What Was Requested
[完整需求文本]

## What Implementer Claims They Built
[实现者报告]

## CRITICAL: Do Not Trust the Report
❌ 不要相信他们"实现了"
❌ 接受他们对需求的解释
❌ 跳过代码直接看报告

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

## Your Job
**遗漏需求：** 全部实现？跳过或遗漏？声称实现但实际没做？
**额外工作：** 未请求的功能？过度工程？
**误解：** 需求理解偏差？解决错误问题？

Report:
- ✅ Spec compliant
- ❌ Issues found: [具体列出，带 file:line 引用]

为什么"不信任"？

实现者完成得"可疑地快"，报告可能：不完整、不准确、过于乐观。审查者必须阅读实际代码验证。

2.3 代码质量审查模板

前提：必须在规格合规审查通过后

调用方式：
Task tool (superpowers:code-reviewer):
  WHAT_WAS_IMPLEMENTED: [实现者报告]
  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
  BASE_SHA: [任务前提交]
  HEAD_SHA: [当前提交]
  DESCRIPTION: [任务摘要]

额外检查：
- 每个文件单一职责、清晰接口？
- 单元可独立理解和测试？
- 遵循计划定义的文件结构？
- 创建的新文件是否已过大？

两阶段审查的意义：

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

先确保"做了对的事"，再确保"把事做好了"。

---

三、状态处理：优雅地应对各种情况

子代理会返回四种状态，每种都有对应的处理方式。

四种状态

状态	含义	处理方式
DONE	完成工作	进入规格审查
DONE_WITH_CONCERNS	完成但有疑虑	读疑虑 → 决定是否处理
NEEDS_CONTEXT	缺少信息	提供缺失信息 → 重新派遣
BLOCKED	无法完成	评估后决定下一步

BLOCKED 处理决策树

BLOCKED → 什么原因？
    ↓
上下文问题 → 提供更多上下文 → 重新派遣（同模型）
    ↓
推理能力不足 → 重新派遣（更强模型）
    ↓
任务太大 → 拆分成更小任务
    ↓
计划本身错误 → 上报人工

重要原则：永远不要忽略 BLOCKED 或强行用相同模型重试

如果子代理说卡住了，必然有东西需要改变。忽略它只会产生糟糕的工作。

---

四、模型选择策略：最小可用模型原则

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

任务类型与模型选择

任务类型	复杂度信号	推荐模型
机械实现	1-2 文件，规格完整	快速廉价模型
集成判断	多文件协调，调试	标准模型
架构审查	设计决策，广泛理解	最强模型

复杂度判断规则

Touches 1-2 files with complete spec → cheap model
Touches multiple files with integration concerns → standard model
Requires design judgment or broad codebase understanding → most capable model

为什么这样设计？

成本考虑： 强模型调用成本高，简单任务用强模型是浪费。

速度考虑： 强模型响应慢，简单任务用强模型影响迭代速度。

质量考虑： 复杂任务用弱模型会产生低质量结果，得不偿失。

---

五、两套审查机制对比

Superpowers 有两套代码审查机制，各有用途。

对比表

位置	用途	触发时机
agents/code-reviewer.md	项目步骤完成后审查	重大里程碑
skills/requesting-code-review/code-reviewer.md	任务级别审查	每个任务完成后

code-reviewer 模板结构

## What Was Implemented
{DESCRIPTION}

## Requirements/Plan
{PLAN_REFERENCE}

## Git Range to Review
Base: {BASE_SHA}
Head: {HEAD_SHA}

## Review Checklist
- Code Quality（关注点分离、错误处理、DRY、边界情况）
- Architecture（设计决策、可扩展性、性能、安全）
- Testing（测试逻辑、边界覆盖、集成测试、全部通过）
- Requirements（需求满足、规格匹配、无范围蔓延）
- Production Readiness（迁移策略、向后兼容、文档、无 bug）

## Output Format
### Strengths
### Issues (Critical / Important / Minor)
### Recommendations
### Assessment (Ready to merge? Yes/No/With fixes)

审查输出示例

### Strengths
- Clean database schema with proper migrations (db.ts:15-42)
- Comprehensive test coverage (18 tests, all edge cases)
- Good error handling with fallbacks (summarizer.ts:85-92)

### Issues

#### Important
1. **Missing help text in CLI wrapper**
   - File: index.ts:1-31
   - Issue: No --help flag, users won't discover --concurrency
   - Fix: Add --help case with usage examples

#### Minor
1. **Progress indicators**
   - File: indexer.ts:130
   - Issue: No "X of Y" counter for long operations

### Assessment
**Ready to merge: With fixes**

---

六、关键设计洞察

1. 为什么子代理不继承会话历史？

问题： 会话历史包含大量上下文噪音——之前的讨论、尝试、错误、修正...

解决： 精确构建子代理需要的全部信息，不继承任何历史。

好处：

• 子代理聚焦任务，不受干扰
• 你的上下文用于协调，不被实现细节占满
• 避免上下文污染导致的错误决策

2. 为什么必须重新审查？

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

为什么不能一次过？

• 修复可能引入新问题
• "修复"可能根本没修复
• 只有审查者确认才算通过

这不是不信任，是工程实践。

3. 为什么不让子代理读计划文件？

问题： 让子代理自己读文件会带来不可控的上下文。

解决： 控制器提前读取计划，提取任务文本，直接粘贴到子代理的 Prompt 中。

好处：

• 子代理只看到相关内容
• 避免读到其他任务产生干扰
• 控制器可以添加场景设定上下文

---

七、Red Flags：绝对不能做的事

❌ 禁止：

**并行相关：**
- 并行派遣多个实现子代理（会冲突）

**审查相关：**
- 跳过任一阶段审查
- 规格审查通过前开始代码质量审查
- 审查发现问题后不重新审查
- 用自我审查替代正式审查

**上下文相关：**
- 让子代理自己读计划文件
- 跳过场景设定上下文
- 忽略子代理疑问

✅ 必须：

- 回答子代理疑问后再让其继续
- 发现问题 → 修复 → 重新审查
- 按顺序：实现 → 规格 → 质量
- 提供完整任务文本和上下文

---

八、实战案例：完整的子代理调度流程

假设我们有一个计划包含 3 个任务，看看子代理如何调度：

=== Task 1: 创建用户模型 ===

[控制器读取计划，提取 Task 1 文本和上下文]
[派遣 implementer 子代理]

Implementer: 我有个问题：密码字段需要加密吗？
Controller: 是的，使用 BCrypt，强度 10。

Implementer: 明白。
- 创建 User.java
- 添加密码 BCrypt 加密
- 测试通过
- 已提交
- 自我审查：无问题
- Status: DONE

[派遣 spec reviewer 子代理]

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

[派遣 code quality reviewer 子代理]

Code Reviewer: 
优点：命名清晰，加密实现正确
问题（重要）：缺少密码强度验证

[implementer 修复]

Implementer: 已添加密码强度验证（至少 8 位，包含数字和字母）

[Code Reviewer 重审]

Code Reviewer: ✅ 批准

=== Task 1 完成 ===

[继续 Task 2...]

---

九、总结

子代理系统的核心设计理念：

理念	实现
上下文隔离	子代理不继承会话历史，精确构建所需信息
质量把关	两阶段审查（规格 → 质量），确保"对的事"且"做好了"
灵活调度	四种状态处理，针对不同情况采取不同策略
成本优化	最小可用模型原则，简单任务用廉价模型
责任清晰	控制器协调，子代理执行，审查者把关

核心原则：

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

这看似增加了开销，实则节省了调试和返工的时间。慢即是快。

---

参考资料

• Superpowers 源码
• 作者博客：Superpowers 介绍
• Claude Code 文档

---

本文是 Superpowers 源码学习系列第四阶段笔记。下一阶段将深入测试系统，了解如何验证技能的正确性。