Agent 系统详解与开发方法 - 学习笔记-Claude Code-上海佼艾

一、Agent 系统概述

Claude Code 的 Agent 系统是一个基于大语言模型的自主任务执行框架。其核心思想是：让 AI 模型不再仅仅被动地回答用户问题，而是能够主动地规划任务、执行多步操作、自主决策并完成复杂工作流。Agent 系统将 Claude Code 从一个"问答工具"升级为一个"自主工作引擎"。

核心理念：Agent = LLM + 工具 + 记忆 + 规划能力。Agent 拥有对环境的感知能力（通过工具读取信息）、决策能力（通过 LLM 推理选择行动）和执行能力（通过工具改变环境），能够自主完成多步骤复杂任务。

1.1 Agent vs Tool

理解 Agent 和 Tool 的区别是掌握 Agent 系统的第一步：

维度	Tool（工具）	Agent（代理）
定义	单一功能的 API 调用	自主决策的执行实体
能力范围	执行特定操作（如搜索、读写文件）	多步骤规划、自主选择工具、综合分析
状态管理	无状态，每次调用独立	有状态，维护上下文和进度追踪
复杂度	单一原子操作	多步骤工作流编排
典型应用	文件读取、代码搜索、命令执行	代码审查、项目分析、批量重构

1.2 Agent 架构概览

Claude Code 的 Agent 系统采用分层架构设计，从底层到顶层依次为：

Agent 系统架构层次
[用户请求]
↓
┌─────────────────────────────┐
│ Orchestrator Layer │ ← 主 Agent 调度层
│ (任务分解 & 子代理分发) │
└─────────────────────────────┘
↓ ↓ ↓
┌─────────┐ ┌─────────┐ ┌─────────┐
│ SubAgent │ │SubAgent │ │SubAgent │ ← 子代理执行层
│ (A) │ │ (B) │ │ (C) │
└─────────┘ └─────────┘ └─────────┘
↓ ↓ ↓
┌─────────────────────────────┐
│ Tool Execution Layer │ ← 工具执行层
│ (Read/Write/Edit/Grep...) │
└─────────────────────────────┘

在这个架构中：主 Agent（Orchestrator）负责任务分析和分解，将大任务拆分为可并行或串行执行的子任务，分发给 SubAgent 执行；SubAgent 各自独立完成任务，使用底层工具与文件系统交互；最终主 Agent 收集所有结果并进行综合汇总。

1.3 Agent 系统的核心能力

任务分解：自动将复杂问题分解为可管理的子任务
并行执行：多个 SubAgent 同时运行，大幅提升效率
上下文隔离：每个 SubAgent 拥有独立的上下文空间
结果聚合：自动收集和整合所有 SubAgent 的输出
通信协调：SubAgent 之间可以相互发送消息进行协作
生命周期管理：创建、监控、终止 SubAgent 的全流程控制

二、Agent 类型详解

Claude Code 提供了多种内置 Agent 类型，每种类型针对特定场景进行了优化。理解不同类型的特性和适用场景，是高效使用 Agent 系统的前提。

2.1 Explore Agent（探索代理）

Explore Agent 专门用于代码库探索和知识获取。它的核心任务是在不修改代码的前提下，深入理解项目结构、代码逻辑和业务规则。

典型场景：
- 新成员接手项目时快速了解代码架构
- 查找特定功能的实现位置和调用链
- 分析代码中的潜在问题和技术债务
- 生成项目文档和架构图

特性	说明
模式	只读模式，不执行任何修改操作
主要工具	Read、Glob、Grep、WebSearch
输出	分析报告、架构图、文档
最佳用途	代码审查、架构分析、技术调研

2.2 Plan Agent（规划代理）

Plan Agent 专注于任务规划和方案设计。在执行复杂操作之前，Plan Agent 会分析需求、制定详细实施方案、评估风险和依赖关系。

典型场景：
- 功能开发前的技术方案设计
- 重构任务的步骤分解和风险评估
- 多文件变更的依赖关系分析
- 测试方案和测试用例设计

特性	说明
模式	分析和设计模式，不做代码修改
输出	实施方案、步骤列表、风险评估
最佳用途	复杂任务的先行规划
注意	通常作为主流程的第一步使用

