Claude Code Subagent：让 AI 学会”分身术”

作者

Subagent 解决的核心问题：让多个 AI 并行工作，而不是串行等待。

适合的场景：

  • 大型项目的代码搜索和分析
  • 批量文件修改和重构
  • 同时调研多个技术方案
  • 需要同时处理多个独立子任务的复杂工作

不适合的场景：

  • 简单的单文件修改
  • 有严格先后依赖的任务
  • 需要频繁人工确认的交互式工作

什么是 Subagent？

简单说，Subagent 就是 Claude Code 的”小助手团队”。

当你给 Claude Code 一个复杂任务时，它不会傻傻地一步步串行执行，而是会聪明地把任务拆分，派出多个专门的 Subagent 同时处理不同的子任务。

每个 Subagent 都有自己独立的 200K 上下文窗口，这意味着它们可以各自深入处理大量信息，最后再把结果汇总给主 Agent。

就像一个高效的项目经理，知道什么时候该亲自上阵，什么时候该分配给团队成员。

三种内置 Subagent

Claude Code 内置了三种 Subagent，各有专长：

1. Explore Agent（探索者）

专长：快速搜索和理解代码库

这是一个只读型的轻量级 Agent，擅长：

  • 快速定位文件和函数
  • 搜索代码模式
  • 理解项目结构

当你问”这个项目的认证逻辑在哪里”时，Claude Code 会派出 Explore Agent，它能在几秒内扫描整个代码库给你答案。

2. Plan Agent（规划者）

专长：设计实现方案

在动手写代码之前，Plan Agent 会先帮你：

  • 分析需求
  • 识别关键文件
  • 规划实现步骤
  • 评估技术方案

这就像请了一个软件架构师，先帮你想清楚再动手。

3. General-purpose Agent（通用型）

专长：处理复杂的多步骤任务

当任务既需要搜索又需要修改，或者需要复杂推理时，这个全能选手就会出场。它拥有完整的工具访问权限，可以独立完成端到端的任务。

最佳使用场景

场景一：大规模代码搜索

痛点：在大型项目中找特定的代码实现，像大海捞针

用法：直接描述你要找什么，让 Claude Code 并行派出多个 Explore Agent

"找出所有处理用户权限的代码，包括前端和后端"

Claude Code 会同时搜索多个目录，几秒内给你完整清单。

场景二：批量文件修改

痛点：重命名函数、更新 API、修改配置……要改的文件太多

用法：描述修改需求，Claude Code 会自动并行处理

"把所有文件中的 getUserInfo 改成 fetchUserProfile，保持调用方式不变"

场景三：多维度代码分析

痛点：要同时了解项目的多个方面

用法：一次性提出多个问题

"帮我分析这个项目：
1. 整体架构是什么
2. 数据库用的什么方案
3. 有哪些第三方依赖
4. 测试覆盖率如何"

四个问题会被四个 Subagent 并行处理，一次性返回所有答案。

场景四：深度研究任务

痛点：需要综合多个来源的信息做决策

用法：让 Claude Code 帮你做调研

"对比 Redis 和 Memcached 在我们这个场景下的优劣，结合项目现状给出建议"

进阶技巧：自定义 Subagent

内置的三种 Subagent 不够用？你可以创建自己的专属”员工”。

方式一：本地创建

在项目的 .claude/agents/ 目录下创建 Markdown 文件：

---
name: code-reviewer
description: 专门审查代码质量、安全漏洞和性能问题
tools:
  - Read
  - Grep
  - Glob
---

你是一个资深代码审查专家。审查时重点关注：
1. 安全漏洞（SQL注入、XSS等）
2. 性能瓶颈
3. 代码规范
4. 潜在的 bug

输出格式：按严重程度分级列出问题。

保存后，Claude Code 会自动识别并在合适的时候调用它。

方式二：通过 Plugin 打包分发

如果你想把 Subagent 分享给团队或社区，可以打包成 Plugin：

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # 插件清单
├── agents/              # 你的 Subagents
│   ├── code-reviewer.md
│   ├── test-writer.md
│   └── doc-generator.md
├── skills/              # 配套技能
└── commands/            # 斜杠命令

别人只需运行 /plugin install 就能用上你的全套工具。

自定义 Subagent 的最佳场景

场景一：团队代码规范检查

每个团队都有自己的编码规范。创建一个懂你们规范的 Subagent：

---
name: style-checker
description: 检查代码是否符合团队规范
tools: [Read, Grep]
---

