Claude Code 中的子代理：在不失控制的情况下进行委派

无限上下文的问题

想象一下，你让 Claude 研究项目的身份验证是如何工作的。它开始读取文件。很多文件。突然你的上下文就被 50,000 个令牌的代码填满了，而这些代码你只需要查阅，而不是记住。

现在每个响应都变得更慢。也更贵。当你想做其他事情时，所有这些上下文仍然在那里，占用着思维空间。

解决方案：子代理。你启动一个专门的代理，它在自己的独立上下文中完成繁重的工作，给你返回一个摘要，然后消失。你的主对话保持清洁。

什么是子代理

子代理是 Claude 的一个独立实例，它：

• 拥有自己的上下文（不会污染你的对话）
• 可以拥有受限的工具（只读、只有 bash 等）
• 可以使用不同的模型（haiku 用于简单任务，opus 用于复杂任务）
• 可以在前台（阻塞）或后台（并行）执行

把它们想象成专门的实习生。你给他们分配任务，他们独立工作，完成后向你汇报。

你已经拥有的子代理

Claude Code 自带几个集成的子代理：

最有用的是 Explore。当 Claude 需要在你的代码库中搜索内容时，它会启动一个 Explore，疯狂地读取文件，处理一切，然后只返回相关内容。

如何启动子代理

从 REPL（正常对话）

只需用自然语言请求：

使用子代理研究缓存系统是如何工作的

启动 Explore 代理找到所有 API 端点

在我继续工作的同时并行研究身份验证

Claude 理解这些请求，并在内部使用 Task 工具启动适当的子代理。

从技能（Skill）

在技能中，你可以通过 context: fork 强制在独立的子代理中执行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
name: deep-analysis
description: 架构深度分析
context: fork
agent: Explore
---

分析项目的完整架构。
生成包含以下内容的报告：
- 目录结构
- 主要依赖
- 检测到的设计模式

使用 context: fork，技能在子代理中执行。使用 agent: Explore，你指定使用哪种类型的代理。

按类型显式启动

如果你想要具体指定：

使用 Explore 代理映射项目结构
使用 general-purpose 代理重构支付模块
使用 Bash 代理执行完整的测试套件

前台 vs 后台

前台（阻塞）

默认情况下，子代理在前台执行。你的会话等待它们完成。

研究速率限制是如何工作的
[Claude 启动子代理，你等待，接收结果]

当你需要立即得到结果时很有用。

后台（并行）

你可以通过两种方式将子代理发送到后台：

1. 明确请求：

在后台研究缓存系统，同时我检查其他东西

2. 在执行时使用 Ctrl+B：

如果子代理已经在运行，你想继续工作，按 Ctrl+B。代理转入后台，你可以继续。

> 分析项目中的所有测试
[开始执行...]
[按 Ctrl+B]
> 好的，同时请解释这个文件的作用
[继续工作，分析在并行进行]

查看后台任务

使用 /tasks 命令查看正在运行的任务：

/tasks

这显示所有后台任务及其 ID、状态和进度。

与子代理的通信

了解它在做什么

当子代理在前台时，你可以实时看到其进度（它读取哪些文件，执行哪些命令）。

如果它在后台，使用 /tasks 查看状态。完成时，Claude 会自动通知你结果。

给出额外指令

如果子代理正在运行，你想添加上下文：

顺便说一下，忽略测试文件，我只对生产代码感兴趣

如果可能的话，Claude 会尝试将这些信息传递给子代理。

停止子代理

要停止后台任务：

停止分析任务
取消正在运行的子代理

或者从 /tasks，你可以通过 ID 取消特定任务。

恢复子代理

子代理在会话内保持其历史记录。你可以从中断的地方继续：

继续之前的身份验证分析
现在也检查授权

Claude 使用其完整的先前上下文恢复子代理。

创建你自己的子代理

使用 /agents 命令（推荐）

/agents

选择 Create new agent，选择范围（用户或项目），描述你想要的，Claude 会为你生成文件。

手动创建

在 .claude/agents/（项目）或 ~/.claude/agents/（全局）中创建 Markdown 文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
name: security-scanner
description: 扫描代码寻找漏洞。在身份验证或数据处理变更后主动使用。
tools: Read, Grep, Glob
model: opus
---

你是安全专家。分析代码寻找：

- SQL 注入
- XSS
- 硬编码的密钥
- 输入验证不足
- 有漏洞的依赖

按严重程度报告：严重 > 高 > 中 > 低。
不要修改代码，只报告。

前言配置

权限模式

示例：只读代理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
name: code-reader
description: 读取和分析代码而不修改任何内容
tools: Read, Grep, Glob
disallowedTools: Write, Edit, Bash
permissionMode: plan
---

分析请求的代码。
永远不要建议修改，只描述你发现的内容。

示例：测试代理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

---
name: test-runner
description: 执行测试并报告失败。在代码变更后使用。
tools: Bash, Read
model: haiku
---

1. 执行：`uv run pytest -x --tb=short`
2. 如果有失败，读取相关文件
3. 报告：
   - 通过的测试：X
   - 失败的测试：Y
   - 每个失败的摘要（文件、行号、错误）

不要尝试修复测试，只报告。

常见用例

1. 代码库研究

使用 Explore 了解通知系统是如何工作的

Explore 读取所有必要的内容，你收到摘要而不会污染你的上下文。

2. 并行分析

并行研究：
- 身份验证如何工作
- 支付系统如何工作
- 邮件发送如何工作

Claude 启动三个并发的子代理。每个研究其区域。

3. 后台测试

在我实现这个功能的同时在后台执行测试

你不必等待。当它们失败（或通过）时，它会通知你。

4. 隔离的代码审查

使用子代理审查我刚才所做更改的安全性

审查在独立的上下文中进行。你收到反馈而没有噪音。

5. 安全重构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
name: safe-refactor
description: 带验证的代码重构
tools: Read, Edit, Bash
hooks:
  PostToolUse:
    - matcher: "Edit"
      hooks:
        - type: command
          command: "uv run pytest -x"
---

每次编辑都会自动触发测试。

子代理 vs 技能：何时使用每一个

你也可以组合使用：带有 context: fork 的技能启动子代理。

限制

• 不能嵌套：子代理不能启动另一个子代理
• 后台权限：后台的子代理自动拒绝未预批准的权限
• 单一会话：子代理的上下文只在会话期间存在

高级技巧

禁用特定子代理

在 settings.json 中：

1
2
3
4
5

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(my-custom-agent)"]
  }
}

自动压缩

子代理在上下文的 95% 时有自动压缩。要更早触发：

1

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

查看转录

子代理日志保存在：

~/.claude/projects/{project}/{session}/subagents/agent-{id}.jsonl

对调试或审计很有用。

禁用后台任务

如果你希望一切都是阻塞的：

1

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

结论

子代理是在不让上下文爆炸的情况下扩展 Claude Code 使用的方法。它们委派繁重的工作，保持你的对话清洁，并可以并行工作。

将它们用于研究、分析、测试和任何生成大量你不需要记住的输出的任务。为具有特定限制的重复任务创建你自己的代理。

技能（做什么）+ 子代理（在哪里做）+ 钩子（何时验证）的组合给你对 Claude 如何工作的相当细致的控制。

总结：子代理是用于特定任务的 Claude 的隔离实例。它们保持你的上下文清洁，可以并行运行（Ctrl+B），你可以在 .claude/agents/ 中创建自己的代理。使用 /tasks 监控它们，使用 /agents 管理它们。

官方文档：Subagents - Claude Code Docs