Claude Code Subagent 深度实战：用并行子代理同时处理多个代码库任务

当单线程遇上大型代码库

假设你接手了一个 300 多个文件的中型后端项目，被要求在一天内完成三件事：审查最近 20 个 PR 的代码质量、扫描整个仓库的安全漏洞、评估测试覆盖率并找出薄弱模块。如果让 Claude Code 用"一个会话从头干到尾"的方式来做，你会很快撞上两堵墙。

第一堵墙是上下文污染。代码审查要读几十个文件的 diff，安全扫描要 grep 海量调用链，测试分析要跑测试并解析输出。这些中间结果全堆进主对话，上下文窗口很快塞满，后面的任务开始"失忆"，关键决策被噪声淹没。

第二堵墙是串行等待。三个任务彼此独立却只能排队——代码审查 8 分钟、安全扫描 6 分钟、测试分析 10 分钟，加起来 24 分钟，而你明明有三个核可以同时跑。

这正是 Claude Code 的 Subagent（子代理）要解决的问题：把任务拆给多个独立的"分身"，每个分身有自己的上下文、工具权限、模型选择，并可以并行执行。

Subagent 是什么：给 Claude Code 装上"分身术"

Subagent 是 Claude Code 中一种特殊的 AI 助手。它由主对话通过 Agent 工具派生，运行在独立的上下文窗口里，拥有自定义系统提示、受限工具集和独立权限模式。子代理干完活后只把最终摘要返回给主对话——中间的搜索结果、文件内容、日志输出统统留在它自己的上下文里，不污染父会话。

Claude Code 自带几个内置子代理，理解它们能帮你建立直觉：

Explore：只读、搜索优先的代码库探索代理，写和编辑权限被禁用，适合文件发现和代码搜索。
Plan：计划模式下的研究代理，在主对话保持只读时负责收集上下文、形成方案。
General-purpose：通用代理，拥有全部工具，适合既需要探索又需要改动的复杂多步任务。

除内置的以外，你可以创建自定义子代理，由一个 Markdown 文件定义，核心能力来自四个维度：

上下文隔离：子代理不继承父会话历史，只接收 Agent 工具调用时传入的提示。它可以放心读 50 个文件，父会话只会看到一个总结。
工具限制：通过 tools 字段白名单控制。只读审查代理只配 Read, Grep, Glob，从根本上杜绝误改文件。
模型路由：每个子代理可指定不同 model。高频低难度搜索任务路由到 Haiku，需要深度推理的安全审计留给 Opus，在成本和质量间取得平衡。
并行执行：多个子代理可并发运行，独立子任务的完成时间取决于最慢的那个，而非所有任务之和。

理解这四点，就掌握了 Subagent 的精髓。接下来动手配置。

从零配置：打造你的并行子代理团队

子代理文件存放位置决定作用范围。项目级放 .claude/agents/（随仓库走，适合团队共享），用户级放 ~/.claude/agents/（所有项目可用），优先级上项目级更高。我们先建一个项目级的并行审查团队。

目录结构

my-project/
├── CLAUDE.md
└── .claude/
    └── agents/
        ├── code-reviewer.md
        ├── security-scanner.md
        └── test-coverage-analyzer.md

三个子代理的定义

第一个是代码审查代理，只读、用 Sonnet 平衡速度与质量：

---
name: code-reviewer
description: 审查代码质量与可维护性。在代码变更后或审查 PR 时主动使用。
tools: Read, Grep, Glob
model: sonnet
---
你是资深代码审查工程师。针对给定文件或 diff，从以下维度评估：
- 命名与可读性
- 函数职责单一性
- 错误处理是否完备
- 重复代码与潜在抽象点

输出格式：按文件分组，每条问题含【严重程度】【位置】【问题描述】【改进建议】。
不要修改任何文件，只输出审查报告。

第二个是安全扫描代理，用 Opus 保证推理深度：

---
name: security-scanner
description: 扫描代码库中的安全漏洞与风险模式。在安全审计或引入新依赖时使用。
tools: Read, Grep, Glob, Bash
model: opus
---
你是应用安全专家。系统性检查以下风险：
- SQL 注入、XSS、命令注入等注入类漏洞
- 认证与授权逻辑缺陷
- 硬编码的凭证、密钥、Token
- 不安全的反序列化与文件操作
- 依赖项中已知高危 CVE

