2026年Claude Code 子代理（Subagent）

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

在 Claude Code 中，你可以创建专门的 AI 子代理（Subagent），用于处理特定类型的任务，从而获得更好的上下文隔离、更强的约束控制和更高的执行效率。

子代理运行在独立的上下文窗口中，每个子代理都可以拥有独立的系统提示、指定的模型、明确的工具访问权限、独立的权限模式，以及跨会话的持久记忆。当 Claude 判断你的请求符合某个子代理的描述时，会自动将任务委托给它，由子代理独立完成后返回结果。

子代理只接收自身的系统提示和基础环境信息（如工作目录），不会继承完整的 Claude Code 系统提示，这保证了行为的纯净和可控。

子代理的核心价值在于隔离 + 专业化，主要体现在以下几个方面：

保留主对话上下文：把探索、日志分析等"重任务"放到子代理中，主对话只接收结论摘要，不被大量中间输出淹没。研究表明，并行运行三个子代理分析 5 万行项目约需 45 秒，而串行执行需要 3 分钟。

强制执行约束：通过工具白名单或黑名单限制子代理的能力，例如只读分析、禁止执行危险命令。

行为专业化：为特定领域（代码审查、调试、数据分析）设计专用 AI，在系统提示中明确指出代理的能力边界，避免不必要的调用。

控制成本：将简单任务交给 Haiku，将复杂分析交给 Sonnet，通过环境变量 CLAUDE_CODE_SUBAGENT_MODEL 统一设置所有子代理使用的模型。

跨项目复用：用户级子代理一次配置，所有项目可用。

这两个概念容易混淆，区别在于任务粒度和运行范围：

Claude Code 已内置多种子代理，通常会自动使用，无需手动配置。

用于只读搜索与分析代码库。模型默认使用 Haiku（速度快、延迟低），只开放只读工具（不能 Edit / Write）。当 Claude 需要查看代码但不修改代码时，会自动使用 Explore 代理。支持不同探索深度：quick、medium、very thorough。

在计划模式下收集代码库信息，帮助 Claude 理解项目结构，为后续方案制定积累上下文。只开放只读工具，在不产生嵌套代理的前提下安全地收集规划所需信息。

用于复杂、多步骤任务，开放全部工具，继承主对话的模型。适合"看 + 改 + 推理"的综合场景，以及需要多步骤代码修改的任务。

在 Claude Code 中执行以下命令，打开完整的子代理管理界面：

/agents

该界面提供所有子代理管理能力：查看全部可用代理（内置 / 用户级 / 项目级 / 插件）、创建新代理、编辑已有代理，以及在同名冲突时查看哪个版本实际生效。

在界面中选择 Create new agent:

然后选择 Project (.claude/agents/)，代理文件会保存到当前目录的 .claude/agents/ 目录下，如果选择 ~/.claude/agents/ 目录，则对所有项目生效：

使用 Claude 推荐的：

我们可以直接用自然语言告诉 Claude 这个代理要做什么，Claude 会自动生成系统提示和初始配置。例如：

一个代码改进代理，扫描项目文件， 针对可读性、性能和**实践提出建议， 并给出改进示例。

生成完成后，按 e 键可以手动编辑所有配置内容。

只做代码审查 → 仅勾选只读工具（Read / Grep / Glob）
需要修改代码 → 保留 Edit / Write 工具
模型推荐选择 Sonnet，分析能力与执行速度较为均衡

直接选 Contiune 然后回车：

接下来的选默认回车就好。

选择 User：在 ~/.claude/agent-memory/ 建立持久记忆，跨所有项目积累经验
选择 None：不保留学习成果，每次任务从零开始

使用 code-improver 子代理为此项目提出改进建议

代理会在独立上下文中运行，完成后将结果摘要返回给主对话。

子代理本质上是带 YAML frontmatter 的 Markdown 文件，存放位置决定了它的作用范围和优先级：

存放位置作用范围优先级 CLI --agents 标志仅当前会话最高 .claude/agents/ 当前项目高 ~/.claude/agents/ 所有项目（全局）中插件 agents 插件作用域最低

当同名子代理在不同位置都存在时，优先级高的会覆盖低的。可通过 /agents 命令查看当前哪个版本实际生效。

