Claude Code 中文教程

主题

Agent 团队与多智能体 ​

一个 agent 走不完的路，让一队 agent 分头走完。

单 agent 为什么会遇到天花板 ​

写到一定复杂度，你会开始撞墙。这四种痛几乎每个人都会遇到。

上下文污染。 主 loop 里让 Claude 读 30 个文件找一段逻辑，读完这 30 个文件的内容全部留在上下文里，后面每一次对话都要拖着它们走。任务越长，噪音越厚，模型开始丢关键信息。

串行慢。 一次要研究认证、数据库、路由三个模块，一个 agent 只能挨个看，wall-clock 时间是三份工作的总和。

视角单一。 让写代码的那个 agent 自己评审自己写的代码，它几乎必然给自己打高分。它心里已经有了这段代码"应该长什么样"的模型，看不见那些真正会出问题的边界。

验证缺失。 一段能编译、跑得过测试的实现，不代表它做对了任务要求的事。你需要一个不受主 loop 污染、独立看结果的第二意见。

Anthropic 在 Research 系统上的内部评测里，用 Opus 4 做 lead、Sonnet 4 做 worker 的多 agent 架构，比单 agent Opus 4 高了 90.2%。代价是 token 用量大约 15 倍于普通对话。这个数字告诉你两件事：多 agent 是有用的，但它贵。

Claude Code 里的两种派 agent 方式 ​

Agent 工具：主 loop 里直接派 ​

主 loop 的 Agent 工具是最轻的入口。它做一件事：起一个子 agent 去执行一段独立任务，等它跑完，把最终结果作为一条消息塞回主 loop。

子 agent 分两种。Fresh subagent 拿的是空白上下文，看不到主 loop 的对话历史、读过的文件。Fork 则完整继承主 agent 的上下文，用于那种"我想让一个副本去探索，中间产物我不想留在自己脑子里"的场景。

判断标准很简单：这一堆中间输出主 loop 以后还用得上吗？用不上就 fork。fork 天然吃 prompt cache，比 fresh subagent 便宜。

Workflow：脚本化编排 ​

当你要 fan-out 十几个 agent，需要确定性拓扑、需要断点续跑、需要清晰的 pipeline 而不是让 Claude 临场决定要不要派 agent，就要升级到 Workflow。它是脚本化的 agent 编排器，下一章会展开。

并行的两个动作 ​

同一条消息里发多个 Agent 调用。 这是最直接的并行。主 loop 一次 tool_use 里放三个 Agent block，三个子 agent 同时启动，wall-clock 只等最慢那个。

typescript
// 一条消息里的多个 Agent 调用同时执行
Agent({ subagent_type: "fork", description: "查认证",
        prompt: "找 /src/auth 下 session 流程的所有入口" })
Agent({ subagent_type: "fork", description: "查数据库",
        prompt: "找 /src/db 下所有事务边界" })
Agent({ subagent_type: "fork", description: "查路由",
        prompt: "找 /src/routes 下所有需要鉴权的路径" })

Anthropic 在 Research 上的做法：lead agent 一次 spin up 3 到 5 个 worker 并行探索，每个 worker 内部再并行调 3 个以上的工具。这两级并行把复杂查询的时间砍掉了 90%。

自定义 agent 类型 ​

在 .claude/agents/ 下放一个 markdown 文件，就多了一种可派的 agent 类型。文件长这样。

markdown
---
name: security-reviewer
description: 审查代码中的安全漏洞。写完认证或数据处理相关代码后主动使用。
tools: Read, Grep, Glob, Bash
model: opus
---
你是一位资深安全工程师。审查以下方面：
- 注入类漏洞（SQL / XSS / 命令注入）
- 认证与授权缺陷
- 硬编码的密钥或凭证
- 不安全的数据流转
指出具体行号，给出修复建议。

name 决定别人怎么调它，description 决定主 agent 什么时候会自动 delegate 过来，tools 是白名单（不写就继承主 loop 的全部工具），model 允许高风险审查用更强的模型，日常任务用更便宜的 haiku。文件主体是这个 agent 的 system prompt。

放在 ~/.claude/agents/ 就是个人级，放在 .claude/agents/ 就是项目级，可以 commit 到 git 让整个团队共享。

Lead-worker 模式 ​

Anthropic 的 Research 系统采用 orchestrator-worker 架构，可以直接照搬到你自己的项目里。

Lead agent 负责三件事：拆解用户查询、给每个 worker 写清晰的任务描述、综合所有 worker 的结果输出最终答案。

Worker agent 各自独立探索：拿到明确的目标、输出格式、允许使用的工具和边界后，各自跑自己的搜索或分析，最后返回一份精炼过的结论。

Anthropic 从踩坑里总结的关键规则值得抄一遍：

  • 明确 delegate。给 worker 一个含糊的"研究一下半导体短缺"，几乎必然导致三个 worker 搜到几乎相同的东西。要给每个 worker 明确的目标、输出格式、工具建议、任务边界。
  • effort 分级。简单查询 1 个 worker 加 3 到 10 次工具调用；对比类查询 2 到 4 个 worker、每个 10 到 15 次调用；复杂研究才动用 10 个以上的 worker。让 lead 自己判断规模，几乎每次都会过度投入。
  • 先广后深。让 worker 先做短而宽的查询探路，再逐步收窄，别一上来就写超长超具体的 query。

三个可以直接用的团队场景 ​

Finders + Verifier。三个 fresh subagent 并行去代码库不同区域找 bug 的可能位置，跑完把候选清单交给一个 verifier subagent 逐一验证。分工清晰，主 loop 只拿到最终 verified 列表。

Multi-lens verify。同一段代码，一个 agent 从性能视角审查，一个从安全视角，一个从可读性视角，三个视角并行给出评审报告。哪一路发现问题都不会被其他视角淹没。

Judge panel。方案 A 和方案 B 拿不定主意时，派 3 到 5 个 judge agent 各自独立打分并给理由，主 loop 只看汇总的多数决和分歧点。适合选型、方案对比、code review 的最终判决。

Adversarial 验证

让写代码的 agent 自己评审自己，几乎必然过关。Claude Code best practices 明确建议：用一个 verification subagent 或一个动态 workflow，让一个 fresh model 尝试 refute 主 agent 的结果。做事的人不该同时是打分的人。

什么时候 NOT 用多 agent ​

多 agent 不是万灵药，以下场景老老实实用单 agent：

  • 任务很小，主 loop 一次就能做完，派 agent 只是徒增启动成本
  • 步骤强依赖，后一步必须看到前一步的完整中间过程，不适合把中间产物压缩掉
  • 上下文本来就极小，隔离没什么价值
  • 预算敏感，多 agent 大约 15 倍于普通对话的 token 消耗，得算清楚账

Anthropic 自己也说，大部分 coding 任务里真正可以并行的部分并不多，agent 间实时协调的能力还没到位。别为了用而用。

参考来源 ​

本教程为社区中文学习整理，非官方发布。Claude Code 属于 Anthropic。

Copyright © 2026 Claude Code 中文教程