---
title: "配置 Subagents"
description: "Claude Code Subagents 用隔离上下文处理专门任务。学会内置 agents、自定义 frontmatter、工具边界、MCP 限域、skills 预加载、memory、background 和 worktree。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-05"
---

Subagent 的价值不是“多开一个 AI”，而是把会污染主会话的大量搜索、日志、文件阅读和专项判断，隔离到另一个上下文里，最后只把结论带回来。——Aaron

> [!NOTE]
> **这一章用 17 分钟换什么**：上一章讲了 Skills。Skills 解决“可复用知识和流程”；Subagents 解决“隔离上下文里的专门 worker”。读完你应该能判断什么时候用内置 Explore、什么时候写自定义 subagent、怎么限制工具、怎么预加载 Skills、怎么处理后台任务和 worktree 隔离。

## 1. Subagent 解决什么问题

Subagent 是 Claude Code 里的专门 AI assistant。它有自己的上下文窗口、系统提示词、工具访问和权限设置。

适合用 Subagent：

- 读很多文件，但主会话只需要摘要。
- 搜索大量日志、测试输出、文档或代码。
- 并行验证多个独立假设。
- 让一个专门 worker 做安全审查、性能审查、测试审查。
- 用更快或更便宜的模型处理低风险探索。
- 给某类任务固定工具边界，例如只读 reviewer。

不适合用 Subagent：

- 单文件小修改。
- 需要你频繁来回确认的任务。
- 多阶段共享大量上下文的主线实现。
- 需要 subagent 再继续 spawn subagent 的嵌套流程。
- 只是想“看起来更自动化”的简单任务。

> [!IMPORTANT]
> **第一性原理**：Subagent 用来隔离中间过程，不是替代主会话。主会话负责目标、判断和整合；Subagent 负责自包含子任务。

```mermaid
flowchart TD
    Task["当前任务"]
    Verbose["会产生大量中间信息？"]
    NeedSummary["主会话只需要结论？"]
    Independent["子任务能独立完成？"]
    NeedsChat["需要频繁来回确认？"]
    UseSubagent["用 Subagent"]
    Main["留在主会话"]

    Task --> Verbose
    Verbose -->|否| Main
    Verbose -->|是| NeedSummary
    NeedSummary -->|否| Main
    NeedSummary -->|是| Independent
    Independent -->|否| Main
    Independent -->|是| NeedsChat
    NeedsChat -->|是| Main
    NeedsChat -->|否| UseSubagent

    style UseSubagent fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Main fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
```

## 2. 内置 Subagents

Claude Code 自带几个常用 Subagents。大多数时候你不需要手动配置它们，Claude 会自动判断。

Explore：

- 快速、只读。
- 官方定位是文件发现、代码搜索、代码库探索。
- 模型偏快，适合低延迟探索。
- 不能写文件、不能编辑文件。

Plan：

- plan mode 里使用。
- 用于正式给方案前收集代码库上下文。
- 只读，避免计划阶段误修改。
- 防止 plan mode 中出现无限嵌套。

General-purpose：

- 能处理复杂多步任务。
- 可以探索，也可以修改。
- 使用主会话模型。
- 适合需要探索和行动结合的任务。

其他 helper agents：

- `statusline-setup`：配置状态栏时使用。
- `claude-code-guide`：回答 Claude Code 功能问题时使用。

> [!TIP]
> **新手默认策略**：只读探索先用 Explore；复杂多步但仍在一个会话内的子任务用 general-purpose；需要长期复用的角色再写自定义 subagent。

## 3. Subagent 和 Skill 怎么区分

Skill 和 Subagent 经常一起出现，但职责不同。

Skill：

- 是可复用知识或流程。
- 默认在主会话上下文里运行。
- 可以由 `/skill-name` 调用。
- 适合 checklist、参考资料、发布流程。

Subagent：

- 是一个独立 worker。
- 有自己的上下文窗口。
- 最后把摘要返回主会话。
- 适合大量搜索、专项审查、隔离探索。

组合方式：

- Skill 通过 `context: fork` 启动 subagent。
- Subagent 通过 `skills` 字段预加载指定 Skills。

