Claude Code 进阶：用 Subagents 打造你的 AI 开发团队

发表于 更新于 分类于 阅读次数： 本文字数： 7.5k 阅读时长 ≈ 7 分钟

cover

上周我在用 Claude Code 做一个代码审查任务，让它同时检查安全漏洞、代码风格和测试覆盖率。跑到一半，Claude 开始”忘事”——之前分析过的文件，它又重新问了一遍。上下文窗口撑不住了。

这不是 Claude 的问题，是我用错了方式。

Subagents（子代理）就是为这种场景设计的。三个 Subagents 并行跑，各自有独立的上下文窗口，互不干扰，几秒钟后三份报告同时返回。

根据 Anthropic 的数据，截至 2026 年 2 月，4% 的公开 GitHub 提交是由 Claude Code 创建的，Anthropic 自己 90% 的代码都是 AI 编写的。Subagents 是这个效率背后的关键技术之一。

什么是 Subagents？为什么需要它

先搞清楚一个概念：Subagents 不是”更强大的 Claude”，而是”更多的 Claude”。

传统方式：

你在一个 Claude 会话中做所有事情。分析代码、写新功能、运行测试、生成文档。所有的对话历史、代码内容、分析结果都堆在一个上下文窗口里。

随着任务进行，上下文越来越满。Claude 开始”忘记”之前的内容，或者需要花更多 token 来处理无关信息。

Subagents 方式：

你把任务拆分成多个独立的子任务，每个子任务由一个 Subagent 处理。每个 Subagent 有自己的上下文窗口，只关注自己的任务。

主 Claude 负责协调，Subagents 负责执行。就像一个项目经理带着几个专家团队。

Subagents 的三大优势：

1. 保持上下文清晰

探索代码库、实验性修改、调试输出，这些都不会污染你的主对话。主对话只保留关键决策和最终结果。

2. 并行处理任务

多个 Subagents 可以同时运行。代码审查从”逐个检查”变成”并行扫描”，时间从分钟级降到秒级。

3. 专业化分工

每个 Subagent 可以有专门的系统提示、工具权限、甚至使用不同的模型。安全审查用 Opus（最强），代码格式检查用 Haiku（最快最便宜）。

Subagents 和其他概念的区别

在深入实践之前，我们需要理解 Subagents 和其他概念的区别。

Subagents vs Skills

  • Skills 是知识和流程，告诉 Claude 怎么做事
  • Subagents 是独立的执行者，有自己的上下文和工具

Skills 像是操作手册，Subagents 像是专业团队成员。

Subagents vs MCP

  • MCP 提供外部工具的访问能力
  • Subagents 是独立的 AI 助手，可以使用这些工具

MCP 是工具箱，Subagents 是使用工具的人。

Subagents vs Agent Teams

  • Subagents 在同一个会话中工作，向主 Claude 报告
  • Agent Teams 是多个独立的 Claude 会话，可以互相通信

Subagents 像是一个团队的不同角色，Agent Teams 像是多个独立的团队在协作。

90% 的情况下，你需要的是 Subagents。只有在极其复杂的项目中，才需要 Agent Teams。

内置的 Subagents：开箱即用

Claude Code 自带了三个内置 Subagents，你可以直接使用。

1. Explore（探索者）

用途：快速搜索和分析代码库

特点：

  • 只读权限（Read, Grep, Glob）
  • 不会修改任何文件
  • 专门优化了搜索性能

使用场景：

1
让 Explore 找出所有使用了 useState 的组件
1
用 Explore 分析这个项目的目录结构

Explore 会在独立的上下文中搜索，不会占用你的主对话空间。

2. Plan（规划者）

用途：制定实现方案，不执行代码

特点：

  • 只读权限
  • 专注于分析和规划
  • 给出详细的实现步骤

使用场景：

1
让 Plan 设计一个用户认证模块的实现方案
1
用 Plan 分析如何重构这个组件

Plan 会给你一个清晰的实现计划，然后你可以决定是否执行。

3. general-purpose（通用助手）

用途：处理各种通用任务

特点：

  • 完整的工具权限
  • 可以读写文件、执行命令
  • 适合独立的子任务

使用场景：

1
让 general-purpose 生成测试用例
1
用 general-purpose 更新文档

这三个内置 Subagents 已经能覆盖很多场景。但真正的威力在于创建自定义 Subagents。

实战：创建你的第一个 Subagent

