配置 Subagents

Subagent 的价值不是“多开一个 AI”，而是把会污染主会话的大量搜索、日志、文件阅读和专项判断，隔离到另一个上下文里，最后只把结论带回来。——翔宇

1. Subagent 解决什么问题

Subagent 是 Claude Code 里的专门 AI assistant。它有自己的上下文窗口、系统提示词、工具访问和权限设置。

适合用 Subagent：

• 读很多文件，但主会话只需要摘要。
• 搜索大量日志、测试输出、文档或代码。
• 并行验证多个独立假设。
• 让一个专门 worker 做安全审查、性能审查、测试审查。
• 用更快或更便宜的模型处理低风险探索。
• 给某类任务固定工具边界，例如只读 reviewer。

不适合用 Subagent：

• 单文件小修改。
• 需要你频繁来回确认的任务。
• 多阶段共享大量上下文的主线实现。
• 需要 subagent 再继续 spawn subagent 的嵌套流程。
• 只是想“看起来更自动化”的简单任务。

flowchart TD
    Task["当前任务"]
    Verbose["会产生大量中间信息？"]
    NeedSummary["主会话只需要结论？"]
    Independent["子任务能独立完成？"]
    NeedsChat["需要频繁来回确认？"]
    UseSubagent["用 Subagent"]
    Main["留在主会话"]

    Task --> Verbose
    Verbose -->|否| Main
    Verbose -->|是| NeedSummary
    NeedSummary -->|否| Main
    NeedSummary -->|是| Independent
    Independent -->|否| Main
    Independent -->|是| NeedsChat
    NeedsChat -->|是| Main
    NeedsChat -->|否| UseSubagent

    style UseSubagent fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style Main fill:#e0f2fe,stroke:#0284c7,stroke-width:2px

2. 内置 Subagents

Claude Code 自带几个常用 Subagents。大多数时候你不需要手动配置它们，Claude 会自动判断。

Explore：

• 快速、只读。
• 官方定位是文件发现、代码搜索、代码库探索。
• 模型偏快，适合低延迟探索。
• 不能写文件、不能编辑文件。

Plan：

• plan mode 里使用。
• 用于正式给方案前收集代码库上下文。
• 只读，避免计划阶段误修改。
• 防止 plan mode 中出现无限嵌套。

General-purpose：

• 能处理复杂多步任务。
• 可以探索，也可以修改。
• 使用主会话模型。
• 适合需要探索和行动结合的任务。

其他 helper agents：

• statusline-setup：配置状态栏时使用。
• claude-code-guide：回答 Claude Code 功能问题时使用。

3. Subagent 和 Skill 怎么区分

Skill 和 Subagent 经常一起出现，但职责不同。

Skill：

• 是可复用知识或流程。
• 默认在主会话上下文里运行。
• 可以由 /skill-name 调用。
• 适合 checklist、参考资料、发布流程。

Subagent：

• 是一个独立 worker。
• 有自己的上下文窗口。
• 最后把摘要返回主会话。
• 适合大量搜索、专项审查、隔离探索。

组合方式：

• Skill 通过 context: fork 启动 subagent。
• Subagent 通过 skills 字段预加载指定 Skills。

4. Subagent 和 Agent team 怎么区分

Subagent 运行在单个 Claude Code session 内，由主会话管理，只把结果回报给主会话。

Agent team 是多个独立 Claude Code sessions 组成的团队。一个 lead 负责协调，teammates 各自有独立上下文，并且可以互相通信。

Subagent 适合：

• 结果比过程重要。
• worker 不需要互相交流。
• 子任务聚焦、短期、自包含。
• 你想降低主会话上下文污染。

Agent team 适合：

• 多个 worker 需要互相挑战、共享发现、协调任务。
• 大功能拆分。
• 多假设调试。
• 前后端测试等跨层并行。

官方说明 Agent teams 目前仍是 experimental，需要显式开启，并且 token、协调和冲突成本更高。

5. 创建入口：优先用 /agents

官方推荐入口：

/agents

这个界面可以：

• 查看内置、user、project、plugin subagents。
• 创建新 subagent。
• 用 Claude 生成配置。
• 编辑 tool access。
• 删除自定义 subagent。
• 看同名定义里哪个当前生效。
• 在 Running tab 查看正在运行的 subagents。

