子代理是 Claude Code 可以委派任务的专用 AI 助手，每个子代理拥有独立的上下文窗口，可配置自定义系统提示和工具权限。本文将全面解析其 6 个内置代理、完整配置项、高级特性如后台任务、工作树隔离与持久记忆，并提供从创建到使用的完整操作指南。

Claude Code 子代理系统完全指南：内置代理、自定义配置与高级特性 #

子代理（Subagent）是 Claude Code 中用于委派复杂或专业化任务的独立 AI 助手。它拥有自己的上下文窗口和系统提示，能防止主对话上下文被污染，并支持并行执行。通过自定义配置，你可以精确控制每个子代理的能力范围。Claude HowTo 教程指南 提供了从内置代理到高级特性的系统性学习路径。

内置子代理概览 #

Claude Code 预置了 6 个内置子代理，它们始终可用，覆盖了常见的协作任务场景。

子代理配置详解 #

子代理通过 Markdown 文件定义，使用 YAML frontmatter 进行配置，后接系统提示。

文件位置与加载优先级 #

子代理定义文件的存放位置决定了其作用范围。当存在同名代理时，高优先级源将覆盖低优先级源。

完整配置字段说明 #

以下是子代理 frontmatter 支持的全部字段：

---
name: your-sub-agent-name
description: 描述何时应调用此子代理。包含 “use PROACTIVELY” 可鼓励自动调用。
tools: tool1, tool2  # 可选，省略则继承所有工具。支持 `Agent(agent_name)` 语法限制可生成的子代理。
disallowedTools: tool4  # 可选，明确禁止使用的工具。
model: sonnet  # 可选，指定模型：sonnet, opus, haiku, inherit。
permissionMode: default  # 可选，权限模式：default, acceptEdits, dontAsk, bypassPermissions, plan。
maxTurns: 20  # 可选，限制子代理的最大交互轮数。
skills: skill1, skill2  # 可选，预加载到上下文中的技能。v2.1.133+ 版本起，子代理也能自动发现项目、用户和插件技能。
mcpServers: server1  # 可选，为该子代理启用的 MCP 服务器。
hooks:  # 可选，组件级钩子（PreToolUse, PostToolUse, Stop）。
  PreToolUse:
    - matcher: “Bash”
      hooks:
        - type: command
          command: “./scripts/security-check.sh”
memory: user  # 可选，持久记忆范围：user, project, local。
background: false  # 可选，设为 true 则始终作为后台任务运行。
effort: high  # 可选，推理努力程度：low, medium, high, max。
isolation: worktree  # 可选，设为 worktree 则在独立 Git 工作树中运行。
initialPrompt: “Start by analyzing the codebase”  # 可选，作为主代理运行时自动提交的首轮提示。
---

在此处编写子代理的系统提示，应清晰定义其角色、能力与解决问题的方法。

tools 字段的三种配置方式：

1. 继承所有工具：省略 tools 字段。
2. 指定具体工具：tools: Read, Grep, Glob, Bash。
3. 条件性工具访问：tools: Read, Bash(npm:*), Bash(test:*)。

通过 CLI 快速定义 #

你可以使用 --agents 标志通过 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”
  }
}'

高级特性与配置 #

后台子代理与管理快捷键 #

通过设置 background: true，可以让子代理在后台运行，不阻塞主对话。

---
name: long-runner
background: true
description: Performs long-running analysis tasks in the background
---

在运行时，可以使用以下快捷键管理后台任务：

• Ctrl+B：将当前正在运行的子代理任务移至后台。
• Ctrl+F：终止所有后台代理（按两次确认）。

若要全局禁用后台任务，可设置环境变量：export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1。

工作树隔离 #

设置 isolation: worktree 可以让子代理在一个独立的 Git 工作树中工作，其代码修改不会影响主工作区。

graph TB
    Main[“Main Working Tree”] -->|spawns| Sub[“Subagent with<br/>Isolated Worktree”]
    Sub -->|makes changes in| WT[“Separate Git<br/>Worktree + Branch”]
    WT -->|no changes| Clean[“Auto-cleaned”]
    WT -->|has changes| Return[“Returns worktree<br/>path and branch”]

如果子代理没有进行任何修改，工作树会自动清理。如果存在修改，主代理会收到工作树路径和分支名，以便审查或合并。

持久记忆 #

memory 字段为子代理提供一个跨会话持久化的目录，用于存储笔记和发现。

