第 5 章 · 01 子代理是什么与配置结构

第 5 章 · 01 子代理是什么与配置结构

本节摘要:子代理 = 隔离上下文 + 独立提示词 + 工具权限的专门 AI 助手,主 agent 按 description 自动委派。配置文件是带 frontmatter 的 Markdown,放 .claude/agents/(项目)或 ~/.claude/agents/(用户);必填 description(何时调用它)与 prompt(系统提示词),可选 tools(省略则继承全部)与 model(inherit 或指定)。内置代理有 general-purpose、Plan、Explore、Bash 等。调用方式四种:自动委派/显式要求/@agent-name 提及/会话级固定。高级能力:可恢复代理(长任务接力)、代理串联、后台代理、worktree 隔离、Agent Teams(实验性)。

学习目标

阅读完本节,你应当能够:

1. 说出子代理的三要素与配置文件的必填/可选字段。
2. 说出四个内置代理及调用方式的四种形式。
3. 说出三个高级能力(可恢复/串联/后台)各自解决什么问题。

一、子代理是什么

子代理是拥有隔离上下文、独立提示词与工具权限的专门 AI 助手。主 agent 的上下文不会自动传给子代理——它按自己的提示词与工具集独立工作,再把结果带回。这让它具备三个价值:并行(多个子代理同时干活)、分工(各自只带所需上下文)、隔离(任务之间互不污染)。

二、配置结构

.claude/agents/code-reviewer.md    # 项目级
~/.claude/agents/code-reviewer.md  # 用户级
​

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: inherit        # 或 sonnet / opus / haiku
---
You are a senior code reviewer. Focus on code quality, security, and best practices.
​

必填:description(何时调用它——自动委派的依据)、prompt(系统提示词);可选:tools(省略=继承全部,显式列出=只给这些)、model。内置代理:general-purpose(通用)、Plan(规划)、Explore(探索代码库)、Bash 相关及 statusline 等。

三、调用方式

1. 自动委派:主 agent 判断任务适合某子代理时自动调用(靠 description);
2. 显式要求:对话中直接说"用 code-reviewer 审查这段代码";
3. @提及:@code-reviewer 指定;
4. 会话级固定:整个会话固定由某代理执行。

claude agents 命令可列出所有已配置代理。

四、高级能力

• 可恢复代理:长任务接力(断点续跑);
• 代理串联:审查 → 测试 → 文档,流水线式接力;
• 后台子代理:不阻塞主对话;
• worktree 隔离:在隔离工作树中执行(第 9 章);
• Agent Teams(实验性):多角色协作——注意与子代理"委派单任务"的区别。

规模限制(原书标注):subagent 生成上限 200/会话、并发上限 20、嵌套深度 3——设计多代理流程时注意。

小结

子代理把"让 AI 干活"升级为"让 AI 团队干活":description 决定分工,prompt 决定水平,tools 决定权限边界。下一节精读八个生产级示例,看职责怎么定义。