> [!IMPORTANT]
> **判断句**：你要复用一套流程，用 Skill；你要隔离一个子任务，用 Subagent；你要两者兼得，就让 Skill fork 到 Subagent 或让 Subagent 预加载 Skills。

## 4. Subagent 和 Agent team 怎么区分

Subagent 运行在单个 Claude Code session 内，由主会话管理，只把结果回报给主会话。

Agent team 是多个独立 Claude Code sessions 组成的团队。一个 lead 负责协调，teammates 各自有独立上下文，并且可以互相通信。

Subagent 适合：

- 结果比过程重要。
- worker 不需要互相交流。
- 子任务聚焦、短期、自包含。
- 你想降低主会话上下文污染。

Agent team 适合：

- 多个 worker 需要互相挑战、共享发现、协调任务。
- 大功能拆分。
- 多假设调试。
- 前后端测试等跨层并行。

官方说明 Agent teams 目前仍是 experimental，需要显式开启，并且 token、协调和冲突成本更高。

> [!WARNING]
> **不要把 Agent team 当默认并行方式**：普通隔离和简单并行先用 Subagent。只有 worker 需要彼此通信时，才考虑 Agent team。

## 5. 创建入口：优先用 `/agents`

官方推荐入口：

```text
/agents
```

这个界面可以：

- 查看内置、user、project、plugin subagents。
- 创建新 subagent。
- 用 Claude 生成配置。
- 编辑 tool access。
- 删除自定义 subagent。
- 看同名定义里哪个当前生效。
- 在 Running tab 查看正在运行的 subagents。

命令行只列出配置：

```bash
claude agents
```

手动写文件也可以，但直接改磁盘上的 subagent 文件后，要重启会话才会加载。通过 `/agents` 创建或编辑通常会立即生效。

> [!TIP]
> **先用 `/agents` 生成，再手动修**：界面能帮你选 scope、tools、model、color、memory，减少 YAML 配错。

## 6. Subagent 文件放哪里

Subagent 是 Markdown 文件，带 YAML frontmatter。

常见路径：

- Managed：组织级下发，优先级最高。
- CLI `--agents`：只在当前启动会话生效。
- Project：`.claude/agents/<agent-name>.md`，当前项目可用，可提交。
- User：`~/.claude/agents/<agent-name>.md`，所有项目可用。
- Plugin：`<plugin>/agents/<agent-name>.md`，插件启用时可用。

优先级从高到低：

1. Managed settings
2. `--agents` CLI flag
3. Project `.claude/agents/`
4. User `~/.claude/agents/`
5. Plugin agents

注意：

- Project subagents 会从当前工作目录往上发现。
- `--add-dir` 只给文件访问，不会扫描里面的 subagents。
- Plugin subagents 会出现在 `/agents`，但有安全限制。

> [!IMPORTANT]
> **Project subagent 是团队资产**：如果一个 worker 是这个代码库专用的，放 `.claude/agents/` 并提交；如果只是你个人习惯，放 `~/.claude/agents/`。

## 7. 最小文件格式

一个基本 subagent：

```markdown
---
name: code-reviewer
description: Reviews code for quality, security, maintainability, and missing tests. Use after code changes.
tools: Read, Glob, Grep, Bash
model: inherit
---

You are a senior code reviewer.

When invoked:

1. Inspect the recent changes.
2. Focus on modified files.
3. Identify correctness, security, maintainability, and test risks.
4. Return findings ordered by severity.

Output:

- Critical issues
- Warnings
- Suggestions
- Tests to run
```

Frontmatter 是配置。正文是 subagent 的 system prompt。

官方提醒：Subagent 不会继承完整 Claude Code system prompt。它收到的是自己的 system prompt，加上基础环境信息，例如 working directory。`CLAUDE.md` 和项目 memory 会按正常消息流加载。

> [!WARNING]
> **正文要写成角色说明，不是用户请求**：Subagent 文件定义的是“这个 worker 是谁、何时做什么、怎么输出”，不是某一次任务。

## 8. Frontmatter 字段速览

