05c - Agentic Loop 与 Subagent
本文是《AI Agent 实战手册》第 5 章第 3 节。 上一节：CLAUDE.md 编写指南 | 下一节：Plan Mode 与 Act Mode
概述
Claude Code 的核心竞争力不在于”更聪明的补全”，而在于它的 Agentic Loop（代理循环） 机制——一个能自主规划、执行、验证、修正的闭环系统。当单个循环的上下文窗口不够用时，Subagent（子代理） 机制允许 Claude Code 生成独立的专业化工作者并行处理任务。本节深入解析这两个核心机制的工作原理、内部架构和实战用法。
1. Agentic Loop：核心工作机制
1.1 什么是 Agentic Loop
Agentic Loop 是 Claude Code 的”心脏”——一个单线程的主循环，驱动 Claude 从接收用户输入到返回最终结果的全过程。与传统的”问答式”AI 不同，Agentic Loop 让 Claude 能够自主决策：读取哪些文件、执行哪些命令、如何验证结果、失败后如何调整策略。
核心设计哲学：简单的单线程循环 + 纪律化的工具使用 = 可控的自主性。
1.2 循环流程图
以下是 Agentic Loop 的完整工作流程：
1.3 循环的六个阶段
| 阶段 | 动作 | 说明 |
|---|---|---|
| ① 接收输入 | 用户发送自然语言指令 | 支持文本、图片（Ctrl+V）、文件引用（@） |
| ② 意图分析 | 模型理解任务目标 | 结合 CLAUDE.md、项目上下文、对话历史 |
| ③ 工具选择 | 决定使用哪些工具 | 从内置工具集中选择（搜索、编辑、执行等） |
| ④ 工具执行 | 调用工具并获取结果 | 每次调用一个工具，结果反馈到消息历史 |
| ⑤ 结果评估 | 检查执行结果是否正确 | 如果失败，自动调整策略重试 |
| ⑥ 响应生成 | 生成最终文本响应 | 当不再需要工具调用时，循环自然终止 |
1.4 内部架构：主循环引擎
Claude Code 的内部架构遵循分层设计，核心组件包括：
┌─────────────────────────────────────────────┐
│ 用户交互层（CLI / IDE / Web） │
├─────────────────────────────────────────────┤
│ Agent 核心调度层 │
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
│ │ 主循环引擎 │ │ 异步消息 │ │ 上下文 │ │
│ │ (nO) │ │ 队列(h2A) │ │ 压缩器 │ │
│ └──────────┘ └──────────┘ └───────────┘ │
├─────────────────────────────────────────────┤
│ 工具层 │
│ 搜索 │ 文件读写 │ 编辑 │ Shell │ MCP │ ... │
├─────────────────────────────────────────────┤
│ 安全与权限层 │
│ 权限检查 │ 沙箱 │ Hooks │ 审计日志 │
└─────────────────────────────────────────────┘关键组件说明：
- 主循环引擎（nO）：单线程
while(tool_call)循环，维护一个扁平的消息列表（无复杂线程），每次迭代执行一个工具调用 - 异步消息队列（h2A）：支持暂停/恢复，允许用户在 Claude 执行任务过程中插入新指令，无需重启整个流程
- 上下文压缩器：当上下文窗口使用率达到约 92% 时自动触发，将对话历史压缩摘要并存入长期记忆（Markdown 文件）
1.5 工具系统：Agentic Loop 的”手脚”
Claude Code 的工具是 Agentic Loop 的执行器。每次循环迭代中，模型从以下工具集中选择：
| 工具类别 | 工具名称 | 功能 | 示例 |
|---|---|---|---|
| 搜索 | Grep、Glob、FileSearch | 在代码库中搜索文件和内容 | 查找所有包含 TODO 的文件 |
| 读取 | View、ReadFile | 读取文件内容 | 查看 src/main.ts 的第 10-50 行 |
| 编辑 | Edit、MultiEdit | 修改文件内容 | 替换函数实现、添加导入语句 |
| 执行 | Bash | 运行 shell 命令 | npm test、git commit |
| 写入 | Write | 创建新文件 | 创建 src/utils/helper.ts |
| MCP | 自定义工具 | 连接外部服务 | 查询数据库、发送 Slack 消息 |
| 子代理 | Subagent | 生成独立工作者 | 并行探索代码库 |
1.6 自我修正机制
Agentic Loop 最强大的特性之一是自我修正——当工具执行失败时，Claude 不会简单放弃，而是分析错误原因并调整策略：
典型的自我修正链路：
1. Claude 尝试运行 `npm test` → 测试失败
2. 分析错误信息 → 发现类型错误
3. 使用 Grep 搜索相关类型定义
4. 使用 Edit 修复类型错误
5. 再次运行 `npm test` → 测试通过 ✅这种”尝试→失败→分析→修正→重试”的循环可以嵌套多层，直到任务完成或达到合理的重试上限。
1.7 实时转向：中途修改指令
传统 AI 工具在执行任务时，如果你想修改方向，通常需要中断并重新开始。Claude Code 的异步消息队列（h2A）支持实时转向：
场景：Claude 正在重构一个模块
你：（按 Esc 中断）"等一下，重构时请保留原来的函数签名，只改内部实现"
Claude：收到，我会保持所有公开 API 不变，只重构内部实现...这种能力让你可以在 Claude 执行过程中随时调整方向，而不会丢失已完成的工作。
2. Subagent：分布式任务处理
2.1 为什么需要 Subagent
单个 Agentic Loop 有一个根本限制：上下文窗口是有限的。当你让 Claude 分析一个大型代码库时，探索过程中积累的文件内容会迅速填满上下文窗口，挤占后续推理和编辑所需的空间。
Subagent 解决了这个问题：将任务委托给独立的工作者，每个工作者有自己的上下文窗口，完成后只返回压缩摘要。
工具推荐
| 工具 | 用途 | 价格 | 适用场景 |
|---|---|---|---|
| Claude Code 内置 Subagent | 任务委托与并行处理 | 包含在 Claude Code 订阅中 | 代码探索、复杂任务分解 |
| Claude Code Swarm Mode | 多 Agent 团队协作 | 包含在 Claude Code 订阅中（2026 年初发布） | 大型重构、并行开发 |
/agents 命令 | 创建和管理自定义子代理 | 包含在 Claude Code 订阅中 | 定制化工作流 |
| Haiku 模型（子代理用） | 快速、低成本的子代理执行 | $1/$5 每百万 token（输入/输出） | 只读探索、快速查询 |
| Sonnet 模型（子代理用） | 平衡能力与成本 | $3/$15 每百万 token（输入/输出） | 复杂推理、代码修改 |
2.2 Subagent 架构：Orchestrator-Worker 模式
Claude Code 的 Subagent 采用 Orchestrator-Worker（编排者-工作者） 模式：
核心特征：
- Lead Agent（主代理） 负责战略规划和任务分解
- Subagent（工作者） 在独立的上下文窗口中执行具体任务
- 每个 Subagent 拥有独立的 256K 上下文窗口
- Subagent 返回压缩摘要（数百 token），而非完整对话记录（数千 token）
- Subagent 不能再生成 Subagent（防止无限嵌套）
2.3 内置 Subagent 类型
Claude Code 内置了多种专业化的 Subagent 类型：
| Subagent 类型 | 使用模型 | 工具权限 | 用途 | 自动触发场景 |
|---|---|---|---|---|
| Explore | Haiku（快速低延迟） | 只读（禁止写入/编辑） | 代码库搜索和分析 | 需要搜索或理解代码库时 |
| Plan | 继承主对话模型 | 只读（禁止写入/编辑） | Plan Mode 下的代码库研究 | Plan Mode 中需要理解代码库时 |
| General-Purpose | 继承主对话模型 | 全部工具 | 复杂多步骤任务 | 需要探索+修改的复杂任务 |
| Bash | 继承主对话模型 | 终端命令 | 在独立上下文中运行命令 | 需要隔离的命令执行 |
| Claude Code Guide | Haiku | 文档查询 | 回答 Claude Code 使用问题 | 用户询问 Claude Code 功能时 |
Explore Subagent 的三种深度级别：
| 深度 | 说明 | 适用场景 |
|---|---|---|
quick | 快速定向查找 | 查找特定函数或文件 |
medium | 平衡探索 | 理解模块结构和依赖 |
very thorough | 全面深度分析 | 大型代码库的完整理解 |
2.4 何时生成 Subagent
Claude Code 会在以下场景自动生成 Subagent：
适合使用 Subagent 的场景：
- 代码库探索：分析大型项目结构，避免探索过程污染主对话上下文
- 并行研究：同时调查多个目录或模块
- 复杂重构：将大任务拆分为独立的子任务并行执行
- Plan Mode 研究：在规划阶段收集代码库信息
- 隔离实验：在不影响主对话的情况下尝试不同方案
不适合使用 Subagent 的场景：
- 简单的单文件编辑：开销大于收益
- 需要跨步骤状态共享的任务：Subagent 之间无法直接通信
- 需要用户实时交互的任务：Subagent 在后台运行，无法与用户对话
2.5 隔离边界与上下文继承
理解 Subagent 的隔离机制对于有效使用至关重要：
┌─────────────────────────────────────────────────┐
│ Lead Agent（主代理） │
│ 上下文窗口：200K tokens │
│ ┌─────────────────┐ │
│ │ 用户对话历史 │ │
│ │ CLAUDE.md 内容 │ │
│ │ 项目上下文 │ │
│ │ Subagent 返回摘要 │ ← 只接收压缩后的摘要 │
│ └─────────────────┘ │
├─────────────────────────────────────────────────┤
│ Subagent A（隔离） │ Subagent B（隔离） │
│ 256K 独立上下文 │ 256K 独立上下文 │
│ ┌───────────────┐ │ ┌───────────────┐ │
│ │ 自定义系统提示 │ │ │ 自定义系统提示 │ │
│ │ 任务指令 │ │ │ 任务指令 │ │
│ │ 工具执行结果 │ │ │ 工具执行结果 │ │
│ │ ❌ 无用户历史 │ │ │ ❌ 无用户历史 │ │
│ │ ❌ 无其他Agent │ │ │ ❌ 无其他Agent │ │
│ └───────────────┘ │ └───────────────┘ │
└─────────────────────────────────────────────────┘继承规则：
| 属性 | 是否继承 | 说明 |
|---|---|---|
| 权限设置 | ✅ 继承 | Subagent 继承父对话的权限配置 |
| CLAUDE.md | ✅ 继承 | 项目上下文文件自动加载 |
| MCP 连接 | ✅ 继承 | 可访问已配置的 MCP Server |
| 对话历史 | ❌ 不继承 | Subagent 从空白上下文开始 |
| 工具权限 | ⚠️ 可限制 | 可通过配置限制 Subagent 可用的工具 |
| 模型选择 | ⚠️ 可覆盖 | 可为 Subagent 指定不同的模型（如 Haiku） |
2.6 性能影响与成本考量
Subagent 是强大的工具，但也有明确的成本代价：
| 指标 | 单 Agent | 使用 Subagent | 说明 |
|---|---|---|---|
| Token 消耗 | 基准 | 约 3-15 倍 | 每个 Subagent 都有独立的系统提示和上下文开销 |
| 延迟 | 基准 | 并行时可降低总时间 | 多个 Subagent 可同时执行 |
| 上下文效率 | 受限于单窗口 | 大幅提升 | 主对话只接收压缩摘要 |
| 复杂任务成功率 | 基准 | 提升约 90%+ | 专业化分工提高准确性 |
| 调试难度 | 简单 | 中等 | 需要追踪多个 Agent 的执行链路 |
成本优化策略：
- 为只读任务使用 Haiku 模型：Explore Subagent 默认使用 Haiku，成本仅为 Sonnet 的 1/3
- 控制 Subagent 数量：并行 2-4 个通常是最佳平衡点
- 明确任务边界：给 Subagent 清晰的任务描述，避免不必要的探索
- 利用后台执行：
run_in_background参数让 Subagent 非阻塞运行，主 Agent 可继续工作
3. 自定义 Subagent
操作步骤
步骤 1：使用 /agents 命令创建
在 Claude Code 对话中输入：
/agents选择”Create new agent”，按提示填写配置。
步骤 2：手动创建 Markdown 文件
Subagent 定义为带 YAML frontmatter 的 Markdown 文件：
项目级（仅当前项目可用）：
.claude/agents/
├── code-reviewer.md
├── test-writer.md
└── security-auditor.md用户级（所有项目可用）：
~/.claude/agents/
├── my-reviewer.md
└── my-researcher.md步骤 3：编写 Subagent 配置文件
---
# code-reviewer.md
name: Code Reviewer
model: sonnet
description: >
Reviews code changes for quality, security, and best practices.
Use this agent when you need a thorough code review.
tools:
- View
- Grep
- Glob
- Bash
denied_tools:
- Edit
- Write
- MultiEdit
---
# Code Reviewer Agent
You are a senior code reviewer. Your job is to:
1. Analyze code changes for potential bugs, security issues, and style violations
2. Check for proper error handling and edge cases
3. Verify test coverage for new functionality
4. Suggest improvements with specific code examples
## Review Checklist
- [ ] No hardcoded secrets or credentials
- [ ] Proper input validation
- [ ] Error handling covers edge cases
- [ ] New code has corresponding tests
- [ ] No performance regressions步骤 4：配置关键字段说明
| 字段 | 必填 | 说明 |
|---|---|---|
name | ✅ | Subagent 显示名称 |
model | ❌ | 使用的模型（haiku、sonnet、opus），默认继承主对话 |
description | ✅ | Claude 根据此描述决定何时委托任务给该 Subagent |
tools | ❌ | 允许使用的工具白名单 |
denied_tools | ❌ | 禁止使用的工具黑名单 |
permissions | ❌ | 权限模式（default、allowAll） |
hooks | ❌ | 绑定的 Hook 配置 |
skills | ❌ | 加载的 Skills 列表 |
提示词模板
创建探索型 Subagent
帮我创建一个自定义 Subagent，用于分析项目的依赖关系：
- 名称：Dependency Analyzer
- 模型：haiku（快速低成本）
- 只允许只读工具（View、Grep、Glob、Bash）
- 禁止任何写入操作
- 系统提示：分析 package.json / Cargo.toml / requirements.txt 等依赖文件，
识别过时依赖、安全漏洞、重复依赖创建代码生成型 Subagent
帮我创建一个自定义 Subagent，专门生成单元测试：
- 名称：Test Generator
- 模型：sonnet（需要较强推理能力）
- 允许所有工具
- 系统提示：为指定的函数或模块生成全面的单元测试，
覆盖正常路径、边界值、错误处理，使用项目现有的测试框架4. Swarm Mode：多 Agent 团队协作
4.1 从 Subagent 到 Swarm
2026 年初，Anthropic 随 Claude Sonnet 5 发布了 Swarm Mode——将 Claude Code 从单 Agent 助手升级为多 Agent 团队编排器。Swarm Mode 是 Subagent 机制的进化版本，核心区别在于：
| 特性 | Subagent | Swarm Mode |
|---|---|---|
| 协作模式 | 主从（Lead → Worker） | 团队（Leader + Teammates） |
| Agent 间通信 | 无（只通过 Lead 中转） | 点对点消息传递 |
| 工作空间 | 共享同一 Git 仓库 | 每个 Agent 独立 Git Worktree |
| 任务管理 | Lead Agent 手动分配 | 共享任务列表，自动协调 |
| 代码冲突 | 需要手动处理 | 测试通过后自动合并 |
| 启用方式 | 默认可用 | 需要启用实验性功能 |
4.2 Swarm Mode 架构
4.3 启用 Swarm Mode
# 方式 1：环境变量
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude
# 方式 2：在 Claude Code 设置中启用
claude config set experimental.agentTeams true4.4 Swarm Mode 使用示例
我需要为这个项目添加用户认证功能。请用 Swarm Mode 并行处理：
1. 一个 Agent 负责后端 API（JWT + 中间件）
2. 一个 Agent 负责前端页面（登录/注册表单）
3. 一个 Agent 负责编写测试（单元 + E2E）
每个 Agent 在独立的 Git Worktree 中工作，完成后自动合并。实战案例：用 Subagent 并行分析大型代码库
场景
你接手了一个 10 万行的遗留项目，需要快速理解代码结构、找出技术债务、评估测试覆盖率。
操作流程
cd legacy-project
claude第一步：启动并行探索
请用 4 个并行 Subagent 分析这个项目：
1. Agent 1：分析 src/ 目录结构和核心模块依赖关系
2. Agent 2：分析 tests/ 目录，评估测试覆盖率和质量
3. Agent 3：搜索所有 TODO、FIXME、HACK 注释，汇总技术债务
4. Agent 4：分析 package.json 依赖，找出过时和有安全漏洞的包第二步：观察 Subagent 工作
Claude 会生成 4 个 Explore Subagent（使用 Haiku 模型，只读权限），它们在后台并行工作。你可以看到类似的输出：
⏺ Spawning 4 subagents for parallel analysis...
→ Agent 1: Exploring src/ directory structure...
→ Agent 2: Analyzing test coverage...
→ Agent 3: Searching for TODO/FIXME/HACK...
→ Agent 4: Auditing dependencies...第三步：获取综合报告
所有 Subagent 完成后，Lead Agent 综合它们的压缩摘要，生成一份完整的项目分析报告。
第四步：基于报告制定行动计划
根据分析报告，帮我制定一个优先级排序的重构计划，
先处理安全漏洞，再处理技术债务，最后补充测试覆盖。案例分析
这个案例展示了 Subagent 的核心价值：
- 上下文效率：4 个 Subagent 各自拥有 256K 上下文，总共可处理约 1M token 的代码内容，而主对话只接收 4 份压缩摘要
- 并行加速：4 个分析任务同时进行，总时间约等于最慢的那个任务
- 成本控制：Explore Subagent 使用 Haiku 模型，成本仅为 Sonnet 的 1/3
- 上下文隔离：探索过程中的大量文件内容不会污染主对话，为后续的规划和执行保留了充足的上下文空间
避坑指南
❌ 常见错误
-
过度使用 Subagent 处理简单任务
- 问题：每个 Subagent 都有系统提示和上下文初始化的开销（约 2000-5000 token），简单任务直接在主循环中完成更高效
- 正确做法：只在需要隔离上下文或并行处理时使用 Subagent
-
期望 Subagent 之间直接通信
- 问题：标准 Subagent 模式下，工作者之间无法直接交换信息，所有通信必须经过 Lead Agent
- 正确做法：如果需要 Agent 间通信，使用 Swarm Mode；或者让 Lead Agent 在 Subagent 之间传递关键信息
-
不限制 Subagent 的工具权限
- 问题：给只需要读取代码的 Subagent 全部工具权限，可能导致意外的文件修改
- 正确做法：遵循最小权限原则——探索任务只给只读工具，只有明确需要修改时才给写入权限
-
忽略 Subagent 的 token 成本
- 问题：每个 Subagent 独立消耗 token，4 个并行 Subagent 的成本可能是单 Agent 的 4-15 倍
- 正确做法：为只读探索任务指定 Haiku 模型，监控
/cost输出
-
在 Agentic Loop 中给过大的任务
- 问题：单次循环中任务过大，导致上下文窗口被中间结果填满，后续步骤质量下降
- 正确做法：将大任务拆分为小步骤，每步验证后再继续；或使用 Subagent 分担
-
不使用
/compact管理上下文- 问题：长对话中 Agentic Loop 的历史消息累积，挤占可用上下文空间
- 正确做法：每完成一个独立任务后使用
/compact压缩历史，或在上下文压缩器自动触发前主动管理
✅ 最佳实践
- 理解 Agentic Loop 的单线程本质——它一次只做一件事，但做得很彻底
- 用
@引用文件主动提供上下文，减少 Agentic Loop 的搜索开销 - 为不同类型的任务创建专业化的自定义 Subagent
- 利用 Explore Subagent 的 Haiku 模型优势，降低代码探索成本
- 在 Swarm Mode 中使用 Git Worktree 隔离，避免并行 Agent 的代码冲突
- 监控
/cost输出，了解 Subagent 的实际 token 消耗 - 善用 Hooks 在 Agentic Loop 的关键节点自动执行检查（lint、test、安全扫描）
相关资源与延伸阅读
官方文档
- Create Custom Subagents — Anthropic — Subagent 的官方创建指南
- Advanced Tool Use — Anthropic Engineering — 高级工具使用和 Agent 架构的工程博客
GitHub 资源
- Awesome Claude Skills — GitHub — 社区精选的 Claude Skills 集合，包含 Subagent 定义模板
- Awesome Claude Code — GitHub — Claude Code 工作流和 Subagent 配置示例
学习资源
- How Does Claude Code Actually Work? — Rubric Labs — 深入解析 Claude Code 的 Agentic Loop 内部机制
- From Tasks to Swarms — AlexOp — 从单 Agent 到多 Agent 协作的实战指南
- Claude Code Multi-Agents Guide — Turion AI — 多 Agent 和 Subagent 编排的完整教程
社区
- r/ClaudeAI — Claude 用户社区，有 Agentic Loop 和 Subagent 的使用经验分享
- ClaudeLog — Claude Code 功能详解站点，持续追踪新特性
参考来源
- Claude Code: Behind-the-scenes of the master agent loop — PromptLayer （2025-08）
- Create custom subagents — Anthropic 官方文档 （持续更新）
- How does Claude Code actually work? — Rubric Labs （2025-11）
- Claude Code and the Architecture of Autonomous Software Engineering — Catalaize （2026-02）
- Claude Code Multi-Agents and Subagents: Complete Orchestration Guide — Turion AI （2025-12）
- Claude’s AI Sub-Agents Turn One Assistant Into a Team of Specialists — Implicator AI （2026-02）
- Claude Code Swarm Mode Guide — API易 （2026-02）
- Introducing advanced tool use — Anthropic Engineering （2025-11）
- Claude Code 2026: Major Technical Advancements — NextGen Tech Insider （2026-02）
- From Tasks to Swarms: Agent Teams in Claude Code — AlexOp （2026-02）
📖 返回 总览与导航 | 上一节：CLAUDE.md 编写指南 | 下一节：Plan Mode 与 Act Mode
Last updated on