第 6 课：多代理协作 — 子代理架构全解析

王小酱
3 阅读10分钟

核心命题： 每个子代理是"新鲜的"，主控精心构造它需要的信息。不信任、双阶段评审、允许求助。

课前回顾

第 5 课产出了两样东西：设计文档和实施计划。本课讲解计划是如何被执行的 — 通过一个多代理协作系统。

本课涉及的文件：

skills/subagent-driven-development/
├── SKILL.md                        ← 主控逻辑
├── implementer-prompt.md           ← 实现者模板
├── spec-reviewer-prompt.md         ← 规格审查者模板
└── code-quality-reviewer-prompt.md ← 质量审查者模板

skills/requesting-code-review/SKILL.md  ← 请求评审
skills/receiving-code-review/SKILL.md   ← 接收评审
skills/dispatching-parallel-agents/SKILL.md ← 并行派发
skills/executing-plans/SKILL.md        ← 备选执行方式
agents/code-reviewer.md                ← Agent 角色定义

6.1 主控流程

文件： skills/subagent-driven-development/SKILL.md

完整流程

主控 Agent（你）
│
│  ① 一次性读取计划文件
│  ② 提取所有任务的完整文本和上下文
│  ③ 创建 TodoWrite 跟踪进度
│
├── 任务 1
│   ├── 派发 Implementer → 实现 + 自审 + 提交
│   ├── Implementer 有问题？→ 回答后重新派发
│   ├── 派发 Spec Reviewer → 逐行验证需求
│   ├── Spec 不通过？→ Implementer 修复 → 重新 Spec Review
│   ├── 派发 Code Quality Reviewer → 代码质量审查
│   ├── Quality 不通过？→ Implementer 修复 → 重新 Quality Review
│   └── 通过 → 标记任务完成
│
├── 任务 2 ... 任务 N（同样流程）
│
├── 派发最终 Code Reviewer（整体审查）
└── 调用 finishing-a-development-branch

核心原则：上下文隔离

You delegate tasks to specialized agents with isolated context. By precisely
crafting their instructions and context, you ensure they stay focused and
succeed at their task. They should never inherit your session's context or
history — you construct exactly what they need.

子代理不继承主控的会话历史。 每次派发都是一个"新鲜"的代理，只接收主控精心构造的信息。

为什么这样设计？

  1. 防止上下文污染 — 前一个任务的调试信息不会干扰后一个任务
  2. 保护主控的上下文窗口 — 主控只需要协调，不需要记住所有实现细节
  3. 聚焦 — 子代理只看到自己需要的信息，更容易做好一件事

计划提取策略

Read plan file once at start, extract all tasks with full text

主控在开始时一次性读取计划文件，提取所有任务的完整文本。之后不再让子代理去读文件 — 而是把完整文本传给它们。

为什么不让子代理自己读文件？

  • 文件读取消耗上下文（子代理读了一个大文件，可用窗口变少）
  • 子代理可能读到多余的信息（其他任务的内容）
  • 主控负责"策展"上下文，确保子代理只收到必要的信息

6.2 三个 Prompt 模板

Implementer Prompt — 实现者

文件： skills/subagent-driven-development/implementer-prompt.md

核心结构：

你正在实现任务 N: [任务名称]

## Task Description（完整任务文本 — 主控粘贴，不是让子代理读文件）
## Context（场景上下文 — 这个任务在整体中的位置）
## Before You Begin（鼓励提问）
## Your Job（6 步：实现 → 测试 → 验证 → 提交 → 自审 → 报告）
## Code Organization（文件职责单一性）
## When You're in Over Your Head（允许求助）
## Before Reporting Back: Self-Review（4 维度自检）
## Report Format（4 种状态）

"Before You Begin" — 鼓励提问

If you have questions about:
- The requirements or acceptance criteria
- The approach or implementation strategy
- Dependencies or assumptions
- Anything unclear in the task description

**Ask them now.** Raise any concerns before starting work.

这不是客气话 — 它改变了子代理的行为。没有这段话，子代理会默默开始工作然后在中途卡住。有了这段话，子代理会在开始前主动提出疑问。

"When You're in Over Your Head" — 允许求助

It is always OK to stop and say "this is too hard for me."
Bad work is worse than no work.

**STOP and escalate when:**
- The task requires architectural decisions with multiple valid approaches
- You feel uncertain about whether your approach is correct
- You've been reading file after file without progress

