Multi-agent orchestration: Claude Code design guide

Key takeaways

• Start with the simplest evaluated design. Add a multi-step system only when that design falls short.
• For multi agent orchestration Claude Code projects, clean task boundaries matter more than agent count.
• Parallel contexts increase token use, communication cost, and operational complexity.

The important decision is not how many agents to launch. It is whether the work can be divided without making agents compete over files, contracts, permissions, or shared state. Draw those boundaries first. Agent count follows.

Can Claude Code use multiple agents?

Yes. Claude Code supports teammates, and its planning controls can keep implementation behind an approval boundary for complex or risky work. A teammate can remain in read-only plan mode until the lead approves its approach.

That creates a concrete control loop:

1. The teammate plans while remaining read-only.
2. The lead reviews the approach.
3. If the lead rejects it, the teammate stays in plan mode and revises from the feedback.
4. The teammate resubmits the plan.
5. Implementation begins after approval.

This is a useful example of a multiagent workflow in Claude Code because authority is visible. Planning and implementation are separate states, and the lead controls the transition between them. The design question is still larger than the feature. A team also needs rules for who handles each part, what can happen at the same time, and how completed work returns to a coherent project.

The approval gate narrows the teammate's authority at the point where an approach becomes an implementation. A rejection does not move the teammate into a writing state. It keeps the teammate in read-only planning, carries the lead's feedback into a revision, and requires another approval request. That makes the state of the assignment legible before repository changes begin.

What does a multi-agent orchestration system coordinate?

A multi-agent orchestration system divides a larger objective across agents and coordinates control, isolation, handoffs, and synthesis. It is the harness around the workers. Parallelism is only one possible execution choice.

A handoff transfers control according to context or the user's request, allowing an agent with the right focus to take that part of the task. Isolation bounds each execution context. Synthesis brings the separate outputs back into one usable project state. These mechanisms matter because dividing a task creates several active boundaries that the harness must keep coherent.

Most real workflows mix execution modes. Dependent steps run sequentially, while independent steps can run in parallel. A multi-agent workflow in Claude Code might use a planning gate, concurrent implementation packages, ordered merges, and integrated validation. The dependency structure sets that order. A fixed roster of agent roles does not.

That distinction separates a team from its orchestration. The agents do the assigned work. The orchestration system decides when they act, where control moves, how execution stays isolated, and how the outputs return to one state. A larger team without those controls only creates more places for an unclear boundary to become active.

For a broader architecture vocabulary, our agent orchestration glossary separates the coordinating system from the agents it directs.

When does Claude Code multi-agent orchestration earn its cost?

Claude Code multi-agent orchestration earns consideration when the objective contains independent work packages with clean boundaries. If one step needs the previous step's output, keep those steps sequential. If separate agents can complete different tasks without waiting, the tasks can run concurrently.

Start with the simpler design and evaluate it. Add a multi-step agentic system only when simpler approaches fall short. That test prevents a team from becoming the default answer to work that one agent or an ordered workflow can already handle.

Clean boundaries are the practical threshold. Parallel Claude Code agents speed development only when the task has clean boundaries. In our decision worksheet, that means checking dependencies, assigning file or module ownership, defining shared contracts before implementation, and naming integrated validation. Those are the worksheet's operating tests, not a definition supplied by the clean-boundaries claim.

The cost side belongs in the same decision. Running agents in parallel increases token use because several context windows consume tokens at once. Communication and operational complexity also increase. Parallel work has to earn those costs through a workload that can actually proceed independently.

Use four questions before making that trade. Does either task require the other task's output? Can both proceed without waiting? Are the file boundaries clean? Is the parallel work substantial enough to justify extra contexts and coordination? The first two questions determine the execution order. The last two test whether concurrency is likely to preserve the benefit it promises.

This check often produces a hybrid answer. Independent packages can run together, while anything that consumes their outputs waits. That is a more precise design than declaring the entire feature parallel or sequential. It also gives each merge and validation step a reason to exist in the order you chose.

Our guide to agentic teams examines the team boundary in more depth. For the feature in front of you, the fastest useful check is a dependency graph and a written delegation contract.

Write the delegation contract before spawning agents

Map the dependency graph, then use this four-column worksheet to turn one bounded feature into assignments with explicit owners and completion checks.

Treat the two-minute, separable-file test as a rough heuristic. Parallelism adds decomposition, synchronization, and debugging costs. The worksheet therefore requires both enough work to justify those costs and file boundaries that can remain independently owned.

Containment starts below the model

Permissions in a prompt are not the whole control surface. Claude Code settings govern the starting model, actions that can run without asking, files the agent cannot read, and controls enforced by the organization. Those are concrete system boundaries, not descriptions of desired behavior.