常用字段：

- `name`：唯一标识，必填，小写字母和连字符。
- `description`：Claude 判断何时委派的依据，必填。
- `tools`：允许使用的工具列表。省略时继承主会话全部工具。
- `disallowedTools`：从继承或指定工具中移除。
- `model`：使用 `sonnet`、`opus`、`haiku`、完整 model ID 或 `inherit`。
- `permissionMode`：权限模式，例如 `default`、`auto`、`plan`。
- `maxTurns`：最多 agentic turns。
- `skills`：启动时预加载的 Skills。
- `mcpServers`：只给这个 subagent 的 MCP server。
- `hooks`：只在这个 subagent 生命周期内运行的 hooks。
- `memory`：持久记忆 scope，支持 `user`、`project`、`local`。
- `background`：设为 `true` 时默认后台运行。
- `effort`：该 subagent 的 reasoning effort。
- `isolation`：设为 `worktree` 时使用临时 git worktree。
- `color`：UI 中显示颜色。
- `initialPrompt`：当它作为 main session agent 运行时自动提交的第一条用户消息。

> [!TIP]
> **新手先用五个字段**：`name`、`description`、`tools`、`model`、`maxTurns`。其他字段等需求明确再加。

## 9. description 决定自动委派

Claude 会根据任务描述、当前上下文和 subagent 的 `description` 决定是否自动委派。

弱描述：

```yaml
description: Helps with code.
```

强描述：

```yaml
description: Reviews recently changed code for security issues, missing tests, risky migrations, and unclear error handling. Use proactively after code edits.
```

写法原则：

- 写任务类型。
- 写触发场景。
- 写不负责什么。
- 放关键词在前面。
- 如果希望主动使用，写清 `Use proactively`。

> [!IMPORTANT]
> **description 是路由规则**：写得越泛，越容易误触发；写得越窄，越可能需要你显式点名。

## 10. 模型选择和优先级

`model` 字段可以设置：

- `haiku`：快速、便宜，适合只读探索。
- `sonnet`：平衡质量和速度，适合 review、调试、专项分析。
- `opus`：更强推理，适合复杂架构判断。
- 完整 model ID：精确指定。
- `inherit`：继承主会话。

官方模型解析优先级：

1. `CLAUDE_CODE_SUBAGENT_MODEL` 环境变量。
2. 某次 invocation 传入的 model。
3. subagent 文件里的 `model`。
4. 主会话模型。

> [!TIP]
> **成本策略**：探索类用更快模型；关键审查和复杂诊断用更强模型；不确定时 `inherit`。

## 11. 工具边界：`tools` 和 `disallowedTools`

默认情况下，subagent 继承主会话所有工具，包括 MCP tools。

如果你想做只读 reviewer，用 `tools` allowlist：

```yaml
tools: Read, Grep, Glob, Bash
```

这样它不能 `Edit`、`Write`，也不能使用没有列出的 MCP tools。

如果你想继承大部分能力，只禁文件写入，用 `disallowedTools`：

```yaml
disallowedTools: Write, Edit
```

边界：

- `tools` 是允许列表。
- `disallowedTools` 是拒绝列表。
- 如果两者都写，先应用 `disallowedTools`，再按 `tools` 解析。
- 同时出现在两边的工具会被移除。

> [!CAUTION]
> **只读 subagent 不等于无风险**：如果允许 Bash，它仍可能通过命令读取大量文件或访问网络。必要时继续用 permissions 和 hooks 限制。

## 12. 限制能 spawn 哪些 Subagents

当某个 agent 作为主线程运行时，比如：

```bash
claude --agent coordinator
```

它可能通过 Agent tool 再 spawn subagents。可以用 `Agent(agent_type)` 限制：

```yaml
tools: Agent(worker, researcher), Read, Bash
```

这表示只能 spawn `worker` 和 `researcher`。

如果写：

```yaml
tools: Agent, Read, Bash
```

表示可以 spawn 任意 subagent。

官方说明：v2.1.63 起 `Task` tool 重命名为 `Agent`，旧的 `Task(...)` 引用仍作为 alias 可用。

