03 - 子代理体系设计

1. 定位

子代理是 Claude Code 跨隔离上下文窗口并行化工作的机制。每个子代理拥有独立的上下文窗口，不会污染主会话。

核心价值：

并行执行：多个独立任务同时进行
上下文隔离：研究类任务不消耗主会话上下文
专业化分工：不同代理可指定不同模型和工具权限

2. 内置子代理（直接可用，无需配置）

Claude Code 已内置以下子代理类型，通过 Task 工具调用：

子代理类型	用途	可用工具	模型
Explore	代码库探索	Glob, Grep, Read, WebFetch, WebSearch	继承主会话
Plan	架构设计	Glob, Grep, Read, WebFetch, WebSearch	继承主会话
Bash	命令执行	Bash	继承主会话
general-purpose	通用任务	全部（除 Task）	继承主会话

注意事项：

所有内置子代理不能创建子子代理（Task 工具不可用）
max_turns 可控制子代理最大交互轮数，防止失控
内置子代理适合不需要工具/模型定制的快速派发场景

3. 自定义子代理

当内置子代理不够用时——需要特定工具集、特定模型、或专属权限——可以创建自定义子代理。

文件格式

每个自定义子代理是一个 Markdown 文件，位于 .claude/agents/<name>.md：

markdown

---
name: agent-name
description: >
  一句话说明用途和使用场景。
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Bash
disallowedTools:
  - Edit
  - Write
permissionMode: default
maxTurns: 10
---

# Agent Title

Detailed instructions for this agent...

关键 frontmatter 字段

字段	必填	说明
`name`	否	代理名称，省略时用文件名
`description`	推荐	用途和触发条件，路由决策的依据
`model`	否	指定模型：`sonnet`/`opus`/`haiku`，默认继承主会话
`tools`	否	白名单，只允许使用列出的工具；支持 `Agent(type)` 语法限制可派发的子类型
`disallowedTools`	否	黑名单，禁止使用列出的工具
`permissionMode`	否	权限模式（详见 §4），默认 `default`
`maxTurns`	否	最大交互轮数，超过后子代理自动停止
`memory`	否	持久记忆范围：`user`/`project`/`local`（详见 §5）
`skills`	否	启动时预加载的 Skill 列表
`mcpServers`	否	该代理可用的 MCP 服务器列表
`hooks`	否	该代理范围内的 Hooks 定义
`background`	否	设为 `true` 时总是后台运行
`isolation`	否	设为 `worktree` 时在独立 git worktree 中运行（详见 §6.1）

/agents 命令

Claude Code 提供 /agents 命令管理自定义子代理：

/agents          列出所有可用子代理
/agents create   交互式创建新子代理
/agents edit     编辑现有子代理

实战示例

code-reviewer — 只读审查代理

markdown

---
description: >
  只读代码审查。审查 git diff、搜索代码模式，不修改任何文件。
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Bash
disallowedTools:
  - Edit
  - Write
  - NotebookEdit
permissionMode: default
---

# Code Reviewer

Review code changes with focus on correctness, security, and performance.
Run `git diff` to see changes, then analyze each file systematically.

其他示例：

代理	模型	工具	权限	用途
debugger	opus	Read,Edit,Bash,Grep,Glob	acceptEdits	问题诊断与修复，有文件修改权限
research-agent	haiku	Read,Grep,Glob,WebFetch,WebSearch	default	快速研究，搜索代码库和网络，不修改文件

完整示例参见 Anthropic 官方文档。

何时需要自定义子代理

只需要隔离上下文，不需要定制？     → 用内置子代理
需要限制工具集（如只读审查）？     → 自定义子代理 + tools 白名单
需要指定更便宜/更快的模型？       → 自定义子代理 + model 字段
需要特殊权限模式？               → 自定义子代理 + permissionMode
需要预加载特定 Skill？            → 自定义子代理 + skills 字段
需要子代理在独立 worktree 中工作？ → 自定义子代理 + isolation: worktree
需要子代理拥有持久记忆？          → 自定义子代理 + memory 字段

tools 字段中的 Agent(type) 语法

