### 步骤 2：选择位置

切换到 **Library** 标签页，选择 **Create new agent**，然后选择 **Personal**。这会将子代理保存到 `~/.claude/agents/`，使其在所有项目中可用。

### 步骤 3：用 Claude 生成

选择 **Generate with Claude**。当提示输入时，描述子代理：

```text theme={null}
A code improvement agent 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.

Claude 会委派给你的新子代理，子代理扫描代码库并返回改进建议。

**至此你拥有了一个可在任何项目中使用的子代理**，用于分析代码库和提出改进建议。

你也可以手动创建 Markdown 文件形式的子代理、通过 CLI 标志定义，或通过插件分发。以下章节涵盖所有配置选项。

## 配置子代理

### 使用 /agents 命令

**`/agents` 命令打开一个标签式界面来管理子代理。** **Running** 标签页列出活跃和最近完成的子代理，允许你打开或停止它们。**Library** 标签页允许你：

* 查看所有可用子代理（内置、用户、项目和插件）
* 通过引导设置或 Claude 生成来创建新子代理
* 编辑现有子代理的配置和工具访问权限
* 删除自定义子代理
* 查看存在重名时哪个子代理处于活跃状态

这是创建和管理子代理的推荐方式。如需手动创建或自动化，也可以直接添加子代理文件。

### 选择子代理的作用域

**子代理是带有 YAML frontmatter 的 Markdown 文件。** 根据作用域将它们存放在不同位置。当多个子代理同名时，Claude Code 使用更高优先级位置的那个。

| 位置 | 作用域 | 优先级 | 创建方式 |
| :--- | :--- | :--- | :--- |
| 托管设置 | 组织范围 | 1（最高） | 通过[托管设置](https://code.claude.com/docs/en/settings)部署 |
| `--agents` CLI 标志 | 当前会话 | 2 | 启动 Claude Code 时传入 JSON |
| `.claude/agents/` | 当前项目 | 3 | 交互式或手动 |
| `~/.claude/agents/` | 所有项目 | 4 | 交互式或手动 |
| 插件的 `agents/` 目录 | 启用插件的地方 | 5（最低） | 随[插件](https://code.claude.com/docs/en/plugins)安装 |

**项目子代理**（`.claude/agents/`）适用于特定代码库的子代理。将它们提交到版本控制，让团队协作使用和改进。

项目子代理通过从当前工作目录向上遍历来发现，因此当前目录到仓库根之间的每个 `.claude/agents/` 都会被扫描。自 v2.1.178 起，当多个嵌套目录定义了相同的 `name` 时，Claude Code 使用最靠近工作目录的定义。

通过 `--add-dir` 添加的目录也会被扫描：附加目录中的 `.claude/agents/` 文件夹与项目子代理一起加载。关于 `--add-dir` 加载哪些其他配置类型，请参阅 [Additional directories](https://code.claude.com/docs/en/permissions#additional-directories-grant-file-access-not-configuration)。要在不使用 `--add-dir` 的情况下跨项目共享子代理，请使用 `~/.claude/agents/` 或[插件](https://code.claude.com/docs/en/plugins)。

**用户子代理**（`~/.claude/agents/`）是在所有项目中可用的个人子代理。

Claude Code 会递归扫描 `.claude/agents/` 和 `~/.claude/agents/`，因此你可以将定义组织到子文件夹中，如 `agents/review/` 或 `agents/research/`。子目录路径不影响子代理的标识或调用方式，因为身份仅来自 `name` frontmatter 字段。在同一作用域内保持 `name` 值唯一：如果同一作用域内两个文件声明了相同的名称，Claude Code 会保留一个并丢弃另一个，且不会发出警告。

插件 `agents/` 目录也会被递归扫描。与项目和用户作用域不同，插件 `agents/` 目录内的子文件夹会成为[作用域标识符](#invoke-subagents-explicitly)的一部分：插件 `my-plugin` 中 `agents/review/security.md` 文件注册为 `my-plugin:review:security`。

**CLI 定义的子代理**在启动 Claude Code 时通过 JSON 传入。它们仅存在于当前会话，不会保存到磁盘，适合快速测试或自动化脚本。你可以在单个 `--agents` 调用中定义多个子代理：

macOS、Linux、WSL：

```bash theme={null}
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` 标志接受的 JSON 与文件形式子代理使用相同的 [frontmatter](#supported-frontmatter-fields) 字段：`description`、`prompt`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`isolation` 和 `color`。其中 `prompt` 对应文件形式中 markdown 正文部分的系统提示词。

**托管子代理**由组织管理员部署。将 Markdown 文件放在[托管设置目录](https://code.claude.com/docs/en/settings#settings-files)中的 `.claude/agents/` 下，使用与项目和用户子代理相同的 frontmatter 格式。托管定义优先于同名的项目和用户子代理。

**插件子代理**来自你安装的[插件](https://code.claude.com/docs/en/plugins)。它们与你的自定义子代理一起显示在 `/agents` 中。关于创建插件子代理的详情，请参阅[插件组件参考](https://code.claude.com/docs/en/plugins-reference#agents)。

> **注意**
> 出于安全考虑，插件子代理不支持 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 字段。从插件加载代理时这些字段会被忽略。如果需要它们，请将代理文件复制到 `.claude/agents/` 或 `~/.claude/agents/`。你也可以在 `settings.json` 或 `settings.local.json` 的 [`permissions.allow`](https://code.claude.com/docs/en/settings#permission-settings) 中添加规则，但这些规则适用于整个会话，而不仅是该插件子代理。

任何作用域的子代理定义也可用于[代理团队](https://code.claude.com/docs/en/agent-teams#use-subagent-definitions-for-teammates)：生成队友时，你可以引用子代理类型，队友会使用其 `tools` 和 `model`，定义的正文作为附加指令追加到队友的系统提示词中。关于哪些 frontmatter 字段适用，请参阅[代理团队](https://code.claude.com/docs/en/agent-teams#use-subagent-definitions-for-teammates)。

### 编写子代理文件

**子代理文件使用 YAML frontmatter 进行配置，后跟 Markdown 格式的系统提示词：**

> **注意**
> 子代理在会话启动时加载。如果你直接在磁盘上添加或编辑了子代理文件，需要重启会话才能加载。通过 `/agents` 界面创建的子代理则无需重启即可立即生效。

```markdown theme={null}
---
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.