记忆目录中 MEMORY.md 文件的前 200 行会自动加载到子代理的系统提示中。子代理会自动获得 Read、Write 和 Edit 工具权限来管理其记忆文件。

Forked 子代理（context: fork） #

Forked 子代理在启动时继承父代理的完整对话上下文，而非从空白开始。这非常适合探索替代实现方案。

---
name: alternative-explorer
description: Explore an alternative implementation path while preserving parent context
context: fork
tools: Read, Edit, Bash, Grep, Glob
---

在外部构建版本（非官方分发）中，需要先设置环境变量 export CLAUDE_CODE_FORK_SUBAGENT=1 才能启用此功能。

限制可生成的子代理 #

在 tools 字段中使用 Agent(agent_name) 语法，可以控制当前子代理能够生成（委派）的其他子代理范围。

---
name: coordinator
description: Coordinates work between specialized agents
tools: Agent(worker, researcher), Read, Bash
---

以上配置意味着 coordinator 子代理只能生成 worker 和 researcher 这两个子代理，即使系统中定义了其他子代理，它也无法调用。

v2.1.133+：子代理的技能发现 #

从 v2.1.133 版本开始，子代理不再局限于其自身通过 skills 字段预加载的技能。它们现在可以通过 Skill 工具自动发现并使用项目级、用户级以及通过插件安装的技能，这与主会话的技能目录完全相同。这极大地扩展了子代理的能力边界。

插件子代理的安全限制 #

出于安全考虑，插件提供的子代理定义不允许使用以下字段，以防止插件通过子代理进行权限提升：

• hooks：不能定义生命周期钩子。
• mcpServers：不能配置 MCP 服务器。
• permissionMode：不能覆盖权限设置。

操作指南：创建与使用 #

创建子代理 #

方法一：使用 /agents 命令（推荐）

1. 在对话中输入 /agents。
2. 选择 “Create New Agent”。
3. 选择存储位置（项目级或用户级）。
4. 详细描述子代理的功能。
5. 选择要授予的工具权限（或留空继承所有工具）。
6. 保存。

方法二：直接文件管理

1. 创建目录：mkdir -p .claude/agents（项目级）或 mkdir -p ~/.claude/agents（用户级）。
2. 创建 Markdown 文件，如 .claude/agents/code-reviewer.md，并写入上述配置格式的内容。

方法三：CLI 配置（临时） 使用上文提到的 claude --agents ‘{…}’ 命令。

使用子代理 #

1. 自动委派：在任务描述中包含明确的关键词（如 “review this code”），Claude 会根据子代理的 description 字段自动选择最匹配的子代理。在 description 中包含 “use PROACTIVELY” 可鼓励自动调用。
2. 显式调用：直接在对话中指令，例如 “Use the test-runner subagent to fix failing tests”。
3. @提及调用：使用 @ 前缀强制调用特定子代理，例如 @”code-reviewer (agent)” review the auth module。
4. 作为主代理运行：使用 claude --agent <agent-name> 命令启动一个完整的会话，该会话完全由指定子代理的规则和能力驱动。

验证安装 #

安装完成后，运行 /agents 命令。你应该能在列表中看到新安装的子代理，与内置代理并列显示。

FAQ #

Q: 什么时候应该使用子代理？ A: 当任务复杂、需要隔离上下文、需要特定领域专业知识、或需要并行处理多个独立子任务时，使用子代理。对于简单的单步任务，直接使用主代理更高效。

Q: 如何限制一个子代理只能调用特定的其他子代理？ A: 在该子代理的 tools 配置字段中使用 Agent(agent_name) 语法。例如 tools: Agent(code-reviewer, tester) 将只允许它生成这两个子代理。

Q: 后台任务如何管理？ A: 使用 Ctrl+B 可将前台任务移至后台，Ctrl+F（按两次）可终止所有后台任务。在配置中设置 background: true 可强制子代理始终在后台运行。

Q: user、project 和 local 记忆范围有什么区别？ A: user 范围记忆存储在 ~/.claude/agent-memory/，适用于个人偏好；project 范围记忆在 .claude/agent-memory/，适合与团队共享项目知识；local 范围在 .claude/agent-memory-local/，存放不需要提交到版本控制的敏感或本地特定信息。

Q: Forked 子代理（context: fork）的典型用途是什么？ A: 当你想在不丢失当前工作上下文的前提下，探索一条替代的实现路径或进行“假设分析”时，可以使用 Forked 子代理。它会继承父代理的完整对话历史开始工作。