05_子代理
什么是子代理
子代理本质上是一个拥有独立上下文窗口的专用 AI 实例。当你在 Claude Code 主对话中下达任务时，Claude 可以判断该任务是否适合委派给某个子代理，由子代理独立完成后将结果摘要返回主对话。
每个子代理拥有：
- 独立的系统提示词 — 定义子代理的角色、行为和工作流程
- 独立的上下文窗口 — 与主对话隔离，不会互相污染
- 指定的模型 — 可以选择 Haiku / Sonnet / Opus，或继承主对话
- 受限的工具权限 — 可精确控制子代理能使用哪些工具
- 独立的权限模式 — 控制操作确认的行为
- 生命周期钩子 — 在特定时机触发自定义脚本
为什么需要子代理
| 痛点 | 子代理如何解决 |
|---|---|
| 探索性任务消耗大量上下文 | 子代理在独立上下文中完成，只有摘要返回主对话 |
| 需要严格约束某类操作（如只读审查） | 通过 tools 字段限制子代理只能使用只读工具 |
| 团队中不同角色需要不同 AI 行为 | 为每种角色创建专用子代理，各有专属提示词 |
| 简单任务不想消耗昂贵的 Opus 额度 | 将简单任务路由到 Haiku，复杂任务才用 Sonnet/Opus |
| 某些规范 Claude 总是犯错 | 在子代理提示词中写死约束，比口头提醒更可靠 |
一句话总结：子代理 = 职责明确、权限受限、上下文隔离的专用 AI 助手。
子代理运行机制
生命周期
个子代理从创建到结束，经历以下阶段：
任务匹配 → 实例创建 → 独立执行 → 结果回传 → 实例销毁- 任务匹配：当你在主对话中提出请求时，Claude 会将请求内容与所有已注册子代理的
description字段进行语义匹配。如果某个子代理的描述与当前任务高度吻合，Claude 就会决定将任务委派出去；你也可以在对话中显式指定子代理名称来跳过匹配过程。 - 实例创建：匹配成功后，Claude Code 为该子代理创建一个全新的 AI 实例。这个实例拥有独立的上下文窗口，加载子代理配置中定义的系统提示词，并按照
tools字段初始化工具权限。此时子代理与主对话之间的上下文是完全隔离的——子代理看不到主对话的历史，主对话也不会被子代理的中间过程所干扰。 - 独立执行：子代理在自己的上下文窗口中自主工作，可以调用被授权的工具（读取文件、执行命令、编辑代码等），经历多轮推理和工具调用，直到完成任务。整个过程中，子代理只受自身的系统提示词和工具权限约束，不受主对话上下文的影响。
- 结果回传：子代理完成任务后，将工作成果以摘要形式返回主对话。注意，返回的是精炼后的结论和关键信息，而非子代理执行过程中的全部中间步骤。这正是子代理能有效保护主对话上下文的核心原因。
- 实例销毁：结果回传后，子代理实例即被释放。下次调用同名子代理时会创建一个全新的实例
上下文隔离模型
主对话与子代理之间的关系可以用下图理解：
┌──────────────────────────────────────────────┐ │ 主对话 │ │ 上下文窗口：保留完整的用户对话历史 │ │ │ │ 用户："审查 src/auth 模块的代码质量" │ │ ↓ 任务委派 │ │ ┌───────────────────────────────────────┐ │ │ │ 子代理：code-reviewer │ │ │ │ 独立上下文窗口（与主对话完全隔离） │ │ │ │ │ │ │ │ 系统提示词 → 工具调用 → 多轮推理 │ │ │ │ Read(auth.ts) → Grep(漏洞模式) → ... │ │ │ │ ↓ │ │ │ │ 生成审查报告 │ │ │ └──────────────┬────────────────────────┘ │ │ ↓ 仅返回摘要 │ │ Claude："审查完成，发现 3 个问题：……" │ └────────────────────────────────────────────────┘这种隔离模型带来三个关键好处：
- 上下文保护：子代理在执行过程中可能读取大量文件、运行多次搜索，这些中间数据全部留在子代理的上下文中，不会挤占主对话的 Token 预算。
- 行为可控：子代理只能看到自己的系统提示词和被授权的工具，不会受到主对话中其他无关信息的干扰，行为更加可预测。
- 故障隔离：即使子代理执行出错或超时，也不会破坏主对话的状态，你可以在主对话中继续工作或重新委派任务。
与主对话的协作方式
子代理并非完全孤立地工作——它与主对话之间存在以下协作通道：
| 通道 | 方向 | 说明 |
|---|---|---|
| 任务指令 | 主对话 → 子代理 | 主对话将任务描述和必要的上下文传递给子代理 |
| 结果摘要 | 子代理 → 主对话 | 子代理将工作成果以精炼摘要的形式返回 |
| 文件系统 | 双向共享 | 子代理对文件的读写操作会直接作用于项目的真实文件系统（除非使用 isolation: worktree） |
| 权限确认 | 子代理 → 用户 | 前台子代理执行敏感操作时，权限确认提示会正常弹出给用户 |
需要特别注意的是：子代理对文件系统的修改是即时生效的。如果子代理编辑了某个文件，主对话中后续操作看到的就是修改后的版本。这一点与上下文隔离不同——上下文隔离的是对话历史，而非文件系统。如果需要连文件系统也隔离，可以使用isolation: worktree让子代理在独立的 git worktree 中工作。
内置子代理
Claude Code 已经内置了多种子代理，在日常使用中会自动调用，无需手动配置。
| 子代理 | 模型 | 工具权限 | 用途 | 自动触发场景 |
|---|---|---|---|---|
| Explore | Haiku | 只读（禁止 Write/Edit） | 文件搜索、代码结构分析、定义查找 | 需要阅读代码但不修改时 |
| Plan | 继承主对话 | 只读（禁止 Write/Edit） | Plan Mode 下的项目调研 | 进入 Plan Mode 后 |
| General-purpose | 继承主对话 | 全部工具 | 复杂的多步骤研究与修改 | 需要综合分析 + 代码修改时 |
| Bash | 继承主对话 | 终端命令 | 在独立上下文中执行命令 | 需要运行 shell 命令时 |
| Claude Code Guide | Haiku | 只读 | 回答 Claude Code 使用问题 | 咨询 Claude Code 功能时 |
其中Explore子代理支持三种探索深度：
quick— 快速定向查找，适合已知目标medium— 平衡探索，适合一般性搜索very thorough— 全面分析，适合复杂的跨模块调研
创建自定义子代理
使用 /agents 命令
/agents提供交互式界面，是创建和管理子代理最便捷的方式：
> /agents进入后可以：
- 查看所有子代理— 包括内置、用户级、项目级的全部子代理
- 创建新子代理— 支持 Claude 自动生成或手动编写
- 编辑已有子代理— 修改配置、提示词、工具权限
- 删除自定义子代理
创建流程：
- 运行
/agents→ 选择Create new agent - 选择作用域（User-level 全局可用 / Project-level 仅当前项目）
- 选择Generate with Claude，输入需求描述，例如：
一个代码审查代理，扫描最近的代码变更， 从可读性、安全性、性能三个角度给出改进建议， 并附上修改示例。- Claude 自动生成系统提示词和初始配置
- 按
e可手动编辑，按回车确认 - 选择工具权限（只读 / 可写 / 全部）
- 选择模型（Haiku / Sonnet / Opus /自定义）
- 保存 —立即生效，无需重启会话
手动创建文件
子代理配置文件是带 YAML 前置元数据的 Markdown 文件，放在指定目录即可生效：
# 创建项目级子代理（仅当前项目可用，可提交到 Git 共享给团队） mkdir -p .claude/agents # 创建用户级子代理（所有项目可用） mkdir -p ~/.claude/agents然后在目录中创建.md文件，例如.claude/agents/code-reviewer.md。
注意：手动创建的文件需要重启会话或运行
/agents才能被加载。
CLI 参数传入（临时使用）
适合临时测试或在自动化脚本中使用：
claude --agents '{ "code-reviewer": { "description": "代码质量与安全审查专家。在代码变更后主动使用。", "prompt": "你是一名资深代码审查工程师...", "tools": ["Read", "Grep", "Glob"], "model": "sonnet" } }'配置文件详解
基本结构
--- name: code-reviewer description: 代码质量审查专家。在编写或修改代码后主动使用，检查质量、安全性和可维护性。 tools: Read, Grep, Glob, Bash model: sonnet --- 你是一名资深代码审查工程师。 被调用时： 1. 运行 git diff 查看最近的代码变更 2. 聚焦已修改的文件 3. 按优先级反馈问题：严重 → 警告 → 建议---之间是YAML 前置元数据（配置部分），---之后是系统提示词（行为定义）。
完整字段说明
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| name | 是 | string | 唯一标识符，使用小写字母和连字符（如 code-reviewer） |
| description | 是 | string | 关键字段：描述子代理的用途，Claude 据此决定是否委派任务 |
| tools | 否 | string/list | 允许使用的工具列表，省略则继承所有工具 |
| disallowedTools | 否 | string/list | 明确禁止的工具 |
| model | 否 | string | 使用的模型：haiku / sonnet / opus / inherit（默认 inherit） |
| permissionMode | 否 | string | 权限模式（见下文） |
| maxTurns | 否 | number | 子代理最大交互轮次 |
| skills | 否 | list | 启动时预加载的技能列表 |
| mcpServers | 否 | list | 可用的 MCP 服务器 |
| hooks | 否 | object | 生命周期钩子配置 |
| memory | 否 | string | 持久化记忆范围：user / project / local |
| background | 否 | boolean | 设为 true 则始终在后台运行 |
| isolation | 否 | string | 设为 worktree 则在独立 git worktree 中运行 |
description 字段：自动委派的关键
Claude 决定是否将任务委派给子代理，主要依据description字段。编写 description 时的技巧：
# 好的写法：明确、具体，包含主动触发词 description: "代码审查专家。在编写或修改代码后主动使用（proactively）。分析代码质量、安全性和可维护性。" # 差的写法：模糊、宽泛 description: "一个帮助处理代码的助手。"关键词：在 description 中使用主动使用、proactively、immediately、must use when等词汇，可以提高子代理被自动调用的概率。
你也可以在对话中显式调用：
> 使用 code-reviewer 子代理检查最近的提交 > 让 security-auditor 审计 src/auth 目录作用域与优先级
子代理配置文件放在不同位置，对应不同的作用域。同名子代理按优先级覆盖：
| 优先级 | 位置 | 作用域 | 典型用途 |
|---|---|---|---|
| 1（最高） | CLI --agents 参数 | 当前会话 | 临时测试、自动化脚本 |
| 2 | .claude/agents/ | 当前项目 | 项目专用，提交到 Git 团队共享 |
| 3 | ~/.claude/agents/ | 所有项目 | 个人通用工具 |
| 4（最低） | 插件的 agents/ 目录 | 插件作用域 | 第三方插件提供的子代理 |
实践建议：
- 项目级子代理（
.claude/agents/）：与代码一起提交到 Git，团队成员自动共享。适合放项目专属的审查规则、测试流程等 - 用户级子代理（
~/.claude/agents/）：跨项目复用个人偏好工具，如个人常用的代码审查风格、日志分析方式等 - CLI 临时子代理：适合在 CI/CD 流水线或一次性脚本中使用