当自定义子代理需要派发下级子代理时，可以通过 Agent(type) 语法精确限制其可产生的子类型：

yaml

tools:
  - Agent(worker, researcher)   # only allowed to spawn worker and researcher sub-agents
  - Read
  - Bash

这防止子代理产生预期之外的代理类型，增强可控性。

4. 权限模式

子代理（包括自定义子代理）可以通过 permissionMode 字段控制操作权限。这决定了子代理在执行工具调用时是否需要人工确认。

六种权限模式

模式	行为	适用场景
`default`	按 settings.json 规则确认	日常使用，保持正常权限控制
`acceptEdits`	自动批准文件编辑，其他仍需确认	信任的写码代理，减少交互
`delegate`	继承父会话的权限设置	子代理行为与主会话一致
`dontAsk`	自动批准所有操作	完全信任的自动化流程
`bypassPermissions`	跳过所有权限检查	危险模式，慎用
`plan`	只读+分析，不执行修改	方案设计、影响分析

个人开发者推荐

日常开发：    default — 保持正常确认流程
信任的子代理：acceptEdits — 自动批准编辑，其他操作仍需确认
研究/分析：   plan — 只读模式，不修改文件
自动化流程：  dontAsk — 仅用于充分验证过的流程

原则：权限最小化。只给子代理完成任务所需的最小权限。

5. 子代理记忆与技能注入

持久记忆

自定义子代理可以通过 memory 字段配置持久记忆，让代理在跨会话中保留学习到的知识。代理运行过程中写入 MEMORY.md，下次启动时自动注入。

范围	存储位置	版本控制	作用域
`user`	`~/.claude/agent-memory/<name>/MEMORY.md`	不入 git	用户级别，所有项目共享
`project`	`.claude/agent-memory/<name>/MEMORY.md`	可入 git	项目级别，团队共享
`local`	`.claude/agent-memory-local/<name>/MEMORY.md`	不入 git（gitignored）	本地级别，仅个人

yaml

memory: project   # This agent remembers across sessions

工作机制：启动时自动将对应 MEMORY.md 的前 200 行注入系统提示。代理可在会话中更新记忆文件，积累的知识在后续会话中持续可用。

技能注入

通过 skills 字段，在子代理启动时注入指定 Skill 的内容：

yaml

skills:
  - code-standards
  - review

注意：Skills 在子代理启动时一次性注入上下文，不是按需加载。注入过多 Skill 会占用子代理的上下文空间。

6. 调度原则

6.1 Worktree 隔离

子代理可通过 isolation: worktree 在独立的 git worktree 中运行，避免多个子代理同时修改同一文件：

yaml

# in .claude/agents/worker.md frontmatter
isolation: worktree   # each instance gets its own git worktree

每个子代理实例获得独立的 git worktree（完整仓库副本），无改动时自动清理。完成后由主会话/Lead 负责合并。CLI 也支持 claude --worktree feature-auth 创建顶层 worktree（位于 <repo>/.claude/worktrees/<name>）。

6.2 何时用子代理 vs 直接执行

直接执行（不用子代理）：
  - 单个文件的修改
  - 简单的 grep/glob 搜索（1-2 次查询能找到）
  - 运行一条命令

使用子代理：
  - 需要广泛搜索代码库（Explore Agent）
  - 需要设计方案并对比多个选项（Plan Agent）
  - 多个独立任务可以并行
  - 研究类任务（不想消耗主会话上下文）

6.3 并行 vs 串行 vs 后台

并行派发（同时执行）：
  条件：3+ 独立任务、无共享状态、文件边界清晰
  示例：同时写前端组件 + 后端 API + 测试

串行派发（依次执行）：
  条件：任务有依赖、共享文件、作用域不清晰
  示例：先设计 schema → 再写 migration → 再写 API

后台派发（不阻塞主线程）：
  条件：研究/分析类任务，结果不急用
  示例：扫描全代码库的技术债、搜索最佳实践
  使用 run_in_background: true，结果通过 output_file 获取

6.4 resume 机制

后台子代理或中断的子代理可以通过 resume 参数恢复执行，继续之前的上下文：