> [!IMPORTANT]
> **Subagent 不能再 spawn subagent**：这个限制主要用于 `claude --agent` 让某个 agent 成为主线程时。

## 13. MCP 限域：只给某个 Subagent

`mcpServers` 可以让某个 subagent 拥有专属 MCP。

例子：

```yaml
name: browser-tester
description: Tests UI behavior in a real browser.
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
```

含义：

- `playwright` 是 inline MCP，只在这个 subagent 启动时连接，结束时断开。
- `github` 是引用父会话已有 MCP server。

如果你不想让主会话加载某个 MCP tool description，就把它定义为 subagent inline MCP，而不是放在 `.mcp.json`。

> [!TIP]
> **高噪音 MCP 适合限域**：浏览器、数据库、日志、监控工具如果只服务某个 worker，就放到 subagent 的 `mcpServers`。

## 14. 权限模式：`permissionMode`

Subagent 可以设置 `permissionMode`：

- `default`：标准权限检查。
- `acceptEdits`：自动接受工作目录和 additional directories 内的编辑及常见文件系统命令。
- `auto`：使用 auto mode 分类器。
- `dontAsk`：自动拒绝需要确认的权限请求。
- `bypassPermissions`：跳过权限提示。
- `plan`：只读计划模式。

重要边界：

- 父会话如果是 `bypassPermissions` 或 `acceptEdits`，会优先生效，subagent 不能覆盖。
- 父会话如果是 `auto`，subagent 会继承 auto mode，frontmatter 里的 `permissionMode` 会被忽略。
- `bypassPermissions` 风险很高，会跳过大多数权限提示；根目录和 home 目录删除仍会触发 circuit breaker。

> [!WARNING]
> **不要默认给 subagent bypass**：worker 越独立，越需要工具和权限边界清晰。

## 15. 预加载 Skills

Subagent 不会自动继承主会话调用过的 Skills。要在 subagent 启动时加载某些 Skills，用 `skills`：

```yaml
name: api-developer
description: Implements API endpoints following team conventions.
skills:
  - api-conventions
  - error-handling-patterns
```

注意：

- 加载的是 Skill 全文，不只是 description。
- 这些内容在 subagent 启动时进入它的上下文。
- 不能预加载 `disable-model-invocation: true` 的 Skills。
- 缺失或禁用的 Skill 会被跳过并写入 debug log。

这和 Skill 里的 `context: fork` 是反方向：

- Subagent 的 `skills`：以 subagent 为主，Skill 是参考资料。
- Skill 的 `context: fork`：以 Skill 为主，把任务交给 subagent。

> [!IMPORTANT]
> **不要把所有 Skills 都预加载**：只给这个 worker 真正需要的领域知识，否则只是把上下文污染从主会话搬到 subagent。

## 16. Persistent memory

Subagent 可以有自己的持久记忆：

```yaml
memory: project
```

三种 scope：

- `user`：`~/.claude/agent-memory/<agent-name>/`，跨项目复用。
- `project`：`.claude/agent-memory/<agent-name>/`，项目共享，可提交。
- `local`：`.claude/agent-memory-local/<agent-name>/`，项目本地，不提交。

启用 memory 后：

- Subagent system prompt 会包含读写 memory 的说明。
- 会加载 memory 目录里 `MEMORY.md` 的前 200 行或 25KB，取较小值。
- Read、Write、Edit 会自动启用，让 subagent 管理 memory 文件。

官方建议 `project` 是常用默认，因为项目知识可以团队共享。`user` 适合跨项目通用经验，`local` 适合个人本机经验。

> [!CAUTION]
> **memory 会自动启用写工具**：如果你本来想做严格只读 reviewer，启用 memory 前要重新检查工具边界和仓库提交策略。

## 17. Hooks：给 Subagent 加动态规则

如果 `tools` 太粗，无法表达“只允许 SELECT，不允许 UPDATE”，就用 hooks。

典型场景：

- `PreToolUse` 校验 Bash 命令。
- `PostToolUse` 编辑后运行 linter。
- `Stop` 收尾。
- 主会话里的 `SubagentStart` 和 `SubagentStop` 监听某类 subagent。

