子智能体

创建和使用专门的子智能体：内置类型、文件格式与字段、选模型、控制工具和权限、前后台运行及常见模式。

子智能体是处理特定类型任务的专门 AI 助手。当旁支任务会用搜索结果、日志或文件内容淹没主对话时，就用子智能体：它在自己的上下文里完成工作，只返回摘要。当你总在用同样的指令派生同一类工作者时，就定义一个自定义子智能体。

每个子智能体在自己的上下文窗口中运行，有自定义系统提示、特定的工具权限和独立的权限。它发出的请求同样计入和主对话相同的用量限制。当 Claude 遇到与某个子智能体描述相匹配的任务时，就会委派给它。

子智能体帮你：

保留上下文：把探索和实现挡在主对话之外
强制约束：限制子智能体能用的工具
跨项目复用配置：通过用户级子智能体
专门化行为：为特定领域写聚焦的系统提示
控制成本：把任务路由到更快更便宜的模型（如 Haiku）

Claude 根据每个子智能体的 description 决定何时委派，所以要写清楚；描述会占用上下文，保持简短。所有自定义子智能体的描述合计超过 15000 token 时，启动时会警告。

子智能体在单个会话内工作。要并行运行许多独立会话并在一处监控，见智能体视图（agent view）；要让不同会话互相传消息，见跨会话消息；要由 Claude 派生并监督的协同团队，见智能体团队（agent teams）。

内置子智能体

Claude Code 内置一些子智能体，Claude 会在合适时自动使用。它们继承父对话的权限规则，多数用受限的工具集运行。

Explore：快速、只读的智能体，专为搜索和分析代码库优化。模型继承自主对话（在 Claude API 上以 Opus 封顶），工具是只读的（Write 和 Edit 被拒绝）。Claude 调用时会指定彻底程度：quick（定向查找）、medium（均衡探索）或 very thorough（全面分析）
Plan：计划模式下用来先收集上下文再呈现计划的调研智能体，同样只读，让探索输出留在单独的上下文窗口，主对话保持只读
General-purpose：能力全面的智能体，用于需要探索加行动的复杂多步骤任务，拥有子智能体可用的全部工具
其他辅助智能体：claude（不适合更专门智能体时的兜底）、statusline-setup（运行 /statusline 时使用，Sonnet）、claude-code-guide（问到 Claude Code 功能时使用，Haiku）

Explore 和 Plan 会跳过你的 CLAUDE.md 和 git 状态快照，让调研又快又省；其他内置和自定义子智能体两者都会加载（除非定义里设了 omitClaudeMd）。

限制内置子智能体：把某个类型加入 permissions.deny；拒绝 Agent 工具本身可阻止 Claude 委派给任何子智能体；设置 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 只移除内置的 Explore 和 Plan（需要 v2.1.198 或更新版本）。

创建你的第一个子智能体

子智能体是带 YAML 前置信息的 Markdown 文件。可以让 Claude 帮你写，也可以自己写。

Create a personal code-improver subagent in ~/.claude/agents/ 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. Make it read-only and have it use Sonnet.

Claude 会写出带 name、description、tools 列表、model 和系统提示的文件：

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---
You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

文件在 ~/.claude/agents/，所以这个子智能体在本机每个项目中都可用；想限定到单个项目，移到该项目的 .claude/agents/。然后试用：

Use the code-improver agent to suggest improvements in this project

注意：从 v2.1.198 起，/agents 命令不再打开交互式创建向导，而是提醒你让 Claude 创建或直接编辑 .claude/agents/；文件格式、字段和位置不变。

配置子智能体

选择作用范围

多个子智能体同名时，用优先级更高的位置里的那个：

位置	范围	优先级
托管设置	组织范围	1（最高）
`--agents` CLI 标志	当前会话	2
`.claude/agents/`	当前项目	3
`~/.claude/agents/`	你所有的项目	4
插件的 `agents/` 目录	插件启用处	5（最低）

项目子智能体适合特定于代码库的，建议提交进版本控制让团队共同改进；用户子智能体是对所有项目可用的个人子智能体。这两个目录都会被递归扫描，可以分子文件夹（如 agents/review/），子目录路径不影响识别，身份只取决于 name 字段，所以要保证 name 在整棵树里唯一。

CLI 定义的子智能体以 JSON 在启动时传入，只存在于当次会话、不保存到磁盘，适合快速测试或自动化脚本：

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

插件子智能体随已安装的插件自动加载。出于安全原因，插件子智能体不支持 hooks、mcpServers、permissionMode 字段（会被忽略），需要的话把文件复制到 .claude/agents/ 或 ~/.claude/agents/。

子智能体文件格式

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

前置信息定义元数据和配置，正文是引导子智能体行为的系统提示。子智能体只收到这段系统提示加上工作目录等基本环境信息，不会收到 Claude Code 完整的系统提示。Claude Code 会监视 ~/.claude/agents/ 和 .claude/agents/，改动几秒内生效、无需重启（但会话启动时还不存在的 agents 目录、--add-dir 添加的目录，需要重启）。

子智能体在主对话当前的工作目录里启动，其中的 cd 不会在工具调用之间持久，也不影响主对话。想给它一份隔离的仓库副本，设置 isolation: worktree。

前置信息字段

只有 name 和 description 必填。多词字段用驼峰命名（如 maxTurns、disallowedTools），必须与表中完全一致，否则会被忽略而不报错。

