Layer 5：Subagents 实战教学

前置阅读：Layer1-长期上下文.md / Layer2-工具能力.md / Layer3-工作流Skills.md（六层架构前三层）、实战-钱塘江标书全流程.md（12 章标书的完整实战故事）

关联 Skill：report-writing（subagent 写作模板 + 4 维度检查框架）

你的现状：Subagent 已经用得很熟了——标书并行写作、多 Agent 审阅、表格批量填写都做过。但权限管理和约束设计还有缺口，钱塘江标书的"单位名称泄露事故"就是证据。这份教学重点补这个短板。

---

怎么读这份文件

这份文件不是 Subagent 入门教程——你不需要入门，你已经在用了。这份文件是从你的实战经验中提炼出来的改进指南，重点解决"用了但没用好"的问题。

九章的逻辑：

第一章  核心价值    → Subagent 的价值不是"快"，而是"隔离"
第二章  使用判断    → 什么时候该用、什么时候不该用
第三章  权限控制    → 你目前最大的短板（直接决定安全性）
第四章  Agent 定义  → .claude/agents/ 目录下的 agent 定义文件
第五章  Prompt 写法 → 好 prompt vs 坏 prompt 的对照
第六章  实战案例    → 我们做过的三个真实项目
第七章  模型选择    → 什么任务用什么模型
第八章  反模式      → 踩过的坑和常见错误
第九章  TODO        → 接下来要做的改进

建议读法：

• 如果你想补权限短板：直接跳到第三章，这是全文最重要的一章
• 如果你想改进 prompt：第五章有好坏对照，拿来就能用
• 如果你想复习实战经验：第六章是案例复盘
• 每章末尾的 <!-- 批注区 --> 是留给你追问的位置

---

一、Subagent 的核心价值不是"并行"而是"隔离"

1.1 最常见的误解

大多数人（包括你最初）对 Subagent 的理解是：并行加速。3 个 subagent 同时写，速度是 1 个的 3 倍。

没错，并行确实快。但并行只是副产品。如果只是为了快，你可以开 3 个 CC 窗口手动跑——效果差不多。

Subagent 真正的价值是 context 隔离。

1.2 什么叫 context 隔离

主会话有 200K 的 context 窗口。每个 subagent 也有自己独立的 200K 窗口。关键在于：

• Subagent 的中间过程不进主会话。 Subagent 搜索了 50 个文件、读取了 3 万字的素材、写了 8000 字的初稿——这些统统留在 subagent 自己的 context 里。主会话只收到最终结果（比如"第 3 章已写入 ~/Work/zdwp/bid/md/ch03.md"）。
• 主会话的 context 保持干净。 你调度了 3 个 subagent 写 12 章，主会话的 context 里只有调度指令和结果汇报，不会被 12 章的文字内容塞满。
• Subagent 之间互不影响。 写第 1 章的 subagent 不知道写第 5 章的 subagent 在做什么。它们各自在自己的 200K 窗口里工作。

1.3 用钱塘江标书举例

当时我们 3 个 subagent 并行写 12 章初稿。如果不用 subagent，在主会话里一章一章写会怎样？

用 subagent 的话，主会话从头到尾只存了调度信息——"第 1 章交给 agent-A，第 5 章交给 agent-B"——context 始终干净，随时可以做全局判断。

1.4 一句话总结

并行是 subagent 的"速度收益"，隔离是 subagent 的"质量收益"。速度可以用其他方式弥补（多窗口、异步等），隔离只有 subagent 能做到。

---

二、什么时候该用 Subagent

2.1 判断表

2.2 两条判断规则

规则 1：任务能拆成独立子任务吗？

如果能拆——而且子任务之间不需要实时通信——就用 subagent。

能拆的：12 章标书（每章独立）、5 章审阅（每章独立）、89 张表格（按章节分组）
不能拆的：需要前后章节交叉引用的润色、需要全文统一数据的校验

规则 2：中间过程会污染主会话吗？

如果一个任务需要读取大量文件、做大量搜索，中间过程会占用主会话的 context，就应该派 subagent。

