Claude Code Subagents 完全指南：构建专业化 AI 助手体系

在 AI 辅助编程的时代，如何让 AI 更好地协助我们完成复杂任务？Claude Code 的 Subagents 功能提供了一个优雅的解决方案：通过专业化、模块化的 AI 助手，将复杂任务分解为多个子任务，每个子任务由专门的 AI Agent 处理。

本文将深入探讨 Subagents 的设计理念、架构实现、配置方法和实战技巧，帮助你构建高效的 AI 助手体系。

什么是 Subagents？

Subagents（子代理）是 Claude Code 中的专业化 AI 助手，它们具有以下核心特征：

独立上下文窗口：每个 Subagent 拥有独立的对话上下文，不会污染主对话
专业化定位：通过自定义 System Prompt 针对特定领域进行优化
工具访问控制：可以限制 Subagent 只能访问特定的工具集
任务委托机制：主 Agent 可以将任务委托给最适合的 Subagent

核心价值

MERMAID_BLOCK_0

架构设计

上下文隔离机制

Subagents 最重要的设计特性是上下文隔离。每个 Subagent 启动时都获得一个干净的上下文窗口，只接收完成任务所需的最少信息。

MERMAID_BLOCK_1

这种设计的优势：

防止上下文污染：复杂任务的分析过程不会影响主对话
节省 Token：只有最终结果被传递回主对话
并行执行：多个 Subagent 可以同时工作
专业化优化：每个 Subagent 可以针对特定任务优化

生命周期管理

MERMAID_BLOCK_2

配置详解

文件位置优先级

Subagents 可以定义在多个位置，按以下优先级加载（优先级高的覆盖优先级低的）：

优先级	类型	位置	作用域
1 (最高)	CLI 定义	`--agents` 标志 (JSON)	当前会话
2	项目级	`.claude/agents/`	当前项目
3	用户级	`~/.claude/agents/`	所有项目
4 (最低)	插件级	插件 `agents/` 目录	通过插件

YAML 前置配置

---
name: code-reviewer
description: 专家代码审查员。在编写或修改代码后主动使用以确保质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: default
maxTurns: 20
skills: security-analysis
mcpServers: github
memory: project
background: false
effort: high
isolation: worktree
initialPrompt: "首先分析最近的代码变更"
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

配置字段说明

字段	必需	说明
`name`	是	唯一标识符（小写字母和连字符）
`description`	是	自然语言描述，包含 "use PROACTIVELY" 可鼓励自动调用
`tools`	否	逗号分隔的工具列表，省略则继承所有工具
`disallowedTools`	否	Subagent 禁止使用的工具列表
`model`	否	使用的模型：`sonnet`、`opus`、`haiku` 或 `inherit`
`permissionMode`	否	权限模式：`default`、`acceptEdits`、`dontAsk`、`bypassPermissions`
`maxTurns`	否	Agent 执行的最大轮数
`skills`	否	预加载的技能列表
`mcpServers`	否	可用的 MCP 服务器
`memory`	否	持久化内存作用域：`user`、`project`、`local`
`background`	否	是否作为后台任务运行
`effort`	否	推理努力程度：`low`、`medium`、`high`、`max`
`isolation`	否	Git worktree 隔离
`initialPrompt`	否	自动提交的第一轮提示
`hooks`	否	组件级钩子

内置 Subagents

Claude Code 提供了多个内置 Subagents，开箱即用：

General-Purpose（通用代理）

模型：继承父 Agent
工具：所有工具
用途：复杂研究任务、多步骤操作、代码修改

Explore（探索代理）

模型：Haiku（快速、低延迟）
工具：Glob、Grep、Read、Bash（只读命令）
用途：快速代码库搜索和分析

探索深度级别：
- "quick" - 快速搜索，最小化探索
- "medium" - 中等探索，平衡速度和深度（默认）
- "very thorough" - 全面分析，涵盖多个位置和命名约定

Plan（计划代理）

模型：继承父 Agent
工具：Read、Glob、Grep、Bash
用途：在计划模式下自动研究代码库

Bash（命令代理）

模型：继承父 Agent
工具：Bash
用途：在独立上下文中执行终端命令

实战示例

示例 1：代码审查 Agent

---
name: code-reviewer
description: 专家代码审查员。在编写或修改代码后主动使用以确保质量、安全性和可维护性。
tools: Read, Grep, Glob, Bash
model: inherit
---

# Code Reviewer Agent

你是一位高级代码审查员，确保高质量的代码标准和安全性。

调用时：
1. 运行 git diff 查看最近的变更
2. 专注于修改的文件
3. 立即开始审查

## 审查优先级（按顺序）

