来源：Claude Code Skills

构建多 Agent 系统的完整方法论

概述

多代理系统（Multi-Agent System）正在成为 AI 应用开发的主流范式。与其让一个 AI 做所有事情，不如让多个专注于不同任务的 AI 代理协同工作——就像一个运转良好的团队，每个人各司其职，通过标准化的接口沟通协作。

但构建多 Agent 系统远比「多跑几个 AI」复杂。你需要考虑任务分解、代理编排、接口标准化、错误处理、状态管理等一系列架构问题。如果没有系统化的方法论，很容易构建出一个脆弱、难以调试、无法扩展的系统。

这篇指南将展示如何利用 Claude Code 的技能体系，从架构设计到具体实现，构建一个健壮的多 Agent 系统。

适合人群：

• 有一定开发经验，想要构建 AI Agent 应用的开发者
• 正在评估多 Agent 架构的技术负责人
• 希望理解 Agent 编排模式的 AI 工程师

你将用到的核心技能：

• 并行代理调度（Parallel Agent Dispatch）
• 子代理驱动开发（Sub-agent Driven Development）
• MCP 构建器（MCP Builder）

核心概念

在深入技能之前，先统一几个关键概念。

Agent（代理）

Agent 是一个能够自主执行任务的 AI 实体。与普通的 AI 对话不同，Agent 具备以下能力：

• 自主性：给它一个目标，它能自己决定执行步骤
• 工具使用：能调用外部 API、读写文件、执行命令
• 状态维护：能记住之前的操作结果，并基于此做决策
• 循环执行：遇到失败能重试，遇到阻碍能换路径

MCP（Model Context Protocol，模型上下文协议）

MCP 是 Anthropic 推出的开放标准，定义了 AI 模型如何与外部工具和数据源交互。你可以把它理解为「AI 世界的 USB 接口」——只要工具实现了 MCP 标准，任何支持 MCP 的 AI 都能使用它。

MCP 的核心价值：

• 标准化：不同工具、不同模型之间有统一的通信协议
• 可组合：工具可以像乐高积木一样自由组合
• 可复用：构建一次 MCP 服务器，所有 MCP 客户端都能使用

编排（Orchestration）

编排是指协调多个 Agent 的工作。包括：

• 任务分配：哪个 Agent 做什么
• 依赖管理：哪些任务必须按顺序执行，哪些可以并行
• 结果汇总：如何将多个 Agent 的产出合并为最终结果
• 错误处理：某个 Agent 失败了怎么办

技能1：并行代理调度（Parallel Agent Dispatch）

什么时候用

当你有一个大任务可以被分解为多个相互独立的子任务时，并行代理调度能显著提升效率。

典型场景：

• 同时分析一个代码库中的多个模块
• 并行处理多个独立的数据转换任务
• 同时对多个文件执行代码评审
• 并行运行不同策略的测试套件

核心原则

1. 独立性判断：只有真正独立的任务才能并行。如果任务B依赖任务A的结果，就不能并行。

2. 上下文隔离：每个并行 Agent 有自己独立的上下文，不共享状态。如果需要共享信息，必须通过显式的数据传递。

3. 结果汇聚：并行任务完成后，需要一个汇聚步骤来整合结果。这个步骤通常由主 Agent（Orchestrator）执行。

实际操作方式

使用 Claude Code 的并行代理调度，你需要：

步骤1：明确总任务和子任务
「我需要对这个项目的 5 个核心模块做代码评审。
这 5 个模块是独立的，可以并行评审。」

步骤2：定义每个子任务的输入和输出
每个子 Agent 需要知道：
- 评审哪个模块（输入）
- 按什么标准评审（规则）
- 输出什么格式的报告（输出模板）

步骤3：启动并行执行
Claude Code 会为每个模块启动独立的评审流程，
它们在不同的 Git Worktrees 中同时工作。

步骤4：汇总结果
所有评审完成后，主 Agent 汇总各模块的评审报告，
生成一份整体的代码质量报告。

注意事项

• 不要过度并行：并行度太高会导致资源竞争。通常 3-5 个并行 Agent 是比较合适的上限。
• 设置超时：给每个并行任务设置合理的超时时间，避免一个卡住的任务拖累整个流程。
• 幂等设计：并行任务应该是幂等的（多次执行结果相同），这样失败后可以安全重试。

