第五章. 子代理（Subagents）

本章学习路径

5.1. 内置子代理解析

在学习如何创建自定义子代理之前，我们先来看看 Claude Code 自带的三个内置子代理。理解它们的设计思路，有助于我们创建更好的自定义子代理。

5.1.1. Explore 子代理：只读探索专家

“我想让 Claude 帮我找一下项目里所有处理用户认证的代码，但不要改任何东西。”

这种 “只看不摸” 的需求，就是 Explore 子代理的专长。

核心特点：

允许的 Bash 命令：

Explore 子代理只能执行这些只读命令：

• ls —— 列出文件
• git status / git log / git diff —— 查看 Git 状态
• find —— 查找文件
• cat / head / tail —— 查看文件内容

触发方式：

Claude 会自动判断何时使用 Explore 子代理。当你的请求是 “查找”、“搜索”、“分析” 类型时，它会自动委派给 Explore。

你也可以显式指定：

1

› 用 Explore 子代理帮我找一下所有包含 "TODO" 的文件

5.1.2. Plan 子代理：规划模式助手

“我想让 Claude 先分析一下这个重构任务，给我一个方案，但先别动手。”，在旧版本中通过 Shift + Tab 在不同的 权限模式 之间 循环 切换

但现在 claude 简化了这个规则，只要语义中与“规划”，“Plan”相关都可以进入规划模式

核心特点：

工作流程：

1. 你切换到 plan 模式
2. 你提出一个任务（如 “重构用户模块”）
3. Claude 委派给 Plan 子代理进行代码分析
4. Plan 子代理返回分析结果
5. Claude 基于分析结果给你一个重构方案

5.1.3. General-purpose 子代理：通用任务执行者

“这个任务比较复杂，需要先搜索代码、再修改文件、最后运行测试。”

General-purpose 子代理是一个 “全能型” 助手，可以执行复杂的多步骤任务。

核心特点：

与主 Claude 的区别：

General-purpose 子代理运行在 独立的上下文 中。这意味着：

• 它不会污染主对话的上下文
• 它可以进行大量的探索和尝试，而不会让主对话变得冗长
• 任务完成后，只有结果会返回给主对话

5.1.4. 本节小结

三个内置子代理的定位：

5.2. 自定义子代理

内置子代理覆盖了通用场景，但你可能有更专业的需求：

• “我想要一个专门做代码审查的子代理，它知道我们团队的代码规范”
• “我想要一个专门写测试的子代理，它熟悉我们的测试框架”
• “我想要一个专门分析数据的子代理，它会用 SQL 和 Python”

这就需要创建 自定义子代理。

5.2.1. 文件格式与存放位置

子代理配置是一个 Markdown 文件，包含 YAML 前置元数据和系统提示词。

存放位置：

优先级：项目级 > 用户级。如果两个位置有同名子代理，项目级的会覆盖用户级的。

文件命名：

文件名就是子代理的名称。例如 code-reviewer.md 创建的子代理名为 code-reviewer。

5.2.2. 配置字段详解

一个完整的子代理配置文件结构如下：

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

---
name: your-agent-name
description: 描述这个子代理的用途和触发场景
tools: Tool1, Tool2, Tool3
model: sonnet
permissionMode: default
skills: skill1, skill2
---

这里是子代理的系统提示词。

你可以用多个段落详细描述子代理的角色、能力和行为准则。

字段说明：

5.2.3. 工具权限控制

tools 字段决定了子代理能使用哪些工具。这是一个重要的安全机制。

示例 1：只读子代理

1

tools: Read, Grep, Glob, Bash

注意：即使列出了 Bash，子代理也只能执行只读命令（如 ls、cat），因为写入类命令需要 Write 或 Edit 工具。

示例 2：代码修改子代理

1

tools: Read, Edit, Write,Grep, Glob, Bash

这个子代理可以读取、修改文件，也可以执行命令。

示例 3：数据分析子代理

1

tools: Read, Bash, Write

只给它读取数据、执行分析脚本、输出结果的能力，不给它修改源代码的能力。

5.2.4. 本节小结

自定义子代理的核心配置：

5.3. 实战：创建代码审查子代理

理论讲完了，现在来实战创建一个专门做代码审查的子代理。

5.3.1. 需求分析

我们想要一个子代理，它能够：

• 自动检查最近的代码变更（git diff）
• 按照团队的代码规范进行审查
• 输出结构化的审查报告（分为 “必须修复”、“建议修复”、“可选优化”）
• 只读不写——它只负责发现问题，不负责修复