会污染的：代码库探索（搜索 50 个文件）、大量文献阅读、多目录对比
不会污染的：改一行代码、查一个配置、问一个问题

两条规则满足任意一条就考虑用 subagent。两条都满足则必须用。

---

三、权限控制（最关键的改进点）

3.1 为什么权限控制是你最大的短板

钱塘江标书的"单位名称泄露事故"直接暴露了这个问题。回顾一下事故：

• 5 个 subagent 在填写表格引导段落时，写入了"杭州市水文水资源监测中心"
• 技术标是匿名评审，出现投标单位名称 = 废标
• 全文搜索发现 110 处泄露，紧急清理

根因：subagent 的权限和主线程完全一样——能读任何文件、能搜网页、能写任何内容。没有任何约束。

这就好比你把公司公章交给实习生，然后告诉他"注意别乱盖"——你指望他"应该知道"什么该盖什么不该盖。正确的做法是把公章锁起来，只在需要的时候拿出来。

3.2 Subagent 的四个权限配置项

白名单 vs 黑名单怎么选？

推荐：优先用白名单。因为白名单是"默认拒绝"——没明确允许的工具都不能用。黑名单是"默认允许"——忘记禁止一个危险工具，就有安全隐患。

3.3 实战权限配置对照表

这张表直接回答"什么场景配什么权限"：

3.4 maxTurns：防止 subagent 跑飞

maxTurns 限制 subagent 的最大对话轮数。设太小任务做不完，设太大可能死循环。

3.5 完整配置示例：标书写作 subagent

// 在主会话中调用 subagent 时的配置
{
  prompt: `你是技术报告写作专家。写第 3 章：总体方案设计。
    ...（完整 prompt 见第五章）...`,
  disallowedTools: ["WebSearch", "WebFetch"],
  model: "sonnet",
  maxTurns: 20
}

3.6 完整配置示例：报告审阅 subagent

{
  prompt: `你是报告审阅专家。审阅第 2 章：现状分析。
    按 D1-D4 四维度逐一检查，输出批注清单。
    ...（完整 prompt 见第五章）...`,
  tools: ["Read", "Grep", "Glob"],
  model: "opus",
  maxTurns: 15
}

3.7 如果你只能从这章记住一件事

Subagent 的默认权限和你的主会话一样宽。每次派 subagent 之前，先问自己：这个任务需要联网吗？需要写文件吗？需要执行命令吗？不需要的权限一律不给。

---

四、Agent 定义文件（.claude/agents/）

4.1 什么是 Agent 定义文件

Agent 定义文件是一个 Markdown 文件，放在 ~/.claude/agents/ 目录下。它定义了一类 subagent 的角色、约束和工具权限。

为什么需要它？

如果你每次派 subagent 都要在 prompt 里重复写一遍角色定义、禁止事项、格式规范，那很容易漏掉某一条。Agent 定义文件把这些固化下来——你定义一次，以后每次调用这个 agent 类型时自动加载。

4.2 Agent 定义文件的结构

一个 Agent 定义文件包含三部分：

第一部分：角色定位和约束

# bid-chapter-writer

你是技术标书写作专家。你的任务是根据评分标准和素材文件，撰写标书的指定章节。

## 约束

- 绝对禁止出现任何具体单位名称（投标方、采购方、竞争对手）
- 绝对禁止出现任何具体人名、联系方式
- "采购人"一词用"甲方"替代
- 禁用词：确保、我们、我司
- 禁止使用 bullet point（用表格或段落替代）
- 数据必须标注来源，格式为 [数据来源：XX]

第二部分：工具权限

## 工具限制

禁止使用：WebSearch、WebFetch

第三部分：输出格式要求

## 输出格式

- 输出为 Markdown 文件
- 文件路径：由调用方指定
- 标题层级：章标题用 `#`，节标题用 `##`，小节用 `###`
- 表格必须有表名（格式：表X-Y 表格名称），表名前必须有引导段落（至少80字）
- 引导段落→表名→表格的顺序不可颠倒

4.3 用标书写作 agent 当例子

下面是一个完整的 agent 定义文件，基于我们在钱塘江标书中的经验：