2.3 General-purpose Agent（通用代理）

通用代理是最常用的 Agent 类型，具有完整的读写和执行权限。它可以自主执行从规划到实施的全流程任务。

典型场景：
- 功能开发与代码编写
- Bug 修复和代码优化
- 测试编写和执行
- 项目配置和环境搭建

2.4 Code-reviewer Agent（代码审查代理）

专门用于代码审查的 Agent，它会对代码变更进行逐行检查，发现潜在问题，并提供改进建议。

典型场景：
- Pull Request 审查
- 代码质量评估
- 安全漏洞检测
- 最佳实践合规检查

2.5 不同类型 Agent 的能力对比

能力维度	Explore	Plan	General-purpose	Code-reviewer
文件读取	是	是	是	是
文件写入	否	否	是	否
命令执行	只读命令	否	是	只读命令
搜索查询	是	是	是	是
网络访问	是	是	是	否
代码修改	否	否	是	否
适用阶段	调研期	规划期	实施期	审查期

三、SubAgent 创建与启动

SubAgent 是 Claude Code Agent 系统的核心执行单元。主 Agent 可以通过 Agent 工具动态创建 SubAgent，并将子任务分配给它们执行。SubAgent 运行在独立的执行环境中，拥有自己的上下文和工具集。

什么是 SubAgent？

SubAgent 是由主 Agent 动态生成的子代理实例。每个 SubAgent 是一个独立的 LLM 推理循环，拥有自己的对话历史、工具上下文和执行状态。SubAgent 被创建时接收明确的任务描述，执行完毕后返回结果给主 Agent。

3.1 Agent 工具参数详解

创建 SubAgent 使用 Agent 工具（在 Claude Code 的上下文中），其核心参数如下：

参数	类型	说明	是否必须
name	string	SubAgent 的名称标识，用于日志追踪和管理	是
goal	string	明确的任务目标和期望输出	是
tasks	string[]	需要该 SubAgent 完成的具体任务列表	是
type	enum	Agent 类型（explore/plan/general/code-reviewer）	否
background	boolean	是否后台运行，true 表示异步执行	否
worktree	boolean/string	是否在工作树隔离环境中运行	否
model	string	指定使用的模型版本	否

// SubAgent 创建示例

{

  "name": "analyze-auth-module",

  "goal": "全面分析认证模块的代码结构和潜在安全问题",

  "tasks": [

    "1. 读取 auth/ 目录下的所有源文件",

    "2. 分析认证流程和会话管理逻辑",

    "3. 识别安全漏洞和编码问题",

    "4. 生成分析报告文档"

  ],

  "type": "explore",

  "background": false

}

3.2 启动 SubAgent 的完整流程

任务评估：主 Agent 分析用户请求，判断是否需要创建 SubAgent
子任务分解：将大任务拆分为独立的子任务单元
Agent 配置：确定每个 SubAgent 的名称、目标、任务列表和类型
执行调度：按照依赖关系（串行或并行）启动 SubAgent
状态监控：实时追踪每个 SubAgent 的执行进度
结果收集：等待 SubAgent 完成并获取执行结果
结果聚合：综合所有 SubAgent 的输出形成最终答案

3.3 前台 vs 后台执行模式

特性	前台执行	后台执行
执行方式	同步阻塞	异步非阻塞
主 Agent 状态	等待 SubAgent 完成后继续	可立即处理其他任务
结果获取	直接返回	通过 message 机制查询
适用场景	任务有依赖关系	任务相互独立，需并行执行
超时控制	继承主 Agent 超时	独立超时设置

3.4 SubAgent 生命周期

一个 SubAgent 从创建到销毁经历以下生命周期阶段：

Created：SubAgent 实例被创建，但尚未开始执行
Running：SubAgent 正在执行分配的任务
Blocked：SubAgent 等待依赖条件（如其他 Agent 的结果）
Completed：SubAgent 成功完成任务，输出结果就绪
Failed：SubAgent 执行过程中遇到无法恢复的错误
Terminated：SubAgent 被手动终止或超时

四、Agent 通信机制