用 Grep 定位可疑模式，用 Read 读上下文确认。给出每个问题的 CWE 编号、
攻击路径和修复方案，按优先级从高到低排列。

第三个是测试覆盖率分析代理，需要跑测试，所以带上 Bash：

---
name: test-coverage-analyzer
description: 分析测试覆盖率并定位薄弱模块。在评估测试质量或补充测试前使用。
tools: Bash, Read, Grep, Glob
model: sonnet
---
你是测试工程专家。执行覆盖率工具并解析结果：
1. 运行 `pytest --cov=src --cov-report=term-missing`（Python 项目）
   或对应语言的覆盖率命令
2. 找出覆盖率低于 60% 的模块
3. 列出未覆盖的关键分支与异常路径
4. 为每个薄弱模块给出补充测试用例建议

输出：覆盖率摘要表 + 薄弱模块清单 + 测试建议。

在 CLAUDE.md 中声明协作约定

把项目级协作规范写进 CLAUDE.md，让主对话知道何时该分发任务：

# 项目协作约定

## 并行审查流程
当用户请求"全面审查"或同时涉及代码质量、安全、测试三个维度时：
- 同时派发 code-reviewer、security-scanner、test-coverage-analyzer 三个子代理
- 三个子代理并行执行，互不依赖
- 收齐三份报告后，由主对话汇总成统一审查报告

## 子代理使用原则
- 只读分析类任务优先用 Explore 或自定义只读代理
- 深度推理任务（安全审计、架构评估）指定 opus 模型
- 高频低难度任务（日志解析、简单搜索）指定 haiku 模型控制成本

配置到这里，一个三人的并行审查团队就成型了。

实战：用并行子代理同时分析三个维度

方式一：让 Claude 自动并行分发

在项目根目录启动 Claude Code，直接下达指令，主对话会根据 CLAUDE.md 约定和子代理描述自动派发：

claude

进入交互会话后输入：

对 src/ 目录做一次全面审查，涵盖代码质量、安全漏洞和测试覆盖率三个维度，
三个维度同时分析，最后汇总成一份报告。

Claude 会识别出三个维度对应三个子代理，在同一次回应里发起三个 Agent 工具调用，它们并发执行，终端会看到三个子代理状态同时刷新。

方式二：显式按名称调用

若自动分发不够确定，可点名调用，强制走指定子代理：

并行执行以下三个任务，使用对应的子代理：
1. 用 code-reviewer 审查 src/auth/ 下所有文件
2. 用 security-scanner 扫描整个 src/ 目录的安全风险
3. 用 test-coverage-analyzer 运行覆盖率并分析薄弱模块

方式三：用 --agents 临时注入子代理

不想写文件、只想在单次会话里用一下，可通过 CLI 的 --agents 标志传 JSON 定义：

claude --agents '{
  "code-reviewer": {
    "description": "审查代码质量。代码变更后主动使用。",
    "prompt": "你是资深代码审查工程师，从可读性、职责单一性、错误处理维度评估，只输出报告不修改文件。",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  },
  "security-scanner": {
    "description": "扫描安全漏洞。安全审计时使用。",
    "prompt": "你是应用安全专家，检查注入、认证、凭证泄露等风险，给出 CWE 编号和修复方案。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "opus"
  }
}'

这种方式定义的子代理只在当前会话存活，不落盘，适合快速验证或写自动化脚本。

完整运行步骤

在项目根目录建好 .claude/agents/ 及三个 .md 文件，写好 CLAUDE.md。
启动 claude，若 .claude/agents/ 是本次会话首次出现的新目录，重启一次 Claude Code 让监视器发现它。
下达全面审查指令（方式一或方式二）。
三个子代理的 Agent 工具调用并发启动，各自在自己的上下文里跑。
三个子代理陆续返回摘要，主对话把三份报告合并成统一输出。

性能对比：并行 vs 串行的真实差距

