Claude Code 使用手册 · 第 5 章 子代理 Subagents

Claude Code 使用手册 · 第 5 章 子代理 Subagents

章节摘要:子代理是拥有隔离上下文、独立提示词与工具权限的专门 AI 助手,主 agent 按 description 自动委派任务给它——这是 Claude Code 并行与分工的机制。配置:带 frontmatter 的 Markdown,放 .claude/agents/(项目)或 ~/.claude/agents/(用户);字段:name/description/tools/model/prompt/context。原书提供八个示例代理:审查类(code-reviewer 六维/clean-code-reviewer Clean Code/secure-reviewer 最小权限只读)、实现类(implementation-agent/debugger/test-engineer)、专用类(data-scientist/documentation-writer)。设计三原则:单一职责、描述明确、工具权限最小化。本章共 3 节。

解剖坐标

一句话主线:理解委派机制 → 学会配置 → 精读八个范本 → 按三原则设计自己的代理。

学习目标

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

1. 说出子代理的定位、配置位置与字段(必填 description+prompt,可选 tools/model)。
2. 说出内置子代理清单与四种调用方式。
3. 复述八个示例代理的职责与工具集设计(尤其 secure-reviewer 的只读最小权限)。
4. 背出设计三原则与上下文管理要点。

子章节导航

01 子代理是什么与配置结构

隔离上下文/独立提示词/工具权限三要素;.claude/agents/ 配置;字段详解;内置代理(general-purpose/Plan/Explore/Bash 等);四种调用方式(自动委派/显式要求/@提及/会话固定);高级能力(可恢复/串联/后台/worktree 隔离/Agent Teams)。

02 八个示例代理

审查类:code-reviewer(六维+Severity 输出)、clean-code-reviewer(函数 <20 行/量化严重级别)、secure-reviewer(只读+五类重点+最小权限范例);实现类:implementation-agent(端到端+完成清单)、debugger(根因分析五步)、test-engineer(80%/关键路径 100%);专用类:data-scientist(唯一指定 sonnet 模型)、documentation-writer(按实际代码验证)。

03 设计三原则与上下文管理

单一职责、描述明确(何时调用它)、工具权限最小化(审查型只读/实现型适度/高风险保持审批);System Prompt 要具体不要太长;子上下文尽量小;使用时机(可拆分/需隔离/需分工/需并行)。

前置知识与后续延伸

前置知识:第 2-4 章(子代理常由命令/技能触发)。

后续延伸:第 7 章 Hooks 的 agent 类型(事件触发子代理)、第 8 章插件(agents 是插件四要素之一)。