# Using Subagents

> 指导如何可靠使用 subagents、多个 Agents、并行 Agent 审查、集群搜索和项目分片处理。当用户要求使用 Agents/SubAgents、并行 Agent、对抗审查、多角色审查、集群搜索、项目分片处理，或明确说出“进入agents approve迭代模式”时使用。

- Skill: `lianues/using-subagents` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add lianues/using-subagents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lianues/using-subagents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: lianues (https://skillmd.com/u/lianues)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lianues/using-subagents

---


# 使用 Subagents

## 背景知识

SubAgent 是无状态的：每一次调用的 SubAgent 都是无状态且独立的。它不会继承主 Agent 的聊天记录、主 Agent 已读过的 Skill、其他 Agent 的输出、上一轮结论，也不会知道主 Agent 脑中的计划。

中央数据库 / 共享信息库是同一概念：使用多个 SubAgents、多轮复核、审批、阻断项收敛或任何需要共享状态的任务时，公共事实、决策、阻断项、修订结果、审批结论必须写进外部位置，不能只留在聊天里。例如 `docs/pm/{对应session主题名}/`。

Skill 资源遵循渐进披露：先读取 Skill 主体；当 Skill 主体或任务需要引用附属资料时，再按 `read_skill` 返回的 resources manifest，用 `read_skill_resource` 按需读取 `textReadable=true` 的相关资源。不要无条件读取所有 resources。

集群并行调用 SubAgents 的方法：并行应该在单轮输出中同时调用多次 SubAgents 工具，禁止分轮次调用，除非一个 SubAgent 的输入信息依赖另一个 SubAgent 的输出。

## 调用前门禁

调用任何 SubAgent 之前，主 Agent 必须先判断任务类型。

### 一次性简单任务

如果任务不依赖上一轮结论、不依赖其他 SubAgent 输出、不需要审批收敛，也不需要后续复核，可以直接在 prompt/context 中完整写入目标、背景、约束、范围、输出格式和成功标准。

### 必须使用中央数据库的任务

只要满足以下任一条件，必须先建立或引用中央数据库 / 共享信息库，不允许只靠 prompt 摘要：

- 用户要求使用多个 Agents、SubAgents、并行 Agent、对抗性审查、多角色审查或集群处理。
- 任务出现“第一轮”“第二轮”“上一轮”“复核”“审批”“阻断项”“修订后”“Approve/Blocker 收敛”等语义。
- 需要多个 SubAgents 共享事实或接力。
- 需要后续 SubAgent 继承前一轮结论。
- 需要记录采纳、拒绝、阻断项、验证结果或最终决策。
- 任务会跨多次工具调用、多个 Agent 或多次对话轮次。

中央数据库推荐放在 `docs/pm/{task-name}/`，至少包含：

- `README.md`：索引和文件用途。
- `MASTER_CONTEXT.md`：长期背景、目标、术语、边界和硬约束。
- `STATUS.md`：当前阶段、已完成项、阻断项和下一步。
- `DECISIONS.md`：已采纳/拒绝的关键决策和理由。
- `reports/`：每个 SubAgent 的调研、审查、审批、复核报告。

### Agents Approve 迭代模式

当用户明确说出 `进入agents approve迭代模式`、`进入 agents approve 迭代模式` 或等价表达时，主 Agent 必须进入多 Agent 审批迭代流程。该模式不是普通并行审查，而是一个以 `APPROVE` / `BLOCKER` / `CONCERN` / `NEEDS_INFO` 为结论类型的闭环。

进入该模式后，主 Agent 必须：

1. 建立或引用中央数据库 / 共享信息库。
2. 将目标、长期背景、被审对象、通过标准、阻断标准、当前阶段和报告写入位置写入共享信息库。
3. 并行派发多个 SubAgent 进行独立审查；每个 SubAgent 的 prompt 都必须自包含，或明确要求读取共享信息库中的指定文件。
4. 汇总每个 SubAgent 的结论、证据、阻断项、关注项和缺失信息。
5. 对确认采纳的阻断项进行修订，并把采纳 / 拒绝理由、修订摘要和验证结果回写共享信息库。
6. 再次派发定向复核 SubAgent，直到没有阻断项、用户停止，或主 Agent 判断必须由用户作出产品、架构、安全或取舍决策。

本模式必须强制执行“SubAgent 无状态”这一全局不变量。当然，无论是否进入该模式，SubAgent 都不会自动继承聊天记录、主 Agent 记忆、上一轮结论或其他 SubAgent 输出；本模式只是把这条全局规则用于审批迭代场景，并要求每一轮的阻断项、修订摘要、审批结论和证据路径都回写到中央数据库 / 共享信息库。

### 复核和审批强制字段

二轮或后续复核、审批、阻断项收敛的 prompt 必须包含或引用以下内容；缺一项时不得派发 SubAgent：

1. 中央数据库 / 共享信息库路径。
2. SubAgent 开始前必须读取的文件列表。
3. 上一轮报告路径。
4. 上一轮完整问题清单，每个问题都要有证据路径、行号或来源。
5. 本轮修订摘要，并逐条对应上一轮问题。
6. 被复核对象路径。
7. 期望验证点。
8. 通过标准和仍然阻断的判定标准。
9. 输出格式和报告写入位置。
10. 缺失检查规则：如果无法读取中央数据库、上一轮报告或修订摘要，必须输出 `REJECT: 缺少复核上下文`，不得猜测。

### Skill 驱动任务强制规则

如果 SubAgent 任务依赖某个 Skill，主 Agent 必须执行以下二选一：

1. 主 Agent 先调用 `read_skill`，再按需调用 `read_skill_resource` 读取相关资源，并把必要 Skill 规则和资源摘要写入 SubAgent prompt/context。
2. 在 SubAgent prompt 中明确要求 SubAgent 自己调用 `read_skill`，再按 resources manifest 按需调用 `read_skill_resource`。

禁止只写“参考某 Skill”“继续 Skill 的要求”或“按上面的 Skill 做”。SubAgent 不会自动继承主 Agent 已读过的 Skill。

## 不变量

**硬约束：所有 SubAgents 都必须被视为无状态、独立上下文的执行单元。** 除当前 prompt 明确写入的内容，或 prompt 明确要求读取的共享信息库文件外，SubAgent 看不到主 Agent 聊天记录、上一轮结果、其他 SubAgent 输出、主 Agent 已读 Skill、隐含项目背景或主 Agent 脑中的计划。

SubAgent 无状态不是 `Agents Approve 迭代模式` 的特殊规则，而是所有 SubAgent 调用的不变量。凡是需要跨 Agent、跨轮次、跨复核阶段或跨对话继承的信息，都必须写入 prompt 或中央数据库 / 共享信息库，禁止依赖聊天记录、主 Agent 记忆或上一轮隐含上下文。

主 Agent 的职责不是给 SubAgent 做权限管理，而是分配注意力：让每个 SubAgent 聚焦什么、忽略什么、产出什么，并把结论汇总成可执行决策。

## 工作流

1. **判断是否值得并行**。
   - 适合：多方向搜索、大项目分片、独立复核、对抗性审查、多角色视角、长任务并行产出。
   - 不适合：单文件小改、明确答案、普通单 Agent 代码审查、需要一个连续状态机的任务。
   - 说清切分维度：按来源、模块、文件集合、角色、风险面还是任务阶段。

2. **显式外化共享上下文，并维护中央数据库 / 共享信息库**。
   - 多个 SubAgent 共用的事实，必须写进中央数据库，例如 `docs/pm/` 模式的信息库、设计文档、任务清单、状态文件或报告目录。
   - 中央数据库是外部输入源，不是 SubAgent 记忆；prompt 必须明确要求 SubAgent 读取哪些文件。
   - 主 Agent 负责维护这套信息库：新事实、决策、阻断项、修订结果和复核结论都要回写，不能只留在聊天记录里。
   - 一次性简单任务可以不写文件，但必须在每个 prompt 中完整写入目标、背景、约束、范围、输出格式和成功标准。
   - 如果任务提到“第一轮”“上一轮”“阻断项”“修订后”“复核”，必须列出上一轮结论、阻断项、修订内容和被审文件路径，或指向包含这些内容的上下文文件。
   - 禁止在 SubAgent prompt 中使用相对指代，包括但不限于：“如上”“继续刚才”“上一轮问题”“参考另一个 Agent 的结论”“只审查第一轮阻断问题”。
   - 共享信息库组织方式见 `references/shared-context-store.md`。

3. **选择注意力切分模式**。
   - 集群搜索：按来源、关键词、语言、证据类型或立场拆分。见 `references/cluster-search.md`。
   - 集群处理项目：按模块、文件集合、架构层、风险面或任务阶段拆分。见 `references/cluster-project-work.md`。
   - 对抗性审查：让 SubAgent 独立寻找反例、阻断点、证据缺口和替代设计。见 `references/adversarial-review.md`。
   - 多角色视角：产品、架构、安全、测试、性能、维护者等角色分别审查。见 `references/multi-role-review.md`。

4. **写自包含 prompt**。
   - 因为 SubAgent 没有任何外部记忆，每个 prompt 是它唯一的信息来源。
   - 每个 prompt 包含：任务、背景、输入范围、输出产物、证据要求、完成标准。
   - 若涉及修改，写清文件边界、预期行为、测试要求和冲突规则。
   - 若涉及搜索，写清问题域、关键词、技术约束、排除范围和判断标准。
   - 若涉及复核，必须包含或引用：被复核对象路径、上一轮完整问题清单、每个问题的修订摘要、期望验证点、通过/阻断标准和输出格式；缺少任一项时不得派发 SubAgent。
   - 需要模板时读取 `references/prompt-patterns.md`。

5. **并行隔离，汇总复核**。
   - 第一轮保持独立：不要让一个 SubAgent 的输出污染另一个。
   - 第二轮可以共享阻断点和修正内容，用于定向复核；必须由主 Agent 把上一轮结论、阻断点、修订摘要和证据路径逐条写入新 prompt，SubAgent 不会自动记得上一轮。
   - 主 Agent 负责汇总共识、冲突、证据强度、采纳/拒绝理由、最终修改和验证。

## 输出契约

使用 SubAgents 后，主 Agent 汇报：切分维度、每个 SubAgent 获得上下文的方式（prompt 内嵌 / 引用文件 / 共享信息库路径）、共享信息库更新位置、每个 SubAgent 的任务和结论、证据、冲突点、采纳/拒绝理由、最终修改、验证结果、未验证点。

## 反合理化

| 借口 | 修正 |
| --- | --- |
| “SubAgent 会知道上下文。” | 不会。把上下文写进 prompt 或文件。 |
| “主 Agent 聊天记录里有方案，SubAgent 自然看得见。” | 看不见。每个 SubAgent 只看到自己的 prompt、context、工具结果和被要求读取的文件；主 Agent 脑中的计划不写出来就等于不存在。 |
| “主 Agent 已经读过 Skill，SubAgent 会照着做。” | 不会。把必要 Skill 规则写进 prompt/context，或要求 SubAgent 自己调用 `read_skill` 和 `read_skill_resource`。 |
| “第二轮/复核 Agent 会自动知道第一轮。” | 不会。必须逐条提供上一轮结论、阻断项、修订摘要和证据路径。 |
| “多叫几个 Agent 就更可靠。” | 只有独立切分、证据要求和复核闭环才提高可靠性。 |
| “一个 Agent 已经 Approve。” | 关键结论至少需要独立视角复核。 |
| “让 SubAgent 直接改就快。” | 可以，但要明确文件边界、预期行为、测试要求、合并协议和复核方式。 |