这是一段非常反直觉的指令 — 告诉 AI "可以放弃"。为什么？因为 AI 的默认行为是"硬做" — 即使超出能力也会产出something。但 bad work worse than no work。如果子代理卡住了，主控可以：提供更多上下文、换更强的模型、拆分任务。

四种返回状态

DONE             — 完成了，进入评审
DONE_WITH_CONCERNS — 完成了但有疑虑，主控先看疑虑再决定
NEEDS_CONTEXT    — 需要更多信息，主控提供后重新派发
BLOCKED          — 无法完成，主控升级处理

主控对每种状态的处理：

状态主控动作
DONE进入 Spec Review
DONE_WITH_CONCERNS读疑虑 → 正确性问题则先处理 → 观察性问题则记录后继续
NEEDS_CONTEXT提供信息 → 重新派发同一个模型
BLOCKED提供上下文/升级模型/拆分任务/上报人类

Spec Reviewer Prompt — 规格审查者

文件： skills/subagent-driven-development/spec-reviewer-prompt.md

第一句就定了基调：

## CRITICAL: Do Not Trust the Report

The implementer finished suspiciously quickly. Their report may be incomplete,
inaccurate, or optimistic. You MUST verify everything independently.

**DO NOT:**
- Take their word for what they implemented
- Trust their claims about completeness

**DO:**
- Read the actual code they wrote
- Compare actual implementation to requirements line by line

"suspiciously quickly" — 这个措辞是刻意的。它让审查者带着怀疑的态度去读代码，而不是默认信任实现者的报告。

审查三类问题：

1. Missing requirements — 遗漏了什么？
2. Extra/unneeded work — 多做了什么？
3. Misunderstandings — 理解错了什么？

注意第二类 — "多做了什么"。这对应 YAGNI 原则。AI 有时会"顺便"添加未要求的功能，Spec Reviewer 负责发现并标记。

Code Quality Reviewer Prompt — 质量审查者

文件： skills/subagent-driven-development/code-quality-reviewer-prompt.md

**Only dispatch after spec compliance review passes.**

质量审查只在规格审查通过后才执行。逻辑：先确认"做对了"，再确认"做好了"。如果"做错了"，代码质量再好也没意义。

质量审查复用 agents/code-reviewer.md 的角色定义，但额外检查：

  • 每个文件是否有单一职责？
  • 单元是否可以独立理解和测试？
  • 是否遵循了计划中的文件结构？
  • 新文件是否已经过大？

模型分层策略

**Mechanical implementation tasks** (1-2 files, clear specs): use cheap model
**Integration and judgment tasks** (multi-file coordination): use standard model
**Architecture, design, and review tasks**: use most capable model

不是所有子代理都需要最强的模型。机械性任务（有清晰 spec 的 1-2 个文件修改）用便宜的快速模型就够了。这直接影响成本和速度。

6.3 代码评审的双向技能

请求评审 — requesting-code-review

文件： skills/requesting-code-review/SKILL.md

何时必须评审：

  • 子代理驱动开发中的每个任务完成后
  • 主要功能完成后
  • 合并到主分支之前

评审请求需要填充模板：

WHAT_WAS_IMPLEMENTED: 实现了什么
PLAN_OR_REQUIREMENTS: 需求是什么
BASE_SHA: 起始提交
HEAD_SHA: 结束提交
DESCRIPTION: 摘要

根据反馈严重级别行动：

Critical → 立即修复
Important → 修了才能继续
Minor → 记录，稍后处理

接收评审 — receiving-code-review

文件： skills/receiving-code-review/SKILL.md

这个技能的核心是反对表演性同意：

**NEVER:**
- "You're absolutely right!"
- "Great point!" / "Excellent feedback!"
- "Let me implement that now" (before verification)

**INSTEAD:**
- Restate the technical requirement
- Ask clarifying questions
- Push back with technical reasoning if wrong
- Just start working (actions > words)

为什么禁止说"You're absolutely right"？因为：

  1. 它是一种讨好行为，不是技术判断
  2. 它跳过了"验证评审意见是否正确"的步骤
  3. 它建立了一种不健康的互动模式

正确的做法：

WHEN receiving code review feedback:
1. READ: Complete feedback without reacting
2. UNDERSTAND: Restate requirement in own words
3. VERIFY: Check against codebase reality
4. EVALUATE: Technically sound for THIS codebase?
5. RESPOND: Technical acknowledgment or reasoned pushback
6. IMPLEMENT: One item at a time, test each

先理解，再验证，再行动。 如果评审意见是错的（评审者可能缺少上下文），应该用技术理由 pushback。

YAGNI 检查：