5.3.2. 编写配置文件

步骤 1：创建目录（项目级）

1

mkdir -p .claude/agents

步骤 2：创建配置文件

创建文件 .claude/agents/code-reviewer.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

---
name: code-reviewer
description: 代码审查专家。在代码变更后主动审查代码质量、安全性和可维护性。当用户提交代码、完成功能开发或请求代码审查时使用。
tools: Read, Grep, Glob, Bash
---

# 角色定义

你是一位资深代码审查专家，专注于代码质量、安全性和最佳实践。

# 工作流程

当被调用时，按以下步骤执行：

1. 运行 `git diff HEAD~1` 查看最近的代码变更
2. 如果变更文件较多，先用 `git diff --stat` 获取概览
3. 逐个分析修改的文件
4. 生成结构化的审查报告

# 审查清单

## 代码质量
- 代码是否清晰易读
- 函数和变量命名是否合理
- 是否存在重复代码
- 错误处理是否完善

## 安全性
- 是否存在硬编码的密钥或密码
- 输入验证是否充分
- 是否存在 SQL 注入、XSS 等风险

## 性能
- 是否存在明显的性能问题
- 数据库查询是否优化
- 是否有不必要的循环或计算

# 输出格式

按以下格式输出审查结果：

## 🔴 必须修复（Critical）
[列出必须修复的问题，包含文件路径和行号]

## 🟡 建议修复（Warning）
[列出建议修复的问题]

## 🟢 可选优化（Suggestion）
[列出可以优化但不紧急的点]

## 📊 总结
[一句话总结代码质量]

5.3.3. 测试与调优

步骤 1：验证子代理已加载

1

› /agents

你应该能在列表中看到 code-reviewer。

步骤 2：显式调用测试

1

› 用 code-reviewer 子代理审查一下我最近的代码变更

步骤 3：观察输出

Claude 会委派任务给 code-reviewer 子代理，子代理会：

1. 执行 git diff 获取变更
2. 分析每个修改的文件
3. 输出结构化的审查报告

步骤 4：根据实际效果调优

如果发现子代理的输出不符合预期，可以调整配置文件中的系统提示词。常见的调优方向：

• 审查清单不够全面 → 补充更多检查项
• 输出格式不够清晰 → 调整输出格式模板
• 漏掉了某类问题 → 在提示词中强调该类问题

5.3.4. 本节小结

创建自定义子代理的流程：

5.4. 本章总结与子代理速查

本章我们学习了子代理（Subagents）机制——创建专门的 “专家” 来处理特定类型的任务。核心思想是：让专业的人做专业的事，同时保持主对话的上下文清洁。

5.4.1. 场景速查：遇到这些情况，直接用

场景 1：创建只读探索子代理

创建 .claude/agents/explorer.md：

1
2
3
4
5
6
7
8
9

---
name: explorer
description: 代码探索专家。用于搜索和分析代码，不做任何修改。
tools: Read, Grep, Glob, Bash
model: haiku
---

你是一个代码探索专家，只负责搜索和分析，不做任何修改。
使用 Grep 搜索关键词，使用 Glob 查找文件，使用 Read 阅读内容。

场景 2：创建测试运行子代理

创建 .claude/agents/test-runner.md：

1
2
3
4
5
6
7
8
9
10
11

---
name: test-runner
description: 测试专家。运行测试并分析失败原因。当需要运行测试或分析测试失败时使用。
tools: Read, Bash, Grep
model: sonnet
---

你是一个测试专家。当被调用时：
1. 运行 `npm test` 或相应的测试命令
2. 如果有失败，分析失败原因
3. 给出修复建议（但不要直接修改代码）

场景 3：创建文档生成子代理

创建 .claude/agents/doc-writer.md：

1
2
3
4
5
6
7
8
9
10

---
name: doc-writer
description: 文档专家。生成或更新项目文档。当需要编写 README、API 文档时使用。
tools: Read, Write, Glob
model: sonnet
---

你是一个技术文档专家。
阅读代码后生成清晰、准确的文档。
遵循 Markdown 格式，包含代码示例。

场景 4：查看所有可用子代理

1

› /agents

场景 5：显式调用特定子代理

1
2
3

› 用 code-reviewer 子代理审查这段代码
› 让 test-runner 子代理跑一下测试
› 请 doc-writer 子代理更新 README