Claude Code 子代理 (Subagents) 深度解析：架构、机制与最佳实践

一、引言：为什么需要子代理？

原文链接：How and when to use subagents in Claude Code 发布日期：2026 年 4 月 7 日

Claude Code 在处理复杂的多步骤项目时表现出色，但长会话带来了一个不可忽视的问题：随着对话持续推进，每次文件读取、每次探索、每次未完成的想法都会保留在上下文窗口中——上下文窗口逐渐膨胀，响应速度下降，Token 成本攀升。

子代理提供了一个优雅的解决方案：它们就像浏览器标签页——你可以在新标签页中追逐某个切线问题，而不丢失主线进度。

本文导读

章节	内容
第二节	子代理核心概念与架构设计
第三节	五种触发子代理的方式（从临时到自动化）
第四节	四大实用工作模式（研究/并行/审查/管道）
第五节	何时不应使用子代理
第六节	最佳实践与工程建议

二、子代理核心概念与架构设计

2.1 什么是子代理？

子代理（Subagent）是拥有独立上下文窗口的自包含代理实例。当 Claude Code 的主会话生成一个子代理时，该子代理会在独立的环境中工作——读取文件、探索代码或进行修改——完成后仅将精简的结果返回到主对话。

子代理概念架构

2.2 核心特性

子代理具备三大核心特性，使其与普通的上下文切换有本质区别：

子代理三大核心特性

特性	说明	优势
独立上下文	子代理拥有全新的上下文窗口	不受主对话历史负担，聚焦当前任务
并行执行	多个子代理可并发运行	多任务并行 = 更短的完成时间
差异化权限	每个子代理可有不同的工具权限	研究代理只读，实现代理可编辑

2.3 内置子代理类型

Claude Code 提供了三种内置子代理类型，覆盖最常见的使用场景：

Claude Code 内置子代理类型

选择建议：

通用代理：当任务涉及代码修改时使用（如重构、新功能实现）
计划代理：当需要先理解现有架构再动手时使用（如大型重构前的调研）
探索代理：当只需要搜索和阅读代码时使用（如"认证逻辑在哪里？"）

三、五种触发子代理的方式

Claude Code 提供了从临时到完全自动化的五种触发方式，满足不同层次的自动化需求。

五种触发方式对比

3.1 方式一：对话式调用

最直接的使用方式——在对话中用自然语言要求 Claude 使用子代理。适用于所有 Claude Code 界面（终端、VS Code、JetBrains、Web、桌面应用）。

有效的自然语言模式

# 探索型
"使用子代理探索此代码库中的身份验证如何工作"

# 审查型
"让一个单独的代理审查此代码是否存在安全问题"

# 并行型
"并行研究。同时检查 API 路由、数据库模型和前端组件"

# 修复型
"启动子代理以修复不同包中的这些 TypeScript 错误"

结构化提示词模板

Use subagents to explore this codebase in parallel:
1. Find all API endpoints and summarize their purposes
2. Identify the database schema and relationships
3. Map out the authentication flow
Return a summary of each, not the full file contents.

提示技巧：

技巧	说明
明确范围	告诉子代理要做什么、不做什么
请求并行	明确说"并行"或"同时"来触发多子代理
指定返回	说明需要摘要、发现列表还是具体建议
要求新视角	需要无偏见分析时，要求使用"新上下文"

Pro Tip：当子代理耗时较长时，Ctrl+B 可将其发送到后台。对话继续进行，结果完成后自动浮现。使用 /tasks 命令查看后台运行状态。

3.2 方式二：自定义子代理

当同一种子代理被反复请求时（安全审查员、测试编写器、文档校对者），应将其定义为可复用的自定义子代理。

文件位置

级别	路径	作用域
项目级	`.claude/agents/`	与团队共享
用户级	`~/.claude/agents/`	所有项目可用

创建方式

使用 /agents 命令交互式设置，或从描述生成初稿。

完整示例：安全审查代理

---
name: security-reviewer
description: Reviews code changes for security vulnerabilities,
  injection risks, auth issues, and sensitive data exposure.
  Use proactively before commits touching auth, payments,
  or user data.
tools: Read, Grep, Glob
model: sonnet
---

You are a security-focused code reviewer. Analyze the provided
changes for:

- SQL injection, XSS, and command injection risks
- Authentication and authorization gaps
- Sensitive data in logs, errors, or responses
- Insecure dependencies or configurations

Return a prioritized list of findings with file:line references
and a recommended fix for each. Be critical. If you find nothing,
say so explicitly rather than inventing issues.

关键设计要素解析：

自定义子代理的设计要素

最佳实践：

在 description 中指定触发条件（“before commits touching auth, payments”），不仅仅描述能力
tools 遵循最小权限原则：只读代理只给 Read/Grep/Glob
系统提示词应包含兜底行为（“If you find nothing, say so explicitly”），防止 AI 编造问题

3.3 方式三：CLAUDE.md 指令