技能2：子代理驱动开发（Sub-agent Driven Development）

什么时候用

当你面对一个复杂任务，需要将其分解为多个有依赖关系的步骤时，子代理驱动开发提供了一种结构化的分解方法。

与并行调度不同，子代理驱动开发强调的是层次化分解——把一个大问题拆成子问题，子问题再拆成更小的问题，形成一棵任务树。

分解策略

按功能分解：

主 Agent：构建用户认证系统
├── 子 Agent 1：实现注册功能
│   ├── 表单验证逻辑
│   ├── 密码加密存储
│   └── 邮件验证发送
├── 子 Agent 2：实现登录功能
│   ├── 凭证验证
│   ├── JWT Token 生成
│   └── 刷新 Token 机制
└── 子 Agent 3：实现权限管理
    ├── 角色定义
    ├── 权限检查中间件
    └── 管理员界面

按层次分解：

主 Agent：实现订单创建
├── 子 Agent 1：数据层 — 设计数据模型和数据库操作
├── 子 Agent 2：业务层 — 实现业务逻辑（库存检查、价格计算）
└── 子 Agent 3：接口层 — 实现 API 端点和输入验证

关键原则

1. 单一职责：每个子 Agent 只负责一个明确的任务。如果你不能用一句话描述一个子 Agent 的职责，说明它还需要进一步分解。

2. 清晰的接口契约：子 Agent 之间的通信要通过明确定义的接口。不要让子 Agent 之间直接访问对方的内部状态。

3. 逐层测试：先测试最底层的子 Agent，确保它们正确，再测试上层的组合逻辑。这就是 TDD 在多 Agent 架构中的应用。

4. 失败隔离：一个子 Agent 的失败不应该导致整个系统崩溃。主 Agent 需要有错误处理和降级策略。

技能3：MCP 构建器（MCP Builder）

什么时候用

当你需要让 Agent 与外部系统交互时，MCP 构建器帮你快速创建标准化的工具接口。

典型场景：

• Agent 需要查询数据库
• Agent 需要调用第三方 API（支付、邮件、短信）
• Agent 需要读写文件系统
• Agent 需要与其他内部服务通信

MCP 服务器的结构

一个 MCP 服务器通常包含以下部分：

1. 工具定义（Tool Definition）：声明这个工具能做什么、接受什么参数、返回什么结果
2. 输入验证（Input Validation）：确保传入的参数符合预期
3. 核心逻辑（Core Logic）：实际执行操作的代码
4. 错误处理（Error Handling）：优雅地处理各种异常情况
5. 结果格式化（Result Formatting）：将结果转换为标准格式返回

构建原则

1. 最小权限：每个 MCP 工具只暴露必要的能力。一个查询用户信息的工具不应该有删除用户的权限。

2. 幂等性：查询类操作天然幂等。写入类操作要设计为幂等——多次调用和一次调用的结果相同。

3. 清晰的错误信息：Agent 不能像人类一样看报错截图。错误信息必须结构化、可解析，Agent 才能基于错误信息做出正确的重试或降级决策。

4. 版本管理：MCP 工具要有版本号。当接口变更时，通过版本号区分，避免破坏已有的 Agent 逻辑。

实际构建流程

步骤1：定义工具接口
明确工具名称、描述、参数列表、返回类型。
使用 Claude Code 的 MCP 构建器技能生成接口定义。

步骤2：实现核心逻辑
遵循 TDD——先写测试定义预期行为，再写实现代码。

步骤3：添加错误处理
覆盖所有可预见的错误场景：
网络超时、权限不足、参数无效、上游服务不可用。

步骤4：集成测试
在完整的 Agent 环境中测试 MCP 工具，
确保 Agent 能正确调用并处理返回结果。

步骤5：文档和示例
为每个工具提供使用示例，帮助其他 Agent 或开发者理解如何使用。

架构模式

在实际构建多 Agent 系统时，有几种常见的架构模式可供选择。

模式1：中心化编排（Hub and Spoke）

一个主 Agent（Hub）负责接收任务、分解任务、分配给子 Agent（Spoke），然后汇总结果。