子代理返回 agent_id
  → 后续需要跟进时，用 resume: agent_id 恢复
  → 恢复后子代理保留完整的之前对话历史

适用场景：长时间运行的研究任务、需要分阶段执行的复杂分析。

7. 实际使用模式

模式一：Explore 先行

开始任何新任务前，先用 Explore Agent 了解现状：

提示词："使用 Explore Agent 搜索项目中所有与用户认证相关的文件，
理解当前的认证架构和数据流。"

实际效果：Explore Agent 在独立上下文中执行多次搜索，最后返回一份总结，主会话只接收总结内容。

模式二：并行写码 + 测试

提示词："并行执行以下两个任务：
1. 实现 /app/api/documents/upload/route.ts（上传 API）
2. 为上传 API 编写测试用例（基于接口合同，不看实现代码）"

实际效果：两个子代理同时工作，一个写实现，一个写测试。测试基于接口定义而非实现，更能发现问题。

模式三：三会话隔离审查

从 BUG 防控指南吸收的核心模式：会话 A 完成实现 → 会话 B 审查 git diff（关注边界条件、安全漏洞）→ 会话 C 对抗性测试（尝试打破代码，编写破坏性测试）。每个会话的 AI 没有"实现者"认知偏差，能更客观地发现问题。

模式四：后台研究

使用 run_in_background: true 派发研究类任务（如扫描 TODO/FIXME、搜索最佳实践），不阻塞当前工作。

8. Agent Teams — 多代理协作

8.1 概述

Agent Teams 是 Claude Code 的多代理协作机制，允许多个独立 Claude Code 实例共享任务列表、相互协调。

定义：多个独立 Claude Code 实例共享任务列表（Tasks DAG）、通过消息机制相互协调的协作系统
当前状态：研究预览，需设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 启用
行业背景：Anthropic《2026 Agentic Coding Trends Report》将多代理协调列为八大趋势之二
与标准子代理的区别：标准子代理是单向派发（主会话→子代理→返回结果），Agent Teams 是多向协作（Lead ↔ Worker ↔ Worker）

8.2 推荐架构：Planner-Worker-Judge

Planner（Team Lead）
  ├── 探索代码库，创建任务并分配
  ├── 通过 Tasks DAG 管理任务依赖（blocks / blockedBy）
  ├── 监控 Worker 进度，处理阻塞和冲突
  └── 不直接写代码，专注协调

Worker（Teammate）× N
  ├── 在 Worktree 隔离环境中独立工作
  ├── 完成任务后标记 completed，系统自动通知 Team Lead
  ├── 可通过 SendMessage 向 Lead 或其他 Worker 沟通
  └── 完成当前任务后主动查找下一个可执行任务

Judge（可选，审查角色）
  ├── 每个里程碑后评估整体质量
  ├── 运行集成测试验证多个 Worker 的产出兼容性
  └── 决定继续、调整方向、或终止

角色分配建议：2 人任务用 Planner + Worker；3-5 人任务用 Planner + N Workers；大型任务加入 Judge 做质量门控。

8.3 关键机制

Tasks DAG（任务有向无环图）

- 持久化任务列表，支持依赖关系（blocks/blockedBy）
- 存储位置：~/.claude/tasks/{team-name}/
- Teammate 完成任务后自动检查后续可执行任务
- 任务状态：pending → in_progress → completed
- Lead 通过 TaskCreate/TaskUpdate/TaskList 管理全生命周期

Worktree 隔离

- 每个 Worker 在独立 git worktree 中工作
- 启用方式：子代理 frontmatter 设置 isolation: worktree，或 Task 工具的 isolation 参数
- 每个 worktree 是完整的仓库副本，Worker 间互不干扰
- 无改动时自动清理 worktree
- 完成后由 Lead 负责合并各 worktree 的变更
- 避免多代理并发修改同一文件的冲突

通信机制

- SendMessage：点对点 DM（首选，成本低）
- broadcast：群发所有 Teammate（仅用于紧急事项，成本 = N 条消息）
- Team Lead 自动收到 teammate 的 idle 通知和任务完成消息
- 消息异步送达：teammate 可能正在执行中，消息排队等待其轮次结束

Agent Teams Hooks