选择存放位置的建议：项目代理（.claude/agents/）可以跟随代码一起提交，让团队共享；用户代理（~/.claude/agents/）存放个人习惯与通用工具，跨项目生效；CLI 代理（--agents）用于临时测试或自动化脚本，不保留到磁盘。

每个子代理配置文件由两部分组成：YAML frontmatter（元数据与配置）和 Markdown 正文（系统提示）。

字段是否必填说明 name 必填唯一标识，也是显式调用时的名称。格式：小写字母 + 连字符，如 code-reviewer description 必填 最重要的字段，Claude 是否以及何时自动调用该代理完全依赖于此，务必写清楚使用场景 tools 可选工具白名单；设置后只能使用列出的工具，MCP 工具也会被排除 disallowedTools 可选工具黑名单；继承主对话全部工具，但排除列出的工具（MCP 工具保留） model 可选指定模型，可填 haiku、 sonnet、 opus、完整模型 ID，或 inherit（默认，继承主对话） permissionMode 可选权限行为控制，见下方权限模式章节 memory 可选持久记忆范围： user / project / local，见下方记忆章节 background 可选设为 true 时，该代理始终以后台方式运行（不阻塞主对话） isolation 可选设为 worktree 时，在临时 git worktree 中运行，与主仓库完全隔离 skills 可选在此代理启动时自动加载的 Skills 列表 hooks 可选生命周期钩子： SubagentStart / SubagentStop / PreToolUse / PostToolUse

配置方式行为典型场景两者均不设置继承主对话全部工具，含 MCP 工具通用代理，不需要限制仅设置 tools 只能使用白名单内的工具，MCP 工具被排除只读分析代理、严格约束场景仅设置 disallowedTools 继承全部工具，排除黑名单工具，MCP 工具保留保留 MCP 能力但禁止写操作两者同时设置先应用 disallowedTools，再从剩余工具中按 tools 筛选精细控制工具访问

通过 permissionMode 字段控制子代理执行操作时的权限行为：

模式行为适用场景 default 正常权限提示，每次操作前询问用户通用场景，推荐默认值 acceptEdits 自动接受文件编辑，无需每次确认频繁改动文件的代理，减少交互中断 dontAsk 自动拒绝未授权操作，不中断执行流程严格只读场景，操作失败时静默跳过 bypassPermissions 跳过所有权限检查，直接执行仅限完全可信、受控的自动化环境 plan 只读规划模式，不执行任何写操作方案制定、架构分析

bypassPermissions 只适合完全可信的子代理。另外，子代理会继承父会话的权限模式——如果主会话开启了 bypass，所有子代理也会跟着 bypass，使用时请格外谨慎。

通过 memory 字段，子代理可以在会话之间积累知识，例如代码库规律、调试经验、架构决策等，无需每次重新探索。

范围值存储位置适用场景 user

~/.claude/agent-memory/ 
            
              /

代理的知识适用于所有项目，如通用代码审查规范 project

.claude/agent-memory/ 
            
              /

知识与项目绑定，可通过 git 在团队间共享（推荐默认值） local

.claude/agent-memory-local/ 
            
              /

知识与项目绑定但不提交 git，仅存储个人本地经验

在对话中控制记忆的使用方式：

任务开始前：请先查阅你的记忆，再开始审查（让代理利用已有经验）
任务结束后：任务完成后，把你发现的规律保存到记忆中（持续积累）
也可直接在系统提示中写入"主动维护记忆"的指令，让代理自动执行，无需每次手动提醒

设置 isolation: worktree 后，子代理会在临时 git worktree 中运行，与主仓库完全隔离。适合以下场景：

需要大量文件修改但不确定结果的探索性任务
并行跑多个方案对比，互不干扰
自动化测试、CI 验证等需要干净环境的操作

子代理支持前台和后台两种运行方式，行为不同：

Claude 会根据任务特性自动判断使用前台还是后台。你也可以手动控制：

Ctrl + B：将当前运行的子代理切换到后台
Ctrl + F（按两次确认）：终止所有后台代理
在 frontmatter 中设置 background: true：该代理始终以后台方式运行
消息开头加 &：将该任务作为后台任务发送给 claude.ai 网页端
通过 /tasks 命令随时查看后台任务进度