字段	说明
`name`	唯一标识，如 `code-reviewer`；不能包含 `:`（保留给插件作用域标识符）
`description`	Claude 何时应委派给它
`tools`	子智能体可用的工具，逗号分隔字符串或 YAML 列表；省略则继承子智能体可用的全部工具
`disallowedTools`	要拒绝的工具，从继承的或指定的列表中移除
`model`	`sonnet`、`opus`、`haiku`、`fable`、完整模型 ID（如 `claude-opus-5-5`）或 `inherit`
`permissionMode`	`default`、`acceptEdits`、`auto`、`dontAsk`、`bypassPermissions`、`plan`，或 `manual`（`default` 的别名）
`maxTurns`	子智能体停止前的最大智能体回合数
`skills`	启动时预加载进子智能体上下文的 Skill（注入全文，而不仅是描述）
`mcpServers`	此子智能体可用的 MCP 服务器：已配置的服务器名，或内联定义
`hooks`	限定在此子智能体的生命周期 Hook
`memory`	持久记忆范围：`user`、`project` 或 `local`，启用跨会话学习
`background`	设为 `true` 让它始终在后台运行
`omitClaudeMd`	设为 `true` 则启动时不带用户、项目和本地 CLAUDE.md
`effort`	此子智能体活动时的努力等级：`low`、`medium`、`high`、`xhigh`、`max`
`isolation`	设为 `worktree` 则在临时 git worktree 里运行，没有改动时自动清理
`color`	在任务列表和转录中的显示颜色
`initialPrompt`	当此智能体作为主会话智能体运行时，自动作为第一轮用户输入提交

选择模型

model 字段控制子智能体用哪个模型。Claude Code 按以下顺序确定：

每次调用时传入的 model 参数
子智能体定义的 model 前置信息（inherit 表示用主对话的模型）
环境变量 CLAUDE_CODE_SUBAGENT_MODEL
主对话的模型

想让所有子智能体都用同一个模型，同时设置两个变量（例如都跑在 Haiku 上）：

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

运行子智能体时用 /tasks 查看它实际用的模型。子智能体还会继承主对话的扩展思考配置。

使用子智能体

自动委派

Claude 根据你请求中的任务描述、子智能体配置里的 description 和当前上下文自动委派。想鼓励主动委派，在 description 里写「use proactively」之类的话。

显式调用

三种方式，从一次性建议升级到会话级默认：

自然语言：在提示里点名，Claude 决定是否委派：Use the test-runner subagent to fix failing tests
@ 提及：保证该子智能体运行。输入 @ 并从提示里选，例如 @"code-reviewer (agent)" look at the auth changes；你的整条消息仍然发给 Claude，@ 提及控制调用哪个子智能体，不控制它收到什么提示
整个会话：用 --agent 标志或 agent 设置，让主线程本身扮演该子智能体，受它的工具限制和模型约束

claude --agent code-reviewer

自定义子智能体的系统提示会完全取代默认的 Claude Code 系统提示；CLAUDE.md 和项目记忆仍然照常加载。要让它成为项目内每个会话的默认，在 .claude/settings.json 里设置 "agent": "code-reviewer"，CLI 标志优先于设置。

前台还是后台

前台子智能体阻塞主对话直到完成，权限提示会传给你
后台子智能体并发运行，你可以继续工作；它需要权限时，提示会出现在主会话里并标明是哪个子智能体在请求

按 Ctrl+B 可以把正在运行的任务转入后台。后台子智能体的结果以完成通知的形式在后面的回合到达 Claude。

常见模式

隔离高输出量操作：运行测试、抓取文档、处理日志会消耗大量上下文，委派给子智能体后冗长的输出留在它的上下文里，只有摘要回来：Use a subagent to run the test suite and report only the failing tests with their error messages
并行调研：对相互独立的调查派生多个子智能体同时工作：Research the authentication, database, and API modules in parallel using separate subagents。当研究路径互不依赖时最有效
串联子智能体：多步骤工作流让 Claude 依次使用，每个完成后返回结果，Claude 再把相关上下文传给下一个：Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

子智能体还是主对话

用主对话：任务需要频繁来回或迭代改进；多个阶段共享大量上下文（规划、实现、测试）；做快速的定向修改；延迟重要（非 fork 的子智能体从头开始，可能要花时间收集上下文）。

用子智能体：任务产生你不需要放在主上下文里的冗长输出；想强制特定的工具限制或权限；工作自成一体、可以返回摘要。

想要在主对话上下文里运行的可复用提示或工作流，考虑用 Skill。对话里已有内容的问题，用 /btw：它能看到你的完整上下文但没有工具访问，回答不加入历史。

子智能体也可以再派生自己的子智能体；同时运行的子智能体数量有上限；还可以 fork 当前对话——fork 以当前对话的副本起步，在交互式会话里默认开启 fork 模式，会在后台运行。这些进阶行为见官方原文。

示例子智能体

官方文档给出了代码评审员、调试员、数据科学家和数据库查询校验器（用 PreToolUse Hook 拦截 SQL 写操作，只放行 SELECT）等完整示例，可参考原文页面中的 Example subagents 一节。

深入阅读

配置子智能体：作用范围与优先级、--agents JSON、文件格式、全部前置信息字段、被跳过的文件、选择模型、工具与权限模式、MCP 范围、预载 Skill、持久记忆、Hook
使用子智能体：自动委派、@ 提及与 --agent、前台与后台、命名、API 错误、输出扫描、常见模式、嵌套与并发上限、上下文与恢复
Fork：继承整个对话的子智能体：/subtask、面板操作、与普通子智能体的区别、fork 模式开关