让我们创建一个”代码审查”Subagent，专门用于审查代码质量。

第一步：使用 /agents 命令

在 Claude Code 中输入：

1
/agents

选择 “Create new subagent”，然后选择作用域：

  • user：在所有项目中可用
  • project：只在当前项目中可用

我们选择 user，这样可以在所有项目中使用这个 Subagent。

第二步：定义 Subagent

Claude 会引导你填写信息：

Name（名称）：

1
code-reviewer

Description（描述）：

1
审查代码质量、安全性和最佳实践。检查潜在的 bug、性能问题、安全漏洞。适用于 PR 审查、代码重构前的评估。

描述很重要，Claude 会根据描述判断何时自动调用这个 Subagent。

System Prompt（系统提示）：

Claude 会根据你的描述生成一个系统提示，你可以修改：

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
你是一个代码审查专家，专注于代码质量、安全性和最佳实践。

## 审查重点

### 1. 代码质量
- 可读性：变量命名、函数长度、注释质量
- 可维护性：代码复杂度、重复代码
- 一致性：是否遵循项目的编码规范

### 2. 安全性
- SQL 注入、XSS、CSRF 等常见漏洞
- 敏感信息泄露（API Key、密码）
- 权限检查是否完善

### 3. 性能
- 不必要的循环嵌套
- 数据库查询优化
- 内存泄漏风险

### 4. 最佳实践
- 错误处理是否完善
- 边界条件是否考虑
- 测试覆盖率

## 输出格式

对于每个问题，提供：
1. 问题描述
2. 代码位置（文件名:行号）
3. 严重程度（高/中/低）
4. 建议的修复方案
5. 示例代码（如果适用）

## 注意事项

- 只指出真正的问题，不要吹毛求疵
- 提供具体的改进建议，不要只说"这里不好"
- 考虑项目的实际情况，不要教条主义

第三步：配置工具和模型

Tools（工具权限）：

代码审查只需要读取权限：

1
Read, Grep, Glob

不给 Write、Edit、Bash 权限，确保 Subagent 不会修改代码。

Model（模型）：

代码审查需要较强的推理能力，选择 sonnet：

1
sonnet

如果预算紧张，可以用 haiku，但质量会稍差。

第四步：保存和测试

保存后，Subagent 会被创建在 ~/.claude/agents/code-reviewer/AGENT.md。

测试一下：

1
让 code-reviewer 审查 src/auth/login.js

Claude 会调用你的 Subagent，在独立的上下文中审查代码，然后返回报告。

手动创建 Subagent：理解 AGENT.md 结构

如果你想更精细地控制 Subagent，可以手动创建 AGENT.md 文件。

文件位置

用户级（所有项目可用）：

1
~/.claude/agents/subagent-name/AGENT.md

项目级（只在当前项目可用）：

1
project/.claude/agents/subagent-name/AGENT.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
---
name: security-scanner
description: 扫描代码中的安全漏洞，包括 SQL 注入、XSS、CSRF、敏感信息泄露等。适用于上线前的安全检查。
tools:
  - Read
  - Grep
  - Glob
model: sonnet
memory: true
---

你是一个安全专家，专门检测代码中的安全漏洞。

## 检查清单

### SQL 注入
- 检查是否使用了参数化查询
- 查找字符串拼接的 SQL 语句

### XSS（跨站脚本）
- 检查用户输入是否经过转义
- 查找直接插入 HTML 的变量

### 敏感信息
- 查找硬编码的 API Key、密码、Token
- 检查是否使用了环境变量

### 权限控制
- 检查是否有权限验证
- 查找可能的越权访问

## 输出格式

每个漏洞包含：
- 漏洞类型
- 风险等级（严重/高/中/低）
- 文件位置
- 代码片段
- 修复建议

Frontmatter 字段说明

name（必需）：Subagent 的名称，用于调用

description（必需）：描述何时使用这个 Subagent，Claude 根据这个判断是否自动调用

tools（可选）：限制 Subagent 可以使用的工具

  • 不指定：继承所有可用工具
  • 指定列表：只能使用列表中的工具
  • 常用工具：Read, Write, Edit, Bash, Grep, Glob

model（可选）：指定使用的模型

  • haiku：最快最便宜，适合简单任务
  • sonnet：平衡性能和成本（默认）
  • opus：最强推理能力，适合复杂任务