# bid-chapter-writer

你是技术标书章节写作专家。根据评分标准和素材文件，撰写标书的指定章节。

## 安全约束（最高优先级）

绝对禁止出现以下内容：
- 任何具体的单位名称（投标方、采购方、竞争对手、合作方）
- 任何具体的人名
- 任何联系方式（电话、地址、邮箱）
- "采购人"一词（用"甲方"替代）
- "本院""本所""本公司"等暗示组织类型的称谓

如果你不确定某个名称是否可以出现，用"相关单位""相关部门""投标人"代替。
违反此规则的内容将导致废标。

## 质量框架（4 维度检查）

写完后必须用 4 维度自检：
- D1 来龙去脉：数据和事情的前因后果讲清楚，每个结论有推导过程，不跳步
- D2 乙方立场与措辞：站乙方立场，委婉表达，风险抛给甲方/政策
- D3 报告结构：先现状后方案，汇总一一对齐，结论对应回前文分析
- D4 预判评审：写完假装自己是审查专家，检查能不能问倒自己

## 格式规范

- 禁用词：确保、我们、我司
- 禁止使用 bullet point（用表格或段落替代）
- 数据标注来源：[数据来源：XX]
- 表格必须有表名，格式为"表X-Y 表格名称"
- 表名前必须有引导段落（至少 80 字），说明为什么需要这个表格
- 顺序必须是：引导段落 → 表名 → 表格

## 工具限制

禁止使用：WebSearch、WebFetch

## 输出格式

- 输出为 Markdown 文件
- 章标题用 `#`，节标题用 `##`，小节用 `###`
- 写入调用方指定的文件路径

4.4 目录规划

~/.claude/agents/
├── bid-chapter-writer.md    # 标书章节写作
├── report-reviewer.md       # 报告审阅
├── code-explorer.md         # 代码库探索（只读，用 Haiku）
└── table-filler.md          # 表格批量填写

目前这个目录是空的——这是接下来要建设的（见第九章 TODO）。

4.5 Agent 定义文件 vs Skill

你可能会问：Agent 定义文件和 Skill 有什么区别？

举例：report-writing Skill 定义了 4 维度检查框架和 subagent 写作模板——这是"知识"。bid-chapter-writer Agent 定义了标书写作 subagent 的角色、禁止事项、工具权限——这是"约束"。

一个 subagent 可以同时使用 Agent 定义（约束它的行为）和 Skill（提供它需要的知识）。

---

五、Subagent Prompt 的写法

5.1 坏 prompt vs 好 prompt

坏的 prompt：

帮我写第3章

问题在哪？

• subagent 不知道第 3 章写什么（没有评分标准）
• subagent 不知道要检查什么（没有质量框架）
• subagent 不知道什么不能写（没有禁止事项）
• subagent 不知道格式要求（没有规范）
• subagent 不知道素材在哪（没有路径）
• subagent 不知道写到哪（没有输出路径）

结果：subagent 会根据自己的"理解"去编造内容，格式随意，可能写入敏感信息。

好的 prompt：

你是技术报告写作专家。写第 3 章：总体方案设计。

**评分标准（6分）**：方案设计合理性、技术路线清晰度、创新性

**4 维度检查**：
- D1 来龙去脉：数据和事情的前因后果讲清楚，每个结论有推导过程，不跳步
- D2 乙方立场与措辞：站乙方立场，委婉表达，风险抛给甲方/政策
- D3 报告结构：先现状后方案，汇总一一对齐，结论对应回前文分析
- D4 预判评审：写完假装自己是审查专家，检查能不能问倒自己

**格式规范**：
- 禁用词：确保、我们、我司
- 禁止使用 bullet point（用表格或段落替代）
- 数据标注来源：[数据来源：XX]
- 表格必须有表名，格式为"表X-Y 表格名称"
- 表名前必须有引导段落（至少 80 字）
- 顺序：引导段落 → 表名 → 表格