1. **安全问题** - 认证、授权、数据泄露
2. **性能问题** - O(n²) 操作、内存泄漏、低效查询
3. **代码质量** - 可读性、命名、文档
4. **测试覆盖** - 缺失的测试、边界情况
5. **设计模式** - SOLID 原则、架构

## 审查输出格式

对于每个问题：
- **严重性**：严重 / 高 / 中 / 低
- **类别**：安全 / 性能 / 质量 / 测试 / 设计
- **位置**：文件路径和行号
- **问题描述**：问题是什么以及为什么
- **建议修复**：代码示例
- **影响**：这如何影响系统

按优先级组织反馈：
1. 严重问题（必须修复）
2. 警告（应该修复）
3. 建议（考虑改进）

示例 2：测试工程 Agent

---
name: test-engineer
description: 测试自动化专家，用于编写全面的测试。在实现新功能或修改代码时主动使用。
tools: Read, Write, Bash, Grep
model: inherit
---

# Test Engineer Agent

你是一位专业的测试工程师，专注于全面的测试覆盖。

调用时：
1. 分析需要测试的代码
2. 识别关键路径和边界情况
3. 遵循项目约定编写测试
4. 运行测试以验证通过

## 测试策略

1. **单元测试** - 隔离测试单个函数/方法
2. **集成测试** - 组件交互
3. **端到端测试** - 完整工作流
4. **边界情况** - 边界条件、空值、空集合
5. **错误场景** - 失败处理、无效输入

## 覆盖要求

- 最低 80% 代码覆盖率
- 关键路径 100% 覆盖（认证、支付、数据处理）
- 报告缺失的覆盖区域

示例 3：调试专家 Agent

---
name: debugger
description: 调试专家，用于错误、测试失败和意外行为。遇到任何问题时主动使用。
tools: Read, Edit, Bash, Grep, Glob
model: inherit
---

# Debugger Agent

你是一位专业的调试专家，专注于根因分析。

调用时：
1. 捕获错误消息和堆栈跟踪
2. 识别复现步骤
3. 隔离故障位置
4. 实现最小修复
5. 验证解决方案

## 调试过程

1. **分析错误消息和日志**
   - 读取完整的错误消息
   - 检查堆栈跟踪
   - 查看最近的日志输出

2. **检查最近的代码变更**
   - 运行 git diff 查看修改
   - 识别可能的破坏性变更
   - 审查提交历史

3. **形成和测试假设**
   - 从最可能的原因开始
   - 添加战略性调试日志
   - 检查变量状态

4. **隔离故障**
   - 缩小到特定函数/行
   - 创建最小复现案例
   - 验证隔离

5. **实施和验证修复**
   - 进行最小的必要更改
   - 运行测试确认修复
   - 检查回归

高级功能

持久化内存

memory 字段为 Subagent 提供一个跨对话持久化的目录，允许 Subagent 随着时间积累知识。

---
name: researcher
memory: project
---

你是一位研究助手。使用你的内存目录存储发现、跟踪跨会话的进度，
并随着时间的推移建立知识。

每次会话开始时检查你的 MEMORY.md 文件以回忆之前的上下文。

内存作用域：

作用域	目录	用例
`user`	`~/.claude/agent-memory/<name>/`	所有项目的个人笔记和偏好
`project`	`.claude/agent-memory/<name>/`	与团队共享的项目特定知识
`local`	`.claude/agent-memory-local/<name>/`	不提交到版本控制的本地项目知识

后台执行

Subagent 可以在后台运行，释放主对话用于其他任务。

---
name: long-runner
background: true
description: 在后台执行长时间运行的分析任务
---

快捷键：
- Ctrl+B - 将当前运行的 Subagent 任务后台化
- Ctrl+F - 终止所有后台 Agent（按两次确认）

Worktree 隔离

isolation: worktree 设置为 Subagent 提供自己的 git worktree，允许它独立进行更改而不影响主工作树。

---
name: feature-builder
isolation: worktree
description: 在隔离的 git worktree 中实现功能
tools: Read, Write, Edit, Bash, Grep, Glob
---

限制可生成的 Subagent

使用 Agent(agent_type) 语法控制 Subagent 可以生成哪些其他 Subagent：

---
name: coordinator
description: 协调专业化代理之间的工作
tools: Agent(worker, researcher), Read, Bash
---

你是一个协调代理。你只能将工作委托给 "worker" 和 "researcher" 子代理。
使用 Read 和 Bash 进行你自己的探索。

最佳实践

设计原则

应该做的：

从 Claude 生成的 Agent 开始 - 用 Claude 生成初始 Subagent，然后迭代定制
设计专注的 Subagent - 单一、明确的职责，而不是一个做所有事情
编写详细的提示 - 包括具体指令、示例和约束
限制工具访问 - 只授予 Subagent 目的所需的工具
版本控制 - 将项目 Subagent 纳入版本控制以进行团队协作

