learnaiwithrafa
ClaudeAgents

Split Your Agents by Context, Not by Job Title

Most multi-agent setups fail because people split the work the way they would split it across a team — planner, coder, tester. Anthropic's own guidance calls that the anti-pattern. Here is the split that works, and the bill you are signing up for.

4 min read3 sources
  • #agents
  • #claude-code
  • #architecture

The first multi-agent system almost everyone builds looks like an org chart: a planner agent, an implementer agent, a tester agent, passing work down the line. It feels obviously right. It is also the exact shape Anthropic flags as a failure mode — cutting between planning, implementation and testing produces what they call a telephone game, dropping context at every handoff.

The rule that replaces it: decompose along context boundaries, not problem phases.

Why the org-chart split fails

Phases of one task share a single body of context. Cut between them and every handoff has to squeeze that context into a summary, and each summary loses something the next agent needed. You have not parallelized anything — you have inserted lossy compression between the steps and made three agents responsible for what one agent already understood.

Context boundaries behave differently. Two agents that genuinely never need each other's raw material can run side by side with no handoff loss at all.

The three cases that justify a second agent

Anthropic's guidance names three. If your task does not hit one of them, a single well-equipped agent is the better build:

  • Context protection — one workstream's noise would pollute another's reasoning. Order history should not sit in the window while an agent runs a technical diagnosis.
  • Parallelization — genuinely independent investigation paths, where a lead fans out and no branch needs to read the others.
  • Specialization — you are past roughly 20 tools, domains conflict, or two jobs need system prompts that contradict each other.

What the money buys

Sometimes a lot. Anthropic's Research system — Opus 4 leading, Sonnet 4 subagents — outperformed a single Opus 4 instance by 90.2% on their internal research evaluations. The lead plans, spawns subagents in parallel, synthesizes what returns, then hands everything to a dedicated CitationAgent that maps claims back to sources as its own pass.

Their published sizing is smaller than most people assume. Simple fact-finding: 1 agent, 3–10 tool calls. A direct comparison: 2–4 subagents, 10–15 calls each. Only genuinely complex research goes past 10 subagents.

The part everyone underspecifies

Their most repeated engineering lesson is not about topology. It is about the brief you hand a subagent. Every delegation needs four things: an objective, an output format, guidance on which tools and sources to use, and explicit task boundaries. Leave those vague and subagents duplicate each other or quietly skip the thing you cared about — which is precisely the failure that makes people conclude multi-agent "does not work".

My rule of thumb: if you cannot write the brief in four lines covering those four points, the task is not ready to delegate. That is a spec problem, not an architecture problem.

Do this today

Take a task you have been running as one long agent session and ask a single question: do the pieces need to read each other's raw context? If yes, keep it single-agent and give it better tools. If no, split exactly there — and write each side's brief before you write any config.

In Claude Code the split is a file. Drop one in .claude/agents/ for a project subagent, or ~/.claude/agents/ to get it in every project. Only name and description are required; tools fences it in:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

The body becomes that subagent's system prompt — and it is the only prompt it gets, plus basic environment details, not your main system prompt. Write it accordingly.

Sources