优点： 控制流清晰，容易调试和监控 缺点： 主 Agent 可能成为瓶颈 适用： 大多数场景的首选模式

模式2：流水线（Pipeline）

Agent 按顺序连接，前一个 Agent 的输出是后一个 Agent 的输入。类似工厂流水线。

优点： 每个 Agent 职责单一，容易测试 缺点： 延迟是所有阶段的总和，无法并行 适用： 数据处理、内容生成等有明确阶段的任务

模式3：发布-订阅（Pub/Sub）

Agent 之间通过消息队列通信。一个 Agent 发布事件，感兴趣的 Agent 订阅并处理。

优点： 高度解耦，容易扩展 缺点： 调试困难，消息顺序可能不确定 适用： 大规模、松耦合的系统

模式4：混合模式

实际项目中，通常是以上模式的组合。例如：中心化编排 + 并行调度——主 Agent 分解任务后，独立的子任务并行执行，有依赖的任务按流水线执行。

为什么这套组合有效

构建多 Agent 系统的核心挑战可以归结为三个问题：

这三个技能分别解决了多 Agent 系统的三个核心维度：结构、效率、通信。

单独使用其中任何一个技能都有价值，但组合使用时它们会产生协同效应：

• 子代理驱动开发帮你把大问题分解为小问题
• 分解后的独立子问题可以通过并行调度同时执行
• 子 Agent 之间通过 MCP 标准化接口通信，确保互操作性

最终，你得到的是一个结构清晰、执行高效、接口标准的多 Agent 系统。

下一步行动： 从一个简单的场景开始实践。例如，构建一个「代码分析 Agent」，它由三个子 Agent 组成：一个负责静态分析（代码风格、复杂度），一个负责安全扫描（常见漏洞模式），一个负责性能分析（慢查询、内存泄漏）。三个子 Agent 可以并行运行，最终由主 Agent 汇总为一份综合报告。这个项目足够简单可以在一天内完成，但覆盖了多 Agent 系统的所有核心概念。

Source: Claude Code Skills

Complete Methodology for Building Multi-Agent Systems

Overview

Multi-agent systems represent the frontier of AI-assisted development. Instead of a single AI assistant handling everything sequentially, you orchestrate multiple specialized agents that work in parallel, each focused on a specific task. The result is dramatically faster development, better separation of concerns, and the ability to tackle projects that would overwhelm a single-agent approach.

This guide teaches you how to build and manage multi-agent systems using three Claude Code skills: Parallel Agent Dispatch, Sub-Agent Driven Development, and MCP Builder. Together, they form a complete methodology for designing, implementing, and scaling agent-based architectures --- whether you are building AI-powered applications for end users or optimizing your own development workflow.

This guide is for developers who are comfortable with Claude Code and want to push beyond single-agent usage into orchestrated, multi-agent workflows.

Core Concepts

Before diving into the skills, you need to understand three foundational concepts.

Agents vs. Tools

A tool is a function that an AI can call --- read a file, search the web, query a database. An agent is an AI instance with its own context, instructions, and decision-making loop. An agent uses tools, but it also has autonomy: it can decide which tools to use, in what order, and how to interpret the results. The distinction matters because agents can handle ambiguity and adapt to unexpected situations in ways that simple tool calls cannot.

Orchestration

Orchestration is the practice of coordinating multiple agents to accomplish a larger goal. An orchestrator agent breaks a complex task into subtasks, assigns each subtask to a specialized agent, monitors their progress, and integrates their results. Good orchestration is the difference between agents that work together harmoniously and agents that duplicate effort, contradict each other, or produce incoherent output.

Context Isolation

Each agent operates within its own context window. This is both a limitation and a feature. The limitation is that agents cannot directly read each other's full context. The feature is that each agent can focus entirely on its task without being distracted by irrelevant information. Context isolation is what makes parallel execution possible --- agents working on the frontend do not need to know about database migration details, and vice versa.

Skill 1: Parallel Agent Dispatch

What It Does

The Parallel Agent Dispatch skill enables you to run multiple Claude Code agents simultaneously, each working on a different part of your project. Instead of building features one at a time, you can build the API endpoint, the frontend component, and the test suite all at once.

When to Use It

