Prompt and Context Design for Parallel Claude Agents

In a parallel Claude Code build, the prompt is not just an instruction — it is the entire world a subagent gets to see. There is no shared chat history to fall back on, no teammate to ask. Whatever you put in the context is what the agent knows; whatever you leave out, it cannot use. That makes context design the highest-leverage thing you do when redesigning Claude Code on desktop for many agents. This post is about getting the contents of that window right: what belongs, what to cut, and why.

The temptation, especially when an agent gets something wrong, is to add more — more rules, more examples, more background. With parallel agents that instinct is usually the bug. Every extra token costs you across every spawned agent, and the rules that matter drown in the ones that don't.

Key takeaways

• A subagent's context is its whole world — design it deliberately, not by accumulation.
• Include the task, the scope, the return contract, and only the conventions relevant to this slice.
• Leave out other agents' transcripts, the full repo, and rules that don't apply to this task.
• Put the most important instructions at the start and the contract at the end, where attention is strongest.
• Isolation beats sharing: a clean, narrow context outperforms a rich, noisy one.

What every subagent context must contain

Four things are non-negotiable. First, the task: a specific, bounded statement of what to produce, not a vague goal. Second, the scope: exactly which files or resources this agent owns and may touch. Third, the return contract: the JSON shape its final message must take. Fourth, the minimal relevant context: the handful of conventions, snippets, or constraints that actually bear on this task. Everything beyond these four is a candidate for deletion.

The discipline here is subtractive. Start from those four and add only what a competent engineer would genuinely need to do this one task without asking a question. If you find yourself pasting a 4,000-word style guide so the agent can fix one function, you are briefing the wrong slice.

What to deliberately leave out

Three things almost never belong in a subagent's context. The transcripts of other subagents — including them reintroduces the cross-contamination that isolation exists to prevent. The entire repository — agents read files through tools on demand; pre-loading everything wastes tokens and buries the relevant parts. And rules that don't apply to this task — a translation agent does not need your database migration policy. Cutting these is not just economy; it sharpens the agent's focus.

flowchart TD
  P["Candidate context item"] --> Q{"Needed for THIS task?"}
  Q -->|No| X["Leave out"]
  Q -->|Yes| R{"Available via a tool on demand?"}
  R -->|Yes| T["Let agent fetch it when needed"]
  R -->|No| K{"Small & stable?"}
  K -->|Yes| I["Inline in the briefing"]
  K -->|No| S["Summarize, then inline the summary"]

That decision tree is the core of the whole post. For any piece of information, ask whether the agent needs it for this task; if yes, whether a tool can fetch it on demand; and only inline what is both needed and not cheaply fetchable. Large-but-needed material gets summarized rather than dumped.

Why isolation beats a rich shared context

It is tempting to give every agent the same fat context so they "stay aligned." In practice, a narrow, isolated context produces better work. An agent reasoning over exactly the files it owns and the three rules that apply makes fewer mistakes than one sifting a giant brief for the relevant 5%. Isolation also prevents a subtle failure mode: agents anchoring on irrelevant details from a shared dump and producing changes that technically follow the brief but miss the task.

Alignment in a parallel build does not come from shared context; it comes from a shared contract. Every agent returns the same JSON shape and follows the same scope rules, so their outputs compose even though their contexts differ wildly. Design for compatible outputs, not identical inputs.

Ordering: put attention where it matters

Within a single prompt, position carries weight. Lead with the task and the scope — the things the agent must not forget — and close with the return contract, so the last thing the agent reads is the exact shape it must produce. Reference material and conventions sit in the middle. This is not superstition: instructions at the edges of a prompt are simply less likely to be lost than ones buried in the center of a long block.

A practical template: a short task line, a scope block listing owned paths, a lean conventions section, then the contract spelled out in full. Keep the whole briefing as short as the task allows. A tight 600-token prompt that an agent fully internalizes beats a 4,000-token one it skims. When you do need to include a longer reference — a schema, an interface, a set of examples — set it off clearly with a heading so the agent can navigate to it, rather than blending it into the prose where it competes with the instructions for attention.

Context that changes mid-run

Sometimes an agent learns something the orchestrator should know — a discovered dependency, an ambiguity, a follow-up task. Resist the urge to let agents write back into a shared context to communicate. Instead, surface it through the return contract's followups or notes field. The orchestrator reads those summaries and decides whether to update the briefing for the next round of agents. Context flows down as input and up as structured summary — never sideways as a shared mutable blob.

This downward-and-upward flow also gives you a clean way to evolve context across rounds. The first wave of agents operates on the orchestrator's initial briefing; their notes reveal what was missing or ambiguous; the orchestrator folds those learnings into a tightened briefing for the next wave. Over a few rounds the briefing converges on exactly the information the task needs — discovered empirically rather than guessed up front. The key is that this refinement happens in one place, under the orchestrator's control, instead of accreting silently inside a context the agents all share and quietly mutate. Centralizing context evolution is what keeps a long parallel run from drifting.

Common pitfalls

• Briefing by accumulation. Adding rules every time an agent errs bloats context and buries what matters. Diagnose whether the real fix is a clearer task or a tighter scope.
• Pre-loading the whole repo. Agents fetch files via tools; dumping everything wastes tokens and dilutes focus. Inline only small, stable, needed material.
• Sharing transcripts for "alignment." This reintroduces cross-contamination. Align through a shared contract, not a shared context.
• Burying the contract. If the return shape is mid-prompt, agents drift from it. Put it last.
• Sideways communication. Letting agents write to a shared scratch to talk creates races. Communicate up through structured results only.

Design a subagent's context in 5 steps

1. Write the bounded task and the owned-scope list first.
2. Add the return contract verbatim and place it at the end of the prompt.
3. For every candidate context item, run the decision tree: needed? fetchable? small and stable?
4. Inline only the small, stable, needed material; summarize anything large.
5. Cut other agents' transcripts, the full repo, and irrelevant rules entirely.

Frequently asked questions

What belongs in a parallel subagent's context?

Four things: the bounded task, the file or resource scope it owns, the return contract its final message must follow, and only the conventions or snippets that bear on this specific task. Everything else should be fetched on demand or left out.

Why not give every agent the same rich context?

Because a narrow, isolated context produces sharper work and costs fewer tokens per agent. Shared context also risks cross-contamination and anchoring on irrelevant details. Alignment comes from a shared output contract, not shared input.

How do agents share what they learn if context isn't shared?

Through their structured return value — fields like notes and followups. The orchestrator reads those summaries and decides whether to update briefings for the next round. Information flows down as input and up as summary, never sideways.

Where should the return contract go in the prompt?

At the end. Instructions at the edges of a prompt are least likely to be lost, and making the contract the last thing the agent reads keeps its final message in the exact required shape.

Bringing agentic AI to your phone lines

CallSphere applies this same context discipline to conversations — giving each voice and chat agent exactly the customer context and tools a call needs, nothing more, so it answers every message and books work around the clock. See it 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.