命令行只列出配置：

claude agents

手动写文件也可以，但直接改磁盘上的 subagent 文件后，要重启会话才会加载。通过 /agents 创建或编辑通常会立即生效。

6. Subagent 文件放哪里

Subagent 是 Markdown 文件，带 YAML frontmatter。

常见路径：

• Managed：组织级下发，优先级最高。
• CLI --agents：只在当前启动会话生效。
• Project：.claude/agents/<agent-name>.md，当前项目可用，可提交。
• User：~/.claude/agents/<agent-name>.md，所有项目可用。
• Plugin：<plugin>/agents/<agent-name>.md，插件启用时可用。

优先级从高到低：

1. Managed settings
2. --agents CLI flag
3. Project .claude/agents/
4. User ~/.claude/agents/
5. Plugin agents

注意：

• Project subagents 会从当前工作目录往上发现。
• --add-dir 只给文件访问，不会扫描里面的 subagents。
• Plugin subagents 会出现在 /agents，但有安全限制。

7. 最小文件格式

一个基本 subagent：

---
name: code-reviewer
description: Reviews code for quality, security, maintainability, and missing tests. Use after code changes.
tools: Read, Glob, Grep, Bash
model: inherit
---

You are a senior code reviewer.

When invoked:

1. Inspect the recent changes.
2. Focus on modified files.
3. Identify correctness, security, maintainability, and test risks.
4. Return findings ordered by severity.

Output:

- Critical issues
- Warnings
- Suggestions
- Tests to run

Frontmatter 是配置。正文是 subagent 的 system prompt。

官方提醒：Subagent 不会继承完整 Claude Code system prompt。它收到的是自己的 system prompt，加上基础环境信息，例如 working directory。CLAUDE.md 和项目 memory 会按正常消息流加载。

8. Frontmatter 字段速览

常用字段：

• name：唯一标识，必填，小写字母和连字符。
• description：Claude 判断何时委派的依据，必填。
• tools：允许使用的工具列表。省略时继承主会话全部工具。
• disallowedTools：从继承或指定工具中移除。
• model：使用 sonnet、opus、haiku、完整 model ID 或 inherit。
• permissionMode：权限模式，例如 default、auto、plan。
• maxTurns：最多 agentic turns。
• skills：启动时预加载的 Skills。
• mcpServers：只给这个 subagent 的 MCP server。
• hooks：只在这个 subagent 生命周期内运行的 hooks。
• memory：持久记忆 scope，支持 user、project、local。
• background：设为 true 时默认后台运行。
• effort：该 subagent 的 reasoning effort。
• isolation：设为 worktree 时使用临时 git worktree。
• color：UI 中显示颜色。
• initialPrompt：当它作为 main session agent 运行时自动提交的第一条用户消息。

9. description 决定自动委派

Claude 会根据任务描述、当前上下文和 subagent 的 description 决定是否自动委派。

弱描述：

description: Helps with code.

强描述：

description: Reviews recently changed code for security issues, missing tests, risky migrations, and unclear error handling. Use proactively after code edits.

写法原则：

• 写任务类型。
• 写触发场景。
• 写不负责什么。
• 放关键词在前面。
• 如果希望主动使用，写清 Use proactively。

10. 模型选择和优先级

model 字段可以设置：

• haiku：快速、便宜，适合只读探索。
• sonnet：平衡质量和速度，适合 review、调试、专项分析。
• opus：更强推理，适合复杂架构判断。
• 完整 model ID：精确指定。
• inherit：继承主会话。

官方模型解析优先级：

1. CLAUDE_CODE_SUBAGENT_MODEL 环境变量。
2. 某次 invocation 传入的 model。
3. subagent 文件里的 model。
4. 主会话模型。

11. 工具边界：tools 和 disallowedTools

默认情况下，subagent 继承主会话所有工具，包括 MCP tools。

如果你想做只读 reviewer，用 tools allowlist：

tools: Read, Grep, Glob, Bash

这样它不能 Edit、Write，也不能使用没有列出的 MCP tools。

如果你想继承大部分能力，只禁文件写入，用 disallowedTools：

disallowedTools: Write, Edit

