Claude的专职AI员工—— Subagents详解

你有没有遇到过这样的场景：在 Claude Code 里处理一个稍微复杂的任务，没多久主对话的上下文就被大量的文件搜索结果、测试日志、依赖分析给淹没了，真正有用的内容反而越来越难被 Claude "看见"？

这正是Subagents（子代理）要解决的核心问题。

一、什么是 Subagents？

官方的定义很直接：Subagent 是处理特定类型任务的专职 AI 助手。每个 subagent 在自己独立的 context window 中运行，拥有自定义的 system prompt、特定的工具权限和独立的执行环境。当 Claude 遇到与某个 subagent 描述匹配的任务时，它会将工作委托给该 subagent，后者独立完成后只返回结果摘要。

用一句话概括：Subagents 是 Claude Code 里可以被派出去"跑腿"的专职员工，干完活只汇报结论，不把一路上的"废话"带回主会话。

二、三个内置 Subagents

Claude Code 内置了三个 subagent，清楚地展示了这套设计思想：

Explore：只读、默认跑在 Haiku 上，专门负责搜索和理解代码库，不做任何修改。优化目标是速度和成本。

Plan：在计划模式下收集上下文信息，帮助 Claude 在给出策略前充分理解代码结构，同样是只读工具。

General-purpose：处理需要同时探索和修改的复杂多步骤任务，具备全量工具。

这三个内置 agent 会被 Claude 按需自动调用，不需要你主动指名道姓地呼唤它们。除此之外，Claude Code 还有 claude-code-guide（回答 Claude Code 相关问题时调用）和 statusline-setup 等辅助 agent。

三、如何创建自定义 Subagent

文件格式

每个 subagent 是一个 Markdown 文件，顶部用 YAML 做配置声明，下方的正文即为该 agent 的 system prompt。格式如下：

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 andprovide specific, actionable feedback on quality, security,and best practices.

Subagent 只接收这个 system prompt（加上工作目录等基础环境信息），不会获得完整的 Claude Code 系统提示词。

存储位置与优先级

按优先级从高到低依次是：

组织级 managed settings → --agents CLI 标志 → .claude/agents/（项目级）→ ~/.claude/agents/（用户级）→ 插件 agents/ 目录。同名时高优先级覆盖低优先级。 Claude

最佳实践：团队共用的专职 agent（如代码审查、文档写手）放在 .claude/agents/ 并提交到 git；个人跨项目通用的 agent（如你自己的代码风格守护者）放在 ~/.claude/agents/。

通过 /agents 命令管理

直接在 Claude Code 里运行 /agents 命令，可以打开一个标签式界面，浏览所有可用 subagent（内置、用户级、项目级、插件），并可通过引导流程新建、编辑或删除自定义 subagent。通过 /agents 界面创建的 subagent 无需重启即可生效；直接编辑磁盘上的文件则需要重启 session 才能加载。 Claude

四、关键配置字段解析


字段	说明
`name`	唯一标识符，小写字母+连字符
`description`	Claude 据此决定何时委托任务，写得越精准越关键
`tools`	工具白名单，省略则继承主会话全部工具
`disallowedTools`	工具黑名单，从继承集合中排除
`model`	`sonnet` / `opus` / `haiku` / 完整 model ID / `inherit`
`permissionMode`	权限模式：`default` / `auto` / `bypassPermissions` 等
`maxTurns`	最大执行轮次，防止失控
`memory`	`user/ project / local，开启跨对话持久记忆`
`background`	`true，则始终在后台运行`
`isolation`	`worktree，则在独立 git worktree 中运行，文件互不干扰`

五、三种核心使用模式

1. 隔离高噪音操作

最有效的用法之一是将产生大量输出的操作隔离到 subagent 中。跑测试、抓取文档、处理日志都会大量消耗 context。将这些委托给 subagent，详细输出留在它自己的 context 里，只把相关摘要返回给你的主对话。

2. 并行研究

对于相互独立的调查，可以同时派出多个 subagent 并行工作——例如让三个 subagent 分别研究认证、数据库和 API 模块，最后 Claude 综合所有发现。

3. 链式调用

将 subagent 串联成多步骤工作流——例如先用 code-reviewer subagent 找出性能问题，再用 optimizer subagent 修复它们。

六、何时用 Subagent，何时留在主会话

适合主会话的场景：需要频繁来回迭代的任务；多个阶段（计划→实现→测试）共享大量上下文；快速的点对点修改；对延迟敏感的操作（subagent 需要重新建立上下文）。

适合Subagent的场景：任务会产生你不想污染主 context 的详细输出；需要强制特定工具权限；工作自闭合，能返回摘要。

值得注意的是：Subagent 不能再派生 subagent，嵌套委托需通过 Skills 或在主会话串联 subagent 来实现。

七、实战示例：代码审查专员

以下是一个开箱即用的 code-reviewer subagent 配置（存为 .claude/agents/code-reviewer.md）：

You are a senior code reviewer.

When invoked:

1.Run git diff to see recent changes

2.Focus on modified files

3.Begin review immediately

Review checklist:

-No exposed secrets or API keys

-Input validation implemented

-Proper error handling

-No duplicated code

-Performance considerations

Provide feedback organized by priority:

-Critical issues (must fix)

-Warnings (should fix)

-Suggestions (consider improving)

保存后在对话中输入 Use the code-reviewer subagent to look at my recent changes，Claude 便会自动委托这位专职审查员，干净地把结论带回主对话。

小结

Subagents 本质上是把"无限扩展的单线程幻觉"换成了有边界的专职团队。每个 subagent 工具单一、职责清晰，主会话只看摘要。随着 Claude Code 向 Agent Teams（多 session 协作）方向演进，Subagents 是你现在就能稳定使用的基石能力。

2026 年，大多数开发任务 subagents 就是正确答案——它们稳定、易理解，且隔离模型与工程师对任务拆解的思维方式天然契合。

官方文档：code.claude.com/docs/en/sub-agents
相关话题：Agent View（后台多 session 监控）、Agent Teams（实验性多 session 协作）