Claude Code 能够高效处理复杂的多步骤项目，但随着会话时间的增长，累积的上下文信息会增加负担。每次读取的文件、探索的分支、未完成的思路都会留在上下文窗口中，导致响应变慢且代币消耗增加。

举例来说，在一个大型 TypeScript 单体仓库中开发新功能时，主要工作是实现功能，但同时会出现许多辅助任务：追踪现有服务的认证流程、查找共享的日期格式化工具、确认设计系统中是否已有类似组件。这些辅助任务不需要完整的项目上下文，在主会话中处理会增加噪音。如果能并行处理这些任务会怎样？

这时，子代理（subagents）就派上用场了。子代理是独立的 Claude 实例，拥有自己的上下文窗口。它们接收任务，独立完成工作，并仅返回结果。可以把子代理想象成 Claude Code 会话中的浏览器标签页：用来探索分支而不影响主线任务。

本文将介绍何时适合使用子代理，如何调用它们，以及何时不值得使用。

什么是子代理？

子代理是自包含的助手，拥有独立的上下文窗口。当 Claude 创建子代理时，该助手独立工作，读取文件、探索代码或进行修改，完成后只将相关结果返回给主会话。

每个子代理都是全新的，不受主会话历史或已调用技能的影响。多个子代理可以并行运行，且权限可不同：研究子代理可能只有只读权限，实施子代理则拥有完整编辑权限。

Claude Code 内置了多种子代理类型，包括：

  • 通用代理：处理复杂多步骤任务
  • 计划代理：先研究代码库，再提出实施方案
  • 探索代理：优化快速只读代码搜索

Claude Code 经常自动生成子代理来处理任务，也可以通过明确指令调用，或定义可复用的专家子代理由 Claude 自动委派。掌握何时使用子代理是发挥其价值的关键。

何时使用子代理？

某些工作类型明显适合委派给子代理，识别这些场景能大幅提升效率。

研究密集型任务

当理解某功能如何工作是修改前提时，子代理可以独立探索代码库并返回总结，而不是将大量文件内容直接丢入主会话。

**信号：**需要阅读大量文件以收集上下文。

**好处：**主会话保持简洁，得到的是综合的研究结果而非原始内容。

多个独立任务

当修复多个文件中的错误、更新多个组件的模式，或进行互不依赖的修改时，子代理并行处理能更快完成任务。

**信号：**子任务之间无依赖关系。

**好处：**多个子代理同时工作通常比顺序处理更高效。

需要全新视角

当需要对实现进行无偏见的审查时，子代理提供了干净的环境，不受主会话的假设、上下文或盲点影响。

**信号：**需要独立验证，避免历史对分析的影响。

**好处：**获得更客观、清晰的反馈。

**小贴士：**使用 /clear 命令也能重置上下文，但会丢失历史。子代理则能保持主会话完整的同时提供新视角。

提交前验证

在最终提交代码前，独立子代理能检查实现是否过拟合测试或遗漏边缘情况。

**信号：**提交前需要第二意见。

**好处：**发现熟悉代码时可能忽视的问题。

流水线工作流

当任务有明确阶段（设计、实现、测试）时，每个阶段由专注的子代理负责更有效。

**信号：**任务分阶段且有明确交接。

**好处：**每个子代理专注于当前阶段，避免其他阶段上下文干扰。

**小贴士：**当任务涉及十个以上文件或三个以上独立子任务时，强烈建议使用子代理。

如何调用子代理

调用子代理的方法多样，从简单对话到自动化工作流都有。选择合适的起点取决于具体流程，随着使用深入可逐步增加复杂度。

对话式调用

最灵活的方式是直接在对话中请求 Claude 使用子代理，适用于所有 Claude Code 界面（终端、VS Code、JetBrains、网页和桌面应用）。

常见自然语言调用示例：

  • “用子代理探索这个代码库的认证流程”
  • “让另一个代理审查这段代码的安全问题”
  • “并行研究API路由、数据库模型和前端组件”
  • “启动子代理同时修复不同包中的 TypeScript 错误”

明确说明任务范围、请求并行执行（若任务独立）、描述期望输出非常重要。

示例提示语：

用子代理并行探索这个代码库：

1. 找出所有API端点并总结其功能
2. 识别数据库模式及关系
3. 绘制认证流程图

返回每项总结，而非完整文件内容。

该提示明确划分了三个独立任务，要求并行执行并指定输出格式，Claude 会据此生成合适的子代理。