边界：

• tools 是允许列表。
• disallowedTools 是拒绝列表。
• 如果两者都写，先应用 disallowedTools，再按 tools 解析。
• 同时出现在两边的工具会被移除。

12. 限制能 spawn 哪些 Subagents

当某个 agent 作为主线程运行时，比如：

claude --agent coordinator

它可能通过 Agent tool 再 spawn subagents。可以用 Agent(agent_type) 限制：

tools: Agent(worker, researcher), Read, Bash

这表示只能 spawn worker 和 researcher。

如果写：

tools: Agent, Read, Bash

表示可以 spawn 任意 subagent。

官方说明：v2.1.63 起 Task tool 重命名为 Agent，旧的 Task(...) 引用仍作为 alias 可用。

13. MCP 限域：只给某个 Subagent

mcpServers 可以让某个 subagent 拥有专属 MCP。

例子：

name: browser-tester
description: Tests UI behavior in a real browser.
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  - github

含义：

• playwright 是 inline MCP，只在这个 subagent 启动时连接，结束时断开。
• github 是引用父会话已有 MCP server。

如果你不想让主会话加载某个 MCP tool description，就把它定义为 subagent inline MCP，而不是放在 .mcp.json。

14. 权限模式：permissionMode

Subagent 可以设置 permissionMode：

• default：标准权限检查。
• acceptEdits：自动接受工作目录和 additional directories 内的编辑及常见文件系统命令。
• auto：使用 auto mode 分类器。
• dontAsk：自动拒绝需要确认的权限请求。
• bypassPermissions：跳过权限提示。
• plan：只读计划模式。

重要边界：

• 父会话如果是 bypassPermissions 或 acceptEdits，会优先生效，subagent 不能覆盖。
• 父会话如果是 auto，subagent 会继承 auto mode，frontmatter 里的 permissionMode 会被忽略。
• bypassPermissions 风险很高，会跳过大多数权限提示；根目录和 home 目录删除仍会触发 circuit breaker。

15. 预加载 Skills

Subagent 不会自动继承主会话调用过的 Skills。要在 subagent 启动时加载某些 Skills，用 skills：

name: api-developer
description: Implements API endpoints following team conventions.
skills:
  - api-conventions
  - error-handling-patterns

注意：

• 加载的是 Skill 全文，不只是 description。
• 这些内容在 subagent 启动时进入它的上下文。
• 不能预加载 disable-model-invocation: true 的 Skills。
• 缺失或禁用的 Skill 会被跳过并写入 debug log。

这和 Skill 里的 context: fork 是反方向：

• Subagent 的 skills：以 subagent 为主，Skill 是参考资料。
• Skill 的 context: fork：以 Skill 为主，把任务交给 subagent。

16. Persistent memory

Subagent 可以有自己的持久记忆：

memory: project

三种 scope：

• user：~/.claude/agent-memory/<agent-name>/，跨项目复用。
• project：.claude/agent-memory/<agent-name>/，项目共享，可提交。
• local：.claude/agent-memory-local/<agent-name>/，项目本地，不提交。

启用 memory 后：

• Subagent system prompt 会包含读写 memory 的说明。
• 会加载 memory 目录里 MEMORY.md 的前 200 行或 25KB，取较小值。
• Read、Write、Edit 会自动启用，让 subagent 管理 memory 文件。

官方建议 project 是常用默认，因为项目知识可以团队共享。user 适合跨项目通用经验，local 适合个人本机经验。

17. Hooks：给 Subagent 加动态规则

如果 tools 太粗，无法表达“只允许 SELECT，不允许 UPDATE”，就用 hooks。

典型场景：

• PreToolUse 校验 Bash 命令。
• PostToolUse 编辑后运行 linter。
• Stop 收尾。
• 主会话里的 SubagentStart 和 SubagentStop 监听某类 subagent。

Subagent frontmatter 里的 hooks 只在该 subagent 生命周期内生效，结束后清理。

Project settings 里的 SubagentStart / SubagentStop 则在主会话监听 subagent 生命周期。

18. 显式调用 Subagent

有三种层级。

自然语言：

Use the code-reviewer subagent to review the auth changes.

这种方式通常能触发，但最终仍由 Claude 判断。

@ mention：