Use Parallel Agent Dispatch when your project has tasks that are independent of each other. Common scenarios include:

• Building multiple API endpoints that do not depend on each other
• Writing tests for different modules simultaneously
• Implementing frontend and backend components in parallel
• Running code review on multiple pull requests at once
• Generating documentation for different sections of your codebase

How It Works

The skill uses Git worktrees (or separate working directories) to give each agent its own isolated workspace. Each agent receives a focused prompt that describes only its specific task, along with any shared context it needs (API contracts, type definitions, design specifications).

A typical parallel dispatch flow looks like this:

1. Define the tasks. Break your current milestone into independent pieces. For example: "Build the user profile API endpoint," "Build the user profile UI component," "Write integration tests for user profile."

2. Prepare shared context. Create a brief document that defines the interfaces between the parallel tasks. For the user profile example, this would be the API contract (endpoint URL, request format, response schema). Every agent gets this document.

3. Dispatch agents. Launch each agent in its own worktree with its specific task prompt and the shared context.

4. Monitor and integrate. As agents complete their tasks, review their output and merge their work into the main branch. Resolve any integration issues.

Practical Tips

• Keep tasks genuinely independent. If task B depends on the output of task A, do not run them in parallel. Run A first, then dispatch B with A's output.
• Define clear interfaces. The shared context document is critical. Vague interfaces lead to incompatible implementations. Spend extra time making API contracts, type definitions, and data schemas precise.
• Start with two agents. Do not jump to five parallel agents on your first try. Start with two, get comfortable with the workflow, and scale up as your orchestration skills improve.
• Use consistent coding standards. When multiple agents write code independently, style drift is inevitable without shared guidelines. Include your linting configuration and coding standards in the shared context.

Skill 2: Sub-Agent Driven Development

What It Does

Sub-Agent Driven Development (SADD) is a methodology where a primary agent decomposes a complex task into subtasks and delegates each one to a specialized sub-agent. Unlike Parallel Agent Dispatch, which focuses on running independent tasks simultaneously, SADD focuses on hierarchical decomposition --- breaking a hard problem into manageable pieces.

When to Use It

Use SADD when you face a task that is too complex for a single agent's context window or attention span. Common scenarios include:

• Building a complete feature that spans multiple architectural layers
• Refactoring a large module where understanding all the dependencies exceeds a single context window
• Implementing a complex algorithm that benefits from step-by-step decomposition
• Migrating a codebase from one framework to another

How It Works

The primary agent acts as an architect and project manager. It analyzes the task, identifies the logical components, defines the interfaces between them, and then delegates each component to a sub-agent with focused instructions.

Here is the SADD workflow:

1. Analyze. The primary agent reads the requirements, examines the existing codebase, and identifies the components that need to be built or modified.

2. Decompose. Break the task into subtasks, each small enough for a single agent to handle within its context window. Define the dependencies between subtasks.

3. Specify. For each subtask, write a clear specification that includes: what to build, what inputs it receives, what outputs it produces, what constraints it must satisfy, and what existing code it should integrate with.

4. Delegate. Assign each subtask to a sub-agent with its specification and relevant context (but only the relevant context --- do not dump the entire codebase).

5. Integrate. As sub-agents complete their work, the primary agent reviews each piece, verifies it meets the specification, and integrates it into the whole.

6. Verify. The primary agent runs the full test suite and performs integration testing to ensure all the pieces work together correctly.

The Art of Decomposition

The hardest part of SADD is deciding how to split the work. Here are principles that help:

• Split along natural boundaries. Database layer, business logic, API handler, and frontend component are natural boundaries. So are separate domain concepts (users, orders, payments).
• Minimize cross-cutting concerns. If two subtasks need to share a lot of context, they might be better as one task. If a subtask requires understanding the entire system, it is not decomposed enough.
• Make subtasks testable independently. Each sub-agent's output should be verifiable on its own, before integration. If you cannot write a test for a subtask's output in isolation, rethink the decomposition.

Skill 3: MCP Builder

What It Does

The MCP (Model Context Protocol) Builder skill teaches you to create custom tools that extend Claude Code's capabilities. MCP servers expose functionality --- database access, API integrations, file transformations, domain-specific calculations --- through a standardized protocol that Claude Code can discover and use automatically.