memory（可选）：是否启用记忆功能

  • true：Subagent 可以记住之前的发现和模式
  • false：每次都是全新的上下文（默认）

并行运行多个 Subagents

Subagents 的真正威力在于并行处理。

场景：全面代码审查

你可以同时运行多个 Subagents，每个关注不同方面：

1
2
3
4
5
6
7
同时运行以下审查：
1. code-reviewer 检查代码质量
2. security-scanner 检查安全漏洞
3. performance-analyzer 检查性能问题
4. test-coverage 检查测试覆盖率

审查 src/api/ 目录下的所有文件

Claude 会并行启动这四个 Subagents，每个在独立的上下文中工作。几秒钟后，你会收到四份独立的报告。

场景：多语言项目分析

1
2
3
4
并行分析：
1. 用 frontend-analyzer 分析 React 组件
2. 用 backend-analyzer 分析 Node.js API
3. 用 database-analyzer 分析 SQL 迁移文件

每个 Subagent 专注于自己熟悉的领域，效率远高于一个通用 Agent。

性能对比

传统方式（单个 Claude）：

  • 逐个检查每个文件
  • 所有分析结果堆在一个上下文中
  • 总耗时：5-10 分钟

Subagents 并行方式：

  • 多个 Subagents 同时工作
  • 每个有独立的上下文
  • 总耗时：30-60 秒

速度提升 5-10 倍。

高级技巧

技巧一：成本优化

不同的任务用不同的模型：

1
2
3
4
---
name: style-checker
model: haiku  # 简单的格式检查，用最便宜的模型
---
1
2
3
4
---
name: architecture-reviewer
model: opus  # 复杂的架构分析，用最强的模型
---

Haiku 的成本是 Opus 的 1/5。合理分配模型可以大幅降低成本。

技巧二：工具权限最小化

只给 Subagent 必需的权限：

1
2
3
4
5
6
7
---
name: log-analyzer
tools:
  - Read
  - Grep
# 不给 Write、Edit、Bash，确保只读
---

这样可以防止 Subagent 意外修改文件或执行危险命令。

技巧三：启用记忆功能

对于需要学习项目模式的 Subagent，启用记忆：

1
2
3
4
5
6
7
8
9
10
11
---
name: code-reviewer
memory: true
---

在审查过程中，记录：
- 项目的编码规范
- 常见的问题模式
- 团队的偏好

下次审查时，参考这些记忆，提供更符合项目风格的建议。

Subagent 会在 ~/.claude/agents/code-reviewer/memory/ 目录下保存记忆。

技巧四：与 MCP 集成

Subagent 可以使用 MCP 工具：

1
2
3
4
5
6
7
8
9
10
11
12
13
---
name: github-pr-reviewer
tools:
  - Read
  - Grep
---

## 审查流程

1. 使用 `mcp__github__get_pull_request` 获取 PR 信息
2. 使用 `mcp__github__list_pr_files` 查看修改的文件
3. 审查每个文件的改动
4. 使用 `mcp__github__create_review_comment` 添加评论

Subagent 可以自动完成整个 PR 审查流程。

最佳实践

1. 一个 Subagent 一个职责

不要创建”万能 Subagent”。每个 Subagent 应该专注于一个明确的任务。

好的例子：

  • security-scanner：只检查安全问题
  • performance-analyzer：只分析性能
  • test-generator：只生成测试用例

不好的例子：

  • code-helper：什么都做

职责单一的 Subagent 更容易维护，Claude 也更容易判断何时调用。

2. 写清楚 description

description 是 Claude 判断何时调用 Subagent 的关键。要包含：

  • 这个 Subagent 做什么
  • 什么时候使用
  • 相关的关键词

好的 description：

1
description: 扫描代码中的安全漏洞，包括 SQL 注入、XSS、CSRF、敏感信息泄露。适用于上线前的安全检查、PR 审查、代码审计。关键词：安全、漏洞、注入、XSS

不好的 description：

1
description: 检查代码

3. 限制工具权限

遵循最小权限原则。只给 Subagent 必需的工具。

  • 只读任务：Read, Grep, Glob
  • 代码生成：Read, Write, Grep, Glob
  • 完整任务：Read, Write, Edit, Bash, Grep, Glob

不要给所有 Subagent 完整权限。

4. 合理选择模型

根据任务复杂度选择模型：

  • Haiku：格式检查、简单搜索、日志分析
  • Sonnet：代码审查、重构建议、测试生成（默认）
  • Opus：架构设计、复杂问题诊断、安全审计