有效调用技巧：

  • 明确任务范围，如“探索支付流程”优于“探索所有内容”
  • 明确请求并行，如“这些任务可以并行执行”
  • 指定返回内容，如总结、具体发现或建议
  • 需要无偏见分析时，要求子代理不访问之前对话

**小贴士：**当子代理运行较慢时，按 Ctrl+B 可将其置于后台，主会话可继续，结果完成后自动显示。使用 /tasks 查看后台任务。

自定义子代理

如果某类子代理频繁被调用（如安全审查、测试编写、文档校对），可以定义为自定义子代理。

Claude 会自动将匹配的任务委派给它，无需每次提示。

自定义子代理以 Markdown 文件形式存放于 .claude/agents/（项目级，团队共享）或 ~/.claude/agents/（用户级，跨项目可用）。每个子代理有独立的系统提示、工具权限，且可指定模型。

创建方式：使用 /agents 命令交互式设置，或手写配置文件，例如：

---
name: security-reviewer
description: 审查代码变更中的安全漏洞、注入风险、认证问题和敏感数据泄露。提交涉及认证、支付或用户数据时主动使用。
tools: Read, Grep, Glob
model: sonnet
---

你是专注安全的代码审查员。分析提供的变更，关注：
- SQL注入、XSS及命令注入风险
- 认证和授权漏洞
- 日志、错误或响应中的敏感数据
- 不安全的依赖或配置

返回带文件和行号的优先级问题列表及修复建议。请严格批判，若无问题请明确说明，不要编造问题。

配置完成后，Claude 会自动将匹配任务路由给该子代理，也可通过名称调用：“让 security-reviewer 审查暂存变更。”

自定义子代理适合：

  • 需要自动委派的专门角色
  • 任务受益于明确系统提示和权限限制
  • 需团队共享或跨项目复用配置

**小贴士：**描述字段决定委派时机，具体说明触发条件比仅写能力更有效。

完整配置及权限模式详见Claude Code 子代理文档。

CLAUDE.md 指令

自定义子代理定义专家角色，CLAUDE.md 文件定义何时调用它们。比如所有代码审查都应使用只读子代理，或所有架构问题先触发研究流程，规则写在 CLAUDE.md 中。Claude 会在每次对话开始时读取，确保行为一致，无需人工提醒。

适合用 CLAUDE.md 的场景：

  • 代码审查必须使用只读子代理
  • 项目有特定研究流程需遵循
  • 团队成员和会话间需保持一致行为

示例 CLAUDE.md：

## 代码审查标准

请求审查代码时，始终使用只读子代理（Glob, Grep, Read only）。审查内容必须包括：
- 安全漏洞
- 性能问题
- 遵循 /docs/architecture.md 中的项目模式

返回带文件和行号的优先级问题列表。

此配置确保所有代码审查请求自动使用定义的模式，无需重复说明。

更多 CLAUDE.md 相关内容见定制 Claude Code：设置 CLAUDE.md 文件及CLAUDE.md 文件文档。

技能（Skills）

对于反复执行的复杂多步骤工作流，技能提供可复用接口。在 .claude/skills/ 中定义一次，之后可用 /技能名 调用，或由 Claude 根据任务描述自动加载。

技能与 CLAUDE.md 的区别在于范围：CLAUDE.md 始终加载，影响所有交互；技能按需加载，适合非每次都应用的工作流。

适合使用技能的场景：

  • 某些操作定期执行
  • 不同成员需访问相同复杂操作
  • 团队需统一任务执行标准

示例深度审查技能：

# .claude/skills/deep-review/SKILL.md

---
name: deep-review
description: 综合代码审查，平行检查安全、性能和风格。用于提交或PR前审查暂存变更。
---

对暂存变更运行三项并行子代理审查：

1. 安全审查 - 检查漏洞、注入风险、认证问题和敏感数据泄露
2. 性能审查 - 检查N+1查询、多余迭代、内存泄漏和阻塞操作
3. 风格审查 - 检查是否符合 /docs/style-guide.md 中的项目规范

将结果综合成单一总结，列出优先级问题，每项包括文件、行号和修复建议。

该技能通过 /deep-review 按需触发，也可自动匹配相关上下文调用。

技能是目录结构，除 SKILL.md 外，还可包含模板、示例输出或工作流脚本。相比旧版 .claude/commands/ 单文件格式，功能更丰富。