Subagent frontmatter 里的 hooks 只在该 subagent 生命周期内生效，结束后清理。

Project settings 里的 `SubagentStart` / `SubagentStop` 则在主会话监听 subagent 生命周期。

> [!IMPORTANT]
> **条件性安全规则用 Hook**：`tools: Bash` 只能决定能不能用 Bash，不能判断 Bash 里是不是危险 SQL。细粒度检查交给 `PreToolUse` hook。

## 18. 显式调用 Subagent

有三种层级。

自然语言：

```text
Use the code-reviewer subagent to review the auth changes.
```

这种方式通常能触发，但最终仍由 Claude 判断。

`@` mention：

```text
@agent-code-reviewer look at the auth changes
```

这会保证指定 subagent 运行。你也可以从 typeahead 里选择，plugin subagent 会显示为 `<plugin-name>:<agent-name>`。

整场会话使用某个 agent：

```bash
claude --agent code-reviewer
```

也可以在项目设置里设默认：

```json
{
  "agent": "code-reviewer"
}
```

此时 subagent 的 system prompt 会替代默认 Claude Code system prompt；`CLAUDE.md` 和 project memory 仍按正常消息流加载。

> [!TIP]
> **显式调用适合排障**：自动委派不稳定时，先用 `@agent-name` 验证 subagent 本身是否工作正常。

## 19. 前台和后台运行

Subagent 可以前台运行，也可以后台运行。

前台：

- 主会话等待 subagent 完成。
- 权限提示和澄清问题会传给你。
- 适合需要互动、权限不确定、风险较高的任务。

后台：

- 你可以继续在主会话工作。
- 启动前会预先请求该 subagent 需要的工具权限。
- 运行后继承这些权限。
- 未预批准的权限请求会自动拒绝。
- 澄清问题会失败，但 subagent 会继续。

你可以要求后台：

```text
Run this in the background.
```

也可以用 `Ctrl+B` 把正在运行的任务放到后台。

关闭后台任务功能：

```bash
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 claude
```

> [!WARNING]
> **后台任务要更保守**：它不会在中途等你确认。权限和任务边界要在启动前说清楚。

## 20. Worktree isolation

如果 subagent 可能改文件，而你不想它直接写当前 checkout，可以设置：

```yaml
isolation: worktree
```

效果：

- Subagent 在临时 git worktree 里工作。
- 文件修改不会直接落到当前 checkout。
- 如果 subagent 没有改动，worktree 会自动清理。
- 如果有改动，你需要后续检查和整合。

适合：

- 并行实现不同方案。
- 高风险重构。
- 让 worker 试验修复。
- 不希望污染主工作区的验证。

> [!CAUTION]
> **worktree 隔离不是免审查**：它保护当前 checkout，但最终合并前仍要 review diff、跑测试、处理冲突。

## 21. Resume 和 transcript

每次 subagent 调用默认是新实例、新上下文。

如果要继续已有 subagent 的工作，可以让 Claude resume 它。官方说明 resumed subagent 会保留完整会话历史，包括工具调用、结果和 reasoning。

限制：

- Resume 依赖 `SendMessage`。
- `SendMessage` 目前只在 Agent teams 开启时可用。
- Subagent transcript 存在主项目 session 目录下的 `subagents/`。
- transcript 会按 `cleanupPeriodDays` 清理，默认 30 天。

Subagent compaction：

