CC-301: Multi-Agent Architecture

Learning Guide

Claude Code's multi-agent architecture transforms how you approach complex development tasks. Instead of a single agent wrestling with an entire problem, you can decompose work across specialized subagents -- each with a focused context, clear responsibilities, and isolated execution environments. This module covers the full spectrum of subagent capabilities, from basic dispatch to advanced orchestration patterns.

Understanding Subagent Types

Claude Code provides several built-in subagent types through the Agent tool, each optimized for different categories of work. Understanding when to reach for each type is the foundation of effective multi-agent design.

General-Purpose Subagents

The default subagent type inherits a broad set of tools and can perform any task the parent agent can. You dispatch a general-purpose subagent when the work is self-contained but doesn't fit neatly into a specialized category. These agents receive their own context window and can read files, write code, run commands, and use any available tool.

// Dispatching a general-purpose subagent
Agent({
  prompt: "Refactor the authentication module to use JWT tokens.
           Read src/auth/ first to understand the current implementation.",
  tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
})

The Explore Agent

The Explore agent is a read-only specialist. It can search, read, and analyze code but cannot modify anything. This is ideal for reconnaissance tasks: understanding a codebase, finding patterns, mapping dependencies, or answering architectural questions. Because it cannot write, you can dispatch it freely without worrying about unintended side effects.

The Plan Agent

Plan agents analyze requirements and produce structured implementation plans without executing them. They are excellent for breaking down complex features into discrete steps, identifying risks before implementation begins, and creating roadmaps that other agents can follow.

Code-Reviewer Agent

This specialized agent focuses on reviewing code changes for correctness, style, security vulnerabilities, and adherence to project conventions. It reads diffs, examines test coverage, and produces structured review feedback. Pair it with your project's CLAUDE.md to enforce team-specific standards.

Agent Tool Parameters

The Agent tool accepts parameters that shape how a subagent behaves. The most important are:

• prompt -- The task description. Be specific about what the agent should accomplish, what files to examine, and what output format you expect.
• tools -- The set of tools available to the subagent. Restricting tools is a powerful governance mechanism: a review agent doesn't need Bash, and an exploration agent doesn't need Write.
• model -- Optionally specify a different model for cost optimization. Use lighter models for simple tasks, and reserve the full model for complex reasoning.

Worktree Isolation

When multiple agents need to modify code simultaneously, git worktrees provide filesystem-level isolation. Each agent operates in its own worktree -- a separate working directory linked to the same repository but checked out to a different branch. This eliminates merge conflicts during parallel execution and lets agents work independently.

The EnterWorktree and ExitWorktree tools manage this lifecycle. An orchestrating agent can spin up a worktree for each subagent, let them work in parallel, and then merge results back to the main branch. This pattern is essential for large-scale refactoring where multiple files change across different subsystems.

// Worktree isolation pattern
// Agent 1: works on auth module in worktree-auth branch
// Agent 2: works on API routes in worktree-api branch
// Agent 3: works on tests in worktree-tests branch
// Orchestrator: merges all branches when agents complete

Parallel Agent Dispatch

The real power of multi-agent architecture emerges when you dispatch agents in parallel. Independent tasks -- analyzing different modules, writing tests for separate components, reviewing distinct PRs -- can run simultaneously rather than sequentially. This dramatically reduces wall-clock time for complex operations.

The key constraint is independence: parallel agents must not need each other's output and should not modify overlapping files (unless using worktree isolation). The orchestrating agent identifies which tasks are truly independent and batches them accordingly.

Patterns for Parallel Dispatch

1. Fan-out/Fan-in: Dispatch N agents for independent subtasks, collect all results, then synthesize. Example: analyzing security vulnerabilities across 10 modules simultaneously.
2. Map-Reduce: Each agent processes a partition of the work (map phase), and a final agent aggregates results (reduce phase). Example: counting code patterns across a monorepo.
3. Pipeline with Parallel Stages: Sequential stages where each stage internally parallelizes. Example: Stage 1 (parallel explore) feeds Stage 2 (parallel implement) feeds Stage 3 (parallel test).

Agent Communication Patterns

Agents communicate primarily through their return values. When a subagent completes, its output flows back to the parent agent, which can then pass relevant context to subsequent agents. This is an implicit message-passing model -- the orchestrator serves as a hub.

The SendMessage pattern enables more direct communication in specific scenarios. However, in practice, the hub-and-spoke model (orchestrator dispatches, collects, redistributes) is cleaner and easier to reason about. Direct agent-to-agent messaging introduces complexity that is rarely justified.

Foreground vs. Background Agents

Foreground agents block the parent until they complete. The orchestrating agent waits for the result before proceeding. This is appropriate when the result is needed immediately -- for example, an Explore agent gathering context that will inform the next implementation step.

Background agents run asynchronously. The parent dispatches them and continues with other work. Background execution is ideal for long-running tasks that don't block the critical path: running a comprehensive test suite, performing a deep security audit, or generating documentation while implementation continues.

Agent Specialization Patterns

The most effective multi-agent architectures use highly specialized agents with narrow, well-defined responsibilities:

• The Scout: An Explore-type agent that maps the codebase, identifies relevant files, and produces a context summary for implementation agents. It eliminates the "cold start" problem where an agent wastes context window reading irrelevant files.
• The Implementer: A focused agent that receives a precise specification and implements it. It doesn't explore or plan -- it executes against a clear contract.
• The Validator: A testing agent that verifies implementations against requirements. It writes tests, runs them, and reports failures. It never fixes the code -- it only reports what's broken.
• The Reviewer: A code-review agent that examines changes for quality, security, and convention adherence. It produces structured feedback but makes no modifications.

Designing Agent Prompts

The prompt you give a subagent is the single most important factor in its success. Effective agent prompts follow these principles:

1. State the objective clearly. "Refactor X to achieve Y" is better than "Clean up the code."
2. Specify the scope. List the files or directories the agent should focus on. Unbounded scope leads to wasted context and poor results.
3. Define the output format. If you need structured data (a list of files, a test report, a review summary), say so explicitly.
4. Include constraints. "Do not modify any test files." "Only use the existing API surface." "Follow the patterns in CLAUDE.md."
5. Provide relevant context. If you already know which files matter, tell the agent. Don't make it rediscover what you already know.

// Good agent prompt
"Review the changes in src/api/v1/users/ for:
 1. SQL injection via unsanitized inputs
 2. Missing authentication checks
 3. Unbounded queries without .limit()
 4. TOCTOU vulnerabilities in UPDATE/DELETE operations
 Report findings as a numbered list with file:line references."

// Poor agent prompt
"Check the code for bugs."

Practical Architecture Example

Consider implementing a new feature that spans API routes, database migrations, UI components, and tests. An effective multi-agent architecture might look like:

1. Phase 1 (Explore): Dispatch a Scout agent to map the existing codebase patterns, find similar features already implemented, and produce a context document.
2. Phase 2 (Plan): A Plan agent receives the Scout's output and produces a step-by-step implementation plan with file-level specificity.
3. Phase 3 (Implement): Three Implementer agents work in parallel via worktrees -- one for the database layer, one for API routes, one for UI components.
4. Phase 4 (Validate): A Validator agent writes and runs tests. A Reviewer agent examines all changes for quality.
5. Phase 5 (Merge): The orchestrator merges worktrees and runs final integration tests.

This five-phase pattern is reusable across virtually any feature implementation. It scales from small features (where phases collapse) to large ones (where each phase involves multiple parallel agents).

For the full technical reference on subagent capabilities and parameters, see the Claude Code Sub-Agents documentation.