20. 子代理 subagents

子代理到底解决什么问题

你在用 Claude Code 时可能遇到这种情况：让它分析整个代码库，它读了上百个文件，搜索结果和日志把主对话塞得满满当当。等它分析完，你想让它接着改代码，结果上下文窗口快满了，前面的重要信息被挤出去。

子代理（Subagent）就是解决这个的。它是处理特定任务的专门 AI 助手，在自己的上下文窗口里干活，干完只把结论摘要返回给主对话。中间那些搜索结果、日志、文件内容，全留在子代理的上下文里，不污染主对话。

打个比方：子代理像你派的实习生。你让他去调研某个问题，他自己翻了一堆资料、做了厚厚笔记，最后给你一份两页的总结报告。那些厚笔记不占你桌面，你要的是结论。

子代理帮你做这些事：

• 保留上下文：探索和实现的中间过程留在子代理里，主对话只收摘要
• 强制约束：限制子代理只能用某些工具（比如只读，不能改文件）
• 跨项目复用：用户级子代理一次配置，所有项目可用
• 专门化行为：为特定领域写专注的系统提示
• 控制成本：把简单任务路由到更便宜的模型（如 Haiku）

Claude 用每个子代理的描述判断什么时候该委托。所以写子代理时，描述要清晰，让 Claude 知道啥时候该用它。

内置子代理

Claude Code 自带几个内置子代理，Claude 在合适时自动调用。每个都继承父对话的权限，有额外的工具限制。

Explore：只读探索

快速的、只读的代理，专门为搜索和分析代码库优化。

• 模型：从主对话继承（Claude API 上限制为 Opus，不会比你会话选的模型更贵）
• 工具：只读工具，拒绝 Write 和 Edit
• 用途：文件发现、代码搜索、代码库探索

Explore 和 Plan 会跳过你的 CLAUDE.md 和父会话的 git 状态，保持研究快速低成本。其他内置和自定义子代理都会加载这俩。

调用 Explore 时，Claude 会指定彻底程度：quick（针对性查找）、medium（平衡探索）、very thorough（全面分析）。

Plan：规划研究

在 plan 模式期间使用的研究代理，呈现计划前先收集上下文。

• 模型：从主对话继承
• 工具：只读工具，拒绝 Write 和 Edit
• 用途：用于规划的代码库研究

Plan subagent 把探索输出留在单独的上下文窗口里，主对话保持只读。

General-purpose：通用代理

能处理复杂、多步骤任务的代理，需要探索和操作。

• 模型：从主对话继承
• 工具：所有工具
• 用途：复杂研究、多步骤操作、代码修改

任务需要探索+修改、复杂推理解释结果、或多个依赖步骤时，Claude 委托给它。

其他辅助代理

代理	模型	什么时候用
statusline-setup	Sonnet	你跑 /statusline 配状态栏时
claude-code-guide	Haiku	你问 Claude Code 功能问题时

怎么限制内置子代理

• 阻止特定的内置类型：加到 permissions.deny
• 防止委托给任何子代理：拒绝 Agent 工具本身
• 只移除内置 Explore 和 Plan：设 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1（v2.1.198+）
• 非交互模式和 SDK：设 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 移除所有内置类型

创建自定义子代理

子代理是带 YAML frontmatter 的 Markdown 文件。两种创建方式：让 Claude 帮你写，或自己写文件。

让 Claude 写

在 Claude Code 里描述你要的子代理和保存位置：

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude 会用 name、description、tools、model 和系统提示写好文件。

自己写文件

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Frontmatter 定义元数据和配置，正文成为指导子代理行为的系统提示。子代理只接收这个系统提示（加基本环境信息如工作目录），不继承完整的 Claude Code 系统提示。

子代理放哪：五种范围

文件位置决定谁能用，优先级决定同名时谁生效：

位置	范围	优先级	怎么创建
托管设置	组织范围	1（最高）	通过 managed settings 部署
--agents CLI 标志	当前会话	2	启动时传 JSON
.claude/agents/	当前项目	3	让 Claude 写或手动建
~/.claude/agents/	你的所有项目	4	让 Claude 写或手动建
插件的 agents/ 目录	启用插件处	5（最低）	随插件安装