Agent Teams 支持专属 Hooks，用于自动化质量门控和流程管理：

Hook	触发时机	典型用途
`TeammateIdle`	团队成员空闲时	自动分配下一个任务、检测卡住的代理
`TaskCompleted`	任务标记完成时	自动运行测试、触发代码审查、通知 Lead

json

{
  "hooks": {
    "TaskCompleted": [{
      "command": "npm test -- --related",
      "description": "Run related tests when a task is completed"
    }]
  }
}

8.4 适用场景

推荐：
  - 跨 3+ 独立模块的重构（前端 + 后端 + 测试并行）
  - 并行研究多个技术方案（3 个 Worker 各研究一种，Lead 汇总对比）
  - 竞争假设调试（2 个 Worker 验证不同 Bug 假设，先找到根因的胜出）
  - 大规模代码迁移（每个 Worker 负责一个模块的迁移）

不推荐：
  - 单模块功能开发（标准子代理更高效）
  - 紧耦合的串行任务（无法并行化，反而增加协调开销）
  - 预算有限时（成本 = 单代理 × N，且协调本身消耗额外 token）

8.5 风险与缓解

风险	表现	缓解
无限循环	代理陷入争论或重复	设置 maxTurns，Lead 监控并裁决
上下文丢失	交接时关键信息遗漏	Tasks 描述写完整，include 文件路径
成本螺旋	N 倍 API 调用瞬间飙升	从 2-3 个代理起步，设预算上限
幻觉级联	一个代理的错误在链中放大	Judge 角色做质量门控
文件冲突	多代理修改同一文件	Worktree 隔离 + 任务边界清晰
合并困难	各 Worker 产出不兼容	Lead 定义清晰接口契约，Judge 验证集成

8.6 个人开发者建议

从 2-3 个代理验证价值，确认 ROI 后再扩展。大多数场景下，标准的子代理 + 后台模式 + 手动多终端已足够。Agent Teams 的核心价值在大规模并行场景。

启动建议：

先用标准子代理处理日常任务，积累多代理协作直觉
当发现"手动开 3+ 终端并行"成为常态时，考虑引入 Agent Teams
首次使用选一个低风险的并行研究任务（而非直接用于生产代码修改）

9. 选择指南：何时用什么

需要隔离上下文但不需要定制？       → 内置子代理
需要特定工具/模型/权限的专家？     → 自定义子代理
需要在主会话上下文中执行？         → Skill
需要隔离执行的 Skill？             → Skill + context:fork
需要多个代理相互通信协作？         → Agent Teams

决策树

任务需要主会话的完整上下文吗？
  ├── 是 → 直接执行或用 Skill
  └── 否 → 需要多个代理相互通信协作吗？
            ├── 是 → 跨 3+ 独立模块？→ Agent Teams
            │         └── 否 → 标准子代理 + 后台模式
            └── 否 → 需要定制工具/模型/权限吗？
                      ├── 是 → 自定义子代理
                      └── 否 → 内置子代理
                                ├── 搜索/研究 → Explore
                                ├── 方案设计 → Plan
                                ├── 运行命令 → Bash
                                └── 复杂多步 → general-purpose

10. 成本控制

子代理的成本管理是实际问题：

模型分级策略

基于 2026 年初定价（每百万 token）：

模型	输入	输出	相对成本
Opus 4.6	$5	$25	1x（基准）
Sonnet 4.6	$3	$15	~0.6x
Haiku 4.5	$1	$5	~0.2x

主会话：Opus 4.6（最强推理，成本已较旧款大幅下降）
子代理：默认 Sonnet 4.6（编码能力接近 Opus，成本约为其 60%）
后台研究/分类/路由：Haiku 4.5（高吞吐场景，成本约为 Opus 的 20%）

设置方法：
自定义子代理在 frontmatter 中指定 model 字段
内置子代理通过 Task 工具的 model 参数指定

Sonnet 4.6 与 Opus 4.6 在编码基准测试上差距很小（SWE-bench 79.6% vs 80.8%），但 Opus 在长上下文推理和复杂指令跟随上仍有优势。主会话保持 Opus 的主要理由是推理深度，而非成本差异。