**绝对禁止出现以下内容**：
- 任何具体的单位名称（投标方、采购方、竞争对手）
- 任何具体的人名
- 任何联系方式（电话、地址、邮箱）
- "采购人"一词（用"甲方"替代）
如果你不确定某个名称是否可以出现，用"相关单位""相关部门"代替。

**素材文件**：
- 招标文件采购需求：~/Work/zdwp/bid/requirements.md
- 评分标准：~/Work/zdwp/bid/scoring.json
- 项目区域资料：~/Work/zdwp/bid/area_info.md

**输出**：~/Work/zdwp/bid/md/ch03.md

5.2 好 prompt 的七个要素

从上面的好 prompt 中提炼出结构：

5.3 Prompt 模板（可直接复用）

这个模板来自 report-writing Skill，是我们在标书项目中验证过的：

你是技术报告写作专家。写第 {N} 章：{章节标题}。

**评分/要求**：{评分标准或合同要求}

**4 维度检查**：
- D1 来龙去脉：数据和事情的前因后果讲清楚，每个结论有推导过程，不跳步
- D2 乙方立场与措辞：站乙方立场，委婉表达，风险抛给甲方/政策
- D3 报告结构：先现状后方案，汇总一一对齐，结论对应回前文分析
- D4 预判评审：写完假装自己是审查专家，检查能不能问倒自己

**格式规范**：
- 禁用词：确保、我们、我司
- 禁用格式：bullet point（用表格或段落替代）
- 数据必须标注来源

**绝对禁止**：
- {根据场景填写具体的禁止事项}

**素材路径**：{参考文件1}, {参考文件2}
**输出**：{输出文件路径}

5.4 审阅 prompt 模板

审阅和写作的 prompt 结构不同。审阅 prompt 重点在"输出格式"——批注清单必须格式统一，否则后续合并去重很困难。

你是报告审阅专家。审阅第 {N} 章：{章节标题}。

**文件路径**：{待审阅文件路径}

**审阅维度（按 D1-D4 逐一扫描）**：
- D1 来龙去脉：推导链完整吗？数据从哪来？事情为什么这样？
- D2 乙方立场与措辞：有没有越位表述？有没有绝对词需要软化？
- D3 报告结构：信息顺序对吗？结论能对应回前文分析吗？
- D4 预判评审：审查专家会问什么问题？文中已经回答了吗？

**输出格式**：
每条批注一行，格式为：
[维度编号] L行号: "原文" → 修改建议（理由）

示例：
[D2] L42: "必须整改" → 建议改为"建议按标准改造完善"（乙方不做行政定论）
[D1] L78: "经筛选剩余12座" → 缺少筛选过程，建议补充"从XX座中按XX标准排除XX座"

**输出文件**：{批注输出路径}

---

六、我们的实战案例

6.1 案例 1：标书并行写作（钱塘江项目）

项目背景：钱塘江流域杭州部分取用水监测计量能力提升项目，95 万元技术标，12 章。

第一轮：3 个 subagent 写初稿

主会话（调度）
├── subagent-A：第 1-4 章（项目背景、现状分析、总体方案、技术方案细节）
├── subagent-B：第 5-6 章（设备选型、数据平台方案）
└── subagent-C：第 7-8 章（实施方案、组织架构）

第二轮：重写薄弱章节

验收后发现第 1 章结构不好（应该用漏斗结构：宏观政策→省级要求→杭州需求→本项目），第 9 章重难点分析太泛。

主会话（验收 + 再分配）
├── subagent-D：重写第 1 章（漏斗结构）
├── subagent-E：重写第 9 章（具体技术难点 + 解决方案）
└── subagent-F：写第 10 章（进度计划 + 甘特图）

第三轮：管理章节 + 表格填写

主会话
├── subagent-G：第 11 章（质量保障方案）
├── subagent-H：第 12 章（售后服务方案）
├── subagent-1：第 1-3 章表格填写
├── subagent-2：第 4-5 章表格填写
├── subagent-3：第 6-7 章表格填写
├── subagent-4：第 8-9 章表格填写
└── subagent-5：第 10-12 章表格填写

教训：

6.2 案例 2：报告多 Agent 审阅（景宁项目）