Build deterministic containment at the environment layer before relying on model behavior. Agents still interact with ordinary computing surfaces: they read files, open sockets, and spawn processes. Mature containment tools and hard blast-radius limits therefore remain relevant.

For each assignment, inspect the surfaces the agent can reach:

• Which files can it read?
• Which actions can run without asking?
• Which sockets can it open?
• Which processes can it spawn?
• Which settings does the organization enforce?

These questions turn a role description into an authority boundary. The objective may say what an agent should do, while environment controls determine what it can do. Claude Code settings cover unattended actions, unreadable files, the starting model, and organization-enforced behavior. Keep both layers explicit so a narrow assignment does not sit inside a broad execution environment.

Each surface answers a different control question. Unreadable files limit the information available to the process. Rules for unattended actions place an approval boundary around execution. Socket and process access define where the agent can act beyond the current file operation. Organization-enforced settings apply controls above an individual session.

The order matters because model behavior is probabilistic while the environment boundary is deterministic. Behavioral instructions can steer an agent toward the intended path. Environment containment sets the hard edge of that path when model-level control does not catch a problem. That is the control layer that limits the blast radius.

The same workload analysis that selects an execution pattern should include these authority surfaces. Our AI agent architecture patterns guide treats authority and failure mode as part of the architecture choice, alongside the work itself.

Multi agent orchestration Claude Code example: a dashboard

Consider a dashboard feature. Schema planning, API design, and frontend structure can begin at the same time because the example gives them no blocking dependency. The remaining work waits for the contracts it needs:

• Visualization waits for the API contract.
• Permission controls wait for user roles and API routes.
• Tests wait for stable contracts and expected behavior.

This is a multi agent orchestration Claude Code example built from the dependency graph, not from a generic roster. Three workstreams can start early. Three others have explicit reasons to wait. The graph creates a hybrid workflow without forcing the whole feature into either serial or parallel execution.

The API contract is the clearest boundary in the example. API design can start early, but visualization waits because it consumes that contract. Permission controls have two inputs, user roles and API routes, so starting them before both inputs exist would ignore the graph. Tests wait for stable contracts and expected behavior for the same reason: they depend on a defined target.

After implementation, review can split by risk. A code-quality reviewer can inspect maintainability, duplication, naming, and structure. A business-logic reviewer can check metrics, filters, and dashboard behavior against requirements. A security reviewer can examine authorization, data exposure, input handling, and risky defaults. Those reviews can run in parallel before issues return to the relevant agents for repair and the orchestrator collects the final state.

How should plans, handoffs, and validation work together?

Plans set the boundary. Handoffs report what crossed it. Validation checks the result before another agent or the lead depends on it.

A useful handoff contains five fields:

1. Changed files.
2. Tests run.
3. Deferred work.
4. Acceptance criteria used.
5. The receiver's exact next scope.

Together, those fields show the receiver what changed, which checks ran, what remains open, which acceptance criteria were applied, and exactly what to do next. That is enough to continue without reconstructing the sender's path from a vague status summary.

New constraints should change the plan through a traceable reason. In the dashboard example, permission controls depend on user roles and API routes. If that work changes after those inputs stabilize, the revised plan should identify the relevant artifact, comment, or decision. A plan change without that reference leaves the rest of the team guessing which boundary moved.

Deterministic checks can catch drift before review begins, but they do not replace review. A check can flag a broken rule or failed test. Review then examines the completed work against its acceptance criteria and the receiver's next scope.

Shared state is where isolated agents can still collide

Separate worktrees isolate file edits. They do not settle architecture, shared contracts, migration identifiers, or integrated testing. Those concerns can cross worktree boundaries because agents may make independent decisions about the same project-level state.

One reported Claude Code incident makes the risk concrete. Two instances worked in different worktrees and created different database migrations. Both used the same filename, migration 267. The second migration silently overwrote the first.

The edits were isolated, but the identifier was shared. A worktree could not decide which migration number belonged to which agent, reconcile two different schemas, or protect the overwritten result. That is why file isolation cannot replace stable contracts, explicit ownership, a planned merge order, and integrated validation.

The collision is useful because neither instance needed to edit the other's worktree to create the conflict. Both agents independently created the same project-level identifier. The failure appeared when those isolated decisions met. Shared state can therefore include a filename or migration number, not only a file that several agents edit directly.

Treat that kind of identifier as a coordination boundary during planning. The dependency graph should expose it, the contract should give the surrounding module one owner, and integrated validation should inspect the combined project. Worktrees still isolate edits, but they cannot perform those architecture and coordination decisions for the team.

Apply the delegation worksheet to one bounded feature before you spawn a team. If the dependency graph points toward a larger pattern, work through our coordination-budget architecture guide before adding more agents.