成本差异：Haiku < Sonnet < Opus（1:3:5）

5. 提供清晰的输出格式

在系统提示中定义输出格式，让结果更易读：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
## 输出格式

### 问题列表

每个问题包含：
1. 标题：简短描述问题
2. 位置：文件名:行号
3. 严重程度：🔴 严重 / 🟡 中等 / 🟢 轻微
4. 详细说明：为什么这是个问题
5. 修复建议：具体的改进方案

### 总结

- 发现的问题总数
- 按严重程度分类统计
- 优先修复建议

6. 版本控制 Subagent 配置

把项目级 Subagent 提交到 Git：

1
2
git add .claude/agents/
git commit -m "feat: add custom subagents for code review"

这样团队成员都能使用相同的 Subagents。

常见问题排查

问题 1：Subagent 没有被自动调用

症状：你创建了 Subagent，但 Claude 从不自动使用它。

原因：description 不够清晰，或者与任务不匹配。

解决：

  1. 检查 description 是否包含关键词
  2. 尝试显式调用：让 code-reviewer 审查这个文件
  3. 如果显式调用有效，说明 Subagent 本身没问题，需要改进 description

问题 2：Subagent 权限不足

症状：Subagent 尝试执行操作，但提示权限不足。

原因：tools 字段限制了权限。

解决：

编辑 AGENT.md，添加需要的工具：

1
2
3
4
5
tools:
  - Read
  - Write  # 添加写权限
  - Grep
  - Glob

问题 3：Subagent 成本太高

症状：使用 Subagents 后，token 消耗大幅增加。

原因：所有 Subagents 都用了 Opus 模型，或者创建了太多 Subagents。

解决：

  1. 检查每个 Subagent 的 model 字段，改用 Haiku 或 Sonnet
  2. 合并功能相似的 Subagents
  3. 只在必要时并行运行多个 Subagents

问题 4：Subagent 结果不一致

症状：同样的任务，Subagent 每次给出不同的结果。

原因：系统提示不够具体，或者没有启用记忆功能。

解决：

  1. 在系统提示中提供更具体的检查清单
  2. 启用记忆功能：memory: true
  3. 提供示例输出，让 Subagent 理解预期格式

实际应用场景

场景一：代码审查流水线

创建一套 Subagents，覆盖代码审查的各个方面：

1
2
3
4
5
6
并行运行：
1. style-checker（Haiku）：检查代码风格
2. security-scanner（Sonnet）：检查安全漏洞
3. performance-analyzer（Sonnet）：分析性能问题
4. test-coverage（Haiku）：检查测试覆盖率
5. documentation-checker（Haiku）：检查文档完整性

5 个 Subagents 并行运行，30 秒内完成全面审查。

场景二：多语言项目维护

为不同的技术栈创建专门的 Subagents：

  • react-expert：审查 React 组件
  • nodejs-expert：审查 Node.js 后端
  • sql-expert：审查数据库查询
  • docker-expert：审查容器配置

每个 Subagent 有专门的知识和最佳实践。

场景三：自动化文档生成

1
2
3
4
1. code-analyzer：分析代码结构
2. api-doc-generator：生成 API 文档
3. readme-updater：更新 README
4. changelog-generator：生成 CHANGELOG

一条命令，自动生成完整的项目文档。

场景四：持续集成检查

在 CI/CD 流程中使用 Subagents：

1
2
3
4
# .github/workflows/code-review.yml
- name: Run Claude Code Review
  run: |
    claude "并行运行 security-scanner 和 performance-analyzer，审查本次 PR 的所有改动"

自动化的代码质量检查。

写在最后

我现在的工作流里有三个常驻 Subagents：一个专门做安全扫描，一个做测试覆盖率检查，一个做文档同步。每次提交前并行跑一遍，大概 40 秒出结果。

这三个 Subagents 解决的都是我之前觉得”太烦了懒得做”的事情。不是因为它们难，而是因为每次手动做都要打断思路。现在它们在后台跑，我继续写代码。

创建 Subagent 的过程，其实是在逼自己想清楚：哪些工作是重复的？哪些可以并行？哪些需要专门的知识？把这些梳理清楚，创建对应的 Subagents，效率提升是实实在在的。

从一个开始。代码风格检查、测试用例生成，随便哪个都行。跑几次之后，你会自然知道下一个该创建什么。