项目子代理（.claude/agents/）适合代码库特定的子代理，检入版本控制团队共享。从当前工作目录向上遍历发现，会扫描到仓库根目录之间的每个 .claude/agents/。v2.1.178 起，多个嵌套目录定义同名时，用最接近工作目录的。

用户子代理（~/.claude/agents/）是个人跨项目的子代理。

Claude Code 递归扫描这俩目录，所以能建子文件夹组织（如 agents/review/、agents/research/）。子目录路径不影响识别或调用，身份只来自 name 字段。

CLI 临时定义

启动时传 JSON，仅该会话存在，不存盘，适合快速测试或自动化：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

--agents 标志接受跟文件子代理一样的字段：description、prompt、tools、disallowedTools、model、permissionMode、mcpServers、hooks、maxTurns、skills 等。系统提示用 prompt，等同文件子代理的正文。

frontmatter 字段详解

只有 name 和 description 是必填，其他都可选：

字段	必填	说明
name	是	小写字母和连字符的唯一标识符。文件名不必匹配
description	是	Claude 何时该委托给这个子代理
tools	否	能用的工具。省略则继承所有
disallowedTools	否	要拒绝的工具，从继承或指定列表里删
model	否	用的模型：sonnet/opus/haiku/fable/完整 ID/inherit。默认 inherit
permissionMode	否	权限模式：default/acceptEdits/auto/dontAsk/bypassPermissions/plan
maxTurns	否	停止前的最大代理轮数
skills	否	启动时加载到上下文的技能，注入完整内容
mcpServers	否	此子代理可用的 MCP 服务器
hooks	否	限于此子代理的生命周期钩子
memory	否	持久记忆范围：user/project/local
background	否	设 true 始终后台运行。v2.1.198 起默认后台
effort	否	努力级别：low/medium/high/xhigh/max
isolation	否	设 worktree 在临时 git worktree 里跑，给隔离的仓库副本
color	否	显示颜色：red/blue/green/yellow/purple/orange/pink/cyan
initialPrompt	否	作为主会话代理运行时自动提交的首轮提示

模型怎么选

model 字段控制子代理用的 AI 模型：

• 别名：sonnet、opus、haiku、fable
• 完整 ID：如 claude-opus-4-8、claude-sonnet-5
• inherit：跟主对话一样
• 省略：默认 inherit

解析顺序：CLAUDE_CODE_SUBAGENT_MODEL 环境变量 > 每次调用的 model 参数 > frontmatter 的 model > 主对话模型。

工具控制

子代理默认继承主对话的内部工具和 MCP 工具。有些工具跟 UI 或会话状态相关，子代理用不了：AskUserQuestion、EnterPlanMode、ExitPlanMode（除非子代理的 permissionMode 是 plan）、ScheduleWakeup、WaitForMcpServers。

允许列表（tools）只给指定工具：

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

拒绝列表（disallowedTools）继承所有但删掉指定工具：

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

两个都设时，disallowedTools 先应用，然后 tools 对剩余的池解析。同时列在两边的工具被删。

MCP 工具也支持服务器级别模式：mcp__<server> 或 mcp__<server>__* 授予或删除该服务器的所有工具。mcp__* 删除所有 MCP 工具。

MCP 服务器限定

mcpServers 字段给子代理配主对话里没有的 MCP 服务器。内联定义的，子代理启动时连接、完成时断开。字符串引用的复用父会话已配置的连接：

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

权限模式

permissionMode 控制子代理怎么处理权限提示。子代理从主对话继承权限上下文，能覆盖模式，除非父模式优先。

父级用 bypassPermissions 或 acceptEdits 时，这优先，子代理覆盖不了。父级用 auto 模式时，子代理继承 auto 模式，frontmatter 里的 permissionMode 被忽略—分类器用跟父会话一样的规则评估子代理的工具调用。

隔离运行：worktree

isolation: worktree 让子代理在临时 git worktree 里跑，给它一个隔离的仓库副本，默认从你的默认分支分支，而不是父会话的 HEAD。

这解决了多个子代理同时改同一文件会打架的问题。每个有 isolation: worktree 的子代理在自己的 worktree 里改，互不干扰。如果子代理不做任何更改，worktree 自动清理。