CLAUDE.md 定义项目级规则，控制 Claude 何时以及如何使用子代理。与自定义代理的区别在于：CLAUDE.md 规则始终加载，塑造每次交互。

适用场景

代码审查应始终使用只读子代理
项目有特定的研究模式需要 Claude 遵循
需要团队成员和会话之间的一致行为

示例配置

## Code review standards

When asked to review code, ALWAYS use a subagent with READ-ONLY
access (Glob, Grep, Read only). The review should ALWAYS check for:

- Security vulnerabilities
- Performance issues
- Adherence to project patterns in /docs/architecture.md

Return findings as a prioritized list with file:line references.

CLAUDE.md 指令机制

3.4 方式四：技能 (Skills)

对于重复运行的复杂多步骤工作流，技能提供了更强大的可复用接口。

技能 vs CLAUDE.md

维度	CLAUDE.md	技能 (Skills)
加载方式	始终加载	按需加载
触发方式	被动（塑造每次交互）	主动（显式调用或自动匹配）
文件结构	单个文件	目录（可含模板、脚本、示例）
适用范围	全局规则	特定工作流

示例：深度审查技能

文件位置：.claude/skills/deep-review/SKILL.md

---
name: deep-review
description: Comprehensive code review that checks security,
  performance, and style in parallel. Use when reviewing staged
  changes before a commit or PR.
---

Run three parallel subagent reviews on the staged changes:

1. Security review - check for vulnerabilities, injection risks,
   authentication issues, and sensitive data exposure

2. Performance review - check for N+1 queries, unnecessary
   iterations, memory leaks, and blocking operations

3. Style review - check for consistency with project patterns
   documented in /docs/style-guide.md

Synthesize findings into a single summary with priority-ranked
issues. Each issue should include the file, line number, and
recommended fix.

这个技能展示了子代理的组合威力——一次调用触发三个并行子代理，分别进行安全、性能、风格审查，最后综合为一份报告。

deep-review 技能：三个并行子代理

注意：技能是一个目录，不是单个文件。除了 SKILL.md，还可以包含 Claude 填充的模板、示例输出、或工作流脚本。

3.5 方式五：挂钩 (Hooks)

挂钩是在 Claude Code 生命周期特定节点自动执行的用户定义操作（Shell 命令、HTTP 端点或 LLM 提示）。

适用场景

每次提交前应自动审查
安全检查应运行无需任何人记住去询问
类似 CI 的质量门应属于本地开发流程

示例：Stop Hook —— 阻止未通过测试的提交

.claude/settings.json 配置：

{
  "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: "Tests are failing. Run `npm test` to see the failures and fix them before finishing."
  }'
  exit 0
fi

exit 0

工作原理：

Stop Hook：阻止未通过测试的提交

这个模式的价值：Claude 不会在测试失败的状态下结束工作——它会被"推回去"继续修复，直到所有测试通过。相当于给 AI 装了一个"质量门卫"。

四、四大实用工作模式

4.1 模式一：实施前研究

场景：在动手实现之前，需要充分了解现有代码库。

Before I implement user notifications, use a subagent to research:
- How are emails currently sent in this codebase?
- What notification patterns already exist?
- Where should new notification logic live based on the
  current architecture?
Summarize findings, then we'll plan the implementation together.

模式一：实施前研究

优势：主对话不会被数十个文件的内容占满，收到的是提炼后的发现。

4.2 模式二：并行修改

场景：多个文件需要应用相同的模式修改，彼此独立。

Use parallel subagents to update the error handling in these files:
- src/api/users.ts
- src/api/orders.ts
- src/api/products.ts
Each should follow the pattern established in src/api/auth.ts.
Work on all three simultaneously.

模式二：并行修改

关键点：三个文件由三个子代理并行修改，总耗时约等于单个文件的修改时间（而非三倍）。

4.3 模式三：独立审查

场景：需要不受之前对话影响的客观审查。

Use a fresh subagent with read-only access to review my
implementation of the payment flow. It should not see our
previous discussion. I want an unbiased review.

Check for: security vulnerabilities, unhandled edge cases,
and error handling gaps. Be critical.

为什么需要"新上下文"？

为什么独立审查需要"新上下文"

核心洞察：当 Claude 参与了代码的设计和实现过程后，它对自己代码的"审查"往往带有确认偏误。子代理提供了真正的"第二意见"。

4.4 模式四：管道工作流

场景：具有清晰交接的顺序阶段。

管道工作流模式

Let's build this feature as a pipeline:
1. First subagent: Design the API contract and write it to
   docs/api-spec.md
2. Second subagent: Implement the backend endpoints based
   on that spec
3. Third subagent: Write integration tests for the
   implementation
Each stage should complete before the next begins. Use the
output files as the handoff mechanism between stages.

管道模式的精妙之处：

设计要点	说明
顺序执行	每个阶段完成后才启动下一个
文件交接	输出文件（而非对话历史）作为阶段间的交接物
上下文隔离	每个子代理只看到本阶段需要的信息
关注点分离	设计者不关心实现，实现者不关心测试策略

