Multi-Agent Code Patterns for Claude: Prompts & Context

Every team that builds more than one multi-agent system eventually notices the same thing: the architecture barely changes between projects, but the success rate swings wildly. The difference is almost never the topology. It's the dozen small decisions about how prompts are structured, how tools are described, and what context each agent carries. Those decisions are reusable patterns, and once you've named them you stop re-deriving them every time.

This post collects the patterns that consistently separate a multi-agent system that ships from one that demos. They're language-agnostic — they apply whether you're in the Claude Agent SDK, Claude Code, or a hand-rolled loop — because they're really about how you talk to Claude, not which framework wraps it.

Pattern: the role-scoped system prompt

The single highest-leverage pattern is giving every agent a tightly scoped role in its system prompt, and nothing beyond it. An orchestrator's prompt should describe only how to plan, dispatch, and synthesize — it should not contain domain knowledge a subagent needs. A subagent's prompt should describe only its narrow job and its return contract. When you let role definitions bleed together, agents start second-guessing each other's responsibilities and you get duplicated or contradictory work.

Make the scope concrete with negative space. "You are a research subagent. You investigate exactly one assigned question and return findings in the specified format. You do not plan, you do not spawn other agents, you do not answer the user directly." Telling Claude what it should not do is as valuable as telling it what it should. The negations close off the failure modes where an over-eager subagent tries to take over the whole task.

Pattern: the explicit return contract

Subagents must return data the orchestrator can parse mechanically, so define the shape and put it in the prompt as a worked example. A return contract is the structured schema a subagent must produce so its output can be validated and merged without re-reading its reasoning. The cleanest version shows Claude a literal example of a good return and a bad one, then says "always match the good shape."

Pair the contract with a confidence or coverage field. Having each subagent report what it could not determine is worth more than any other single field, because it turns silent gaps into visible ones. The orchestrator can then decide to re-dispatch or to flag the limitation. Without it, a subagent that found 60% of the answer reports the same way as one that found 100%, and your synthesis can't tell them apart.

flowchart TD
  P["Role-scoped prompt"] --> A["Agent runs"]
  A --> T{"Needs a tool?"}
  T -->|Yes| TD["Tool with crisp schema"]
  TD --> A
  T -->|No| RC["Emit return contract"]
  RC --> CF{"Confidence field set?"}
  CF -->|Low| RE["Orchestrator re-dispatches"]
  CF -->|High| MG["Merge into synthesis"]
  RE --> A

Pattern: tool descriptions written for the model, not the docs

Tools are how agents touch the world, and the description you give Claude is doing prompt-engineering work, not API documentation. The pattern: write each tool description as if explaining to a sharp new hire when and why to use it, including the gotchas. "search_orders(customer_id): returns the customer's last 50 orders newest-first; use this before answering any order-status question; returns empty if the id is unknown — do not retry, ask for clarification instead." That last clause prevents an entire class of retry loops.

Keep tool surfaces small per agent. A subagent with twenty tools spends reasoning budget deciding which to use and picks wrong more often. Give each agent only the three or four tools its role actually needs. This is another payoff of role-scoping: a tightly defined role implies a small, obvious tool set, which in turn makes the agent's behavior predictable.

Pattern: context budgeting per agent

Every agent should carry the minimum context required for its job. The pattern is to build each agent's context deliberately: its role prompt, its specific task, the smallest slice of reference material that task needs, and nothing else. Dumping the full conversation or an entire document into a subagent doesn't make it smarter — it makes it slower, more expensive, and more likely to fixate on an irrelevant detail.

A practical technique is to have the orchestrator extract and forward only the relevant facts rather than raw material. Instead of handing a subagent a 30-page spec, the orchestrator pulls the three requirements that subagent needs and passes those. This keeps subagent contexts lean and, as a bonus, forces the orchestrator to actually understand the material well enough to extract from it.

Pattern: state passing through the orchestrator, never around it

Because subagents have isolated contexts, any state they need to share must flow through the orchestrator. The anti-pattern is trying to give subagents a shared mutable store they all write to mid-run — it sounds elegant and produces race conditions and stale reads. The reliable pattern is a clean cycle: subagents return, the orchestrator updates its view of the world, then re-dispatches with fresh briefs. State lives in the orchestrator's context, and subagents are stateless workers that get a brief and return a result.

This discipline also makes runs reproducible. If state only ever moves through the orchestrator, you can log the orchestrator's state at each step and replay any run exactly. The moment subagents start sharing hidden state, that property dies and debugging becomes archaeology. Keep the data flow boring and your future self gets observability for free.

Frequently asked questions

What goes in the orchestrator prompt versus the subagent prompt?

The orchestrator prompt holds planning, dispatch, and synthesis logic plus the rules for decomposition. The subagent prompt holds one narrow role, its tool set, and its return contract. Domain facts a subagent needs belong in its brief, not in the orchestrator's system prompt — keep the roles cleanly separated.

How detailed should tool descriptions be?

Detailed enough that Claude knows when to call the tool, what it returns, and how to handle the empty or error case — written like guidance for a smart new hire. Skip the implementation trivia. The most valuable lines tell the model what to do when the tool fails, which prevents retry loops.

Why not give every agent access to all the tools and context?

Because more tools and more context mean more wrong choices and higher cost. A focused agent with three relevant tools and a lean context is faster, cheaper, and more reliable than a maximally-equipped one that spends its reasoning budget deciding what to ignore.

Can subagents talk to each other directly?

Avoid it. Direct subagent-to-subagent communication reintroduces shared mutable state and the race conditions that come with it. Route everything through the orchestrator: subagents return, the orchestrator updates state and re-dispatches. It's a little more verbose and a lot more debuggable.

These patterns, applied to voice

CallSphere builds voice and chat agents on exactly these patterns — role-scoped prompts, tight tool schemas, and lean per-turn context — so an assistant can look up an account, check a calendar, and book a slot without losing the thread. See the patterns in production at callsphere.ai.

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.