When to Use It

Use MCP Builder when your agents need capabilities that do not exist out of the box. Common scenarios include:

• Connecting Claude Code to your company's internal APIs
• Creating tools that interact with specific databases or data stores
• Building domain-specific tools (e.g., a tool that validates medical codes, generates legal citations, or calculates financial metrics)
• Wrapping external services (Stripe, Twilio, SendGrid) in agent-friendly interfaces

How It Works

An MCP server is a program that exposes tools through a standardized JSON-RPC interface. Claude Code discovers the server's capabilities at startup and can call its tools during a conversation, just like built-in tools.

The MCP Builder skill guides you through:

1. Identifying the need. What capability is missing? What would an agent need to call to accomplish its task? Define the tool's purpose, inputs, and outputs.

2. Designing the interface. Write the tool's schema: its name, description, parameter types, and return type. The description is especially important because it tells Claude Code when and how to use the tool.

3. Implementing the server. Write the MCP server code. The skill provides templates for common patterns: database queries, REST API wrappers, file processors, and computation tools.

4. Testing the tool. Verify that the tool works correctly by calling it directly and through Claude Code. Test edge cases: malformed input, network failures, timeout scenarios.

5. Registering the server. Add the MCP server to your Claude Code configuration so it is available in future sessions.

MCP and Multi-Agent Systems

MCP servers become especially powerful in multi-agent architectures. Consider a scenario where you are building an e-commerce platform:

• One MCP server wraps your product catalog API
• Another MCP server handles payment processing
• A third MCP server manages inventory

Each agent in your system can call the tools it needs without knowing how the underlying services work. The payment agent calls the payment MCP tool. The inventory agent calls the inventory MCP tool. The orchestrator agent coordinates them. The MCP layer provides clean abstractions that keep each agent focused on its domain.

Architecture Patterns

As you combine these three skills, several architectural patterns emerge:

Fan-Out / Fan-In

The orchestrator dispatches multiple agents in parallel (fan-out), waits for all of them to complete, then integrates their results (fan-in). Best for tasks where subtasks are independent and the final output is a combination of their results.

Example: Generating a comprehensive code review. Fan out three agents: one reviews security, one reviews performance, one reviews maintainability. Fan in by combining their findings into a single review document.

Pipeline

Agents are arranged in a sequence where each agent's output becomes the next agent's input. Best for tasks with clear sequential dependencies.

Example: Building a feature. Agent 1 writes the database schema and migration. Agent 2 takes the schema and builds the API layer. Agent 3 takes the API contract and builds the frontend component. Each agent's output is the next agent's input.

Supervisor

A supervisor agent monitors other agents' work and intervenes when things go wrong. It does not do the work itself --- it reviews, corrects, and redirects.

Example: A code quality supervisor that reviews each agent's output before integration. If an agent's code does not meet standards, the supervisor sends it back with specific feedback.

Recursive Decomposition

An agent encounters a subtask that is still too complex and spawns its own sub-agents. This creates a tree of agents, each handling progressively smaller pieces of the problem.

Example: A refactoring agent is asked to modernize a large module. It decomposes the module into components, delegates each component to a sub-agent. One of those sub-agents finds that its component is itself complex and spawns further sub-agents for individual functions.

Why This Combination Works

The three skills in this guide address the three fundamental challenges of multi-agent development:

• Parallel Agent Dispatch solves the speed problem. By running agents concurrently, you compress development time from days to hours.
• Sub-Agent Driven Development solves the complexity problem. By decomposing hard tasks into focused subtasks, you keep each agent within its effective operating range.
• MCP Builder solves the capability problem. By creating custom tools, you extend what agents can do beyond their built-in abilities.

Together, they enable a development workflow where you think at the architecture level --- defining components, interfaces, and workflows --- while agents handle the implementation details. You become the architect; the agents become the builders. And like any good architect, your value lies not in laying bricks but in ensuring that the bricks fit together into a coherent, functional structure.

The multi-agent approach is not always necessary. For small features and simple projects, a single Claude Code session is perfectly sufficient. But when you face a project that is large, complex, or time-sensitive, the methodology in this guide gives you a systematic way to scale your development capacity without scaling your headcount.