下面是在一个约 50 个 Python 文件的中型项目上，对三个独立维度做审查的实测对比（示例数据，基于 Sonnet/Opus 混合配置，单次会话）：

执行方式	代码审查	安全扫描	测试覆盖	总耗时	主对话上下文占用
串行单会话	8 分 10 秒	6 分 20 秒	9 分 50 秒	约 24 分	高（三任务结果全堆入）
并行子代理	8 分 10 秒	6 分 20 秒	9 分 50 秒	约 10 分	低（只收三份摘要）

关键结论：

耗时从总和变为最长项。并行后总耗时约等于最慢的测试覆盖任务，而非三者相加，节省近 58%。
上下文占用大幅下降。串行方式下几十个文件的 diff、grep 结果、测试输出全进主对话，很快逼近窗口上限；并行方式下主对话只持有三份摘要，留出充足空间做后续决策。
成本可控。通过模型路由，代码审查和测试分析走 Sonnet，只有安全扫描走 Opus，单位 token 成本比"全程 Opus"低不少。

需说明：并行能省多少时间，取决于任务是否真正独立。若安全扫描依赖代码审查的结论，就只能串行；本例三个维度互不依赖，所以并行收益最大。

想提高并发上限，可设置环境变量（需 Claude Code v2.1.212+，并发数限制需 v2.1.217+）：

# 单个会话允许派生的子代理总数
export CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=20

# 同时并发执行的上限
export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=6

FAQ：5 个高频问题

Q1：我新建了 .claude/agents/ 目录和文件，但 Claude 一直不调用我的子代理，怎么办？

最常见原因：会话启动时这个 agents 目录还不存在，Claude Code 的目录监视器只覆盖启动时已存在的目录。解决办法是退出并重启一次 Claude Code。另外检查 frontmatter 的 YAML 是否合法、name 是否和已有子代理重名。可用 /doctor 命令做诊断，它会报告重名等配置问题。

Q2：并行子代理会互相干扰、改坏文件吗？

不会，前提是配好工具白名单。子代理间上下文完全隔离，互相看不到对方的工具调用。只读代理的 tools 限制为 Read, Grep, Glob，连 Write、Edit 都没有，物理上无法改文件。多个子代理同时写同一文件才需担心冲突——设计任务时让它们各管各的文件区域即可。

Q3：子代理能嵌套吗？一个子代理里再派子代理？

可以。子代理可通过 Agent 工具派生自己的子代理（嵌套子代理），每一层都计入 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 总数。但嵌套会增加编排复杂度和延迟，实际项目中建议控制在两层以内。要协调几十上百个代理时，改用 Agent SDK 的 Workflow 工具，它把编排逻辑移到对话之外的脚本里执行，更适合大规模任务。

Q4：并行子代理能跨多个代码库工作吗？

单会话内的子代理默认在当前工作目录活动。要让它们访问其他目录，启动时用 --add-dir /path/to/other/repo 把额外目录加进来，该目录下的 .claude/agents/ 也会被加载。若要在多个独立会话间并行且彼此通信，那属于 agent teams 范畴，超出单会话子代理的范围。

Q5：子代理失败了，主对话会收到什么？

分情况。若子代理因限流、过载等 API 错误提前结束，且已产出过文本，Agent 工具会返回那部分输出并附注"子代理未完成"；若只产生了工具调用没有任何文本输出，则报错 Agent terminated early due to an API error。这类错误不会作为正常结果传给主对话，主对话可据此决定重试或换策略。注意内置的 Explore 和 Plan 是一次性的，不返回可恢复的 agentId；要支持"断点续跑"，得用自定义子代理或 general-purpose，它们会返回 agentId 供后续 resume。

写在最后

Subagent 的价值不止于"快"，更在于让复杂任务变得可组合。上下文隔离让你敢于让代理放手读海量文件，工具限制让你敢把代理放进生产代码库，模型路由让你在质量和成本间精细权衡，并行执行则把等待时间压到最短。把审查代理固化进 .claude/agents/ 并提交到仓库，整个团队就共享了一套可复用的并行审查能力——这才是子代理从"技巧"升级为"工程实践"的关键一步。