Agent 通信机制是 Claude Code Agent 系统的关键基础设施。它允许不同的 SubAgent 之间、以及 SubAgent 与主 Agent 之间交换信息、协调行动和共享成果。

4.1 SendMessage 机制

SendMessage 是 Agent 间通信的核心原语。任何 Agent 都可以使用 SendMessage 向其他 Agent 发送结构化消息，实现协作交互。

SendMessage 的本质：它是一种异步消息传递机制。发送方 Agent 发出消息后可以继续自己的工作，接收方 Agent 在适当的时机处理消息并可以选择回复。这类似于操作系统中的消息队列模型。

// SendMessage 参数结构

{

  "to": "target-agent-name",  // 接收方 Agent 名称

  "message": "具体的消息内容",  // 消息正文

  "type": "info",  // 消息类型: info | request | response | error

  "context": { },  // 可选的上下文数据

  "priority": 1  // 优先级: 1-5，5最高

}

4.2 消息类型

消息类型	用途	是否需要回复
info	传递信息，如中间结果或状态更新	否
request	请求对方执行特定操作或提供数据	是
response	对 request 消息的回复	否（它是回复本身）
error	报告错误或异常情况	视情况而定
sync	同步点通知，用于协调执行顺序	可能需要确认

4.3 通信模式

点对点通信：一个 Agent 直接向另一个指定 Agent 发送消息，是最基本的通信模式
广播通信：一个 Agent 向所有运行中的 Agent 广播消息，适用于状态通知
请求-响应模式：Agent A 向 Agent B 发送请求消息，Agent B 处理后返回响应
发布-订阅模式：Agent 发布消息到特定频道，订阅该频道的 Agent 接收消息
结果共享模式：一个 Agent 完成子任务后将结果分享给依赖该结果的 Agent

4.4 消息处理与响应

当 Agent 收到消息时，其内部处理流程如下：

消息入队：接收到的消息被放入 Agent 的消息队列
优先级排序：按消息优先级重新排序队列
上下文注入：消息内容被注入到 Agent 的对话上下文中
LLM 推理：Agent 基于当前上下文和消息内容决定如何响应
行动执行：如果消息要求执行操作，Agent 执行相应的工具调用
回复生成：如果需要回复，Agent 构造回复消息并发送

五、并行任务策略

并行任务执行是 Agent 系统最强大的能力之一。通过同时启动多个 SubAgent，可以将大规模复杂任务的处理时间从线性缩短为常数级别，极大提升工作效率。

5.1 并行执行的核心原则

可并行化的前提条件：子任务之间必须没有数据依赖关系。如果任务 B 需要任务 A 的输出结果才能开始，那么这两个任务必须串行执行。识别任务间依赖关系是并行任务编排的关键步骤。

5.2 任务分解策略

有效的任务分解是并行执行的基础。以下是几种常用的分解策略：

策略	描述	适用场景
按文件/模块分解	每个 SubAgent 处理一个或多个文件	代码审查、批量重构
按功能维度分解	不同 SubAgent 分析不同功能方面	系统分析、性能优化
按任务类型分解	不同类型的任务分配给不同 Agent 类型	混合工作流（探索+分析+实现）
按数据分片分解	大型数据集分割后并行处理	数据处理、批量分析
按阶段分解	不同阶段的任务并行推进	完整开发周期管理

5.3 并行执行模式

Fan-Out / Fan-In 模式

这是最常用的并行模式：主 Agent 将任务分解后同时分发（Fan-Out）给多个 SubAgent，所有 SubAgent 并行执行各自的任务，完成后主 Agent 收集所有结果并聚合（Fan-In）为最终输出。

Fan-Out / Fan-In 模式
[主 Agent 接收任务]
↓ 任务分解
┌─────────┬─────────┬─────────┐
│ 子任务1 │ 子任务2 │ 子任务3 │
└────↓────┴────↓────┴────↓────┘
↓ Fan-Out（并行分发）
┌─────────┐ ┌─────────┐ ┌─────────┐
│SubAgent1│ │SubAgent2│ │SubAgent3│
│ (文件A) │ │ (文件B) │ │ (文件C) │
└─────────┘ └─────────┘ └─────────┘
↓ Fan-In（结果聚合）
└──────────┬──────────┘
↓
[主 Agent 汇总输出]

