Claude Code Subagents 指南
系统讲解 Claude Code subagents 的使用场景、创建方式、工具权限、上下文隔离、后台任务、memory、hooks 和团队落地方法。
Claude Code subagents 是带有专门角色的工作代理。它们可以在独立上下文里完成一段聚焦任务，然后把摘要结果返回主会话。最适合的场景不是“把所有事都拆给代理”，而是把会污染主线程的大量搜索结果、日志、测试输出、文件探索或审查清单隔离出去。
最后核查：2026 年 5 月 24 日。Claude Code 现在支持内置 subagents、自定义 user/project subagents、plugin agents、CLI 临时 agents、前台/后台运行、
--agent会话级模式、subagent memory、工具限制、hooks，以及实验性的 forked subagents。Subagents 应该被当成工作流组件，而不是把任务无限拆碎的理由。
快速结论
当任务足够独立、可以用清晰提示词交给一个角色处理，并且只需要返回精简结果时，就适合用 subagent。典型例子包括代码审查、测试失败分析、日志排查、文档资料研究、安全检查、多个模块并行调研。需要频繁来回沟通、规划和实现共享大量上下文、或只是快速改一个点时，继续用主会话更合适。
最关键的一点：普通 subagent 会从新的上下文开始。它不会自动看到主会话历史、之前的工具结果、或主会话已经读过的文件。如果 subagent 需要路径、报错、结论、约束或背景，你必须在委派提示词或 agent 定义里明确写出来。
Subagents 和其它机制的区别
Subagents 解决的是上下文隔离和角色专门化，不是所有自定义能力的替代品。
| 需求 | 更适合的机制 |
|---|---|
| 把大量研究、日志或测试输出隔离出主线程 | Subagent |
| 复用一个带独立提示词和工具限制的角色 | Custom subagent |
| 并行做多个独立调研 | Subagents 或 agent view |
| 复用仍运行在主上下文里的提示词 | Skill 或 slash command |
| 保存项目级长期说明 | CLAUDE.md 或 project rules |
| 在工具执行前做权限约束 | Permission rules 和 hooks |
| 协调多个带共享任务状态的 worker | Agent teams |
| 避免多个编码会话改同一批文件 | Worktrees |
如果只是一个短提示词，用 skill 或 slash command。只有当你需要一个独立角色、独立上下文、工具限制和模型选择时，才创建 subagent。
内置、自定义、插件和 CLI Agents
Claude Code 可以加载多种来源的 agents。
| Agent 类型 | 来源 | 适合场景 |
|---|---|---|
| Built-in agents | Claude Code 内置 | Explore、Plan、general-purpose 这类无需配置的委派。 |
| User subagents | ~/.claude/agents/ | 你个人跨项目复用的 agents。 |
| Project subagents | .claude/agents/ | 某个仓库团队共享的 agents。 |
| Plugin agents | 插件的 agents/ 目录 | 被插件分发的工作流集成。 |
| CLI-defined agents | claude --agents ... | 测试、脚本或自动化里的临时 agents。 |
| Managed agents | 组织托管配置 | 企业级受控 agents 和策略。 |
团队仓库建议先在个人目录或 /agents 里验证，等流程稳定后再放到 .claude/agents/ 并提交版本控制。
创建和管理 Agents
推荐入口是 /agents 命令。它会打开 agents 管理界面，可以查看 built-in、user、project、plugin agents，创建新 agent，编辑工具权限，删除自定义 agent，并在重名时查看哪个 agent 生效。
手动创建也很简单。项目 agent 放到 .claude/agents/：
---
name: code-reviewer
description: Review recent changes for correctness, security, maintainability, and test coverage. Use proactively after code edits.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. Review the current diff first, then inspect only the files needed to verify the change.
Report findings by severity:
1. Blocking bugs or security risks.
2. Regressions or missing tests.
3. Maintainability suggestions.
Do not edit files. Return file paths, line references, and concrete fixes.直接写到磁盘的 subagent 文件会在会话启动时加载。如果 Claude Code 已经运行，再手动新增或修改文件，需要重启会话才会加载。通过 /agents 创建的 agent 会立即可用。
重要 Frontmatter 字段
每个 subagent 都需要清晰的身份和委派描述。可以把 description 理解成 Claude 用来判断是否委派的搜索意图。
| 字段 | 是否必需 | 实战建议 |
|---|---|---|
name | 是 | 用小写和短横线，例如 code-reviewer。 |
description | 是 | 写清什么时候应该委派。只有确实该主动运行时才写 "use proactively"。 |
Markdown body 或 prompt | 是 | agent 的系统提示词。明确流程、输出格式和边界。 |
tools | 否 | 不写则继承工具；也可以收窄成 Read, Grep, Glob。 |
disallowedTools | 否 | 从继承工具里移除高风险工具。 |
model | 否 | 这个角色需要不同模型时再设置。 |
permissionMode | 否 | 可用于窄范围本地流程，但不要拿它绕过上层策略。 |
mcpServers | 否 | 只给 agent 必要的 MCP 访问。 |
hooks | 否 | 只在这个 agent 活跃期间运行生命周期检查。 |
skills | 否 | agent 启动时预加载 skill 内容。 |
memory | 否 | 让 agent 拥有 user、project 或 local 范围的持久记忆。 |
background | 否 | 提示这个 agent 是否适合并发运行。 |
color | 否 | 用于 UI 识别，多个 agent 同时运行时有帮助。 |
name 要保持唯一。如果同一个范围里两个文件声明同名 agent，Claude Code 可能只保留其中一个，而且不一定给出足够清楚的提醒。
如何调用 Subagent
常见有三种方式。
自然语言调用
在提示词里点名 agent，让 Claude 判断是否委派：
Use the test-runner subagent to run the failing test suite and report only the failing cases.这是最轻的方式，适合 agent description 已经足够清晰的情况。
Agent Mention
当你希望某个具体 agent 一定参与这一次任务时，用 agent mention。完整请求仍然先进入主会话，但 mention 会控制 Claude 调用哪个 agent。
@"code-reviewer (agent)" review the auth changes in the current diff.插件提供的 agents 可能有带命名空间的 scoped name。
会话级 Agent
当整个会话都应该以某个 agent 的角色运行时，用 --agent：
claude --agent code-reviewer也可以在 .claude/settings.json 里设项目默认 agent：
{
"agent": "code-reviewer"
}会话级 agent 要谨慎使用。这个模式下，agent 的系统提示词会替换默认 Claude Code 系统提示词，而正常 memory 仍然按流程加载。它适合明确模式，不适合临时小任务。
前台和后台 Subagents
Subagents 可以前台运行，也可以后台运行。
| 模式 | 行为 | 适合场景 |
|---|---|---|
| Foreground | 主会话等待 agent 完成，权限请求会传给你。 | 需要交互审批的审查或修复。 |
| Background | 你可以继续工作；需要新权限的工具调用会被自动拒绝。 | 长时间只读研究、日志、文档查询、测试分析。 |
你可以让 Claude "run this in the background"，也可以按 Ctrl+B 把正在运行的任务转到后台。如果不希望启用后台任务，可以设置 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1。
后台并不等于免费加速。多个 agents 同时运行会增加 token 消耗，如果它们改同一批文件，还会互相冲突。可能重叠的任务优先使用只读工具或 worktree 隔离。
Subagent 能看到什么
普通 subagent 会从新上下文启动。它能看到 agent prompt、Claude 生成的委派任务消息、基础环境信息，以及配置加载的项目 memory。它不会继承完整主会话历史或主会话工具结果。
| 上下文内容 | 普通 subagent 行为 |
|---|---|
| 主会话历史 | 不包含。 |
| 主会话已经读过的文件 | 不包含。 |
| Agent 系统提示词 | 来自 agent 定义。 |
| 委派任务消息 | Claude 根据你的请求生成。 |
CLAUDE.md 和 memory | 大多数自定义 agents 会加载；内置 Explore 和 Plan 会跳过部分 memory 和 git context。 |
| Git status | 可用时加载，除非配置禁用。 |
| 预加载 skills | 只有写在 skills 字段里才会加载。 |
| 工具结果 | 只包含 subagent 自己产生的结果。 |
所以委派提示词一定要具体。不要说“审查刚才讨论的那个东西”。更好的写法是：“review the current diff for src/auth/session.ts and src/auth/callback.ts; focus on token refresh, redirect handling, and missing tests.”
工具权限和安全
默认收窄工具权限。代码审查 agent 通常只需要 Read、Grep、Glob，最多加 Bash 用于 git diff 或测试。它一般不需要 Edit 或 Write。Debug agent 可以有 Edit，但前提是它的职责确实包括修复。
| 角色 | 建议工具 | 一开始避免 |
|---|---|---|
| Code reviewer | Read, Grep, Glob, Bash | Edit, Write |
| Test runner | Read, Bash, Grep, Glob | 宽泛写权限 |
| Documentation researcher | Read, Grep, Glob, WebFetch 如果可用 | 仓库写工具 |
| Security reviewer | Read, Grep, Glob, Bash | 自动修复 |
| Migration implementer | Read, Edit, Bash, Grep, Glob | deploy 工具 |
| Database analyst | Bash 加 hook 护栏 | 写 SQL |
敏感流程要把 subagent tools、permission rules 和 hooks 组合起来。工具列表负责缩小 agent 能力，permissions 和 hooks 负责执行策略。
Memory、Skills、Hooks 和 MCP
Subagents 可以加载额外能力，但要控制成本和权限。
| 能力 | 什么时候用 | 注意点 |
|---|---|---|
skills | agent 启动时就需要领域规则或复用工作流知识。 | 预加载会增加上下文成本。 |
memory | agent 需要跨会话记住项目模式和经验。 | 要清理 memory，不要存 secrets。 |
hooks | agent 活跃期间需要生命周期检查。 | hooks 会运行代码，必须可审计。 |
mcpServers | agent 需要特定外部工具。 | 只授予最小 MCP 面。 |
团队 agent 通常优先用 project-scoped memory，因为它可以跟仓库一起版本化和迭代。本机私有经验放 local memory，跨项目通用经验才放 user memory。
实用 Agent 角色
先从输入和输出都非常明确的角色开始。
Code Reviewer
用途：只审查最近改动，不编辑文件。输出按严重级别排列，带文件和行号。
关键规则：不要总结整个 diff，只报告可行动问题。
Test Triage Agent
用途：运行或检查测试，把噪音压缩成失败用例、报错、可能根因和下一条验证命令。
示例委派：
Use the test-triage subagent to run the auth test suite. Return only failing tests, root-cause hypotheses, and the smallest next verification command.Documentation Researcher
用途：查官方文档、changelog 或资料源，总结哪些口径发生变化。Claude Code 主题变化很快，这类 agent 对内容站特别有价值。
Security Reviewer
用途：检查 secrets、过宽权限、不安全 shell、暴露 token、MCP 写操作风险、输入校验不足。默认保持只读。
Release Checklist Agent
用途：检查 status、changelog、环境变量、migration 和 smoke tests。它很有价值，但除非团队明确授权，不应该让它直接 deploy。
团队落地节奏
不要一上来创建十个 agents。先针对一个反复出现的痛点做一个。
- 观察工作流： 找到输出很吵、或需要固定清单的任务。
- 写窄角色： 一个目的、一个输出格式、一个工具集合。
- 手动调用： 先用真实任务跑几次。
- 收紧描述： 调整 Claude 什么时候应该委派。
- 限制工具： 不需要编辑就移除
Edit和Write。 - 写进
CLAUDE.md： 说明团队什么时候用。 - 提交项目 agents： 行为稳定后再版本化。
这样 subagents 才会变成可预测的效率工具，而不是一层难懂的自动化。
常见错误
| 错误 | 为什么有问题 | 更好的做法 |
|---|---|---|
| 工作流还没验证就创建 agents | 会把错误流程固定下来。 | 先手动跑通，再沉淀角色。 |
| description 太泛 | Claude 无法稳定判断是否委派。 | 写清具体触发场景。 |
| 每个 agent 都给全工具 | 风险更高，也更不聚焦。 | 只给最小可用工具。 |
| 以为主上下文自动可见 | 普通 subagent 是新上下文。 | 显式传路径、报错和结论。 |
| 返回巨大报告 | 主线程仍然被污染。 | 要求精简摘要和证据。 |
| 多个 agents 改同一批文件 | 容易冲突和重复劳动。 | 只读或 worktree 隔离。 |
| 用后台 agent 做大量权限交互 | 后台 agent 会自动拒绝新权限。 | 需要审批时用前台。 |
| 手动改文件后不重启 | 新定义可能没加载。 | 重启会话或通过 /agents 创建。 |
适合本站的起步 Agent 集合
对 Claude Code 知识库项目，先考虑这几个小而明确的角色：
| Agent | 用途 | 工具 |
|---|---|---|
content-reviewer | 检查页面是否薄、口径是否空泛、是否缺内部链接和来源。 | Read, Grep, Glob |
source-checker | 核查 Claude Code 说法是否仍匹配官方文档。 | Read, Grep, Glob, WebFetch 如果可用 |
frontend-qa | 检查页面渲染、布局回归、暗黑模式和移动端溢出。 | Read, Bash |
seo-structure-reviewer | 检查 title、description、H2、FAQ 意图和相关页面链接。 | Read, Grep, Glob |
不要一次性启用所有。先从 content-reviewer 或 source-checker 开始，因为它们最直接服务于搜索流量质量。