以下示例使用 `disallowedTools` 继承主对话的所有工具，但排除 Write 和 Edit。子代理保留 Bash、MCP 工具和其他一切：

```yaml theme={null}
---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

#### 限制可生成的子代理

**当代理通过 `claude --agent` 作为主线程运行时，可以使用 Agent 工具生成子代理。** 要限制它可以生成的子代理类型，在 `tools` 字段中使用 `Agent(agent_type)` 语法。

> **注意** 在 v2.1.63 中，Task 工具已重命名为 Agent。设置和代理定义中现有的 `Task(...)` 引用仍作为别名有效。

```yaml theme={null}
---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

如果 `tools` 列表中完全省略 `Agent`，则代理无法生成任何子代理。

`Agent(agent_type)` 白名单语法仅适用于通过 `claude --agent` 作为主线程运行的代理。在子代理定义中，在 `tools` 中列出 `Agent` 可以让该子代理[生成嵌套子代理](#spawn-nested-subagents)，但括号内的任何类型列表会被忽略。

#### 为子代理限定 MCP 服务器

**使用 `mcpServers` 字段让子代理访问主对话中不可用的 [MCP](https://code.claude.com/docs/en/mcp) 服务器。** 此处定义的内联服务器在子代理启动时连接，完成时断开。字符串引用则共享父会话的连接。

> **注意**
> `mcpServers` 字段在代理文件可以运行的两种场景中都适用：
>
> * 作为子代理，通过 Agent 工具或 @-mention 生成
> * 作为主会话，通过 [`--agent`](#invoke-subagents-explicitly) 或 `agent` 设置启动
>
> 当代理作为主会话时，内联服务器定义在启动时与 [`.mcp.json`](https://code.claude.com/docs/en/mcp) 和设置文件中的服务器一起连接。

列表中每个条目要么是内联服务器定义，要么是引用会话中已配置 MCP 服务器的字符串：

```yaml theme={null}
---
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.

每个列出的技能的完整内容在启动时注入子代理的上下文。此字段控制哪些技能被预加载，而非子代理可以访问哪些技能：即使不设置此字段，子代理仍可在执行过程中通过 Skill 工具发现和调用项目、用户和插件技能。要完全阻止子代理调用技能，从 [`tools`](#available-tools) 列表中省略 `Skill` 或将其添加到 `disallowedTools`。

你无法预加载设置了 [`disable-model-invocation: true`](https://code.claude.com/docs/en/skills#control-who-invokes-a-skill) 的技能，因为预加载与 Claude 可调用的技能来自同一集合。如果列出的技能缺失或被禁用，Claude Code 会跳过它并在调试日志中记录警告。

> **注意**
> 这与[在子代理中运行技能](https://code.claude.com/docs/en/skills#run-skills-in-a-subagent)相反。在子代理中使用 `skills` 时，子代理控制系统提示词并加载技能内容。在技能中使用 `context: fork` 时，技能内容被注入你指定的代理。两者使用相同的底层系统。

#### 启用持久记忆

**`memory` 字段为子代理提供一个跨对话持久化的目录。** 子代理利用此目录随时间积累知识，如代码库模式、调试洞察和架构决策。

```yaml theme={null}
---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Claude Code 通过 stdin 向钩子命令[传递 JSON 格式的钩子输入](https://code.claude.com/docs/en/hooks#pretooluse-input)。验证脚本读取此 JSON，提取 Bash 命令，并[以退出码 2](https://code.claude.com/docs/en/hooks#exit-code-2-behavior-per-event) 阻止写操作：

```bash theme={null}
#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

这对内置和自定义子代理都有效。你也可以使用 `--disallowedTools` CLI 标志：

```bash theme={null}
claude --disallowedTools "Agent(Explore)"

当代理作为子代理被调用时，frontmatter 中的 `Stop` 钩子会自动转换为 `SubagentStop` 事件。

#### 项目级子代理事件钩子

在 `settings.json` 中配置钩子来响应主会话中的子代理生命周期事件。

| 事件 | 匹配器输入 | 触发时机 |
| :--- | :--- | :--- |
| `SubagentStart` | 代理类型名称 | 子代理开始执行时 |
| `SubagentStop` | 代理类型名称 | 子代理完成时 |

两个事件都支持匹配器来按名称定位特定代理类型。以下示例仅在 `db-agent` 子代理启动时运行设置脚本，在任何子代理停止时运行清理脚本：

```json theme={null}
{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

**使用 @-提及子代理。** 输入 `@` 并从提示列表中选择子代理，操作方式与 @-提及文件相同。这能确保指定的子代理一定被调用，而不是交由 Claude 自行决定：

```text theme={null}
@"code-reviewer (agent)" look at the auth changes

子代理的系统提示会完全替换默认的 Claude Code 系统提示，与 [`--system-prompt`](https://code.claude.com/docs/en/cli-reference) 的效果相同。`CLAUDE.md` 文件和项目记忆仍通过正常的消息流加载。代理名称以 `@<name>` 显示在启动头部，方便你确认其已激活。

这对内置和自定义子代理都有效，且选择在恢复会话时会持续保留。

对于插件提供的子代理，只需传入代理名称，Claude Code 会自动查找：

```bash theme={null}
claude --agent security-reviewer

如果插件将代理放在 `agents/` 目录的子文件夹中，作用域名称中需包含子文件夹路径，例如 `claude --agent my-plugin:review:security`。

要将其设为项目中每个会话的默认值，在 `.claude/settings.json` 中设置 `agent`：

```json theme={null}
{
  "agent": "code-reviewer"
}

#### 并行研究

**对于相互独立的调查任务，可以同时启动多个子代理：**

```text theme={null}
Research the authentication, database, and API modules in parallel using separate subagents

### 选择子代理还是主对话

**使用主对话**的场景：

* 任务需要频繁的往返交互或迭代优化
* 多个阶段共享大量上下文，如规划、实现和测试
* 你在做快速、精准的小改动
* 延迟敏感的场景。子代理从零开始，可能需要时间收集上下文

**使用子代理**的场景：

* 任务产生大量你不需要保留在主上下文中的输出
* 你希望强制执行特定的工具限制或权限
* 工作是自包含的，可以返回一份摘要

如果你需要在主对话上下文中运行可复用的提示或工作流（而非隔离的子代理上下文），可以考虑使用 [Skills](https://code.claude.com/docs/en/skills)。

对于关于对话中已有内容的快速提问，使用 [`/btw`](https://code.claude.com/docs/en/interactive-mode#side-questions-with-%2Fbtw) 而不是子代理。它能看到你的完整上下文但无法使用工具，且回答不会被添加到历史记录中。

### 生成嵌套子代理

**从 Claude Code v2.1.172 起，子代理可以生成自己的子代理。** 当被委派的任务本身可以拆分为并行子任务时使用此功能，例如一个审查子代理为每个发现分派一个验证器，这样中间输出永远不会进入你的主对话。只有顶层子代理的摘要会返回给你。

嵌套子代理的配置方式与顶层子代理相同，从相同的[作用域](#选择子代理作用域)解析。提示输入下方的子代理面板显示完整的树结构：每行显示后代数量的 `(+N)` 计数，展开某行会显示该子代理的直接子代理以及返回 `main` 的路径。[`/agents`](#使用-agents-命令) 中的 Running 标签页以扁平列表显示正在运行的子代理。

深度计算为主对话之下的子代理层级数，无论每一层是在[前台还是后台](#前台或后台运行子代理)运行。位于第五层深度的子代理不会获得 Agent 工具，因此无法继续生成子代理。此限制是固定的，不可配置。

从 Claude Code v2.1.187 起，后台子代理的深度在首次生成时确定，之后[恢复](#恢复子代理)不会改变该深度。例如，如果你的主对话生成了子代理 A，A 在第二层生成了后台子代理 B，那么即使你后来直接从主对话恢复 B，B 仍然在第二层。从较浅的上下文恢复子代理不会让它获得深度限制已经阻止的额外生成层级。

要阻止特定子代理生成其他子代理，从其 [`tools`](#可用工具) 列表中移除 `Agent`，或将其添加到 `disallowedTools`。

[分叉](#分叉当前对话)仍然不能生成另一个分叉。它可以生成其他类型的子代理，这些会计入深度限制。

### 管理子代理上下文

#### 启动时加载的内容

**每个子代理启动时拥有全新的、隔离的上下文窗口。** 它看不到你的对话历史、你已调用的 skills 或 Claude 已读取的文件。Claude 会编写一条委派消息来概括任务，子代理从该消息开始工作。例外是[分叉](#分叉当前对话)，它继承父对话而非从零开始。

非分叉子代理的初始上下文包含：

| 内容 | 说明 |
| :--- | :--- |
| 系统提示 | 代理自身的提示加上 Claude Code 附加的环境详情，而非完整的 Claude Code 系统提示。自定义子代理在 [markdown 正文](#编写子代理文件)或 `prompt` 字段中定义。内置代理有预定义的提示。 |
| 任务消息 | Claude 在交接工作时编写的委派提示。 |
| CLAUDE.md 和记忆 | 主对话加载的[记忆层级](https://code.claude.com/docs/en/memory#how-claude-md-files-load)的每一层，包括 `~/.claude/CLAUDE.md`、项目规则、`CLAUDE.local.md` 和托管策略文件。内置的 Explore 和 Plan 代理跳过此项。 |
| Git 状态 | 父会话启动时的快照。当工作目录不是 Git 仓库或 [`includeGitInstructions`](https://code.claude.com/docs/en/settings#available-settings) 为 `false` 时不包含。Explore 和 Plan 无论如何都跳过此项。 |
| 预加载的 skills | 代理 [`skills` 字段](#将-skills-预加载到子代理中)中指定的任何 skill 的完整内容。内置代理不预加载 skills。 |

Explore 和 Plan 是唯一省略 CLAUDE.md 和 git 状态的子代理。没有 frontmatter 字段或针对单个代理的设置可以改变哪些代理跳过它们。

主对话在拥有完整 CLAUDE.md 上下文的情况下读取 Explore 和 Plan 的结果，因此大多数规则不需要传递到子代理本身。如果某条规则必须传递（例如"忽略 `vendor/` 目录"），在委派时的提示中重新声明即可。

#### 恢复子代理

**每次子代理调用都会创建一个新实例。要继续现有子代理的工作而非重新开始，请让 Claude 恢复它。**

恢复的子代理保留其完整的对话历史，包括所有先前的工具调用、结果和推理过程。子代理会从停止的地方精确继续，而不是重新开始。

当子代理完成时，Claude 会收到其代理 ID。内置的 Explore 和 Plan 代理是一次性的，不返回代理 ID，因此无法恢复；当你需要继续工作时，使用 `general-purpose` 或自定义子代理。

Claude 使用 `SendMessage` 工具并将代理 ID 作为 `to` 字段来恢复子代理。`SendMessage` 工具始终可用于通过代理 ID 或名称恢复子代理。结构化的团队协议消息（如 `shutdown_request` 和 `plan_approval_response`）需要启用[代理团队](https://code.claude.com/docs/en/agent-teams)。

要恢复子代理，让 Claude 继续之前的工作：

```text theme={null}
Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

`preTokens` 值表示压缩发生前使用了多少 token。

## 分叉当前对话

> **注意：** 分叉子代理需要 Claude Code v2.1.117 或更高版本。从 v2.1.161 起 `/fork` 命令默认启用；在更早版本中需要将 [`CLAUDE_CODE_FORK_SUBAGENT`](https://code.claude.com/docs/en/env-vars) 环境变量设为 `1`。让 Claude 自行生成分叉是实验性的，可能在未来版本中变更。此功能也可能作为分阶段推出的一部分在交互式会话中启用。

**分叉是继承整个对话历史的子代理，而非从零开始。** 这打破了子代理通常提供的输入隔离：分叉看到的系统提示、工具、模型和消息历史与主会话完全相同，因此你可以将旁支任务交给它而无需重新解释情况。分叉自身的工具调用仍然不会进入你的对话，只有最终结果返回，从而保持主上下文窗口的整洁。当命名子代理需要太多背景信息才能有用时，或者当你想从同一起点并行尝试多种方案时，使用分叉。

要不受分阶段推出的影响地控制分叉模式，将 [`CLAUDE_CODE_FORK_SUBAGENT`](https://code.claude.com/docs/en/env-vars) 设为 `1` 显式启用或设为 `0` 显式禁用。该变量在交互模式以及通过 SDK 或 `claude -p` 使用时均有效。

启用分叉模式后 Claude Code 有两个变化：

* Claude 可以通过在 Agent 工具中显式请求 `fork` 子代理类型来生成分叉。未指定子代理类型的生成仍使用[通用](#内置子代理)子代理，命名子代理如 Explore 仍按原方式生成。
* 每次子代理生成都在[后台](#前台或后台运行子代理)运行，无论是分叉还是命名子代理。将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 设为 `1` 可保持同步生成。

你可以使用 `/fork` 加上指令自行启动分叉，无论该变量是否设置。Claude Code 会从指令的开头几个词为分叉命名。以下示例在你继续在主会话中进行实现的同时，分叉对话来起草测试用例：

```text theme={null}
/fork draft unit tests for the parser changes so far

### 调试器

**一个既能分析也能修复问题的子代理。** 与代码审查器不同，此子代理包含 Edit 工具，因为修复 bug 需要修改代码。提示提供了从诊断到验证的清晰工作流。

```markdown theme={null}
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

### 数据库查询验证器

**一个允许 Bash 访问但通过验证确保只执行只读 SQL 查询的子代理。** 此示例展示了当需要比 `tools` 字段更精细的控制时，如何使用 `PreToolUse` 钩子进行条件验证。

```markdown theme={null}
---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

在 macOS 和 Linux 上，将脚本设为可执行：

```bash theme={null}
chmod +x ./scripts/validate-readonly-query.sh