Claude Code 子代理详解：工作原理与使用时机

可以把子代理理解成一个可委派的函数：Claude 给它一项任务，它在你看不到的独立窗口里完成，然后返回一份干净的答案。用对了，它是让 Claude Code 在数小时会话中始终保持思路连贯的最有效手段；用错了，只会白白消耗 Token、增加延迟。本文既讲清它的实际运行机制和定义文件，也给出一条务实标准：什么任务才值得交给子代理。

20 秒速览：Claude Code 子代理如何工作

一个 Claude Code 子代理会在隔离的上下文中独立完成一项任务，再把简短摘要返回主对话。核心就这么简单。它解决的是一个非常具体的问题：长时间的智能体式会话会不断堆积噪声——grep 结果、构建日志、只读过一次且不再引用的文件——最终模型花在整理杂乱信息上的注意力，反而超过了真正完成任务所需的注意力。

把这些高噪声工作交给子代理，杂乱内容就留在它的窗口里，主线程只接收结论。因此，正确的理解不是“一群 AI 工程师协同开发”，而是带返回值的上下文清理机制。抓住这一点，之后所有关于子代理的取舍都会容易得多。

Claude Code 子代理到底是什么

子代理拥有自己的上下文窗口、定制系统提示词、指定的工具访问权限，以及独立权限。当 Claude 遇到与某个子代理职责描述相符的任务时，就会发起委派；子代理独立执行并返回结果。这是官方定义，而其中真正重要的是“独立上下文窗口”和“返回结果”。

许多介绍在最关键的一点上说错了：子代理从零开始。它看不到你的对话历史、Claude 已经读过的文件，也不知道此前调用过哪些 Skill。Claude 会把任务浓缩成一条简短的委派消息；随后，子代理只能依靠自己的系统提示词，以及工作目录等基础环境信息来工作，而不会获得完整的 Claude Code 系统提示词。等它完成后，返回主会话的只有摘要。

这种隔离既有收益，也有代价。理解这笔交换，是用好子代理的关键：

• 收益： 中间过程再啰嗦也不会进入主上下文——读过的十二个文件、失败的 grep、扫描过的日志都会留在子代理里；你只拿到答案。
• 代价： 子代理必须重新收集你已经掌握的背景。如果任务离不开当前对话才能说清，从零启动的子代理往往会无所适从。

一个子代理由什么文件定义

自定义子代理就是一个带 YAML frontmatter 的 Markdown 文件。frontmatter 负责配置，Markdown 正文则会成为子代理的系统提示词。必填字段只有两个：name 和 description。

---
name: code-reviewer
description: Reviews code for quality and best practices. Use immediately after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, run git diff to see recent
changes, focus on modified files, and review for clarity, naming, error
handling, exposed secrets, input validation, and test coverage. Group your
feedback by priority: critical issues, warnings, then suggestions.

这已经是一个完整可用的子代理。description 绝不是装饰：Claude 正是靠它判断何时委派任务。像“审查代码；编写或修改代码后立即使用”这样的描述，会在正确时机触发子代理；含糊的“代码助手”则很可能让它一直闲置。写描述时，不妨把它当成一份面向专才的岗位说明。

文件不必手写。Claude Code 的 /agents 命令会打开一个用于管理子代理的分页界面：Running 标签页列出正在运行和最近完成的子代理，可以查看或停止；Library 标签页则用于创建、编辑和整理。需要注意的是，子代理会在会话启动时加载，因此如果直接修改磁盘上的文件，必须重启会话才能生效；通过 /agents 界面创建或编辑的子代理则会立即生效。

子代理文件放在哪里，重名时谁优先

同一个子代理文件放在不同位置，会决定谁能使用它；若名称冲突，位置还会决定采用哪一份定义。

两个子代理重名时，优先级更高的位置胜出：托管定义高于项目定义，项目定义又高于用户定义。Claude Code 会从当前工作目录逐级向上查找项目子代理；从 v2.1.178 开始，若发生重名，离工作目录最近的定义优先。还有一种只在当前会话存在的方案：启动 Claude Code 时通过 --agents 参数传入 JSON。它不会把文件写入磁盘，很适合自动化脚本和快速测试。

实用原则很简单：如果子代理承载的是这套代码库特有的审查或测试规范，就把它放进 .claude/agents/ 并纳入版本控制，让全团队共用；如果它只代表你个人的工作偏好，就放进 ~/.claude/agents/，随你在不同项目间使用。

模型与工具：最关键的两个调节项

真正决定效果和成本的，主要是 frontmatter 中的两个字段。把它们配好，子代理才会从“有意思”变成真正划算。