5.4 结果聚合策略

多个 SubAgent 并行执行后的结果需要进行有效的聚合。常见的聚合方式包括：

简单拼接：各 Agent 的输出直接拼接为完整报告
去重合并：去除重复内容后再合并（适用于搜索任务）
分级汇总：先本地汇总再全局汇总（分层聚合）
交叉验证：对多个结果进行一致性检查和交叉验证
投票表决：多个 Agent 对同一问题的不同答案进行投票

5.5 并行任务管理最佳实践

性能优化建议

合理设置并行度：并非越多越好，根据任务复杂度和资源限制调整
使用后台模式：对于耗时较长的 SubAgent，使用 background=true 异步执行
设置超时保护：为每个 SubAgent 设置合理的超时时间，防止无限等待
逐步聚合：不要等所有 Agent 完成后才聚合，支持流式结果处理
错误隔离：单个 SubAgent 的失败不应影响其他正在运行的任务

六、Worktree 隔离模式

Worktree 隔离模式是 Claude Code 提供的一种安全执行环境。当 SubAgent 需要在隔离的环境中执行任务时，可以为其创建独立的 Git Worktree，使其拥有独立的文件系统空间和分支上下文。

6.1 什么是 Worktree 隔离

Git Worktree 是 Git 提供的功能，允许在同一仓库中检出多个分支到不同的工作目录。Claude Code 利用这一机制，为 SubAgent 创建独立的执行环境：每个 SubAgent 获得一个隔离的工作目录，拥有独立的文件副本和 Git 分支。

Worktree 隔离的价值：
- 避免并行 Agent 修改同一文件导致冲突
- 每个 SubAgent 拥有独立的代码快照
- 实验性更改不会影响主工作区
- 方便的任务撤销和分支管理
- 提高了并行执行的安全性

6.2 何时使用 Worktree 隔离

场景	推荐使用 Worktree	理由
并行代码修改	是	避免文件写入冲突
只读分析任务	否	不需要隔离环境
实验性重构	是	失败后不影响主分支
代码生成任务	视情况使用	生成新文件可不用，修改现有文件建议用
多版本测试	是	并行测试不同代码版本
数据采集和分析	否	仅涉及读取操作

6.3 Worktree 的工作原理

分支创建：主 Agent 从当前 HEAD 创建一个新的 Git 分支
Worktree 建立：在 .claude/worktrees/ 目录下创建工作目录
环境初始化：复制必要文件并设置 SubAgent 的工作目录
任务执行：SubAgent 在隔离的工作目录中执行所有操作
结果提交：SubAgent 将修改提交到隔离分支
结果合并：主 Agent 将完成的内容合并回主工作区
清理：任务完成后可选择保留或删除 Worktree

Worktree 使用建议

使用背景：当确认子任务需要修改文件时启用 Worktree 隔离
命名规范：Worktree 名称应反映任务内容，方便识别和管理
及时清理：完成任务后及时清理不再需要的 Worktree
注意磁盘空间：每个 Worktree 都会复制文件，大量 Worktree 会消耗磁盘
分支策略：明确 Worktree 分支是短暂分支还是需要长期保留

七、Agent Teams 开发

Agent Teams 是 Claude Code 提供的高级协作模式，允许多个 Agent 作为一个团队协同工作。与简单的 SubAgent 并行执行不同，Team 模式提供了更强大的任务编排、状态共享和协调机制。

7.1 TeamCreate 工具

TeamCreate 是创建 Agent Team 的核心工具。通过它，主 Agent 可以定义团队成员、角色分配、任务列表和协作规则。

// TeamCreate 配置示例

{

  "team_name": "feature-dev-team",

  "members": [

    {

      "name": "backend-dev",

      "role": "后端开发者",

      "goal": "实现用户认证 API",

      "tasks": ["创建用户模型", "实现 JWT 认证", "编写 API 端点"]

    },

    {

      "name": "frontend-dev",

      "role": "前端开发者",

      "goal": "实现登录注册页面",

      "tasks": ["创建登录表单", "实现表单验证", "对接后端 API"]

    },

    {

      "name": "tester",

      "role": "测试工程师",

      "goal": "编写集成测试",

      "tasks": ["编写后端测试", "编写前端测试", "运行测试套件"]

    }

  ],

  "communication": "task-based",  // 通信模式

  "coordinator": "主 Agent"  // 协调者

}