IF reviewer suggests "implementing properly":
  grep codebase for actual usage
  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
  IF used: Then implement properly

如果评审者建议"正确实现"某个功能，先检查这个功能是否真的被使用了。如果没有，YAGNI 优先。

6.4 并行代理派发

文件： skills/dispatching-parallel-agents/SKILL.md

适用场景

多个失败? ──→ 它们独立吗? ──→ 能并行工作吗? ──→ 并行派发
               │ 否            │ 否
               ▼               ▼
          单个代理调查全部   串行代理

使用条件：

  • 3+ 个测试文件失败，各有不同根因
  • 多个子系统独立出问题
  • 每个问题可以独立理解
  • 代理之间不会互相干扰（不编辑同一个文件）

Prompt 设计原则

好的并行代理 prompt 需要三个特征：

1. Focused — 一个清晰的问题域
2. Self-contained — 包含理解问题所需的所有上下文
3. Specific output — 明确告诉代理返回什么

对比：

❌ 太宽泛："Fix all the tests"
✅ 聚焦："Fix agent-tool-abort.test.ts 的 3 个失败"

❌ 缺上下文："Fix the race condition"
✅ 有上下文：粘贴错误消息和测试名称

❌ 模糊输出："Fix it"
✅ 明确输出："Return summary of root cause and changes"

真实案例

6 个测试失败，分布在 3 个文件：
- agent-tool-abort.test.ts: 3 failures (timing issues)
- batch-completion-behavior.test.ts: 2 failures (event structure)
- tool-approval-race-conditions.test.ts: 1 failure (async)

→ 三个独立的问题域 → 派 3 个代理并行处理

Agent 1: 用事件等待替换超时
Agent 2: 修复事件结构 bug（threadId 位置错误）
Agent 3: 添加异步等待

→ 所有修复独立，无冲突
→ 3 个问题在 1 个问题的时间内解决

6.5 Agent vs. Skill 的本质区别

项目中只有一个 Agent 定义（agents/code-reviewer.md）和 14 个 Skills。它们的区别是什么？

Agent = 角色（WHO）
  "你是一个资深代码审查员"
  定义了身份、专长、行为方式

Skill = 流程（HOW）
  "先做 brainstorming，再做 writing-plans"
  定义了步骤、规则、衔接关系

Agent 被用作子代理的"角色扮演"指令，Skill 被用作行为控制流程。在 subagent-driven-development 中，两者结合：

Implementer 子代理 = 通用 Agent + TDD Skill
Spec Reviewer 子代理 = 自定义 Prompt（spec-reviewer-prompt.md）
Code Quality Reviewer = code-reviewer Agent + 额外检查项

6.6 备选执行路径：executing-plans

文件： skills/executing-plans/SKILL.md

当平台不支持子代理时（如 Gemini CLI），使用 executing-plans 作为备选：

Tell your human partner that Superpowers works much better with access to
subagents. The quality of its work will be significantly higher if run on
a platform with subagent support.

executing-plans 是简化版：在当前会话中逐步执行，没有双阶段评审。它明确告知用户这是"降级模式"。

实践作业

作业 1：分析 Prompt 模板

阅读三个 Prompt 模板（implementer / spec-reviewer / code-quality-reviewer），找出：

  • 每个模板中"鼓励求助"的语句
  • 每个模板的核心"怀疑点"是什么
  • 它们之间的调用顺序为什么不能改变

作业 2：模拟双阶段评审

取你在第 5 课写的 3 任务计划中的一个任务：

  1. 假装你是 Implementer，实现它
  2. 假装你是 Spec Reviewer，用"Do Not Trust the Report"的态度检查
  3. 假装你是 Code Quality Reviewer，检查代码质量
  4. 记录每个角色发现了什么不同的问题

本课自检清单

  • 能画出 subagent-driven-development 的完整协作流程
  • 能说出三个 Prompt 模板各自的核心设计意图
  • 理解"先 Spec Review 再 Code Quality Review"的顺序逻辑
  • 能说出四种返回状态及主控的处理方式
  • 理解 Agent 和 Skill 的本质区别
  • 理解"禁止表演性同意"的设计哲学

下节预告

第 7 课：技能铸造术 — CSO + 心理学 + TDD for Docs

前六课我们读懂了所有技能。第 7 课进入更深的层次：这些技能是怎么被创造出来的？description 字段为什么那么讲究？说服心理学在技能设计中扮演什么角色？如何用 TDD 测试一份文档？

avatar
文章
阅读
粉丝