子代理

Subagent 是 Claude Code 里的专用子代理。它适合处理会产生大量搜索结果、日志、文件内容或中间推理的支线任务:子代理在自己的上下文窗口里工作,最后只把摘要或结果交回主会话。

#适合做什么

如果任务需要你持续来回确认、每一步都依赖主会话历史,通常放在主会话更自然。如果只是复用提示词或工作流,但想继续使用主会话上下文,优先考虑 Skills。

#内置子代理

Claude Code 会在合适时自动使用内置子代理。它们继承主会话权限,但有各自的工具限制。

Explore 和 Plan 为了速度和成本,不会加载 CLAUDE.md 和父会话 git status。其他内置子代理和自定义子代理会加载这些上下文。

限制内置子代理的常见方式:

#创建一个自定义子代理

自定义子代理是一个 Markdown 文件:上方 YAML frontmatter 写配置,正文写系统提示。

---
name: code-reviewer
description: 代码审查专家。写完或修改代码后主动使用,检查质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是资深代码审查员。被调用时先查看相关改动,只做审查和建议,不要编辑文件。
按严重程度输出:必须修复、建议修复、可选优化。每条都给出文件位置、原因和修复方向。

Use the code-reviewer subagent to review my recent changes

Claude Code 会监听 ~/.claude/agents/ 和 .claude/agents/ 的变更。新建或编辑文件后,通常几秒内生效。两个情况需要重启:会话启动时目标 agents 目录还不存在,或启动时用了 --disable-slash-commands。

#作用域和优先级

同名子代理同时存在时,Claude Code 按优先级选择一个定义。

补充规则:

• .claude/agents/ 会从当前工作目录向上扫描;嵌套目录里同名时,离当前目录最近的定义优先。
• .claude/agents/ 和 ~/.claude/agents/ 会递归扫描,但 agent 身份只由 frontmatter 的 name 决定,不是文件名或子目录。
• 同一作用域内不要重复 name;/doctor 可报告部分重复定义问题。
• 插件 agent 的子目录会进入作用域名,例如 my-plugin:review:security。
• 插件 agent 出于安全原因会忽略 hooks、mcpServers、permissionMode。

临时会话也可以用 --agents 传 JSON:

claude --agents '{
  "safe-reviewer": {
    "description": "只读代码审查。修改代码后使用。",
    "prompt": "你是只读代码审查员,输出问题和建议,不要改文件。",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

#Frontmatter 字段

只有 name 和 description 必填。正文是子代理的系统提示。

#模型选择

子代理模型按这个顺序解析:

1. CLAUDE_CODE_SUBAGENT_MODEL
2. 本次调用传入的模型参数
3. agent frontmatter 的 model
4. 主会话模型

model 省略时等同于 inherit。如果组织或 provider 的模型 allowlist 不允许某个值,Claude Code 会跳过该值并回退到继承模型。

#工具和 MCP 限制

tools 是 allowlist,disallowedTools 是 denylist。两者同时出现时,先移除 denylist,再从剩余工具里解析 allowlist。

---
name: safe-researcher
description: 只读研究代理,用于探索代码和日志。
tools: Read, Grep, Glob, Bash
---

---
name: local-only
description: 继承所有工具,但禁止 GitHub MCP。
disallowedTools: mcp__github
---

MCP 工具可以用精确工具名,也可以用 server 级模式:

某些依赖主 UI 或会话状态的工具不会给子代理使用,即使写进 tools 也无效,例如 AskUserQuestion、EnterPlanMode、ScheduleWakeup、WaitForMcpServers。

#子代理专属 MCP

把 MCP server 写进 mcpServers 可以只让这个子代理看到它,避免主会话上下文塞满工具描述。

---
name: browser-tester
description: 用真实浏览器验证页面。
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github
---

内联 MCP 在子代理启动时连接、结束时断开。字符串引用则复用主会话已经配置的同名 server。企业 MCP 策略、--strict-mcp-config、--bare 等限制仍会生效。

#权限和 Hooks

子代理继承主会话权限上下文,也可以用 permissionMode 覆盖。例外是主会话已处于 bypassPermissions、acceptEdits 或 auto 时,父级模式优先。

子代理 frontmatter 里可以写只对它生效的 hooks:

---
name: db-reader
description: 只执行只读数据库查询。
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

项目级 settings.json 也能监听子代理生命周期:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-reader",
        "hooks": [{ "type": "command", "command": "./scripts/setup-db.sh" }]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [{ "type": "command", "command": "./scripts/cleanup-db.sh" }]
      }
    ]
  }
}

#调用方式

--agent 会让主会话本身使用该 agent 的系统提示、工具限制和模型。它不是“启动一个子任务”,而是替换当前会话的默认行为。

#前台、后台和恢复

官方 v2.1.198 起,子代理默认偏向后台运行;当 Claude 需要结果才能继续时会放到前台。

你可以明确要求“后台运行”或“前台运行”,也可以用 Ctrl+B 把运行中的任务转到后台。设置 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 可禁用后台任务能力。

每次调用通常会创建新的子代理实例。要继续旧实例,直接让 Claude resume 它。可恢复的子代理保留完整历史、工具结果和推理上下文。Explore 和 Plan 是一次性内置代理,不会返回可恢复 agent ID;需要继续上下文时用 general-purpose 或自定义 agent。

子代理 transcript 独立保存于主会话之外。主会话 compact 不会清掉它们;清理周期由 cleanupPeriodDays 控制,默认 30 天。

#上下文边界

非 fork 子代理启动时是新的独立上下文,不会看到主会话的完整聊天历史、已经读过的文件或已经调用过的 Skills。它通常会收到:

• 自己的系统提示和 Claude Code 附加的基础环境信息
• Claude 写给它的任务说明
• CLAUDE.md 和 memory 层级,但 Explore / Plan 例外
• 会话开始时的 git status,但 Explore / Plan 例外
• skills 字段预加载的 Skill 全文

需要完整继承主会话上下文时,用 fork。

#Fork 当前会话

/fork 会创建一种特殊子代理:它继承当前会话完整上下文、系统提示、工具、模型和历史,但它的工具调用仍留在子代理 transcript 里,最终只把结果回传。

/fork draft tests for the parser changes so far

Fork 适合“同一上下文下试一个并行方向”,例如让它草拟测试、比较实现方案或继续调查一个分支。它和命名子代理的区别:

CLAUDE_CODE_FORK_SUBAGENT=1 可显式启用 fork 模式,设为 0 可禁用。Fork 不能再 spawn 另一个 fork。

#最佳实践

#官方参考

• Create custom subagents
• Run parallel sessions with worktrees
• Tools reference
• Hooks reference