项目背景：景宁县小型水库工程生态流量核定与保障实施方案，需要多章节审阅。

按章节分（我们采用的方案）：

主会话
├── subagent-审1：审阅第 1-2 章（全部 4 维度）
├── subagent-审2：审阅第 3-4 章（全部 4 维度）
└── subagent-审3：审阅第 5-6 章（全部 4 维度）

每个 subagent 对自己负责的章节做完整的 D1-D4 四维度检查。

为什么不按维度分？

合并去重：

3 个 subagent 各自输出批注清单后，用 review_summary.py 合并：

python3 ~/Dev/scripts/scripts/document/review_summary.py \
  review_ch1-2.md review_ch3-4.md review_ch5-6.md \
  -o review_merged.md

脚本做的事情：

1. 按维度（D1-D4）重新分组所有批注
2. 去掉重复的批注（不同章节可能有相同的措辞问题）
3. 按行号排序

6.3 案例 3：表格批量填写（钱塘江项目）

背景：12 章技术标中有 89 张表格，全部没有表名和引导段落。

方案：5 个 subagent 按章节并行填写。

主会话
├── subagent-1：第 1-3 章（约 18 张表）
├── subagent-2：第 4-5 章（约 17 张表）
├── subagent-3：第 6-7 章（约 20 张表）
├── subagent-4：第 8-9 章（约 16 张表）
└── subagent-5：第 10-12 章（约 18 张表）

每个 subagent 的 prompt 明确要求：

为你负责的章节中每张表格补充：
1. 表名（格式：表X-Y 表格名称，X=章号，Y=序号）
2. 引导段落（至少80字，包含：为什么需要这个表格、依据什么标准、不这样做会怎样）
3. 顺序必须是：引导段落 → 表名 → 表格

教训：table_name_check.py 的检测逻辑有 bug——只检查表格上方第一行是不是表名，但表名和表格之间可能隔了空行，导致误报"没有表名"。修复后改为向上搜索 10 行。

启示：subagent 的输出不能无条件信任。即使 subagent 完成了任务，也需要脚本验证。但验证脚本本身也可能有 bug——所以验证脚本也需要验证（在正常文件上跑一遍确认不误报）。

---

七、模型选择策略

7.1 不同任务用不同模型

7.2 怎么配置模型

在 subagent 调用时通过 model 参数指定：

// 探索任务——用 Haiku 省钱
{
  prompt: "搜索 ~/Work/zdwp/ 下所有包含'生态流量'的文件，列出文件路径和关键行",
  tools: ["Read", "Grep", "Glob"],
  model: "haiku",
  maxTurns: 10
}

// 写作任务——用 Sonnet 平衡质量和成本
{
  prompt: "写第 3 章：总体方案设计...",
  disallowedTools: ["WebSearch", "WebFetch"],
  model: "sonnet",
  maxTurns: 20
}

// 审查任务——用 Opus 确保质量
{
  prompt: "审阅第 2 章：现状分析...",
  tools: ["Read", "Grep", "Glob"],
  model: "opus",
  maxTurns: 15
}

7.3 一条实用原则

写的时候用 Sonnet，审的时候用 Opus。如果你不确定用什么，默认 Sonnet。只有"不能出错"的任务才用 Opus。

为什么不全用 Opus？因为成本。12 章标书每章用 Opus 写，API 费用大约是 Sonnet 的 5 倍。而写作质量的提升不成正比——Sonnet 已经能写出 85 分的内容，Opus 也许能写到 90 分，但价格差了 5 倍。

但审查不同。审查漏掉一个问题（比如单位名称泄露），代价是废标。审查阶段多花 5 倍 API 费用，换来更低的漏检率，完全值得。

---

八、常见反模式

8.1 反模式 1：subagent 权限和主线程一样宽

表现：派 subagent 时不配置 tools 或 disallowedTools，让 subagent 拥有全部工具权限。

后果：subagent 可能执行你没预期的操作——比如上网搜索到投标单位信息、执行危险的 bash 命令、修改不该改的文件。

正确做法：每次派 subagent 前问自己三个问题：