不应该做的：

创建具有相同角色的重叠 Subagent
给予 Subagent 不必要的工具访问权限
对简单的单步骤任务使用 Subagent
在一个 Subagent 的提示中混合关注点
忘记传递必要的上下文

System Prompt 最佳实践

明确角色
你是一位专门从事 [特定领域] 的专家代码审查员
清晰定义优先级
```
审查优先级（按顺序）：
安全问题
性能问题
代码质量
```
指定输出格式
对于每个问题提供：严重性、类别、位置、描述、修复、影响
包含操作步骤
```
调用时：
运行 git diff 查看最近的变更
专注于修改的文件
立即开始审查
```

工具访问策略

从限制性开始：仅从基本工具开始
按需扩展：根据需求添加工具
尽可能只读：对分析 Agent 使用 Read/Grep
沙箱执行：将 Bash 命令限制为特定模式

使用场景

何时使用 Subagents

场景	使用 Subagent	原因
包含多个步骤的复杂功能	是	分离关注点，防止上下文污染
快速代码审查	否	不必要的开销
并行任务执行	是	每个 Subagent 拥有自己的上下文
需要专业知识	是	自定义系统提示
长时间运行的分析	是	防止主上下文耗尽
单个任务	否	不必要地增加延迟

典型工作流

MERMAID_BLOCK_3

Agent Teams（实验性）

Agent Teams 协调多个 Claude Code 实例一起处理复杂任务。与 Subagents（委托子任务并返回结果）不同，teammates 独立工作，拥有自己的上下文窗口，可以通过共享邮箱系统直接相互消息传递。

Subagents vs Agent Teams

方面	Subagents	Agent Teams
委托模型	父代理委托子任务，等待结果	团队负责人协调工作，teammates 独立执行
上下文	每个子任务的全新上下文，结果提炼回主上下文	每个 teammate 维护自己的持久上下文窗口
协调	由父代理管理串行或并行	具有自动依赖管理的共享任务列表
通信	结果仅返回给父代理（无代理间消息传递）	Teammates 可以通过邮箱直接相互消息传递
会话恢复	支持	进程 teammates 不支持
最适合	专注、定义明确的子任务	需要代理间通信和并行执行的复杂工作

启用 Agent Teams

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

或在 settings.json 中：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

性能考虑

上下文效率

主对话保护：Subagents 保护主上下文，实现更长的会话
Token 优化：只有结果被传递回主对话
并行执行：多个 Subagents 可以同时工作

延迟权衡

初始化开销：Subagents 从干净的上下文开始，可能会增加收集初始上下文的延迟
自动压缩：Subagent 上下文在约 95% 容量时自动压缩

关键行为

无嵌套生成：Subagents 不能生成其他 Subagents
后台权限：后台 Subagents 自动拒绝任何未预先批准的权限
后台化：按 Ctrl+B 将当前运行的任务后台化
转录存储：Subagent 转录存储在 ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl

总结

Claude Code 的 Subagents 功能为构建专业化 AI 助手体系提供了强大的基础设施。通过合理设计和配置 Subagents，你可以：

提高开发效率：将复杂任务分解为专业化的子任务
保护上下文：防止长对话中的上下文污染
并行执行：多个 Subagents 同时工作
专业化优化：每个 Subagent 针对特定任务优化
团队协作：通过版本控制共享 Subagents 配置

关键是从小处开始，逐步迭代，根据实际需求设计和优化你的 Subagents。记住，最好的 Subagent 是专注于单一职责、配置合理、提示明确的 Agent。

参考资源：Claude Code Subagents 官方文档 | GitHub Repository

posted @ 2026-04-09 20:09 iTech 阅读(48) 评论(0) 收藏举报

刷新页面返回顶部

iTech's Blog

AI人工智能时代 www.theaiera.cn

Claude Code Subagents 完全指南：构建专业化 AI 助手体系

Claude Code Subagents 完全指南：构建专业化 AI 助手体系

什么是 Subagents？

核心价值

架构设计

上下文隔离机制

生命周期管理

配置详解

文件位置优先级

YAML 前置配置

配置字段说明

内置 Subagents

General-Purpose（通用代理）

Explore（探索代理）

Plan（计划代理）

Bash（命令代理）

实战示例

示例 1：代码审查 Agent

示例 2：测试工程 Agent

示例 3：调试专家 Agent

高级功能

持久化内存

后台执行

Worktree 隔离

限制可生成的 Subagent

最佳实践

设计原则

System Prompt 最佳实践

工具访问策略

使用场景

何时使用 Subagents

典型工作流

Agent Teams（实验性）

Subagents vs Agent Teams

启用 Agent Teams

性能考虑

上下文效率

延迟权衡

关键行为

总结

公告