@agent-code-reviewer look at the auth changes

这会保证指定 subagent 运行。你也可以从 typeahead 里选择，plugin subagent 会显示为 <plugin-name>:<agent-name>。

整场会话使用某个 agent：

claude --agent code-reviewer

也可以在项目设置里设默认：

{
  "agent": "code-reviewer"
}

此时 subagent 的 system prompt 会替代默认 Claude Code system prompt；CLAUDE.md 和 project memory 仍按正常消息流加载。

19. 前台和后台运行

Subagent 可以前台运行，也可以后台运行。

前台：

• 主会话等待 subagent 完成。
• 权限提示和澄清问题会传给你。
• 适合需要互动、权限不确定、风险较高的任务。

后台：

• 你可以继续在主会话工作。
• 启动前会预先请求该 subagent 需要的工具权限。
• 运行后继承这些权限。
• 未预批准的权限请求会自动拒绝。
• 澄清问题会失败，但 subagent 会继续。

你可以要求后台：

Run this in the background.

也可以用 Ctrl+B 把正在运行的任务放到后台。

关闭后台任务功能：

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 claude

20. Worktree isolation

如果 subagent 可能改文件，而你不想它直接写当前 checkout，可以设置：

isolation: worktree

效果：

• Subagent 在临时 git worktree 里工作。
• 文件修改不会直接落到当前 checkout。
• 如果 subagent 没有改动，worktree 会自动清理。
• 如果有改动，你需要后续检查和整合。

适合：

• 并行实现不同方案。
• 高风险重构。
• 让 worker 试验修复。
• 不希望污染主工作区的验证。

21. Resume 和 transcript

每次 subagent 调用默认是新实例、新上下文。

如果要继续已有 subagent 的工作，可以让 Claude resume 它。官方说明 resumed subagent 会保留完整会话历史，包括工具调用、结果和 reasoning。

限制：

• Resume 依赖 SendMessage。
• SendMessage 目前只在 Agent teams 开启时可用。
• Subagent transcript 存在主项目 session 目录下的 subagents/。
• transcript 会按 cleanupPeriodDays 清理，默认 30 天。

Subagent compaction：

• 和主会话类似。
• 默认接近 95% 容量时自动压缩。
• 可用 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 调整触发比例。

22. Forked subagents

Forked subagents 是实验能力，官方要求 Claude Code v2.1.117 或更高，并通过环境变量开启：

CLAUDE_CODE_FORK_SUBAGENT=1 claude

Fork 与 named subagent 不同：

• Fork 继承当前主会话完整历史。
• Named subagent 从自己的定义和任务 prompt 开始。
• Fork 的工具调用仍留在 fork 里，最终结果回到主会话。
• Fork 可以复用主会话 prompt cache。
• 开启 fork mode 后，/fork 会创建 fork，而不是作为 /branch alias。

适合：

• 子任务需要完整上下文，重新解释成本太高。
• 想从当前状态并行尝试几个方向。
• 草拟测试、替代方案、review 观点。

不适合：

• 你想保持输入隔离。
• 你需要专门工具边界和 system prompt。
• 你不想使用实验功能。

23. 常见使用模式

隔离高输出任务：

Use a subagent to run the test suite and report only failing tests with key error messages.

并行研究：

Research the authentication, database, and API modules in parallel using separate subagents.

串联 worker：

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to propose fixes.

只读审查：

Use the code-reviewer agent to review recent changes. Do not edit files.

24. 什么时候留在主会话

留在主会话：

• 需要频繁来回确认。
• 多个阶段共享大量上下文。
• 你正在做小而精确的修改。
• 延迟很重要。
• 子任务结果会立即改变下一步。

用 Subagent：

• 输出很长，但最后只需要摘要。
• 需要强工具限制。
• 子任务自包含。
• 要并行研究。
• 主会话上下文已经很重。

用 Skill：

• 你要复用的是提示词、流程或参考资料。
• 任务仍然适合在主会话里执行。

用 /btw：

• 只是问一个依赖当前上下文的小问题。
• 不需要工具。
• 不想把回答加入历史。

25. 一个好 Subagent 的写法

好的 subagent 文件应该说明：

