Claude Code Subagents 是在独立隔离上下文中运行的自主执行单元，通过 .claude/agents/<name>.md 文件中的 YAML frontmatter 配置 16 个字段来控制其行为。本文系统整理所有配置字段的含义与用法，并结合官方实战案例帮助你快速上手。

Claude Code Subagents 完全指南：16 个 frontmatter 字段与 5 个官方 Agent

什么是 Subagent

Subagent 是 Claude Code 的自主执行单元，运行在独立的上下文窗口中，拥有自己完整的工具集、CLAUDE.md、MCP 服务器和技能。与在主会话内执行的 Command 和 Skill 不同，Subagent 的执行过程不污染主上下文，只有最终结果会返回给调用者。

适合用 Subagent 的场景：

• 任务需要多步自主探索、决策和执行
• 不希望中间工具调用（大量文件读取、grep、死胡同）污染主会话
• 需要使用不同的权限模式或工具集
• 任务可在后台或 git worktree 中并行执行

16 个 Frontmatter 字段

Subagent 配置文件位于 .claude/agents/<name>.md，YAML frontmatter 支持以下字段：

字段	类型	必填	说明
name	string	是	唯一标识符，使用小写字母和连字符
description	string	是	触发时机描述。写 "PROACTIVELY" 可让 Claude 自动调用
tools	string/list	否	允许使用的工具白名单（如 Read, Write, Edit, Bash）。省略则继承全部工具。支持 Agent(agent_type) 语法限制可生成的子代理类型
disallowedTools	string/list	否	禁止使用的工具，从继承或指定的工具集中移除
model	string	否	使用的模型：sonnet、opus、haiku、完整 model ID，或 inherit（默认）
permissionMode	string	否	权限模式：default、acceptEdits、auto、dontAsk、bypassPermissions、plan
maxTurns	integer	否	最大 agentic turn 数，超过后 subagent 停止
skills	list	否	启动时预加载的 skill 名称列表（完整内容注入，而非仅声明可用）
mcpServers	list	否	此 subagent 专用的 MCP 服务器，支持服务器名称字符串或内联 {name: config} 对象
hooks	object	否	仅作用于此 subagent 的生命周期钩子，支持所有 hook 事件
memory	string	否	持久记忆范围：user（跨项目）、project（提交到 git 共享）、local（仅本地不共享）
background	boolean	否	设为 true 则始终作为后台任务运行，默认 false
effort	string	否	此 subagent 激活时的思考深度：low、medium、high、max（仅 Opus 4.6+）
isolation	string	否	设为 "worktree" 则在临时 git worktree 中运行（无变更则自动清理）
initialPrompt	string	否	作为主 session agent 运行时（--agent 或 agent 设置）自动提交的第一条用户消息
color	string	否	在任务列表和记录中显示的颜色：red/blue/green/yellow/purple/orange/pink/cyan

高级字段详解

isolation: "worktree"：在一个隔离的临时 git worktree 中执行任务，适合并行开发或实验性变更。如果 subagent 没有修改任何文件，worktree 会自动清理；否则返回 worktree 路径和分支名。

context: fork（在 Skill/Command 中适用）与 isolation: "worktree" 不同，context: fork 是 skill 和 command 的字段，让它们在隔离的 subagent 上下文中运行。

skills 预加载：与 Skill tool 即时调用不同，skills 字段在 agent 启动时就把 SKILL.md 的完整内容注入上下文，相当于给 agent 预装了"领域知识"，适合 agent 在整个执行过程中都需要参考的技能。

memory 持久记忆：v2.1.33 引入的能力，让 agent 在 session 间积累知识。存储位置：

• user → ~/.claude/agent-memory/<agent-name>/（推荐默认）
• project → .claude/agent-memory/<agent-name>/（团队共享，提交到 git）
• local → .claude/agent-memory-local/<agent-name>/（本地私有）

5 个官方内置 Agent

#	Agent	模型	工具	用途
1	general-purpose	inherit	全部	通用多步任务，默认 agent 类型
2	Explore	haiku	只读（无 Write、Edit）	快速代码库搜索与探索
3	Plan	inherit	只读（无 Write、Edit）	Plan mode 下的预研，设计实现方案
4	statusline-setup	sonnet	Read, Edit	配置 Claude Code 状态栏
5	claude-code-guide	haiku	Glob, Grep, Read, WebFetch, WebSearch	回答 Claude Code 功能、Agent SDK 和 Claude API 问题

实战案例：Weather Agent

以下是仓库中的 weather-agent 配置示例，演示了 Command → Agent → Skill 编排模式中 Agent 的角色：

---
name: weather-agent
description: Use this agent PROACTIVELY when you need to fetch weather data for
  Dubai, UAE. This agent fetches real-time temperature from Open-Meteo
  using its preloaded weather-fetcher skill.
tools: WebFetch, Read, Write, Edit
model: sonnet
color: green
maxTurns: 5
permissionMode: acceptEdits
memory: project
skills:
  - weather-fetcher
---

# Weather Agent

你是一个专门获取迪拜天气数据的代理。
执行时遵循预加载的 weather-fetcher skill 指令，
返回温度值和单位，并更新 agent memory 记录历史数据。

关键设计决策：

• tools 限制为 4 个，最小化权限
• permissionMode: acceptEdits 自动接受文件编辑，无需每次确认
• skills: [weather-fetcher] 预加载领域知识
• memory: project 跨 session 共享天气历史记录

如何创建 Subagent

# 方式 1：通过 /agents 命令交互式创建
claude
/agents

# 方式 2：直接让 Claude 帮你生成
claude
> 帮我创建一个代码审查 agent，限制只能读文件，模型用 sonnet

Claude 会在 .claude/agents/<name>.md 中生成带 frontmatter 和正文的配置文件。

FAQ

Q: Subagent 和直接用 Claude 有什么区别？ A: Subagent 在完全独立的上下文窗口中运行，中间的文件读取、搜索、死胡同等操作不会出现在你的主会话里。你只会看到最终结果，主会话的上下文保持干净。

Q: description 写什么才能让 Claude 自动调用？ A: 在 description 中描述触发场景，并加上 "PROACTIVELY" 关键字。例如："Use this agent PROACTIVELY when reviewing code changes"。Claude 会在对话中语义匹配并自动调用。

Q: 一个 Subagent 最多能运行多久？ A: 通过 maxTurns 控制，没有设置时默认没有硬限制，但会受到 session 级别的限制。对于需要长时间运行的任务，可以结合 background: true 或 /loop 使用。

Q: 同时运行多个 Subagent 会互相干扰吗？ A: 不会。每个 Subagent 都有独立的上下文窗口。如果需要并行操作同一代码库，可以配合 isolation: "worktree" 给每个 agent 独立的工作分支。