v2.1.203 起，有 isolation: worktree 的子代理在其 worktree 内跑 Bash 和 PowerShell 命令。工作目录解析到主检出的命令（比如 worktree 目录在子代理运行时被删了）会报错失败。

前台还是后台

background 字段控制子代理前台还是后台跑：

• 设 true：始终后台运行，即使 Claude 需要它的结果
• 不设：Claude 选择。v2.1.198 起默认后台跑子代理

后台子代理让 Claude 能同时派多个活，不用等一个干完再派下一个。结果回来后 Claude 再汇总。

agent teams：让代理互相协作

子代理是单会话内的”派活收报告”。agent teams 更进一步：多个 Claude Code 实例作为一个团队协作，有共享任务、代理间消息传递、集中管理。

跟子代理啥区别

	子代理	agent teams
上下文	自己的窗口，结果返回调用者	自己的窗口，完全独立
通信	只向主代理报告	队友直接互相发消息
协调	主代理管理所有工作	共享任务列表自我协调
最适合	只有结果重要的专注任务	需要讨论和协作的复杂工作
令牌成本	较低，结果汇总回主上下文	较高，每个队友是独立的 Claude 实例

怎么启用

agent teams 是实验性功能，默认禁用。设 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量启用：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

启用后用自然语言描述任务和队友：

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

Claude 会填充共享任务列表，为每个角度生成队友，让他们探索，完成时综合发现。

两种显示模式

• In-process：所有队友在主终端里跑。上下箭头选队友，Enter 查看并发消息。任何终端都能用，不用额外设置
• Split panes：每个队友一个窗格。同时看到所有人输出，点窗格直接交互。需要 tmux 或 iTerm2

默认 in-process。想用分割窗格，在 ~/.claude/settings.json 设 "teammateMode": "auto"，或启动时传 --teammate-mode auto。

队友能用子代理定义

生成队友时能引用子代理类型，队友用其 tools 和 model，定义正文作为额外指令附加到队友的系统提示。

agent view：后台代理管理中心

agent view 通过 claude agents 打开，是所有后台会话的一个屏幕：什么在跑、什么要你输入、什么已完成。调度新会话，一目了然看状态，需要时才介入。

每个后台会话都是完整的 Claude Code 对话，在没有终端连接的情况下继续运行。你能随时打开它、回复、离开。

核心循环

claude agents

1. 输入任务描述按 Enter，启动后台会话
2. 用箭头选行按 Space，打开窥视面板看最近输出或等待的问题
3. 按 Enter 附加到完整对话，空提示按 ← 分离返回表格

会话状态用图标显示：

状态	图标	含义
工作中	动画	Claude 正在跑工具或生成响应
需要输入	黄色	等你的问题或权限决定
空闲	暗淡	没事做，等下一个提示
已完成	绿色	任务成功完成
失败	红色	任务以错误结束
已停止	灰色	被 Ctrl+X 或 claude stop 停了

行摘要谁生成

每行的单行摘要由 Haiku 级模型生成，所以不用打开记录就能知道会话在干啥。工作中行最多每 15 秒从会话自己的最近输出刷新，每个回合结束时模型写新摘要。

拉取请求状态

会话打开 PR 时，#1234 标签出现在行右边缘，支持超链接的终端里能点开。PR 编号按状态着色：黄色（等检查或审查）、绿色（检查通过没审查阻塞）、紫色（已合并）、灰色（草稿或关闭）。

子代理、agent teams、agent view 怎么选

方案	什么时候用
子代理	单会话内派专注子任务，只要结果
agent teams	多个角色需要讨论和协作，能并行独立探索
agent view	管理多个独立后台会话，一目了然看状态
worktree 隔离	多个子代理同时改代码，怕打架

典型搭配：

• 日常写代码：主对话 + Explore 子代理摸清代码库 + General-purpose 做多步修改
• 大型重构：agent teams 派多个队友各管一层（前端、后端、测试）
• 批量任务：agent view 调度多个后台会话并行跑（修 bug、审 PR、查不稳定测试）

子代理让 Claude Code 从”一个人从头干到尾”变成”会派活、会协调、会汇总”的团队。配好工具限制和权限模式，让每个子代理只干自己擅长的事，主对话保持清爽专注。