• 何时使用。
• 何时不要使用。
• 负责范围。
• 禁止事项。
• 工具边界。
• 输出格式。
• 是否可以修改文件。
• 是否可以调用外部系统。
• 如何处理不确定性。

示例结构：

---
name: security-reviewer
description: Reviews authentication, authorization, token handling, input validation, and secret exposure risks. Use after security-sensitive code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 12
---

You are a security reviewer.

Scope:

- Review only the files relevant to the requested change.
- Prefer evidence from code over speculation.
- Do not edit files.

Output:

- Critical findings
- Warnings
- Evidence with file paths
- Suggested tests
- Residual risk

26. 常见故障：没被自动使用

排查顺序：

1. 运行 /agents 看 subagent 是否存在。
2. 确认直接改文件后是否重启了会话。
3. 检查 description 是否包含自然语言触发词。
4. 用 @agent-name 强制调用测试。
5. 检查是否被更高优先级同名 subagent 覆盖。
6. 检查是否被 permissions deny：Agent(name)。
7. 检查 plugin subagent 是否使用了不支持字段。

27. 常见故障：权限提示太多

原因：

• Subagent 工具范围太宽。
• 后台 subagent 没有预批准需要的工具。
• MCP tool 没有写 permissions allow。
• Teammate / subagent 在多个文件上反复触发确认。

修法：

• 用 tools 缩小能力范围。
• 给常用只读工具预批准。
• 把高风险工具保留 ask。
• 对后台任务提前说明需要什么工具。
• 对 Agent teams，在 spawn 前先补 permissions。

28. 常见故障：结果不可用

常见原因：

• 任务范围太大。
• 输出格式没定义。
• Subagent 没拿到必要背景。
• 工具太少，无法完成任务。
• 背景任务缺权限，中途自动拒绝。
• 并行 subagents 返回了太多细节，反而污染主会话。

改法：

• 让子任务更小。
• 明确输出格式。
• 在 prompt 里给必要上下文。
• 只返回 findings，不返回完整过程。
• 高风险或需要交互的任务改前台。
• 必要时用 worktree 隔离实现任务。

29. 自检清单

学完这一章，你应该能做到：

• 我能解释 Subagent 解决的是上下文隔离。
• 我知道 Explore、Plan、general-purpose 的差别。
• 我知道什么时候该写自定义 subagent。
• 我知道 subagent 文件位置和 scope 优先级。
• 我能写出一个最小 .claude/agents/<name>.md。
• 我知道 tools 和 disallowedTools 的区别。
• 我知道 mcpServers 可以把 MCP 只给某个 subagent。
• 我知道 permissionMode 会受到父会话模式影响。
• 我知道 Subagent 不会自动继承主会话 Skills。
• 我知道 memory 会自动启用读写工具。
• 我知道后台 subagent 会预批准权限并自动拒绝未批准请求。
• 我知道 isolation: worktree 的用途和边界。
• 我知道 forked subagent 与 named subagent 的差别。
• 我知道 Subagent 和 Agent team 的边界。

30. 术语速查

• Subagent：在隔离上下文里执行子任务的专门 assistant。
• Explore：内置只读探索 subagent。
• Plan：plan mode 中用于上下文研究的只读 subagent。
• general-purpose：内置通用复杂任务 subagent。
• /agents：创建、编辑、查看 subagents 的交互入口。
• tools：subagent 可使用工具 allowlist。
• disallowedTools：从可用工具中移除的 denylist。
• permissionMode：subagent 的权限模式。
• mcpServers：只给该 subagent 的 MCP server 配置。
• skills：启动时预加载进 subagent 上下文的 Skills。
• memory：subagent 的持久记忆目录。
• background：让 subagent 默认后台运行。
• isolation: worktree：让 subagent 在临时 git worktree 中工作。
• Agent(agent_type)：限制主线程 agent 可 spawn 哪些 subagents 的工具语法。
• @agent-name：显式调用某个 subagent。
• forked subagent：继承完整主会话历史的实验性 subagent。
• Agent team：多个独立 Claude Code sessions 组成的协作团队。

31. 官方资料

• Create custom subagents
• Orchestrate teams of Claude Code sessions
• Extend Claude Code
• Extend Claude with skills
• Configure permissions
• Automate workflows with hooks