- 和主会话类似。
- 默认接近 95% 容量时自动压缩。
- 可用 `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 调整触发比例。

> [!TIP]
> **长任务要主动要摘要**：不要等 subagent 巨量上下文后再救。让它阶段性返回 findings、风险和下一步。

## 22. Forked subagents

Forked subagents 是实验能力，官方要求 Claude Code v2.1.117 或更高，并通过环境变量开启：

```bash
CLAUDE_CODE_FORK_SUBAGENT=1 claude
```

Fork 与 named subagent 不同：

- Fork 继承当前主会话完整历史。
- Named subagent 从自己的定义和任务 prompt 开始。
- Fork 的工具调用仍留在 fork 里，最终结果回到主会话。
- Fork 可以复用主会话 prompt cache。
- 开启 fork mode 后，`/fork` 会创建 fork，而不是作为 `/branch` alias。

适合：

- 子任务需要完整上下文，重新解释成本太高。
- 想从当前状态并行尝试几个方向。
- 草拟测试、替代方案、review 观点。

不适合：

- 你想保持输入隔离。
- 你需要专门工具边界和 system prompt。
- 你不想使用实验功能。

> [!WARNING]
> **Fork 牺牲输入隔离**：它看到完整主会话。需要严格角色、工具和权限边界时，用 named subagent。

## 23. 常见使用模式

隔离高输出任务：

```text
Use a subagent to run the test suite and report only failing tests with key error messages.
```

并行研究：

```text
Research the authentication, database, and API modules in parallel using separate subagents.
```

串联 worker：

```text
Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to propose fixes.
```

只读审查：

```text
Use the code-reviewer agent to review recent changes. Do not edit files.
```

> [!IMPORTANT]
> **子任务要自包含**：给 subagent 明确范围、输入、输出格式和禁止事项。不要只说“看看这个”。

## 24. 什么时候留在主会话

留在主会话：

- 需要频繁来回确认。
- 多个阶段共享大量上下文。
- 你正在做小而精确的修改。
- 延迟很重要。
- 子任务结果会立即改变下一步。

用 Subagent：

- 输出很长，但最后只需要摘要。
- 需要强工具限制。
- 子任务自包含。
- 要并行研究。
- 主会话上下文已经很重。

用 Skill：

- 你要复用的是提示词、流程或参考资料。
- 任务仍然适合在主会话里执行。

用 `/btw`：

- 只是问一个依赖当前上下文的小问题。
- 不需要工具。
- 不想把回答加入历史。

> [!TIP]
> **不是所有 side question 都要 subagent**：短问题先用 `/btw`，流程复用用 Skill，大量工具调用才用 Subagent。

## 25. 一个好 Subagent 的写法

好的 subagent 文件应该说明：

- 何时使用。
- 何时不要使用。
- 负责范围。
- 禁止事项。
- 工具边界。
- 输出格式。
- 是否可以修改文件。
- 是否可以调用外部系统。
- 如何处理不确定性。

示例结构：

```markdown
---
name: security-reviewer
description: Reviews authentication, authorization, token handling, input validation, and secret exposure risks. Use after security-sensitive code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 12
---

You are a security reviewer.

Scope:

- Review only the files relevant to the requested change.
- Prefer evidence from code over speculation.
- Do not edit files.

Output:

