Claude Code Subagent（子代理）使用完整教程

Claude Code 提供的 Subagent（子代理）功能，是一种多智能体协作机制，允许你在主线程执行任务过程中创建具有独立上下文窗口的辅助智能体，分担主线程工作，避免主线程上下文窗口占满。

本教程将系统介绍 Subagent 的核心概念、适用场景、创建方法、手写配置、分发方式等一系列教程，帮助你掌握这一强大的多代理协作工具。

为什么需要 Subagents？

Claude Code 在执行过程中会有很多次工具调用，期间需要读取文件，执行命令，单元测试等等，上下文窗口很快就占满，最终影响编码和决策效果，所以需要把一些任务丢给一个独立的 agent 来分担一些工作，减少上下文占用。

Subagents 是什么？

Subagents（子代理）会在当前的任务执行的会话创建一个子代理，它可以在独立的上下文窗口运行后把结果总结后返回给主线程，可以避免占用主线程上下文窗口的大小。

每个 subagent 都有自己的独立上下文，拥有自定义系统提示词、特定的工具访问权限和独立的权限设置。当 cc 遇到与 subagent 描述匹配的任务时，会自动委托给该 subagent 执行，然后返回结果摘要给主线程。

适合场景

如果临时任务会生成大量用不到的搜索信息、日志和文件内容，但是主线程不需要这些内容时，就应该使用子代理来执行。比如代码评审agent，代码commit agent。

如何创建和使用 Subagent

创建一个 Subagent 非常简单，cc 提供了一根内置指令方便我们创建 Subagent，只需要在 tui 面板上输入 /agents 指令进入交互式创建。

选择存储的位置

• Project (.claude/agents/)表示仅在当前项目中可用，适合团队协作或项目专属任务。
• Personal (~/.claude/agents/) 表示在所有项目中可用，适合通用任务或跨项目复用，不过这种不方便通过 git 共享。

生成方式选择 Generate with Claude。

接下来输入 agent 的功能描述，比如我们创建一个代码审查的 agent，直接输入下面描述即可

接下来提示你要赋予 agent 的权限，由于我们创建的是代码审查，这里选择 Read-only tools 即可，其他根据实际 agent 运行场景进行选择，选择错了也没关系，可以编辑。

接下来选择模型，代码审查比较重要，这里选择最好的 Opus，不同代号表示模型强弱，与模型费用挂钩。

最后选择你喜欢的 agent 颜色即可，我们来执行下刚创建的 agent，可以看到有标颜色的就是正在在后台运行 subagent，在执行过程中上下文大小不会递增，还可以通过方向键切换到 subagent 查看执行过程。

![[Pasted image 20260604002612.png]]

手写 subagent 示例

如果想定制灵活点，可以自己手写，下面是一个 subagent 示例：

一个只读 subagent，审查代码而不修改它。此示例展示了如何设计一个专注的 subagent，具有有限的工具访问（无 Edit 或 Write）和详细的提示，指定确切要查找的内容以及如何格式化输出。

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
 
You are a senior code reviewer ensuring high standards of code quality and security.
 
When invoked:
 
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
 
Review checklist:
 
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
 
Provide feedback organized by priority:
 
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
 
Include specific examples of how to fix issues.

分发 subagent 两种主要方式

subagent 编写完成之后需要进行共享，达到复用的目的，可以通过下面两种方式进行分发：

通过 Plugin 分发

• 在 plugin 的 agents/ 目录中放置 subagent 文件
• 创建 .claude-plugin/plugin.json 清单定义 plugin
• cc 会对 subagent 自动命名空间化（如 my-plugin:agent-name）

至于如何创建 Claude Code 插件可以查看这篇文章：

通过Git版本控制分发

将 subagent 保存在项目的 .claude/agents/ 目录，这样团队在克隆后就可以直接在项目中使用了。

subagent常见问题

如何显式调用subagent？

默认情况下，cc会自动根据 agent 的描述自动委托subagent 执行，不过你可以通过下面三种方式进行显示调用。

• 输入消息时用自然语言提示要调用哪个 subagent

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

• 使用 @ 关键词从下拉选择你想指定的 subagent

@"code-reviewer (agent)" look at the auth changes

• 会话启动时指定 agent，这样主线程就会采用该 subagent 的系统提示、工具限制和模型

claude --agent code-reviewer

如何后台运行 subagent？

默认 cc 根据任务决定是否在前台或后台运行 subagent，如果你想强制后台执行，可以使用下面两种方法

• 自然语言要求 “在后台运行哪个agent”
• 使用快捷键 Ctrl+B 将运行中的任务放在后台

如何禁用后台运行 subagent？

可以设置环境变量CLAUDE_CODE_DISABLE_BACKGROUND_TASKS = 1 来禁言后台运行 subagent。

最后

到这里已经对 subagent 有大致的认知，但是 subagent 只能应对单一简单的任务，对于一些复杂的任务，比如涉及全代码库扫描、几百个文件批量修改、多角度交叉验，就需要使用到 Agent Teams 了，今天就写到这里了，等我有空再来详细写一篇关于 agent team 的介绍。