7.2 团队协作模式

模式	描述	适用场景
Task-based	基于任务分发的协作，每个成员独立完成任务	模块化开发、并行实现
Pipeline	流水线模式，每个成员的输出是下一个的输入	数据处理、编译流程
Hub-and-spoke	中心协调模式，主 Agent 分派任务并汇总结果	大型项目、多模块分析
Swarm	群智模式，多个 Agent 共同解决同一问题	代码审查、方案设计

7.3 团队生命周期管理

创建阶段：定义团队结构、成员角色和工作目标
启动阶段：初始化团队环境，分发初始任务
执行阶段：监控执行进度，协调成员间通信，处理异常
同步阶段：定期同步进度，协调依赖关系
收尾阶段：收集所有输出，合并成果，生成最终报告
清理阶段：释放资源，清理临时文件，提交更改

7.4 团队协调最佳实践

团队协调要点：
- 明确定义每个成员的职责边界，避免职责重叠
- 建立清晰的依赖关系图，确保任务按正确顺序执行
- 设置定期同步点，及时解决阻塞问题
- 使用消息队列管理团队通信，避免信息过载
- 定义冲突解决策略，当并行修改产生冲突时自动处理

八、Agent SDK 开发指南

Agent SDK 是 Claude Code 提供的一套开发工具包，允许开发者构建自定义 Agent。通过 SDK，你可以定义新的 Agent 类型、配置工具集、管理 Agent 状态和内存，从而构建适用于特定领域的专业 Agent。

Agent SDK 的核心能力

自定义 Agent 开发的核心在于将通用 LLM 能力与领域特定的工具、知识和行为模式相结合。SDK 提供了搭建这一结合体的完整基础设施。

8.1 自定义 Agent 的基本结构

一个完整的自定义 Agent 定义包含以下核心组件：

组件	说明	必须
name	Agent 的唯一名称标识	是
description	Agent 功能的描述，帮助主 Agent 选择合适的 SubAgent	是
tools	Agent 可调用的工具列表	是
system_prompt	系统提示词，定义 Agent 的行为模式	是
memory_config	记忆管理配置，决定如何存储和检索上下文	否
max_turns	最大推理轮次限制	否
allowed_domains	允许的调用域限制	否

8.2 工具定义

自定义 Agent 的工具集是其能力的基础。工具定义遵循标准的函数调用格式：

// 自定义工具定义示例

{

  "tools": [

    {

      "name": "search_knowledge_base",

      "description": "搜索内部知识库",

      "parameters": {

        "query": { "type": "string", "description": "搜索关键词" },

        "limit": { "type": "number", "description": "返回结果数量" }

      }

    }

  ]

}

8.3 Agent 配置管理

Agent 的行为可以通过配置文件进行精细化控制：

模型选择：指定 Agent 使用的 LLM 模型（Opus/Sonnet/Haiku）
温度控制：调节 Agent 输出的创造性和确定性
上下文窗口：配置 Agent 的最大上下文长度
输出格式：定义 Agent 输出的结构化格式要求
权限控制：限制 Agent 的工具调用权限

8.4 记忆管理

自定义 Agent 的记忆管理机制决定了 Agent 如何在多次调用之间保持状态：

记忆类型	存储内容	生命周期
会话记忆	当前任务的对话历史	单次会话
任务记忆	当前任务的进度和中间结果	任务期间
知识记忆	从执行中提取的知识和经验	持久化
工具记忆	常用工具调用模式和参数	持久化

SDK 开发注意事项

工具定义应清晰简洁，避免歧义
系统提示词应包含明确的 Agent 角色和边界
合理设置最大推理轮次，防止无限循环
为关键操作添加错误处理和回退策略
测试 Agent 在边界条件下的行为表现

九、代理提示词工程

提示词工程（Prompt Engineering）是 Agent 开发中最关键也最容易被忽视的环节。高质量的提示词能显著提升 Agent 的执行效果、准确性和可靠性。

