子代理 - 完整参考指南
子代理是 Claude Code 可以委托任务的专用 AI 助手。每个子代理都有特定的用途，使用独立于主对话的上下文窗口，并可配置特定工具和自定义系统提示。
目录
- 概述
- 主要优势
- 文件位置
- 配置
- 内置子代理
- 管理子代理
- 使用子代理
- 可恢复代理
- 链式子代理
- 子代理的持久记忆
- 后台子代理
- Worktree 隔离
- 限制可派生子代理
claude agentsCLI 命令- 代理团队（实验性）
- 插件子代理安全性
- 架构
- 上下文管理
- 何时使用子代理
- 最佳实践
- 本文件夹中的示例子代理
- 安装说明
- 相关概念
概述
子代理通过以下方式在 Claude Code 中实现委托任务执行：
- 创建具有独立上下文窗口的隔离 AI 助手
- 为专业领域提供自定义系统提示
- 强制执行工具访问控制以限制能力范围
- 防止复杂任务造成上下文污染
- 支持多个专用任务的并行执行
每个子代理都以干净的状态独立运行，仅接收完成其任务所必需的特定上下文，然后将结果返回给主代理进行综合处理。
快速开始：使用 /agents 命令以交互方式创建、查看、编辑和管理您的子代理。
主要优势
| 优势 | 描述 |
|---|---|
| 上下文保护 | 在独立上下文中运行，防止主对话受到污染 |
| 专业领域能力 | 针对特定领域进行精调，成功率更高 |
| 可复用性 | 可在不同项目中使用并与团队共享 |
| 灵活权限 | 不同类型子代理拥有不同的工具访问级别 |
| 可扩展性 | 多个代理可同时处理不同方面的任务 |
文件位置
子代理文件可存储在多个具有不同作用域的位置：
| 优先级 | 类型 | 位置 | 作用域 |
|---|---|---|---|
| 1（最高） | CLI 定义 | 通过 --agents 标志（JSON） | 仅当前会话 |
| 2 | 项目子代理 | .claude/agents/ | 当前项目 |
| 3 | 用户子代理 | ~/.claude/agents/ | 所有项目 |
| 4（最低） | 插件代理 | 插件的 agents/ 目录 | 通过插件 |
当存在重名时，高优先级来源的定义优先生效。
配置
文件格式
子代理在 YAML 前置内容中定义，后跟 markdown 格式的系统提示：
yaml
---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3 # Optional - inherits all tools if omitted
disallowedTools: tool4 # Optional - explicitly disallowed tools
model: sonnet # Optional - sonnet, opus, haiku, or inherit
permissionMode: default # Optional - permission mode
maxTurns: 20 # Optional - limit agentic turns
skills: skill1, skill2 # Optional - skills to preload into context
mcpServers: server1 # Optional - MCP servers to make available
memory: user # Optional - persistent memory scope (user, project, local)
background: false # Optional - run as background task
effort: high # Optional - reasoning effort (low, medium, high, max)
isolation: worktree # Optional - git worktree isolation
initialPrompt: "Start by analyzing the codebase" # Optional - auto-submitted first turn
hooks: # Optional - component-scoped hooks
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/security-check.sh"
---
您的子代理系统提示写在这里。可以包含多个段落，
应清晰定义子代理的角色、能力以及解决问题的方式。配置字段
| 字段 | 是否必填 | 描述 |
|---|---|---|
name | 是 | 唯一标识符（小写字母和连字符） |
description | 是 | 用途的自然语言描述。包含 "use PROACTIVELY" 可鼓励自动调用 |
tools | 否 | 特定工具的逗号分隔列表。省略则继承所有工具。支持 Agent(agent_name) 语法以限制可派生子代理 |
disallowedTools | 否 | 子代理不得使用的工具逗号分隔列表 |
model | 否 | 使用的模型：sonnet、opus、haiku、完整模型 ID 或 inherit。默认使用配置的子代理模型 |
permissionMode | 否 | default、acceptEdits、dontAsk、bypassPermissions、plan |
maxTurns | 否 | 子代理可执行的最大代理回合数 |
skills | 否 | 预加载技能的逗号分隔列表。启动时将完整技能内容注入子代理上下文 |
mcpServers | 否 | 供子代理使用的 MCP 服务器 |
hooks | 否 | 组件作用域钩子（PreToolUse、PostToolUse、Stop） |
memory | 否 | 持久记忆目录作用域：user、project 或 local |
background | 否 | 设为 true 则始终以后台任务方式运行此子代理 |
effort | 否 | 推理努力程度：low、medium、high 或 max |
isolation | 否 | 设为 worktree 可为子代理提供独立的 git worktree |
initialPrompt | 否 | 当子代理作为主代理运行时自动提交的第一轮提示 |
工具配置选项
选项 1：继承所有工具（省略该字段）
yaml
---
name: full-access-agent
description: Agent with all available tools
---选项 2：指定单独工具
yaml
---
name: limited-agent
description: Agent with specific tools only
tools: Read, Grep, Glob, Bash
---选项 3：条件工具访问
yaml
---
name: conditional-agent
description: Agent with filtered tool access
tools: Read, Bash(npm:*), Bash(test:*)
---基于 CLI 的配置
使用带 JSON 格式的 --agents 标志为单次会话定义子代理：
bash
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"
}
}'--agents 标志的 JSON 格式：
json
{
"agent-name": {
"description": "Required: when to invoke this agent",
"prompt": "Required: system prompt for the agent",
"tools": ["Optional", "array", "of", "tools"],
"model": "optional: sonnet|opus|haiku"
}
}代理定义的优先级：
代理定义按以下优先级顺序加载（先匹配优先）：
- CLI 定义 -
--agents标志（仅当前会话，JSON） - 项目级别 -
.claude/agents/（当前项目） - 用户级别 -
~/.claude/agents/（所有项目） - 插件级别 - 插件的
agents/目录
这允许 CLI 定义在单次会话中覆盖所有其他来源。
内置子代理
Claude Code 包含几个始终可用的内置子代理：
| 代理 | 模型 | 用途 |
|---|---|---|
| general-purpose | 继承 | 复杂的多步骤任务 |
| Plan | 继承 | 计划模式的研究 |
| Explore | Haiku | 只读代码库探索（快速/中等/非常彻底） |
| Bash | 继承 | 在独立上下文中执行终端命令 |
| statusline-setup | Sonnet | 配置状态栏 |
| Claude Code Guide | Haiku | 解答 Claude Code 功能问题 |
通用子代理
| 属性 | 值 |
|---|---|
| 模型 | 继承自父级 |
| 工具 | 所有工具 |
| 用途 | 复杂研究任务、多步骤操作、代码修改 |
使用时机：需要同时进行探索和修改并具有复杂推理的任务。
Plan 子代理
| 属性 | 值 |
|---|---|
| 模型 | 继承自父级 |
| 工具 | Read, Glob, Grep, Bash |
| 用途 | 在计划模式中自动用于研究代码库 |
使用时机：Claude 需要在呈现计划前理解代码库时。
Explore 子代理
| 属性 | 值 |
|---|---|
| 模型 | Haiku（快速、低延迟） |
| 模式 | 严格只读 |
| 工具 | Glob, Grep, Read, Bash（仅只读命令） |
| 用途 | 快速代码库搜索与分析 |
使用时机：搜索/理解代码而不进行修改时。
彻底性级别 - 指定探索深度：
- "quick" - 快速搜索，最少探索，适合查找特定模式
- "medium" - 适度探索，速度与彻底性平衡，默认方式
- "very thorough" - 跨多个位置和命名约定的综合分析，可能耗时较长
Bash 子代理
| 属性 | 值 |
|---|---|
| 模型 | 继承自父级 |
| 工具 | Bash |
| 用途 | 在独立上下文窗口中执行终端命令 |
使用时机：运行受益于隔离上下文的 shell 命令时。
Statusline Setup 子代理
| 属性 | 值 |
|---|---|
| 模型 | Sonnet |
| 工具 | Read, Write, Bash |
| 用途 | 配置 Claude Code 状态栏显示 |
使用时机：设置或自定义状态栏时。
Claude Code Guide 子代理
| 属性 | 值 |
|---|---|
| 模型 | Haiku（快速、低延迟） |
| 工具 | 只读 |
| 用途 | 解答关于 Claude Code 功能和使用方式的问题 |
使用时机：用户询问 Claude Code 的工作原理或如何使用特定功能时。
管理子代理
使用 /agents 命令（推荐）
bash
/agents这将提供一个交互式菜单，用于：
- 查看所有可用子代理（内置、用户和项目级别）
- 通过引导设置创建新子代理
- 编辑现有自定义子代理及其工具访问权限
- 删除自定义子代理
- 查看存在重名时哪些子代理处于激活状态
直接文件管理
bash
# 创建项目子代理
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: Use proactively to run tests and fix failures
---
You are a test automation expert. When you see code changes, proactively
run the appropriate tests. If tests fail, analyze the failures and fix
them while preserving the original test intent.
EOF
# 创建用户子代理（在所有项目中可用）
mkdir -p ~/.claude/agents使用子代理
自动委托
Claude 基于以下内容主动委托任务：
- 请求中的任务描述
- 子代理配置中的
description字段 - 当前上下文和可用工具
要鼓励主动使用，请在 description 字段中包含 "use PROACTIVELY" 或 "MUST BE USED"：
yaml
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after writing or modifying code.
---显式调用
您可以显式请求特定子代理：
> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error@-提及调用
使用 @ 前缀可确保调用特定子代理（绕过自动委托启发式规则）：
> @"code-reviewer (agent)" review the auth module全会话代理
使用特定代理作为主代理运行整个会话：
bash
# 通过 CLI 标志
claude --agent code-reviewer
# 通过 settings.json
{
"agent": "code-reviewer"
}列出可用代理
使用 claude agents 命令列出来自所有来源的所有已配置代理：
bash
claude agents可恢复代理
子代理可以在保留完整上下文的情况下继续之前的对话：
bash
# 初始调用
> Use the code-analyzer agent to start reviewing the authentication module
# 返回 agentId: "abc123"
# 稍后恢复代理
> Resume agent abc123 and now analyze the authorization logic as well使用场景：
- 跨多个会话的长时间研究
- 不丢失上下文的迭代优化
- 维护上下文的多步骤工作流
链式子代理
按顺序执行多个子代理：
bash
> First use the code-analyzer subagent to find performance issues,
then use the optimizer subagent to fix them这支持复杂工作流，其中一个子代理的输出作为另一个子代理的输入。
子代理的持久记忆
memory 字段为子代理提供一个在多次对话间持久存在的目录。这允许子代理随时间积累知识，存储在会话间持久保存的笔记、发现和上下文。
记忆作用域
| 作用域 | 目录 | 使用场景 |
|---|---|---|
user | ~/.claude/agent-memory/<name>/ | 跨所有项目的个人笔记和偏好 |
project | .claude/agent-memory/<name>/ | 与团队共享的项目特定知识 |
local | .claude/agent-memory-local/<name>/ | 未提交到版本控制的本地项目知识 |
工作原理
- 记忆目录中
MEMORY.md的前 200 行会自动加载到子代理的系统提示中 Read、Write和Edit工具会自动为子代理启用，用于管理其记忆文件- 子代理可在其记忆目录中按需创建其他文件
示例配置
yaml
---
name: researcher
memory: user
---
You are a research assistant. Use your memory directory to store findings,
track progress across sessions, and build up knowledge over time.
Check your MEMORY.md file at the start of each session to recall previous context.后台子代理
子代理可在后台运行，使主对话可以继续处理其他任务。
配置
在前置内容中设置 background: true 可使子代理始终作为后台任务运行：
yaml
---
name: long-runner
background: true
description: Performs long-running analysis tasks in the background
---键盘快捷键
| 快捷键 | 操作 |
|---|---|
Ctrl+B | 将当前运行的子代理任务移至后台 |
Ctrl+F | 终止所有后台代理（按两次确认） |
禁用后台任务
设置环境变量可完全禁用后台任务支持：
bash
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1Worktree 隔离
isolation: worktree 设置为子代理提供其自己的 git worktree，允许其独立进行更改而不影响主工作树。
配置
yaml
---
name: feature-builder
isolation: worktree
description: Implements features in an isolated git worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---工作原理
- 子代理在其独立的 git worktree 的单独分支上运行
- 如果子代理未做任何更改，worktree 会自动清理
- 如果存在更改，worktree 路径和分支名称将返回给主代理以供审查或合并
限制可派生子代理
您可以通过在 tools 字段中使用 Agent(agent_type) 语法来控制给定子代理允许派生哪些子代理。这提供了一种为委托添加特定子代理白名单的方式。
注意：在 v2.1.63 中，
Task工具已重命名为Agent。现有的Task(...)引用仍作为别名有效。
示例
yaml
---
name: coordinator
description: Coordinates work between specialized agents
tools: Agent(worker, researcher), Read, Bash
---
You are a coordinator agent. You can delegate work to the "worker" and
"researcher" subagents only. Use Read and Bash for your own exploration.在此示例中，coordinator 子代理只能派生 worker 和 researcher 子代理。即使在其他地方定义了其他子代理，它也无法派生它们。
claude agents CLI 命令
claude agents 命令按来源（内置、用户级别、项目级别）分组列出所有已配置代理：
bash
claude agents此命令：
- 显示来自所有来源的所有可用代理
- 按来源位置对代理进行分组
- 当较高优先级的代理遮蔽较低优先级的同名代理时（例如，与用户级代理同名的项目级代理），标注覆盖关系
代理团队（实验性）
代理团队协调多个 Claude Code 实例共同处理复杂任务。与子代理（被委托子任务并返回结果）不同，团队成员独立工作，拥有自己的上下文，并通过共享邮箱系统直接通信。
注意：代理团队是实验性功能，需要 Claude Code v2.1.32 以上版本。使用前请先启用。
子代理与代理团队的对比
| 方面 | 子代理 | 代理团队 |
|---|---|---|
| 委托模型 | 父级委托子任务，等待结果 | 团队负责人分配工作，团队成员独立执行 |
| 上下文 | 每个子任务使用新鲜上下文，结果精炼后返回 | 每个团队成员维护自己的持久上下文 |
| 协调 | 顺序或并行，由父级管理 | 具有自动依赖管理的共享任务列表 |
| 通信 | 仅返回值 | 通过邮箱进行代理间消息传递 |
| 会话恢复 | 支持 | 进程内团队成员不支持 |
| 最适合 | 专注、定义明确的子任务 | 需要并行工作的大型多文件项目 |
启用代理团队
设置环境变量或将其添加到 settings.json：
bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1或在 settings.json 中：
json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}启动团队
启用后，在提示中要求 Claude 与团队成员合作：
User: Build the authentication module. Use a team — one teammate for the API endpoints,
one for the database schema, and one for the test suite.Claude 将自动创建团队、分配任务并协调工作。
显示模式
控制团队成员活动的显示方式：
| 模式 | 标志 | 描述 |
|---|---|---|
| 自动 | --teammate-mode auto | 自动为您的终端选择最佳显示模式 |
| 进程内 | --teammate-mode in-process | 在当前终端中内联显示团队成员输出（默认） |
| 分割窗格 | --teammate-mode tmux | 在单独的 tmux 或 iTerm2 窗格中打开每个团队成员 |
bash
claude --teammate-mode tmux您也可以在 settings.json 中设置显示模式：
json
{
"teammateMode": "tmux"
}注意：分割窗格模式需要 tmux 或 iTerm2。在 VS Code 终端、Windows Terminal 或 Ghostty 中不可用。
导航
在分割窗格模式下，使用 Shift+Down 在团队成员之间切换。
团队配置
团队配置存储在 ~/.claude/teams/{team-name}/config.json。
架构
关键组件：
- 团队负责人：创建团队、分配任务并进行协调的主 Claude Code 会话
- 共享任务列表：具有自动依赖跟踪的同步任务列表
- 邮箱：供团队成员交流状态和协调的代理间消息系统
- 团队成员：独立的 Claude Code 实例，每个都有自己的上下文窗口
任务分配与消息传递
团队负责人将工作分解为任务并分配给团队成员。共享任务列表负责：
- 自动依赖管理 — 任务等待其依赖项完成后再开始
- 状态跟踪 — 团队成员在工作时更新任务状态
- 代理间消息传递 — 团队成员通过邮箱发送协调消息（例如："数据库架构已就绪，您可以开始编写查询"）
计划审批工作流
对于复杂任务，团队负责人在团队成员开始工作前创建执行计划。用户审查并批准该计划，确保团队的方法符合预期，然后再进行任何代码更改。
团队的钩子事件
代理团队引入了两个额外的钩子事件：
| 事件 | 触发时机 | 使用场景 |
|---|---|---|
TeammateIdle | 团队成员完成当前任务且没有待处理工作时 | 触发通知、分配后续任务 |
TaskCompleted | 共享任务列表中的某个任务被标记为完成时 | 运行验证、更新仪表板、链接依赖工作 |
最佳实践
- 团队规模：保持 3-5 名团队成员以实现最佳协调
- 任务规模：将工作分解为每个 5-15 分钟的任务 — 足够小以便并行化，足够大以有实质意义
- 避免文件冲突：将不同文件或目录分配给不同团队成员以防止合并冲突
- 从简单开始：第一次使用进程内模式；熟悉后再切换到分割窗格
- 清晰的任务描述：提供具体、可操作的任务描述，以便团队成员独立工作
限制
- 实验性：功能行为可能在未来版本中发生变化
- 不支持会话恢复：进程内团队成员在会话结束后无法恢复
- 每次会话只有一个团队：不能在单次会话中创建嵌套团队或多个团队
- 固定领导角色：团队负责人角色不能转让给团队成员
- 分割窗格限制：需要 tmux/iTerm2；在 VS Code 终端、Windows Terminal 或 Ghostty 中不可用
- 无跨会话团队：团队成员仅存在于当前会话中
警告：代理团队是实验性功能。请先用非关键工作进行测试，并监控团队成员协调是否出现意外行为。
插件子代理安全性
出于安全考虑，插件提供的子代理具有受限的前置内容能力。以下字段在插件子代理定义中不被允许：
hooks- 不能定义生命周期钩子mcpServers- 不能配置 MCP 服务器permissionMode- 不能覆盖权限设置
这防止插件通过子代理钩子提升权限或执行任意命令。
架构
高层架构
子代理生命周期
上下文管理
关键要点
- 每个子代理都获得一个新鲜的上下文窗口，不包含主对话历史
- 只有相关上下文会传递给子代理用于其特定任务
- 结果会被精炼后返回给主代理
- 这防止了长期项目中的上下文令牌耗尽
性能注意事项
- 上下文效率 - 代理保护主上下文，支持更长的会话
- 延迟 - 子代理从干净起点开始，在收集初始上下文时可能增加延迟
关键行为
- 不支持嵌套派生 - 子代理不能派生其他子代理
- 后台权限 - 后台子代理自动拒绝任何未预先批准的权限
- 后台化 - 按
Ctrl+B将当前运行的任务移至后台 - 转录记录 - 子代理转录存储在
~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl - 自动压缩 - 子代理上下文在容量约 95% 时自动压缩（可通过
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE环境变量覆盖）
何时使用子代理
| 场景 | 使用子代理 | 原因 |
|---|---|---|
| 包含多个步骤的复杂功能 | 是 | 分离关注点，防止上下文污染 |
| 快速代码审查 | 否 | 不必要的开销 |
| 并行任务执行 | 是 | 每个子代理拥有独立上下文 |
| 需要专业领域能力 | 是 | 自定义系统提示 |
| 长时间运行的分析 | 是 | 防止主上下文耗尽 |
| 单一任务 | 否 | 不必要地增加延迟 |
最佳实践
设计原则
应该做：
- 从 Claude 生成的代理开始 - 先用 Claude 生成初始子代理，再迭代定制
- 设计专注的子代理 - 单一、清晰的职责，而非一个代理承担所有事情
- 编写详细的提示 - 包含具体指令、示例和约束
- 限制工具访问 - 只授予子代理用途所必需的工具
- 版本控制 - 将项目子代理纳入版本控制以供团队协作
不应该做：
- 创建角色重叠的子代理
- 给予子代理不必要的工具访问权限
- 对简单的单步骤任务使用子代理
- 在一个子代理的提示中混合关注点
- 忘记传递必要的上下文
系统提示最佳实践
明确角色
You are an expert code reviewer specializing in [specific areas]清晰定义优先级
Review priorities (in order): 1. Security Issues 2. Performance Problems 3. Code Quality指定输出格式
For each issue provide: Severity, Category, Location, Description, Fix, Impact包含行动步骤
When invoked: 1. Run git diff to see recent changes 2. Focus on modified files 3. Begin review immediately
工具访问策略
- 从限制开始：仅从必需的工具开始
- 按需扩展：根据需求添加工具
- 尽量只读：分析代理使用 Read/Grep
- 沙箱执行：将 Bash 命令限制为特定模式
本文件夹中的示例子代理
此文件夹包含可直接使用的示例子代理：
1. 代码审查员（code-reviewer.md）
用途：全面的代码质量和可维护性分析
工具：Read, Grep, Glob, Bash
专业领域：
- 安全漏洞检测
- 性能优化识别
- 代码可维护性评估
- 测试覆盖率分析
使用时机：需要关注质量和安全性的自动化代码审查时
2. 测试工程师（test-engineer.md）
用途：测试策略、覆盖率分析和自动化测试
工具：Read, Write, Bash, Grep
专业领域：
- 单元测试创建
- 集成测试设计
- 边界情况识别
- 覆盖率分析（目标 >80%）
使用时机：需要全面的测试套件创建或覆盖率分析时
3. 文档编写员（documentation-writer.md）
用途：技术文档、API 文档和用户指南
工具：Read, Write, Grep
专业领域：
- API 端点文档
- 用户指南创建
- 架构文档
- 代码注释改进
使用时机：需要创建或更新项目文档时
4. 安全审查员（secure-reviewer.md）
用途：以最少权限进行安全专注的代码审查
工具：Read, Grep
专业领域：
- 安全漏洞检测
- 认证/授权问题
- 数据暴露风险
- 注入攻击识别
使用时机：需要在没有修改能力的情况下进行安全审计时
5. 实现代理（implementation-agent.md）
用途：功能开发的完整实现能力
工具：Read, Write, Edit, Bash, Grep, Glob
专业领域：
- 功能实现
- 代码生成
- 构建和测试执行
- 代码库修改
使用时机：需要子代理端到端实现功能时
6. 调试器（debugger.md）
用途：专门用于错误、测试失败和意外行为的调试专家
工具：Read, Edit, Bash, Grep, Glob
专业领域：
- 根本原因分析
- 错误调查
- 测试失败解决
- 最小化修复实现
使用时机：遇到 bug、错误或意外行为时
7. 数据科学家（data-scientist.md）
用途：SQL 查询和数据洞察的数据分析专家
工具：Bash, Read, Write
专业领域：
- SQL 查询优化
- BigQuery 操作
- 数据分析与可视化
- 统计洞察
使用时机：需要数据分析、SQL 查询或 BigQuery 操作时
安装说明
方法 1：使用 /agents 命令（推荐）
bash
/agents然后：
- 选择"创建新代理"
- 选择项目级别或用户级别
- 详细描述您的子代理
- 选择授予访问权限的工具（或留空以继承全部）
- 保存并使用
方法 2：复制到项目
将代理文件复制到项目的 .claude/agents/ 目录：
bash
# 导航到您的项目
cd /path/to/your/project
# 如果不存在则创建代理目录
mkdir -p .claude/agents
# 从此文件夹复制所有代理文件
cp /path/t./subagents/*.md .claude/agents/
# 删除 README（在 .claude/agents 中不需要）
rm .claude/agents/README.md方法 3：复制到用户目录
适用于在所有项目中可用的代理：
bash
# 创建用户代理目录
mkdir -p ~/.claude/agents
# 复制代理
cp /path/t./subagents/code-reviewer.md ~/.claude/agents/
cp /path/t./subagents/debugger.md ~/.claude/agents/
# ... 根据需要复制其他文件验证
安装后，验证代理是否被识别：
bash
/agents您应该看到已安装的代理与内置代理一起列出。
文件结构
project/
├── .claude/
│ └── agents/
│ ├── code-reviewer.md
│ ├── test-engineer.md
│ ├── documentation-writer.md
│ ├── secure-reviewer.md
│ ├── implementation-agent.md
│ ├── debugger.md
│ └── data-scientist.md
└── ...相关概念
相关功能
与其他功能的对比
| 功能 | 用户调用 | 自动调用 | 持久化 | 外部访问 | 隔离上下文 |
|---|---|---|---|---|---|
| 斜杠命令 | 是 | 否 | 否 | 否 | 否 |
| 子代理 | 是 | 是 | 否 | 否 | 是 |
| 记忆 | 自动 | 自动 | 是 | 否 | 否 |
| MCP | 自动 | 是 | 否 | 是 | 否 |
| 技能 | 是 | 是 | 否 | 否 | 否 |
集成模式
附加资源
- 官方子代理文档
- CLI 参考 -
--agents标志及其他 CLI 选项 - 插件指南 - 用于将代理与其他功能捆绑
- 技能指南 - 用于自动调用的能力
- 记忆指南 - 用于持久上下文
- 钩子指南 - 用于事件驱动的自动化
最后更新：2026 年 3 月
本指南涵盖 Claude Code 的完整子代理配置、委托模式和最佳实践。