更多技能使用详见Claude Code 技能文档。

钩子（Hooks）

钩子是用户定义的 shell 命令、HTTP 端点或 LLM 提示，在 Claude Code 生命周期特定时刻自动执行。钩子指南 可用来基于事件自动化子代理工作流，无需手动调用。

适合使用钩子的场景：

  • 每次提交前自动审查
  • 安全检查自动运行，无需人工触发
  • 本地开发流程中集成类似CI的质量门控

示例阻止钩子，阻止 Claude 结束回合直到测试通过：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-tests.sh"
          }
        ]
      }
    ]
  }
}

对应脚本 .claude/hooks/check-tests.sh：

#!/bin/bash
INPUT=$(cat)
STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')

# 防止无限循环
if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
  exit 0
fi

if ! npm test --silent > /dev/null 2>&1; then
  jq -n '{
    decision: "block",
    reason: "测试未通过。请运行 `npm test` 查看失败并修复后再完成。"
  }'
  exit 0
fi

exit 0

当 Claude 结束回合时触发 Stop 事件，脚本运行测试套件，若失败返回阻止决策和原因，Claude 会继续工作并反馈原因。顶部的 stop_hook_active 防止无限阻塞。

钩子是最自动化的子代理编排方式。建议先从对话调用或 CLAUDE.md 指令开始，随着流程成熟再引入钩子。

完整钩子配置见Claude Code 钩子文档及高级定制指南。

子代理的实用模式

以下示例展示了子代理在常见场景中的应用。

实施前研究

在不熟悉代码时，先用子代理做研究，确保实现讨论基于充分信息，而非探索式：

在我实现用户通知功能前，先用子代理研究：
- 代码库中邮件发送的方式
- 已有的通知模式
- 基于当前架构，新通知逻辑应放置的位置

总结研究结果，之后一起规划实现。

得到的是综合总结，而非大量原始文件，讨论更高效。

并行修改

当同一模式需更新多个文件时，子代理并行工作更快且更专注：

用并行子代理更新以下文件的错误处理：
- src/api/users.ts
- src/api/orders.ts
- src/api/products.ts

每个文件遵循 src/api/auth.ts 中的模式。
同时处理这三个文件。

三个子代理同时工作，完成时间约等于单个任务时间，避免相互干扰。

独立审查

复杂实现完成后，用不受之前讨论影响的子代理审查，发现熟悉代码时可能忽视的问题：

用一个全新、只读的子代理审查我的支付流程实现。它不应看到之前的讨论，我需要无偏见的审查。

检查安全漏洞、未处理的边缘情况和错误处理缺陷。请严格批判。

该子代理独立评估代码，提供客观反馈。

流水线工作流

多阶段任务中，按阶段链式调用子代理，保持每阶段专注：

我们用流水线方式构建此功能：

1. 第一个子代理：设计API契约，写入 docs/api-spec.md
2. 第二个子代理：根据契约实现后端接口
3. 第三个子代理：为实现编写集成测试

每阶段完成后再进入下一阶段，使用输出文件作为交接。

设计阶段不受实现细节干扰，实现阶段基于清晰规范，测试阶段独立验证结果。

何时不适合使用子代理？

子代理虽好，但也有开销。每个子代理启动独立上下文，消耗代币，并增加开发者与任务间的间接层。只有当上下文隔离、并行处理或新视角真正有益时才值得。

以下情况建议避免使用子代理：

  • **顺序依赖任务。**步骤二依赖步骤一输出，步骤三依赖前两步，单会话处理更简洁。
  • **同文件编辑。**两个子代理同时编辑同一文件易冲突，保持在一个上下文中更安全。
  • **小任务。**快速修复或简单问题，委派开销大于收益，直接在主会话处理即可。
  • **过多专用子代理。**定义太多子代理会让自动委派不稳定，通常团队选择少量明确职责的子代理。
  • **需要子代理间协调的任务。**子代理只能向主会话汇报，不能相互通信。此类任务应使用代理团队，但成本更高。

前文提到的信号（需要第二意见、子任务无依赖、大量研究）帮助判断是否适合委派子代理。

从对话开始，逐步自动化

子代理的价值在于有意识地使用。Claude 的自动调用虽方便，但主动委派研究、并行任务和请求新视角，效果更佳。

使用子代理时，先从对话提示开始，观察重复请求，逐步构建自动化。目标是让子代理委派变得轻松自然，让你专注于真正重要的工作。