如需彻底禁用后台任务功能，设置以下环境变量：

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

如需统一设置所有子代理使用的模型（例如主对话用 Opus 做复杂推理，子代理用 Sonnet 节省成本）：

export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"

子代理支持以下钩子事件，可用于日志记录、操作验证、结果通知等自动化场景：

钩子事件触发时机典型用途 SubagentStart 子代理启动时记录启动日志、初始化环境 SubagentStop 子代理任务完成时记录结果、触发下游任务、发送通知。包含 agent_id 和 agent_transcript_path 字段 PreToolUse 工具调用前校验操作合法性，脚本退出码为 2 时可阻止该工具调用 PostToolUse 工具调用后格式化输出、生成变更记录

高级用法：通过 PreToolUse 钩子动态控制工具行为。例如，让数据库代理只允许执行只读 SQL 查询，任何写操作都被脚本拦截：

如果你不希望 Claude 自动调用某个内置子代理，可以在 .claude/settings.json 中将其加入禁用列表：

Claude 会根据 description 字段自动判断任务是否适合某个子代理，无需在提示中手动指定：

帮我检查最近的代码改动质量

在提示中明确指定要使用哪个代理：

让 code-reviewer 子代理检查最近的改动

将产生大量中间输出的任务（如运行测试、扫描日志）放到子代理中，主对话只接收精简的结论：

使用子代理运行所有测试，只返回失败的测试和根因分析

同时启动多个子代理处理不同模块，大幅缩短分析时间：

并行使用子代理分别分析认证模块、数据库模块和 API 模块，汇总后给出整体架构建议

将复杂工作流拆分为多个专职代理，按顺序传递结果：

先用 code-reviewer 找出问题，再用 optimizer 子代理修复这些问题

串联工作流的设计原则：每个代理只做一件事，并通过清晰的"输入 → 处理 → 输出 → 交接信号"定义接口。以下是一个生产实践中的三段式流水线示例：

pm-spec：读取需求，生成工作规格，确认后标记 READY_FOR_ARCH
architect-review：验证设计约束，产出架构决策记录（ADR），标记 READY_FOR_BUILD
implementer-tester：实现代码和测试，更新文档，标记 DONE

通过 SubagentStop 钩子监听状态文件，自动触发下一个代理，无需手动干预。

同时启动 style-checker、security-scanner、test-coverage 三个子代理并行审查， 将审查时间从数分钟压缩到数十秒

适合用子代理的场景：

任务自包含，可以给出明确的输入和期望输出
 输出量很大，会显著占用主对话上下文
 需要强约束（只读、隔离 worktree 等）
 同类任务会重复出现，值得固化为代理
 涉及多个独立子域，可以并行处理

适合用主对话的场景：

需要频繁来回调整，交互性强
 多阶段任务有强依赖关系，上下文需要连续
 快速、小改动，启动代理的开销不值得
 实际经验：超过 3～4 个子代理后，管理成本可能反而降低整体效率

子代理不能再创建子代理（防止无限嵌套）。如需嵌套逻辑，请使用 Skills。

description 怎么写

用动作式描述：当用户要求审查 / 分析 / 检查代码质量时调用
 说明前置条件：在规格文档确认后使用，产出架构决策记录
 写清楚代理的边界和不擅长的场景，防止被错误调用

工具权限设计（最小权限原则）

只读代理（审查、审计）：Read, Grep, Glob
 研究代理（信息收集）：Read, Grep, Glob, WebFetch, WebSearch
 实现代理（写代码）：Read, Write, Edit, Bash, Glob, Grep

单一职责

每个代理只做一件事，给出清晰的输入 / 输出 / 交接规则
 不要试图用一个代理包办所有事情

系统提示建议

在系统提示中明确代理的性格：请保持批判性，不要只说好话
 指出代理的弱点和局限，避免过度自信
 如果启用了记忆，在系统提示里写入"主动维护记忆"的指令，让代理自动执行

并行 vs 串行的选择

各子域之间相互独立 → 优先并行，节省时间
 下一步依赖上一步的结果 → 必须串行，保证质量
 避免为了并行而并行：10 个并行代理处理简单任务反而浪费 Token 和协调成本

2026年Claude Code 子代理（Subagent）

相关推荐