核心原则：Agent 的提示词不是写给"人"看的，而是写给"LLM"看的。优秀的 Agent 提示词需要精确、结构化、无歧义，并且包含足够的上下文信息和执行指南。

9.1 Agent 提示词的核心构成

一个完整的 Agent 系统提示词（System Prompt）通常包含以下要素：

要素	说明	示例
角色定义	Agent 的身份和定位	"你是一个资深代码审查专家"
能力边界	Agent 能做什么和不能做什么	"你只能读取文件，不能修改"
任务目标	需要完成的具体任务	"分析 auth 模块的安全性"
输出格式	期望的输出结构和格式	"输出 Markdown 格式的报告"
行为规则	执行过程中的约束条件	"先搜索再分析，最后总结"
决策框架	遇到分支情况时的决策准则	"找到漏洞后按严重性排序"
质量要求	输出应达到的质量标准	"每个结论必须附带代码引用"

9.2 提示词编写技巧

具体化而非抽象："分析用户认证流程"优于"查看代码"
结构化表达：使用编号列表和层次标题组织指令
明确输出规格：说明输出的格式、长度和深度要求
提供参考示例：给出期望的输出样例，建立质量标准
设置优先级：标明哪些目标是必须完成的核心需求
分解复杂指令：将复杂要求分解为简单的子步骤

// 高质量 Agent 提示词模板

"role": "资深后端安全审计专家",

"boundaries": [

  "只能读取文件，不能修改任何代码",

  "只分析与安全相关的代码，不关注业务逻辑"

],

"task": "对 src/auth/ 目录进行安全审计",

"steps": [

  "1. 列出 src/auth/ 下的所有文件",

  "2. 逐个读取文件，重点关注：认证、授权、会话、密码处理",

  "3. 对每个发现的问题标注严重级别 (CRITICAL/HIGH/MEDIUM/LOW)",

  "4. 为每个问题提供修复建议"

],

"output_format": {

  "type": "markdown",

  "sections": ["摘要", "高危漏洞", "中危问题", "改进建议"]

}

9.3 上下文管理

Agent 的上下文窗口有限，有效的上下文管理是提示词工程的重要部分：

上下文压缩：将长文本压缩为摘要，保留关键信息
优先级注入：最重要的指令放在上下文开头和结尾
分页处理：大量数据时分批注入，避免超出上下文限制
相关度过滤：只注入与当前任务相关的上下文
自动摘要：定期对长对话进行摘要，替代完整历史

9.4 常见提示词陷阱

需要避免的提示词问题

过度开放："分析这个项目"过于宽泛，Agent 不知从何入手
信息过载：给 Agent 过多的背景信息，影响核心任务的注意力
模糊指令："尽可能详细"或"适当优化"等模糊表达
矛盾要求：同时要求"全面"和"简洁"等矛盾目标
缺少评估标准：没有定义什么算是"完成"或"合格"
忽略优先级：重要目标和次要目标未作区分

十、最佳实践与模式

基于对 Agent 系统的深入理解，本节总结在实际开发中经过验证的最佳实践和设计模式，帮助你构建更可靠、高效的 Agent 工作流。

10.1 错误处理策略

错误类型	处理策略	实现方法
工具调用失败	重试机制	自动重试 1-3 次，指数退避
上下文溢出	上下文压缩	自动摘要历史，丢弃无关内容
Agent 超时	超时降级	超时后返回部分结果，标记未完成项
结果格式异常	格式修正	二次解析和格式校正
通信中断	消息重发	消息队列持久化，断线重连
依赖失败	备用方案	预定义 fallback 流程

10.2 超时管理

合适的超时设置是 Agent 系统稳定运行的关键：

任务级超时：每个 SubAgent 设置独立超时（建议 2-5 分钟）
通信超时：消息等待回复的超时（建议 30-60 秒）
总执行超时：整个任务链的硬性超时限制
空闲超时：Agent 长时间无操作时的自动终止

超时设置的黄金法则

超时不是越长越好。过长的超时会在任务卡死时浪费大量时间；过短的超时会导致正常任务被错误终止。推荐的策略是：先设置一个较宽松的超时，根据实际执行统计数据逐步收紧。

10.3 结果验证

对 Agent 输出的结果进行验证，确保质量和正确性：

