Appearance
Claude Code Subagents 是专为复杂任务设计的 AI 代理体系，支持将多步骤或高专精需求的工作自动或手动分派给独立的“子代理”处理。每个 Subagent 拥有独立的上下文窗口、专属系统提示词和工具权限，有效隔离主会话的干扰与偏见，防止上下文污染。Subagents 支持 resumable（可恢复）对话、后台执行和工作区隔离等高级特性，是提升 Claude Code 自动化和协作能力的核心模块。
Claude Code Subagents：把复杂任务委托给专职 AI 代理
在日常使用 Claude Code 完全入门：从安装到掌握核心功能 时，你可能会遇到以下场景：
- 需要同时进行代码审查、自动化测试、文档生成等多项任务
- 希望每个任务由专门的 AI 代理独立处理，避免主会话被不同任务的上下文干扰
- 需要为不同任务配置不同的工具权限、系统提示词和记忆空间
此时，Subagents（子代理）功能就派上用场。它允许你将复杂或多步骤任务拆分，分别委托给专职的 AI 子代理，每个代理有自己的“认知窗口”和执行环境，最终由主代理统一汇总结果。
Subagents 能解决什么问题？
- 上下文隔离，防止主会话污染：每个 Subagent 拥有独立的上下文窗口，任务执行时不会携带主会话历史，避免“带偏”或信息泄露。
- 专精分工，提升任务成功率：你可以为每个子代理定制系统提示词、工具权限和技能（Skills），让其专注于某一领域（如代码审查、安全检测、测试生成等）。
- 灵活权限与可扩展性：通过精细配置工具和技能，既能保证安全，又方便团队复用和分享。
- 并行与自动化：多个 Subagent 可同时执行不同任务，主代理负责分派和结果整合，大幅提升效率。
为什么 Subagent 需要独立上下文？（隔离偏见与污染）
主会话的上下文往往包含大量历史对话、需求变更、用户偏好等信息。如果直接用同一窗口处理所有任务，容易出现以下问题：
- 信息“串味”：如代码审查时无意中带入了测试任务的上下文，导致输出混乱或偏见。
- 上下文窗口溢出：长时间会话容易耗尽 token，影响后续任务执行。
- 安全与权限风险：某些任务需要严格限制工具调用，防止越权。
Subagent 的设计理念是“每个任务一块干净的白板”，只传递必要的上下文与输入，最大程度减少主会话的历史影响，确保每个子代理只关注自己该做的事。
Subagent 工作流程总览
下面是典型的“主代理 → 派发 → 汇总”流程：
mermaid
graph TB
User["用户请求"]
Main["主代理（协调者）"]
Reviewer["代码审查子代理"]
Tester["测试子代理"]
Docs["文档子代理"]
User -->|提出复杂需求| Main
Main -->|派发任务| Reviewer
Main -->|派发任务| Tester
Main -->|派发任务| Docs
Reviewer -->|返回结果| Main
Tester -->|返回结果| Main
Docs -->|返回结果| Main
Main -->|整合总结| User每个子代理在独立上下文中处理任务，结果只以精炼摘要返回主代理，主代理再统一反馈给用户。
快速上手：如何配置和使用 Subagents
1. 创建/管理 Subagents
最推荐的方式是使用 /agents 命令，进入交互式管理界面：
bash
/agents你可以：
- 查看所有可用子代理（内置、用户级、项目级）
- 创建新子代理，选择工具、填写描述和系统提示词
- 编辑或删除已有子代理
2. 子代理配置文件结构
每个 Subagent 用 Markdown 文件描述，YAML 前置块定义元信息，正文为系统提示词。例如：
yaml
---
name: code-reviewer
description: 专业代码审查，PROACTIVELY 用于代码变更后
tools: Read, Grep, Glob, Bash
model: inherit
---markdown
你是一名资深代码审查专家，专注于代码质量与安全……重点字段说明：
name：唯一标识，建议小写短横线命名description：何时应自动/主动调用本代理（含“PROACTIVELY”可鼓励自动触发）tools：允许的工具列表（如 Bash、Read、Write 等）skills：预加载的技能（可与 Skills 体系详解 配合）memory：持久记忆作用域（user/project/local）background：设为 true 时任务自动后台执行isolation：如设为 worktree，启用 git 工作区隔离
3. 自动与显式调用
- 自动派发：主代理会根据你输入的任务描述和子代理的
description字段，自动选择合适的 Subagent 执行。 - 显式指定：直接在对话中引用子代理名称即可：
> 用 code-reviewer 子代理审查刚提交的代码 > 让 test-engineer 子代理为新功能补测试 - @-mention 强制调用：
> @"code-reviewer (agent)" 只审查 auth 模块
4. 会话级主代理切换
你也可以通过 CLI 或配置文件指定某个子代理作为主代理：
bash
claude --agent code-reviewer或在 settings.json 中设定：
json
{
"agent": "code-reviewer"
}5. 查看所有可用代理
bash
claude agents进阶亮点
Resumable Agents（可恢复子代理）
Subagent 支持跨会话恢复上下文，适合长周期、需要多轮推理的任务：
bash
# 首次调用
> 用 code-analyzer agent 开始分析 authentication 模块
# 返回 agentId: "abc123"
# 之后继续
> Resume agent abc123，顺带分析 authorization 逻辑应用场景：持续研究、分阶段任务、上下文积累。
Background Execution（后台执行）
对于耗时较长的分析、测试等任务，可将子代理设为后台运行：
yaml
---
name: long-runner
background: true
description: 长时间分析任务，后台执行
---快捷键：
Ctrl+B：将当前子代理任务后台化Ctrl+F：终止所有后台代理
环境变量可全局关闭后台任务：
bash
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1Worktree Isolation（工作区隔离）
通过 isolation: worktree，子代理将在独立的 git 工作区和分支上操作，避免主分支被污染：
yaml
---
name: feature-builder
isolation: worktree
description: 在隔离 git 工作区实现新特性
tools: Read, Write, Edit, Bash, Grep, Glob
---原理简述：
- 子代理在独立 worktree/分支上实现修改
- 无更改时自动清理
- 有更改时返回 worktree 路径和分支，供主代理审核/合并
子代理与上下文隔离示意
mermaid
graph TB
Main["主代理上下文<br/>50,000 tokens"]
B["子代理 1 上下文<br/>20,000 tokens"]
C["子代理 2 上下文<br/>20,000 tokens"]
Main -->|干净上下文| B
Main -->|干净上下文| C
B -->|仅结果| Main
C -->|仅结果| Main- 每个子代理只获得必要的上下文输入
- 处理结果以摘要方式返回主代理
- 避免 token 溢出和信息串扰
子代理持久记忆（Memory）
通过 memory 字段，子代理可获得独立的持久目录（如 ~/.claude/agent-memory/code-reviewer/），用于跨会话积累知识、笔记和上下文。
详细用法见 CLAUDE.md 深度指南：8 层记忆层级与持久上下文管理。
常见问题与注意事项
FAQ
Q: 子代理能否相互嵌套或递归调用？
A: 不支持嵌套调用。每个子代理只能由主代理派发，不能再生成新的子代理。
Q: 如何限制某个子代理只能调用指定的其他子代理？
A: 在 tools 字段中用 Agent(子代理名) 语法白名单允许的代理，例如：tools: Agent(worker), Read。
Q: 插件提供的子代理能否自定义 hooks 或 MCP？
A: 出于安全考虑，插件子代理禁止自定义 hooks、MCP servers 和权限模式，防止越权。
通过合理配置和使用 Subagents，你可以让 Claude Code 高效分工、自动化处理复杂项目中的各类专精任务，既提升团队协作效率，又极大降低上下文污染和权限风险。建议结合 Claude Code Skills 体系详解 与 Claude Code 高级功能全解 深入挖掘自动化潜力。