按照以下团队规范检查代码：
- 函数命名使用 camelCase
- 组件文件使用 PascalCase
- 禁止使用 any 类型
- 必须有错误处理
...

场景二：特定框架的专家

为你常用的框架创建专属助手：

---
name: nextjs-expert
description: Next.js 项目开发专家，熟悉 App Router 和服务端组件
tools: [Read, Grep, Glob, Bash]
---

你是 Next.js 14+ 专家，精通：
- App Router 路由设计
- Server Components vs Client Components
- 数据获取最佳实践
- 性能优化技巧

场景三：自动化测试生成

让 Subagent 帮你写测试：

---
name: test-generator
description: 根据源代码自动生成单元测试
tools: [Read, Write, Glob]
---

分析给定的代码文件，生成对应的单元测试：
- 使用 Jest + Testing Library
- 覆盖正常流程和边界情况
- Mock 外部依赖
- 遵循 AAA 模式（Arrange-Act-Assert）

场景四：文档同步更新

代码改了，文档忘了更新？

---
name: doc-syncer
description: 检查代码变更并更新相关文档
tools: [Read, Write, Grep, Glob]
---

当代码发生变更时：
1. 识别影响的 API 或功能
2. 找到相关文档文件
3. 更新文档内容保持同步
4. 标注变更日期

场景五：调用 Codex CLI 完成单一编码任务

有时候你需要一个专注于单一编码任务的 Subagent，比如生成特定格式的代码、转换数据结构、或者批量处理模板代码。可以创建一个调用 OpenAI Codex CLI 的 Subagent：

---
name: codex-coder
description: 调用 Codex CLI 完成单一、专注的编码任务
tools: [Bash, Read, Write]
---

你是一个代码生成专家，通过调用 Codex CLI 完成单一编码任务。

工作流程：
1. 理解用户的编码需求
2. 使用 Codex CLI 执行任务
3. 验证并整合输出结果

Codex CLI 基本用法：

# 直接执行编码任务（非交互模式）
codex -q "将这个函数转换为 TypeScript 并添加类型注解"

# 指定工作目录
codex -q "重构 utils 目录下的代码" --cd ./src/utils

# 使用全自动模式（自动批准所有操作）
codex -q "生成单元测试" --full-auto

# 指定模型
codex -q "优化这段代码的性能" --model o3

适用任务：
- 代码语言转换（Python → TypeScript）
- 生成样板代码（CRUD、DTO、Schema）
- 批量格式转换（JSON → YAML、CSV → JSON）
- 自动生成单元测试
- 代码重构和优化

实际使用示例：

假设你需要批量将 JavaScript 代码转换为 TypeScript：

"用 codex-coder 把 src/utils 目录下所有的 .js 文件转换成 .ts，添加类型注解"

Claude Code 会派出这个 Subagent，它会执行：

# 进入目标目录，使用 codex 完成转换
codex -q "将当前目录下所有 .js 文件转换为 .ts，添加完整的 TypeScript 类型注解" \
  --cd ./src/utils \
  --full-auto

Codex CLI 常用参数：

参数说明
-q "prompt"非交互模式，直接执行任务
--full-auto全自动模式，自动批准所有文件操作
--cd <path>指定工作目录
--model <name>指定模型（o3, o4-mini 等）
--quiet静默模式，只输出结果

进阶：结合本地模型

如果你有本地部署的代码模型（如 CodeLlama、StarCoder），可以使用 Ollama：

---
name: local-coder
description: 调用本地代码模型完成编码任务，无需联网
tools: [Bash, Read, Write]
---

使用 Ollama 调用本地模型：

# 直接生成代码
ollama run codellama "为这个函数添加错误处理"

# 管道方式处理文件
cat input.js | ollama run codellama "转换为 TypeScript" > output.ts

优势：
- 无需 API 费用
- 数据不出本地，更安全
- 响应更快，无网络延迟

这种方式特别适合：

  • 公司内网环境
  • 敏感代码处理
  • 高频调用场景

写在最后

Subagent 不只是一个效率工具，它代表了 AI 辅助编程的一个重要方向：从单一助手到智能团队。

圣诞老人不会亲自包装每一份礼物，他有精灵帮忙。同样，高效使用 Claude Code 的关键，就是学会让它”分身”。

下次遇到复杂任务，不妨试试这句话：

“帮我并行处理这些任务……”

你会发现，AI 的效率上限，远比你想象的高。

发表评论