- Critical findings
- Warnings
- Evidence with file paths
- Suggested tests
- Residual risk
```

> [!CAUTION]
> **不要写万能 Agent**：`general-purpose` 已经存在。自定义 subagent 应该专门、清晰、可评估。

## 26. 常见故障：没被自动使用

排查顺序：

1. 运行 `/agents` 看 subagent 是否存在。
2. 确认直接改文件后是否重启了会话。
3. 检查 `description` 是否包含自然语言触发词。
4. 用 `@agent-name` 强制调用测试。
5. 检查是否被更高优先级同名 subagent 覆盖。
6. 检查是否被 permissions deny：`Agent(name)`。
7. 检查 plugin subagent 是否使用了不支持字段。

> [!TIP]
> **先强制调用**：如果 `@agent-name` 能跑，问题通常是 description 太弱或任务不适合自动委派。

## 27. 常见故障：权限提示太多

原因：

- Subagent 工具范围太宽。
- 后台 subagent 没有预批准需要的工具。
- MCP tool 没有写 permissions allow。
- Teammate / subagent 在多个文件上反复触发确认。

修法：

- 用 `tools` 缩小能力范围。
- 给常用只读工具预批准。
- 把高风险工具保留 ask。
- 对后台任务提前说明需要什么工具。
- 对 Agent teams，在 spawn 前先补 permissions。

> [!WARNING]
> **不要用 bypassPermissions 快速消音**：提示太多是边界设计问题，先收窄工具和任务。

## 28. 常见故障：结果不可用

常见原因：

- 任务范围太大。
- 输出格式没定义。
- Subagent 没拿到必要背景。
- 工具太少，无法完成任务。
- 背景任务缺权限，中途自动拒绝。
- 并行 subagents 返回了太多细节，反而污染主会话。

改法：

- 让子任务更小。
- 明确输出格式。
- 在 prompt 里给必要上下文。
- 只返回 findings，不返回完整过程。
- 高风险或需要交互的任务改前台。
- 必要时用 worktree 隔离实现任务。

> [!IMPORTANT]
> **Subagent 的输出应该是可行动结论**：不是“读了很多文件”，而是“发现什么、证据在哪、下一步怎么做”。

## 29. 自检清单

学完这一章，你应该能做到：

- 我能解释 Subagent 解决的是上下文隔离。
- 我知道 Explore、Plan、general-purpose 的差别。
- 我知道什么时候该写自定义 subagent。
- 我知道 subagent 文件位置和 scope 优先级。
- 我能写出一个最小 `.claude/agents/<name>.md`。
- 我知道 `tools` 和 `disallowedTools` 的区别。
- 我知道 `mcpServers` 可以把 MCP 只给某个 subagent。
- 我知道 `permissionMode` 会受到父会话模式影响。
- 我知道 Subagent 不会自动继承主会话 Skills。
- 我知道 `memory` 会自动启用读写工具。
- 我知道后台 subagent 会预批准权限并自动拒绝未批准请求。
- 我知道 `isolation: worktree` 的用途和边界。
- 我知道 forked subagent 与 named subagent 的差别。
- 我知道 Subagent 和 Agent team 的边界。

## 30. 术语速查

- `Subagent`：在隔离上下文里执行子任务的专门 assistant。
- `Explore`：内置只读探索 subagent。
- `Plan`：plan mode 中用于上下文研究的只读 subagent。
- `general-purpose`：内置通用复杂任务 subagent。
- `/agents`：创建、编辑、查看 subagents 的交互入口。
- `tools`：subagent 可使用工具 allowlist。
- `disallowedTools`：从可用工具中移除的 denylist。
- `permissionMode`：subagent 的权限模式。
- `mcpServers`：只给该 subagent 的 MCP server 配置。
- `skills`：启动时预加载进 subagent 上下文的 Skills。
- `memory`：subagent 的持久记忆目录。
- `background`：让 subagent 默认后台运行。
- `isolation: worktree`：让 subagent 在临时 git worktree 中工作。
- `Agent(agent_type)`：限制主线程 agent 可 spawn 哪些 subagents 的工具语法。
- `@agent-name`：显式调用某个 subagent。
- `forked subagent`：继承完整主会话历史的实验性 subagent。
- `Agent team`：多个独立 Claude Code sessions 组成的协作团队。

## 31. 官方资料

- [Create custom subagents](https://code.claude.com/docs/en/sub-agents)
- [Orchestrate teams of Claude Code sessions](https://code.claude.com/docs/en/agent-teams)
- [Extend Claude Code](https://code.claude.com/docs/en/features-overview)
- [Extend Claude with skills](https://code.claude.com/docs/en/skills)
- [Configure permissions](https://code.claude.com/docs/en/permissions)
- [Automate workflows with hooks](https://code.claude.com/docs/en/hooks-guide)

<Cards>
  <Card href="/docs/claude-code/official/02-extensions-automation/hooks" title="Hooks" description="Subagent 的工具边界只能粗分；要做确定性阻断、校验和事件自动化，下一章进入 Hooks。" />
  <Card href="/docs/claude-code/official/02-extensions-automation/skills" title="Skills（上一篇）" description="Skill 负责可复用知识和流程；Subagent 负责隔离执行。两者可以通过 skills 字段或 context: fork 组合。" />
  <Card href="/docs/claude-code/understanding/08-multi-agent" title="深度理解：多 Agent 协作" description="想继续理解为什么要拆 worker、什么时候并行、怎么避免主上下文污染，读理解篇多 Agent。" />
</Cards>
