子代理 — 完整参考指南

子代理（Subagent）是 Claude Code 可以委派任务的专业 AI 助手。每个子代理都有特定的用途，使用独立于主对话的上下文窗口（Context Window），并且可以配置特定的工具和自定义系统提示词（Prompt）。

目录

1. 概述
2. 核心优势
3. 文件位置
4. 配置
5. 内置子代理
6. 管理子代理
7. 使用子代理
8. 可恢复代理
9. 链式子代理
10. 子代理的持久记忆
11. 后台子代理
12. 工作树隔离
13. 限制可生成的子代理
14. claude agents CLI 命令
15. 代理团队（实验性）
16. 插件子代理安全
17. 架构
18. 上下文管理
19. 何时使用子代理
20. 最佳实践
21. 本文件夹中的示例子代理
22. 安装说明
23. 相关概念

---

概述

子代理通过以下方式实现 Claude Code 中的委派任务执行：

• 创建具有独立上下文窗口的隔离 AI 助手
• 提供自定义系统提示词以获得专业领域能力
• 执行工具访问控制来限制功能范围
• 防止复杂任务导致的上下文污染
• 支持多个专业任务的并行执行

每个子代理独立运行，拥有干净的初始状态，仅接收其任务所需的特定上下文，然后将结果返回给主代理进行综合。

快速开始：使用 /agents 命令交互式地创建、查看、编辑和管理你的子代理。

---

核心优势

优势	描述
上下文保护	在独立上下文中运行，防止主对话被污染
专业能力	针对特定领域进行微调，成功率更高
可复用性	可在不同项目中使用，并与团队共享
灵活权限	不同类型的子代理有不同的工具访问级别
可扩展性	多个代理可以同时处理不同方面的工作

---

文件位置

子代理文件可以存储在多个位置，具有不同的作用域：

优先级	类型	位置	作用域
1（最高）	CLI 定义	通过 --agents 标志（JSON）	仅当前会话
2	项目子代理	.claude/agents/	当前项目
3	用户子代理	~/.claude/agents/	所有项目
4（最低）	插件代理	插件（Plugin）的 agents/ 目录	通过插件

当存在重名时，优先级更高的来源优先生效。

---

配置

文件格式

子代理在 YAML 前置元数据（Frontmatter）中定义，后跟 markdown 格式的系统提示词：

---
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"
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.