模型。 model 字段可以填写别名（sonnet、opus、haiku、fable）、完整模型 ID（例如 claude-opus-4-8），或 inherit。省略时默认使用 inherit，也就是沿用主会话的模型。这里藏着一个重要的成本开关：如果子代理的全部工作只是“用 grep 扫描代码库并总结发现”，就没必要动用前沿模型。把它设为 model: haiku，机械工作会交给更便宜、更快的模型，而主会话仍可用 Opus 负责判断。

工具。 默认情况下，子代理会继承主会话可用的全部内部工具和 MCP 工具。可以用两个字段之一收窄范围：tools 是允许列表，disallowedTools 是拒绝列表。比如，不应修改文件的研究子代理可以设置 tools: Read, Grep, Glob, Bash，这样它在物理上就无法编辑任何内容。这不只是为了整洁，而是一道真正的安全边界：只读审查者不会意外改写自己正在审查的文件。

还有一个值得了解的配置：isolation: worktree 会让子代理在临时 git worktree，也就是仓库的一份隔离副本中运行。如果子代理没有产生改动，这个 worktree 会自动清理。需要让子代理尝试有风险的操作，又不希望它干扰当前工作树时，就适合使用它。

什么时候该用子代理，什么时候不该用

GitHub 上那些堆满配置的示例往往略过这一节，但真正省时间、省成本的恰恰是这里。子代理并非零成本，所以问题从来不是“这件事能不能交给子代理”，而是“隔离带来的收益，是否足以覆盖它的成本”。

从这套机制出发，以下场景并不适合子代理：

• 需要反复迭代。 如果任务要频繁调整，并且始终需要你的判断，就留在主会话中。委派会打断反馈循环。
• 多个阶段共享上下文。 规划、实现、测试依次推进，而且后一阶段依赖前一阶段背景时，应放在同一线程中；不要拆给三个彼此从零开始的子代理。
• 快速、明确的小改动。 为修正一个拼写错误启动子代理，成本比直接修改更高。
• 对延迟敏感。 子代理必须从头收集背景，天然需要时间。如果答案要得很急，直接在当前会话处理更快。

子代理、Skill、Fork 与 Agent team 有什么区别

Claude Code 现在提供四种组织工作的方式，它们很容易混淆；真正的区别全在上下文。

最容易混淆的是 Skill 与子代理，因为两者看起来都像“保存下来的专业能力”。Skill 是在主会话上下文中运行的可复用指令，因此能看到你正在做的一切；子代理的设计恰好相反：它与主会话隔离，只知道收到的任务。如果希望 Claude 一边与你协作，一边持续应用团队写作规范，那应该使用 Skill；如果希望一次嘈杂的调查在后台独立完成并只汇报结论，就该使用子代理。

Fork 是两者之间很实用的折中：它会继承截至当前的完整对话（包括相同的系统提示词、工具、模型和消息历史），所以无需重新解释背景；不过，它的工具调用仍留在主上下文之外，最终只有结果返回。若某个具名子代理需要的背景太多，难以靠一条委派消息讲清，就使用 Fork。（Fork 模式需通过 CLAUDE_CODE_FORK_SUBAGENT 环境变量启用。）

强大功能及其边界

两项较新的能力显著拓宽了子代理的用途，但各自也有必须尊重的边界。

嵌套。 从 Claude Code v2.1.172 开始，子代理可以继续创建自己的子代理。例如，审查子代理可以为每条发现分别派出一个验证者；所有中间输出都留在内部，只有顶层子代理的摘要会返回给你。嵌套深度固定为五层，不能配置；位于第五层的子代理不会获得 Agent 工具，因此无法继续创建。这个上限有充分理由：层层向外扩散，很容易在不经意间启动一整群代理，Token 开销也会迅速上升。把深度当作预算，不要当作目标。

记忆。 加上 memory: project（也可以是 user 或 local），子代理就会获得一个可跨会话读写的持久记忆目录。带项目记忆的代码审查子代理，会逐步积累团队规范和反复出现的问题，用得越久越准确。推荐默认选择 project，因为它可以通过版本控制共享。启用记忆后，Claude Code 会在启动时把子代理 MEMORY.md 的前 200 行（或 25KB）注入系统提示词，因此这个文件需要持续整理。

一个稳妥的起点，是先做一个职责明确的子代理——只读的 code-reviewer 就是经典例子——把它提交到 .claude/agents/，每次改动后调用。确认确有价值之后，再增加一个使用便宜模型的研究子代理。真正从中获益的团队，并不是同时运行三十个代理，而是只保留三个各自专注于一项工作的代理。如果你首先还在挑选编码工具，那是另一套决策，可以阅读 Codex、Claude Code 与 Cursor 对比，以及更全面的 AI 编码智能体推荐。

如果你正在把 Claude Code 真正接入日常交付流程，这基本就是我持续研究的主题。订阅 Newsletter，获取可以直接落地的工作配置，而不是首发当天的热闹消息。