The Orchestrator's Tax
Rahul Garg (martinfowler.com; edited/guided by Martin Fowler) · rss · 2026-07-28 source ↗ Reader 🖥️
Agent Context Files (CLAUDE.md / AGENTS.md)Cognitive LocalityContext EngineeringContext Rot & Context LimitsHuman as Orchestrator of AgentsMulti-Agent OrchestrationRight-Sizing Boundaries & Primitives
The real value of a subagent is not the wall-clock time it saves through parallel execution but what it keeps out of the orchestrator's context, so multi-agent workflows should be designed and governed around protecting the orchestrator's limited working memory — via task splits that respect 'cognitive locality' and via minimal, fact-justified standing rules — rather than around maximizing delegation, agent count, or governance.
practical · mixed — Structured as a first-person incident narrative (a specific multi-agent coding session) that is progressively generalized into a theoretical claim (context as a competed-for, not just capacity-limited, resource) and then converted into practical prescriptions (four CLAUDE.md rules plus a meta-heuristic for writing future rules).
Structure
| Part | Role |
|---|---|
| Opening incident: four subagents running against a .NET refactor feel harder to reason about than the code itself. | narrative hook / motivating doubt |
| "The Incident Was Not Really About Parallelism": the transcript-polling episode (a full raw agent transcript pulled into the main thread by a throwaway status check) is identified as the standout cost, with an explicit caveat that the ranking is the orchestrator's own self-report, not a measurement. | evidence — reframes the expected cost (duplication/parallelism) as the wrong target |
| "The Costs Were Not All the Same": decomposes the session into distinct culprits — duplicated orientation between two agents in the same code area, an unsafe concurrent git stash operation, and status polling. | evidence — shows the costs are heterogeneous, undermining a single 'four agents is too many' framing |
| "The Scarce Resource Is the Orchestrator's Working Memory": token spend is one-time, but context pollution taxes every subsequent turn; separately, more content in context competes for attention even when the window has room left. | core theoretical claim / pivot |
| "Cognitive Locality Changes What Parallelism Is For": names the duplicated-orientation problem as tasks partitioned by task rather than by the mental model they require, and reframes subagents' function as isolation of noisy reasoning, not speed. | conceptual payoff — defines the mechanism behind the unity claim |
| "Turning a Session into Standing Rules": compresses the incident into four CLAUDE.md rules (agent-count ceiling, no full-transcript polling, no repo-wide git in concurrent prompts, overlapping ownership as consolidation signal). | practical application |
| "The Next Mistake Would Have Been More Governance": a later session's near-miss (a rejected confirm-before-spawn gate) yields the 'one missing fact' heuristic for what deserves a standing rule. | self-correction / refinement of the practical method |
| "Where This Leaves Me": frames the whole method as an open, human-steered flywheel and closes with unresolved questions about measurement and governance calibration. | conclusion with explicit epistemic humility |
Key terms
- Orchestrator Multi-Agent Orchestration
The main AI session/thread that spawns and coordinates subagents — the only part of the system that accumulates understanding across a session (design rationale, constraints, prior trade-offs) and therefore the locus that must be protected. - Cognitive locality Cognitive Locality
Tasks that require reconstructing the same mental model of a codebase (architecture, conventions, surrounding code) should be assigned to the same agent/context; splitting them by task rather than by the knowledge they require forces independent, duplicated reconstruction. - The orchestrator's tax (title term)
The cost paid not by running subagents, but by the orchestrator itself when it lets low-value information (e.g. a raw background-agent transcript) into its own context — a cost that, unlike a one-time token bill, is carried forward and 're-charged' on every subsequent turn. - Standing instruction file (CLAUDE.md)
Treated as itself a scarce, cumulative resource: 'every extra line in a standing instruction file is a cost paid again on every future session,' so a rule must justify its own recurring cost, not just its one-time correctness. - The 'one missing fact' heuristic
A test for whether a discovered gap deserves a new standing rule: ask whether a reasonably competent orchestrator would make the right decision once it knew the single missing fact. If yes, state the fact. If the fix instead specifies a decision procedure (approvals, checkpoints, mandatory steps), that's a sign of encoding process where a small clarification would do.
Propositions
- explicitRunning multiple subagents in parallel is not the primary source of a session's cost or benefit; the wall-clock speedup from parallelism is a visible byproduct, not the interesting part.conf: high
- explicitThe largest identified cost in the described incident came from the orchestrator pulling a full raw transcript of a background agent into its own context to answer a small status check, not from the duplicated orientation work of running four subagents.conf: high
- explicitWhether the transcript-polling incident was actually the single largest cost of the session is an unverified hypothesis based on the orchestrator's own self-report, not a measured fact.conf: high
- explicitA token bill is paid once, but context pollution is paid on every subsequent turn, because polluted content stays in the orchestrator's context and is carried forward whether or not it remains useful.conf: high
- explicitBeyond running out of context-window space, the more that is sitting in context, the harder it gets for a model to pick out what matters right now — a larger context window doesn't fix this, it just gives noise more room to accumulate before anyone notices.conf: high
- explicitThe orchestrator is the only part of the multi-agent system that accumulates understanding across a session (design rationale, constraints, prior trade-offs); subagents are meant to be disposable, with exploration, failed approaches and noisy intermediate reasoning designed to stay in worker contexts and never return to the main thread.conf: highsupportsClaude Code: Best practices for agentic coding · p12 — Restates and specializes the general 'context is a finite, degradable resource' claim into the multi-agent case: the orchestrator specifically is the part of the system that must not be polluted.
- explicitTasks that require reconstructing the same mental model of a codebase should be assigned to the same agent/context ('cognitive locality'); splitting them by task rather than by the knowledge each task requires forces multiple agents to independently rebuild the same understanding from scratch.conf: highextendsAI Is Changing Software Engineering. The Fundamentals Still Matter. · p2 — Gives a specific name and mechanism ('cognitive locality': tasks needing the same mental model should stay together) to the same underlying claim that right-sizing/chunking context correctly is what unlocks value when partitioning work for AI.
- explicitThe actual value of subagents is that they let the orchestrator offload reasoning it doesn't need to hold onto, keeping noisy intermediate work out of the main thread — not that they save wall-clock time; running agents concurrently is 'useful, but ordinary.'conf: highextendsThe Orchestration Tax is You · p15 — Both conclude that spawning/running more agents is not itself the skill; the real discipline is designing the system around a single, non-cloneable, serial resource. Osmani names that resource as the human's attention/review capacity; this piece applies the identical structural insight one level down, to the AI orchestrator's own context.supportsAccelerating Delivery: How AI Agents Can Own the Initial Code Draft · p4 — Agrees that spawning sub-agents for focused tasks keeps the effective context clean, and supplies a mechanism (competing attention, not just token-limit avoidance) for why this works.
- explicitA small set of concrete standing rules (prefer 2-4 agents per wave and ask about merging overlapping tasks at 5+; never fetch a full transcript to answer a lightweight status question; forbid repository-wide git operations inside concurrent agent prompts; treat overlapping file ownership as a signal to consolidate, not to spawn more agents) was sufficient to encode the incident's lessons.conf: high
- explicitA subagent does not automatically inherit skills that are active in the parent/orchestrator session; the orchestrator must explicitly pass the relevant skill along (e.g. by pointing the subagent at the skill file) for it to apply.conf: high
- explicitA proposed new standing rule should be tested by asking whether a reasonably competent orchestrator would make the right decision once it knew the one missing fact; if yes, the rule should just state that fact, and a fix that instead specifies a decision procedure (approvals, checkpoints, mandatory steps) is usually a sign of encoding process where a small clarification would have sufficed.conf: highsupportsYour AGENTS.md might be a big problem · p7 — Both argue that a standing instruction file should be judged by whether each line earns a recurring cost, not by exhaustiveness — 'quality of attention beats coverage' matches this piece's 'does this earn a place in the orchestrator's context.'
- explicitA universal confirm-before-spawn governance gate was rejected because there was no evidence that bad spawn plans were slipping through for lack of confirmation; a blanket gate would add a round-trip cost to every similar session and would likely be approved on autopilot before long, without addressing the actual (context-pollution) problem.conf: high
- implicitThe author treats one well-instrumented but ultimately self-reported incident (partly graded by the AI system being critiqued) as sufficient warrant for writing durable, cross-session changes to a standing instruction file.conf: medium
- explicitcorroboratedThe scarce resource worth watching in long-running agent workflows — after CPU/memory/throughput, then tokens — is the quality of the orchestrator's own working memory, because pollution introduced into it keeps 'charging rent' for the rest of the session.conf: highsupports ←The Conductor Developer · p2 — Both name the human/orchestrator's own attention or working memory — not tokens, not any SDLC stage — as the actual scarce resource once AI writes the code; Laycock frames this as a developer-identity and career shift, Fowler/Garg supply the underlying mechanism (context pollution 'charging rent' every turn) for why it degrades.
- explicitImproving an agentic workflow is an open, human-steered flywheel: a session exposes a gap, a human must notice it felt wrong, judge whether it is real or noise, and decide what becomes a standing rule; the orchestrator can grade its own session and surface clues but cannot make that judgment call itself.conf: high
Arguments
The primary benefit of subagents is protecting the orchestrator's context/working memory, not saving wall-clock time. strength: medium
Explicit premises:
- The duplicated-orientation cost of running four subagents was real but was not identified as the biggest cost.
- The transcript-polling incident introduced tens of thousands of tokens of raw, noisy content that persisted across every subsequent turn.
- A token bill is one-time, but context pollution taxes every future turn.
Implicit premises:
- The orchestrator's downstream judgment quality depends on what currently occupies its context, not merely on whether the context window has remaining capacity.
- Attention is a competitive resource, not just an additive one — more content in context degrades the model's ability to weigh what matters even when space remains.
Inferences:
- If protecting orchestrator context is the real function of subagents, agent count and task splits should be sized by orientation/consolidation logic (cognitive locality) rather than by throughput or wall-clock goals — an inference the author draws explicitly in the following section.
A newly discovered gap should usually be encoded as a stated missing fact, not as a decision procedure (e.g. a confirmation gate).
Explicit premises:
- A confirm-before-spawn gate was proposed after discovering that subagents don't inherit active skills.
- The author found no evidence that bad spawn plans were actually slipping through for lack of a confirmation step.
- A universal gate would add a round-trip cost to every similar future session and risks being rubber-stamped over time ('approving on autopilot').
Implicit premises:
- Decision procedures (approvals, checkpoints) impose a recurring attention cost every time they fire, whereas a stated fact costs attention only when it's actually relevant.
- The human can reliably distinguish, at the time of the incident, a 'missing fact' gap from a genuine 'recurring bad judgment' gap that would warrant a procedural safeguard.
Inferences:
- Any candidate standing rule can be pre-tested by imagining a competent orchestrator that already knows the fact in question — if that alone would produce the right decision, a checkpoint is unnecessary.
Narratives
- The opening incident: four subagents running against a .NET response-pipeline refactor start to feel harder to reason about than the code itself, prompting the author to stop and interrogate the workflow rather than the code.
→ Grounds the entire piece's generalizations in one concrete, present-tense session rather than abstract multi-agent theory; supplies the specific artifact (the transcript dump) that makes the 'pollution vs. parallelism' distinction legible rather than asserted in the abstract. - A status check ('check on the agents') triggers a tool call that imports a full raw background-agent transcript — tens of thousands of tokens of JSONL, reasoning, and tool output — into the main thread, and this happens twice.
→ Supplies the concrete mechanism behind the piece's central claim that context pollution, not duplication or parallelism, was the standout cost — and behind the broader claim that pollution is carried forward on every subsequent turn. - A later session reveals that subagents don't inherit skills active in the parent session; the author's first instinct is to add a universal confirm-before-spawn gate, but he abandons it after realizing there was no evidence of the underlying failure mode it would guard against.
→ Illustrates the 'one missing fact' heuristic in action (rather than stating it abstractly) and demonstrates the author correcting his own over-governance instinct.
Questions addressed
- ✅ What was the actual biggest cost of running four subagents in this session?
Attributed to the orchestrator importing full raw agent transcripts via status polling — but the author explicitly flags this ranking as the orchestrator's own unmeasured self-report, not an instrumented finding. - ✅ Were four subagents simply too many?
Explicitly abandoned as the wrong question rather than answered — the author reframes the inquiry around what belongs in the orchestrator's context instead of how many agents ran. - ✅ What should subagents actually be used for, if not primarily to save time?
To isolate noisy intermediate reasoning from the orchestrator's context and to respect cognitive locality when splitting work. - ⭕ How much governance (confirmation gates, mandatory checkpoints) should be layered onto an agent workflow?
Explicitly left open: "I don't have a settled view of how much governance is enough, and I don't think this piece earns one." - ⭕ How should one measure whether the orchestrator's own self-critique of a session is trustworthy?
Named as an open question in the closing list rather than answered. - ⭕ What decision procedure lets an orchestrator recognize 'cognitive locality' — i.e., detect before spawning that two tasks will require reconstructing the same mental model — so it can act on rules 1 and 4?
Not addressed; the piece supplies the diagnosis after the fact (in the incident review) but not a method for making it prospectively.
Gaps
- incompleteThe four standing rules use specific numeric thresholds ('two to four agents,' 'five as a consolidation signal') that the author explicitly says were calibrated to his own workflow and to one model (Claude Sonnet 5) on one codebase, and disclaims as universal constants — yet the piece gives no method for a different reader to derive their own thresholds, only the instruction to 'modify and optimize.'
Read next: Look for calibration methods rather than fixed numbers — e.g. Osmani's alternative anchor ('the correct number of parallel agents equals the number you can code-review properly') ties the threshold to a measurable capacity rather than to incident review alone. - incompleteThe piece never specifies the actual decision procedure an orchestrator should run to detect 'cognitive locality' before spawning agents — i.e. how it recognizes, in advance, that two tasks will require reconstructing the same mental model of a codebase. Rules 1 and 4 (prefer 2-4 agents; treat overlapping file ownership as a consolidation signal) assume this diagnosis is already available; they don't produce it, and file overlap is only a weak proxy for shared mental-model requirements (two tasks can need the same understanding without touching the same files, or touch the same files with genuinely independent context needs).
Read next: This is the exact gap the task brief flagged and the piece's most productive incompleteness: look for task-decomposition or dependency-analysis frameworks that could operationalize 'shared mental model' as a measurable property rather than a post-hoc diagnosis (e.g. right-sizing-boundaries / chunking-context literature, or explicit action-complexity/context-complexity rubrics). - illogicalThe piece states once, explicitly, that its central ranking claim (transcript-polling as the largest cost) is 'the orchestrator grading its own mistake' and 'not a measured fact' — but the same self-report is then treated as reliable enough to justify permanent CLAUDE.md rules and to found the article's closing thesis about a 'third thing worth watching' in agent workflows. The epistemic caveat is stated once and not carried through the argument's confidence level for the rest of the piece.
Read next: Compare against pieces that build instrumented (not self-reported) cost accounting for agent sessions, to see whether the transcript-polling cost actually dominates duplication cost once measured rather than inferred.closed byMy AI Kept Pushing Me to Ship, So I Asked It Why — Fowler's piece flags that it treats an orchestrator's self-graded, unmeasured claim as reliable enough to justify permanent CLAUDE.md rules without carrying its own stated epistemic caveat through the argument. This article builds and demonstrates exactly the missing discipline: it structurally separates a model's checkable self-report of behavior (trustworthy) from its unreliable self-report of reasons (a confabulated story per Turpin et al.), and validates the resulting standing rule via an independent, fresh-context second opinion rather than trusting the original session's self-grading. - incompleteThe 'one missing fact' heuristic (state a fact, don't prescribe a procedure) is itself applied inconsistently within the essay: rule 3 ('do not allow repository-wide git operations inside concurrent agent prompts') is a decision procedure/hard constraint, not a stated fact, yet it is presented alongside three fact-like rules without acknowledging that some gaps (systemic/safety risks) may genuinely warrant a rule-as-procedure rather than a rule-as-fact, undermining the heuristic's claimed generality.
Read next: Look for a taxonomy distinguishing 'missing fact' gaps from 'systemic risk' gaps that would justify when a hard constraint (vs. a stated fact) is the right form for a standing rule. - uninformedThe piece arrives at its fleet-sizing and context-budget numbers from a single incident without engaging existing multi-agent/harness literature that already proposes related numeric or structural heuristics — e.g. Osmani's 'correct number of parallel agents equals the number you can review' (tied to human review capacity rather than orchestrator context) or Zuill/Herr's practice of keeping an agent's context window around half-full by moving detail into on-demand skill files.
Read next: extract-osmani-orchestration-tax-is-you and extract-software-teaming-age-of-ai-zuill-herr, both already in the corpus, offer adjacent-but-distinct anchors for the same class of threshold.
Related documents
- The Orchestration Tax is You
- Agent Harness Engineering
- The Anatomy of an Agent Harness
- Charlie Hills 🦩's Post
- Claude Code: Best practices for agentic coding
- A harness for every task: dynamic workflows in Claude Code
- Jacob Langvad Nilsson's Post
- No Vibes Allowed: Solving Hard Problems in Complex Codebases – Dex Horthy, HumanLayer
- Advanced Context Engineering for Coding Agents (ace-fca.md)
- Stop Using /init for AGENTS.md