子代理：什么时候拆子代理、怎么写子代理定义

子代理是什么，为什么它值一个章节

子代理（subagent）是 Claude 派出去的"专项工人"：它有自己独立的上下文窗口、自己的系统提示词、受限的工具集，干完活只把结论汇报回主对话。主对话里那些读文件的中间过程，全都留在子代理自己的窗口里。

这就是子代理的全部价值所在：上下文隔离。回忆心智模型那一章：主会话的上下文是你唯一要经营的资源。让主对话直接读二十个文件做调研，就像让你自己复印一百页资料只为了给领导写一页摘要；派子代理去，它复印、它读、它还给你一页摘要。

用一个前置知识表理清"分身"家族：

内置的三个子代理

Claude Code 自带三个常用的子代理，认识它们能帮你理解自动调度：

• Explore：只读探索专家，Write/Edit 被禁。Claude 需要搜索、理解代码库但不改动时派它。调用时还会指定彻底程度：quick（定向查）、medium（平衡）、very thorough（地毯式）；
• Plan：计划模式里做代码调研的那个，同样只读；
• General-purpose：全能型，探索加改动都行，多步骤复杂任务的主力。

另外还有 claude（兜底全能）、statusline-setup（配状态栏）、claude-code-guide（答 Claude Code 用法问题）等辅助型。不想让 Claude 派子代理？在 permissions.deny 里禁掉 Agent 工具即可。

什么时候值得拆

不是所有任务都要拆。我的判断表：

派活话术很简单："用子代理调研一下我们的鉴权系统怎么处理 token 刷新"。加了"用子代理"四个字，Claude 就会明确走派遣路径。

子代理启动时带什么

理解子代理"从什么状态开工"对设计很重要。默认情况下，自定义子代理启动时会加载：你的 CLAUDE.md 文件（用户/项目/本地）和 git 状态快照——所以团队约定它天然知道。但内置的 Explore 和 Plan 反而不带这些（为了探索更快更省）。想让某个子代理轻装上阵，frontmatter 里加 omitClaudeMd。

还能给子代理开持久记忆（memory 字段）：它会维护自己的记忆目录，跨会话积累经验——比如一个长期服役的"部署专家"子代理会记住你环境的各种坑。注意主对话的自动记忆不会传给子代理（fork 型例外），各记各的。

派遣形态：前台、后台与分身

子代理有三种运行形态，覆盖不同的等待耐心：

• 前台（默认）：你等它，主对话阻塞在派遣调用上；
• 后台：让 Claude"在后台跑一个子代理"，主对话继续干活，完成后收到通知；/tasks 命令能看到当前会话所有后台任务的状态；
• 分身（fork）：/subtask <任务> 派出一个继承当前完整对话的后台子代理——它带着你们聊过的全部上下文去干副活，结果送回主对话。和 /fork（复制成独立后台会话）的区别在于：分身的结果回到这条对话线，/fork 则是开了一个新的独立会话。

这套形态选择的心法：等结果再继续的用前台；结果晚点要的用后台；需要"带着记忆去办另一件事"的用分身。

写一个自定义子代理

子代理就是一个 md 文件 + YAML frontmatter。最省事的创建方式是直接让 Claude 写：告诉它"在 ~/.claude/agents/ 创建一个代码审查子代理，只读，用 Sonnet"，它就把文件写好。手写的话长这样——保存为 ~/.claude/agents/code-improver.md（用户级，全项目可用）：

---
name: code-improver
description: 扫描文件并给出可读性、性能和最佳实践改进建议。
  在写完或修改代码之后使用。
tools: Read, Grep, Glob
model: sonnet
---

你是代码改进专家。对每个发现的问题：
1. 解释问题是什么、为什么是问题
2. 展示当前代码
3. 给出改进版本
只读操作，不要修改任何文件。

字段解读：description 依然是自动调度的钥匙，Claude 拿任务和各子代理的 description 匹配决定派谁；tools 限定工具集（不写则继承全部可用工具）；model 指定模型——让杂活跑便宜模型是显式省成本的手段。作用域两档：项目级放 .claude/agents/（进 git 团队共享），用户级放 ~/.claude/agents/。还有更灵活的 frontmatter 字段：permissionMode（子代理自己的权限档）、maxTurns（轮数上限）、memory（给子代理开持久记忆）、isolation、skills 等，见官方子代理文档。

测试：说"用 code-improver 检查这个项目"，转录里会看到 code-improver(建议代码改进) 这样的派遣行。

定义设计的四条经验

经验一：description 短，system prompt 长。 所有子代理的 description 加起来超过 15,000 token 会触发启动警告——每个会话都要背着这些描述。细节放正文里，正文只在派遣时加载。

经验二：工具集宁紧勿松。 只读调研的就只给 Read/Grep/Glob。工具越少，跑偏概率越低，权限弹窗也越少。

经验三：一次性的活别建文件。 临时定义用 --agents 命令行 JSON 传进去，随用随弃：

claude --agents '{
  "debugger": {
    "description": "报错与测试失败的调试专家",
    "prompt": "你是调试专家，分析错误、定位根因、给出修复。"
  }
}'

经验四：给"专家"角色写清输出格式。 子代理的产出是回到主对话的摘要，让它按固定结构汇报（如"结论 / 证据文件列表 / 风险"），主对话消化起来最顺。

与并行会话的协同

子代理在单会话内的分工讲完了，补一层跨会话的协同视角。当你用 --worktree 或 claude --worktree 名字 开并行会话时，每个会话照样可以派自己的子代理——两层并行叠加：会话级并行处理互不相干的任务，会话内的子代理并行消化各自的调研。大改造场景（比如"迁移整个模块"）的正规姿势是 /batch：它把工作拆成 5 到 30 个独立单元，每个单元在独立 worktree 里由后台子代理实现并跑测试——相当于把本章和并行会话那章的机制一次性编排起来。

显式调用与权限

自定义子代理除了自动调度，还能指名道姓地调用：启动时 claude --agent <名> 直接把会话跑在这个代理的身份上（工具限制、模型都按它的定义来），会话内也可以说"用 code-improver 处理这个文件"。权限方面，子代理继承主对话的权限规则——主对话里 deny 的命令它同样碰不了，你不用重复配置；它额外发出的工具请求如果主模式要弹窗，照样弹给你。

派子代理也是花钱的：它发出的每一次模型请求都计入你的用量。所以"一个任务拆五个子代理"不是免费的并行加速，每个都在消耗额度。成本敏感场景记得给杂活代理配 model: haiku，把钱花在主对话的推理上。

理解了这个层次结构，你就有了完整的调度坐标系：任务是横轴（拆给谁），上下文是纵轴（在哪算）。子代理解决"上下文在哪算"，worktree 解决"文件在哪改"，团队解决"谁协调谁"——三者正交，按需组合。

最后划一条与 Agent 团队的边界：子代理活在单个会话内、由主对话单向管理；多个 Claude 实例互相发消息、协同分工，那是 Agent 团队的事，下一章展开。想看"由谁来做"的选型对比在多代理实战部分还有总表。

本章由 WorkBuddy 原创整理，事实性内容参考 Claude Code 官方文档。