五、何时不使用子代理

了解何时不用与知道何时使用同样重要。

使用决策指南

不适合使用的五种情况

情况	原因	替代方案
顺序依赖的工作	步骤 B 需要步骤 A 的完整输出	单个会话处理链
同文件编辑	两个子代理并行编辑同一文件=冲突	串行处理同一文件
小任务	委派开销超过收益	直接在主对话中完成
太多专业代理	选项过多导致自动委派不可靠	精简代理数量
需要协调的工作	子代理之间无法互相通信	使用代理团队 (Agent Teams)

子代理 vs 代理团队：子代理向主对话报告，但彼此无法交流。如果任务需要代理间协调，应该使用 Agent Teams。

六、最佳实践与工程建议

6.1 渐进式自动化策略

Anthropic 推荐的自动化路径是从临时到永久、从手动到自动：

渐进式自动化路径

实施步骤：

从对话开始：用自然语言请求子代理，观察哪些请求反复出现
固化规则：将重复出现的模式写入 CLAUDE.md
创建专用代理/技能：当模式成熟后，创建可复用的定义
设置自动触发：当确定某些检查必须始终运行时，创建挂钩

6.2 提示词设计原则

编写子代理提示词时，遵循以下原则可显著提升效果：

# 好的提示词结构

## 1. 明确目标
"研究认证模块的实现方式"（而非"看看代码"）

## 2. 指定范围
"只查看 src/auth/ 目录下的文件"

## 3. 定义输出
"返回一个包含文件路径、功能描述和潜在问题的表格"

## 4. 设定约束
"不要修改任何文件，只做只读分析"

原则	好的做法	不好的做法
目标清晰	“查找所有 SQL 注入风险”	“检查代码”
范围明确	“只看 src/api/ 目录”	“看看整个项目”
输出定义	“返回问题列表+修复建议”	“告诉我结果”
权限最小	“只读访问（Read, Grep）”	“给所有工具权限”

6.3 权限管理策略

不同类型的子代理应配置不同的工具权限：

权限管理策略

原则：能用只读就不给编辑权限，能限制工具就不给完整权限。

6.4 后台执行与任务管理

当子代理执行时间较长时，充分利用 Claude Code 的后台能力：

操作	快捷键/命令	说明
后台发送	`Ctrl+B`	当前子代理任务移至后台
查看任务	`/tasks`	查看所有后台运行的任务
继续对话	正常输入	后台任务不阻塞主对话
结果浮现	自动	子代理完成后结果自动返回

6.5 常见陷阱与规避

陷阱	症状	规避方法
上下文浪费	子代理返回大量原始内容	在提示词中要求"返回摘要而非原始内容"
并行冲突	多个子代理修改同一文件	确保并行任务操作不同文件
代理泛滥	自动委派变得不可靠	限制自定义代理数量（5-8 个为宜）
过度委派	简单任务也用子代理	只在 10+ 文件或 3+ 独立任务时启用
权限过松	审查代理意外修改代码	严格配置 tools 白名单

七、总结与关键要点

子代理的核心价值

速查决策树

识别信号：需要探索 10+ 文件？涉及 3+ 独立任务？需要无偏见审查？→ 使用子代理
选择方式：临时使用 → 对话式 | 反复使用 → 自定义代理 | 团队规范 → CLAUDE.md/技能 | 必须执行 → 挂钩
配置权限：只读场景 → Read/Grep/Glob | 编辑场景 → 加上 Write/Bash
管理结果：耗时任务 → Ctrl+B 后台 | 多任务 → /tasks 监控

一句话总结

子代理让你在不丢失主线的情况下并行追逐多条线索——它是 Claude Code 处理复杂任务的核心机制，掌握它等于解锁了 AI 编程的并行化能力。

参考资料

「真诚赞赏，手留余香」

一、引言：为什么需要子代理？

本文导读

二、子代理核心概念与架构设计

2.1 什么是子代理？

2.2 核心特性

2.3 内置子代理类型

三、五种触发子代理的方式

3.1 方式一：对话式调用

有效的自然语言模式

结构化提示词模板

3.2 方式二：自定义子代理

文件位置

创建方式

完整示例：安全审查代理

3.3 方式三：CLAUDE.md 指令

适用场景

示例配置

3.4 方式四：技能 (Skills)

技能 vs CLAUDE.md

示例：深度审查技能

3.5 方式五：挂钩 (Hooks)

适用场景

示例：Stop Hook —— 阻止未通过测试的提交

四、四大实用工作模式

4.1 模式一：实施前研究

4.2 模式二：并行修改

4.3 模式三：独立审查

4.4 模式四：管道工作流

五、何时不使用子代理

不适合使用的五种情况

六、最佳实践与工程建议

6.1 渐进式自动化策略

6.2 提示词设计原则

6.3 权限管理策略

6.4 后台执行与任务管理

6.5 常见陷阱与规避

七、总结与关键要点

子代理的核心价值

速查决策树

一句话总结

参考资料

CATALOG

FEATURED TAGS