完整性检查：确保所有要求的输出都已生成
格式验证：检查输出格式是否符合预期规范
一致性检查：检查不同 Agent 的输出是否一致
质量评分：对输出质量进行打分，低于阈值的重新执行
可执行验证：如果是代码修改，确保可以正确编译和执行

10.4 资源管理

资源类型	管理策略	注意事项
上下文窗口	及时清理和压缩	防止溢出导致 Agent 行为异常
文件系统	Worktree 及时清理	多个 Worktree 会占用大量磁盘
API 配额	请求频率控制	避免触发 API 限流
并行 Agent 数	合理的并行度控制	太多 Agent 会降低单 Agent 质量
消息队列	定期清理已处理消息	防止消息堆积

10.5 常用设计模式

模式一：探索-规划-实施三阶段法

这是最通用的 Agent 工作流模式：先用 Explore Agent 探索和理解，再用 Plan Agent 制定方案，最后用 General-purpose Agent 实施。

模式二：Master-Worker 模式

主 Agent（Master）负责任务分解和协调，多个 Worker Agent 并行执行子任务。适用于代码迁移、大规模重构等场景。

模式三：Pipeline 流水线模式

任务按阶段串联，每个阶段的输出是下一阶段的输入。适用于数据处理、编译部署等有严格顺序要求的场景。

模式四：Review-Revise 迭代模式

Code-reviewer Agent 审查代码，发现问题的代码发送给 General-purpose Agent 修改，修改后再审查，迭代直到质量达标。

10.6 生产环境部署检查清单

[ ] 所有 SubAgent 设置了合理的超时时间
[ ] 关键任务有错误重试和降级机制
[ ] 并行 Agent 数量在资源限制范围内
[ ] Worktree 使用后有清理机制
[ ] Agent 间的依赖关系正确定义
[ ] 结果验证逻辑已实现
[ ] 日志记录完整，支持问题排查
[ ] 性能监控指标已配置
[ ] 安全权限已按最小权限原则配置
[ ] 有手动终止异常 Agent 的机制

十一、核心要点总结

Agent 系统的本质理解

Agent = LLM 推理 + 工具执行 + 记忆管理 + 自主规划。Claude Code 的 Agent 系统将 LLM 从一个被动的问答系统升级为主动的任务执行引擎。理解这个本质是掌握所有 Agent 相关技术的基础。

Agent 类型选择指南

任务类型	推荐 Agent 类型	原因
代码探索和分析	Explore Agent	只读模式，安全高效
方案设计	Plan Agent	专注规划，不做执行
功能开发	General-purpose Agent	全权限，适合代码编写
代码审查	Code-reviewer Agent	专项优化，审查质量高

SubAgent 使用口诀

创建要命名，任务要具体；
独立可并行，依赖要串行；
通信用消息，协调靠主控；
超时要设置，错误有处理；
结果要验证，质量有保障。

关键设计原则

单一职责原则：每个 SubAgent 只负责一个明确的子任务
最小隔离原则：只在必要时使用 Worktree 隔离
优雅降级原则：部分失败不应导致整体失败
消息驱动原则：通过消息机制协调 Agent 间通信
结果导向原则：明确每个 Agent 的预期输出和验收标准
渐进式复杂度：从简单任务开始，逐步增加复杂度

开发者成长路径

入门：使用内置 Agent（Explore/Plan）进行基础的代码分析和规划
进阶：创建和管理 SubAgent，实现基本的并行任务
精通：使用 Agent Teams 进行复杂工作流编排
专家：使用 Agent SDK 开发自定义 Agent，设计领域特定解决方案
架构师：设计和优化大型 Agent 系统架构，制定团队开发规范

最终总结

Claude Code 的 Agent 系统是一个强大而灵活的任务执行框架。它通过多层次的架构设计，实现了从简单的单步操作到复杂的多 Agent 协作的各种任务模式。掌握 Agent 系统的关键在于理解其核心概念（SubAgent、通信、并行、隔离），熟练运用各种 Agent 类型和创建策略，并遵循经过验证的最佳实践。随着 Agent SDK 的不断完善，开发自定义 Agent 将成为扩展 Claude Code 能力边界的主要方式。