什么是子代理子代理本质上是一个拥有独立上下文窗口的专用 AI 实例。当你在 Claude Code 主对话中下达任务时Claude 可以判断该任务是否适合委派给某个子代理由子代理独立完成后将结果摘要返回主对话。每个子代理拥有独立的系统提示词 — 定义子代理的角色、行为和工作流程独立的上下文窗口 — 与主对话隔离不会互相污染指定的模型 — 可以选择 Haiku / Sonnet / Opus或继承主对话受限的工具权限 — 可精确控制子代理能使用哪些工具独立的权限模式 — 控制操作确认的行为生命周期钩子 — 在特定时机触发自定义脚本为什么需要子代理痛点子代理如何解决探索性任务消耗大量上下文子代理在独立上下文中完成只有摘要返回主对话需要严格约束某类操作如只读审查通过 tools 字段限制子代理只能使用只读工具团队中不同角色需要不同 AI 行为为每种角色创建专用子代理各有专属提示词简单任务不想消耗昂贵的 Opus 额度将简单任务路由到 Haiku复杂任务才用 Sonnet/Opus某些规范 Claude 总是犯错在子代理提示词中写死约束比口头提醒更可靠一句话总结子代理 职责明确、权限受限、上下文隔离的专用 AI 助手。子代理运行机制生命周期个子代理从创建到结束经历以下阶段任务匹配 → 实例创建 → 独立执行 → 结果回传 → 实例销毁任务匹配当你在主对话中提出请求时Claude 会将请求内容与所有已注册子代理的description字段进行语义匹配。如果某个子代理的描述与当前任务高度吻合Claude 就会决定将任务委派出去你也可以在对话中显式指定子代理名称来跳过匹配过程。实例创建匹配成功后Claude Code 为该子代理创建一个全新的 AI 实例。这个实例拥有独立的上下文窗口加载子代理配置中定义的系统提示词并按照tools字段初始化工具权限。此时子代理与主对话之间的上下文是完全隔离的——子代理看不到主对话的历史主对话也不会被子代理的中间过程所干扰。独立执行子代理在自己的上下文窗口中自主工作可以调用被授权的工具读取文件、执行命令、编辑代码等经历多轮推理和工具调用直到完成任务。整个过程中子代理只受自身的系统提示词和工具权限约束不受主对话上下文的影响。结果回传子代理完成任务后将工作成果以摘要形式返回主对话。注意返回的是精炼后的结论和关键信息而非子代理执行过程中的全部中间步骤。这正是子代理能有效保护主对话上下文的核心原因。实例销毁结果回传后子代理实例即被释放。下次调用同名子代理时会创建一个全新的实例上下文隔离模型主对话与子代理之间的关系可以用下图理解┌──────────────────────────────────────────────┐ │ 主对话 │ │ 上下文窗口保留完整的用户对话历史 │ │ │ │ 用户审查 src/auth 模块的代码质量 │ │ ↓ 任务委派 │ │ ┌───────────────────────────────────────┐ │ │ │ 子代理code-reviewer │ │ │ │ 独立上下文窗口与主对话完全隔离 │ │ │ │ │ │ │ │ 系统提示词 → 工具调用 → 多轮推理 │ │ │ │ Read(auth.ts) → Grep(漏洞模式) → ... │ │ │ │ ↓ │ │ │ │ 生成审查报告 │ │ │ └──────────────┬────────────────────────┘ │ │ ↓ 仅返回摘要 │ │ Claude审查完成发现 3 个问题…… │ └────────────────────────────────────────────────┘这种隔离模型带来三个关键好处上下文保护子代理在执行过程中可能读取大量文件、运行多次搜索这些中间数据全部留在子代理的上下文中不会挤占主对话的 Token 预算。行为可控子代理只能看到自己的系统提示词和被授权的工具不会受到主对话中其他无关信息的干扰行为更加可预测。故障隔离即使子代理执行出错或超时也不会破坏主对话的状态你可以在主对话中继续工作或重新委派任务。与主对话的协作方式子代理并非完全孤立地工作——它与主对话之间存在以下协作通道通道方向说明任务指令主对话 → 子代理主对话将任务描述和必要的上下文传递给子代理结果摘要子代理 → 主对话子代理将工作成果以精炼摘要的形式返回文件系统双向共享子代理对文件的读写操作会直接作用于项目的真实文件系统除非使用 isolation: worktree权限确认子代理 → 用户前台子代理执行敏感操作时权限确认提示会正常弹出给用户需要特别注意的是子代理对文件系统的修改是即时生效的。如果子代理编辑了某个文件主对话中后续操作看到的就是修改后的版本。这一点与上下文隔离不同——上下文隔离的是对话历史而非文件系统。如果需要连文件系统也隔离可以使用isolation: worktree让子代理在独立的 git worktree 中工作。内置子代理Claude Code 已经内置了多种子代理在日常使用中会自动调用无需手动配置。子代理模型工具权限用途自动触发场景ExploreHaiku只读禁止 Write/Edit文件搜索、代码结构分析、定义查找需要阅读代码但不修改时Plan继承主对话只读禁止 Write/EditPlan Mode 下的项目调研进入 Plan Mode 后General-purpose继承主对话全部工具复杂的多步骤研究与修改需要综合分析 代码修改时Bash继承主对话终端命令在独立上下文中执行命令需要运行 shell 命令时Claude Code GuideHaiku只读回答 Claude Code 使用问题咨询 Claude Code 功能时其中Explore子代理支持三种探索深度quick— 快速定向查找适合已知目标medium— 平衡探索适合一般性搜索very thorough— 全面分析适合复杂的跨模块调研创建自定义子代理使用 /agents 命令/agents提供交互式界面是创建和管理子代理最便捷的方式 /agents进入后可以查看所有子代理— 包括内置、用户级、项目级的全部子代理创建新子代理— 支持 Claude 自动生成或手动编写编辑已有子代理— 修改配置、提示词、工具权限删除自定义子代理创建流程运行/agents→ 选择Create new agent选择作用域User-level 全局可用 / Project-level 仅当前项目选择Generate with Claude输入需求描述例如一个代码审查代理扫描最近的代码变更 从可读性、安全性、性能三个角度给出改进建议 并附上修改示例。Claude 自动生成系统提示词和初始配置按e可手动编辑按回车确认选择工具权限只读 / 可写 / 全部选择模型Haiku / Sonnet / Opus /自定义保存 —立即生效无需重启会话手动创建文件子代理配置文件是带 YAML 前置元数据的 Markdown 文件放在指定目录即可生效# 创建项目级子代理仅当前项目可用可提交到 Git 共享给团队 mkdir -p .claude/agents # 创建用户级子代理所有项目可用 mkdir -p ~/.claude/agents然后在目录中创建.md文件例如.claude/agents/code-reviewer.md。注意手动创建的文件需要重启会话或运行/agents才能被加载。CLI 参数传入临时使用适合临时测试或在自动化脚本中使用claude --agents { code-reviewer: { description: 代码质量与安全审查专家。在代码变更后主动使用。, prompt: 你是一名资深代码审查工程师..., tools: [Read, Grep, Glob], model: sonnet } }配置文件详解基本结构--- name: code-reviewer description: 代码质量审查专家。在编写或修改代码后主动使用检查质量、安全性和可维护性。 tools: Read, Grep, Glob, Bash model: sonnet --- 你是一名资深代码审查工程师。 被调用时 1. 运行 git diff 查看最近的代码变更 2. 聚焦已修改的文件 3. 按优先级反馈问题严重 → 警告 → 建议---之间是YAML 前置元数据配置部分---之后是系统提示词行为定义。完整字段说明字段必填类型说明name是string唯一标识符使用小写字母和连字符如 code-reviewerdescription是string关键字段描述子代理的用途Claude 据此决定是否委派任务tools否string/list允许使用的工具列表省略则继承所有工具disallowedTools否string/list明确禁止的工具model否string使用的模型haiku / sonnet / opus / inherit默认 inheritpermissionMode否string权限模式见下文maxTurns否number子代理最大交互轮次skills否list启动时预加载的技能列表mcpServers否list可用的 MCP 服务器hooks否object生命周期钩子配置memory否string持久化记忆范围user / project / localbackground否boolean设为 true 则始终在后台运行isolation否string设为 worktree 则在独立 git worktree 中运行description 字段自动委派的关键Claude 决定是否将任务委派给子代理主要依据description字段。编写 description 时的技巧# 好的写法明确、具体包含主动触发词 description: 代码审查专家。在编写或修改代码后主动使用proactively。分析代码质量、安全性和可维护性。 # 差的写法模糊、宽泛 description: 一个帮助处理代码的助手。关键词在 description 中使用主动使用、proactively、immediately、must use when等词汇可以提高子代理被自动调用的概率。你也可以在对话中显式调用 使用 code-reviewer 子代理检查最近的提交 让 security-auditor 审计 src/auth 目录作用域与优先级子代理配置文件放在不同位置对应不同的作用域。同名子代理按优先级覆盖优先级位置作用域典型用途1最高CLI --agents 参数当前会话临时测试、自动化脚本2.claude/agents/当前项目项目专用提交到 Git 团队共享3~/.claude/agents/所有项目个人通用工具4最低插件的 agents/ 目录插件作用域第三方插件提供的子代理实践建议项目级子代理.claude/agents/与代码一起提交到 Git团队成员自动共享。适合放项目专属的审查规则、测试流程等用户级子代理~/.claude/agents/跨项目复用个人偏好工具如个人常用的代码审查风格、日志分析方式等CLI 临时子代理适合在 CI/CD 流水线或一次性脚本中使用