1. 这个任务需要联网吗？（不需要就禁 WebSearch/WebFetch）
2. 这个任务需要写文件吗？（不需要就只给 Read/Grep/Glob）
3. 这个任务需要执行命令吗？（不需要就禁 Bash）

8.2 反模式 2：输出格式不固定

表现：不在 prompt 中规定输出格式。3 个审阅 subagent，一个输出 Markdown 表格、一个输出纯文本列表、一个输出 JSON。

后果：主会话或合并脚本无法统一处理。你要花大量时间手动对齐格式，或者写 3 套解析逻辑。

正确做法：在 prompt 中明确规定输出格式，精确到每一行的结构。参考第五章的审阅 prompt 模板——批注格式精确到 [维度编号] L行号: "原文" → 修改建议（理由）。

8.3 反模式 3：子任务间有强依赖

表现：subagent-A 写第 1 章的结论，subagent-B 写第 2 章需要引用第 1 章的结论。但 A 和 B 是并行的，B 开始写的时候 A 还没写完。

后果：B 不知道 A 的结论是什么，要么编造、要么跳过、要么报错。

正确做法：子任务必须完全独立。如果有依赖，就串行——先跑完 A，再跑 B。或者把依赖的内容提前准备好，作为素材传给两个 subagent。

# 错误：A 和 B 有依赖但并行
subagent-A → 写第 1 章（产出结论）
subagent-B → 写第 2 章（引用第 1 章结论）  ← 但此时 A 还没写完

# 正确方案 1：串行
subagent-A → 写第 1 章
验收第 1 章，提取关键结论
subagent-B → 写第 2 章（附上第 1 章关键结论作为素材）

# 正确方案 2：预设共享素材
提前准备好"各章节关键结论"的素材文件
subagent-A → 写第 1 章（参考素材文件）
subagent-B → 写第 2 章（参考同一个素材文件）

8.4 反模式 4：没有验收步骤

表现：subagent 写完就直接用，不检查输出质量。

后果：subagent 的输出可能有各种问题——bullet point（CC 天生爱用）、格式不统一、内容重复、数据来源缺失。这些问题在最终交付时才被发现，修复成本高。

正确做法：

调度 → subagent 写作 → 验收 → 后处理 → 再验收 → 交付
                         ↑                    ↑
                    主会话/脚本检查        最终脚本扫描

验收至少两轮：

1. subagent 完成后：主会话快速浏览输出，检查是否偏题、是否有明显错误
2. 后处理完成后：跑质量检查脚本（report_quality_check.py、check_sensitive_words.py）做系统性扫描

---

九、TODO

这些是基于当前实战经验，接下来要做的改进：

• 给标书写作 agent 加上 disallowedTools: ["WebSearch", "WebFetch"]
• 创建 ~/.claude/agents/bid-chapter-writer.md（第四章的完整模板）
• 创建 ~/.claude/agents/report-reviewer.md（审阅 agent 定义）
• 创建 ~/.claude/agents/code-explorer.md（只读探索 agent，默认 Haiku）
• 统一 subagent 的输出格式（写作用 MD、审阅用批注格式、搜索用文件清单）
• 更新 report-writing Skill 的 subagent 模板，加入表格规范和禁止条款
• 配置 PostToolUse Hook：subagent 写文件后自动检查敏感词
• 写一个 bid_sensitive.txt 通用敏感词清单模板

优先级排序：

---

附：快速参考

Subagent 配置速查

{
  prompt: "...",                              // 必填：完整的 prompt（七要素）
  tools: ["Read", "Grep", "Glob"],            // 可选：白名单（推荐）
  disallowedTools: ["WebSearch", "WebFetch"], // 可选：黑名单
  model: "sonnet",                            // 可选：haiku/sonnet/opus
  maxTurns: 20                                // 可选：防止跑飞
}

Prompt 七要素清单

每次写 subagent prompt 前过一遍：

1. 角色定位
2. 具体任务
3. 评分标准/要求
4. 4 维度检查清单
5. 格式规范（禁用词、禁用格式、表格规范）
6. 素材路径
7. 输出路径 + 禁止事项

权限配置速查