何时值得用 Opus 子代理

Opus 与 Sonnet 的成本差距仅约 1.67 倍，架构设计、安全审计、复杂调试等需要深度推理的场景建议升级。如果 Sonnet 子代理反复出错需要纠正，切换到 Opus 反而更省。

避免浪费

不要为简单任务派发子代理（直接用 Grep/Glob 更快更省）
并行 3 个子代理 = 3 倍 token 消耗，确认确实需要并行
后台任务用 Haiku 或 Sonnet 就够
设置 maxTurns 防止子代理无限循环

11. 子代理的限制

必须理解的约束：

内置子代理不能生成子代理 — 自定义子代理可通过 Agent(type) 语法受限地派发下级
子代理不继承主会话的完整上下文 — 需要在 prompt 中提供足够信息
子代理无法修改主会话的状态 — 它只返回结果文本
子代理的工具权限受 settings.json 约束 — deny 规则对子代理同样生效
自定义子代理的 Skill 注入是静态的 — 启动时一次性加载，不能按需切换
Agent Teams 的任务列表是最终一致性 — 并发操作可能产生短暂不一致

12. 与其他子系统的关系

CLAUDE.md 规则 ──约束──→ 子代理行为（自定义子代理也遵守）
Skills ──调度──→ 子代理执行具体任务
Skills ──注入──→ 自定义子代理可预加载 Skill 内容
Hooks ──拦截──→ 子代理的工具调用（同样生效）
MCP ──可被──→ 子代理调用（如果工具权限允许）
settings.json ──约束──→ 所有子代理的权限边界

03 - 子代理体系设计 ​

1. 定位 ​

2. 内置子代理（直接可用，无需配置） ​

3. 自定义子代理 ​

文件格式 ​

关键 frontmatter 字段 ​

/agents 命令 ​

实战示例 ​

何时需要自定义子代理 ​

tools 字段中的 Agent(type) 语法 ​

4. 权限模式 ​

六种权限模式 ​

个人开发者推荐 ​

5. 子代理记忆与技能注入 ​

持久记忆 ​

技能注入 ​

6. 调度原则 ​

6.1 Worktree 隔离 ​

6.2 何时用子代理 vs 直接执行 ​

6.3 并行 vs 串行 vs 后台 ​

6.4 resume 机制 ​

7. 实际使用模式 ​

模式一：Explore 先行 ​

模式二：并行写码 + 测试 ​

模式三：三会话隔离审查 ​

模式四：后台研究 ​

8. Agent Teams — 多代理协作 ​

8.1 概述 ​

8.2 推荐架构：Planner-Worker-Judge ​

8.3 关键机制 ​

8.4 适用场景 ​

8.5 风险与缓解 ​

8.6 个人开发者建议 ​

9. 选择指南：何时用什么 ​

决策树 ​

10. 成本控制 ​

模型分级策略 ​

何时值得用 Opus 子代理 ​

避免浪费 ​

11. 子代理的限制 ​

12. 与其他子系统的关系 ​

03 - 子代理体系设计

1. 定位

2. 内置子代理（直接可用，无需配置）

3. 自定义子代理

文件格式

关键 frontmatter 字段

/agents 命令

实战示例

何时需要自定义子代理

tools 字段中的 Agent(type) 语法

4. 权限模式

六种权限模式

个人开发者推荐

5. 子代理记忆与技能注入

持久记忆

技能注入

6. 调度原则

6.1 Worktree 隔离

6.2 何时用子代理 vs 直接执行

6.3 并行 vs 串行 vs 后台

6.4 resume 机制

7. 实际使用模式

模式一：Explore 先行

模式二：并行写码 + 测试

模式三：三会话隔离审查

模式四：后台研究

8. Agent Teams — 多代理协作

8.1 概述

8.2 推荐架构：Planner-Worker-Judge

8.3 关键机制

8.4 适用场景

8.5 风险与缓解

8.6 个人开发者建议

9. 选择指南：何时用什么

决策树

10. 成本控制

模型分级策略

何时值得用 Opus 子代理

避免浪费

11. 子代理的限制

12. 与其他子系统的关系