CLAUDE.md rules for subagent delegation: batch sizing, model routing, skill propagation, and avoiding orchestrator context pollution from status polling.

subagent-cost-economy.md

Subagent delegation and cost economy

Principle: Protect the main thread. Optimize for its context economy. Delegate to preserve reasoning quality, not to maximize parallelism.

Context economy (research and lookups)

Reading >~3 files or unfamiliar territory to ground a task? Delegate to an Explore/general-purpose subagent with a tight question. Its reads stay in throwaway context; only the synthesis returns. Direct reads in the main thread persist for the entire session. Reserve them for small, targeted lookups.

Large file with one relevant section? Grep to locate it, then Read with offset/limit. Don't read the whole file.

Sibling files sharing structure (specs, fixtures, tests)? Read one in full to learn the pattern, then grep the rest for structural conformance.

Other delegation triggers

• Independent subtasks with no data dependency? Spawn one agent per subtask in a single message instead of running serially, subject to the batching limits below. Follow the orchestration rules below.
• Nontrivial change (core logic, security, or >1 file)? Spawn a fresh agent to independently re-derive correctness before declaring the work complete. Don't rely only on self-review. Skip for one-line or purely mechanical edits.
• Self-contained subtask: clear deliverable, no main-thread context needed, and otherwise >~3 file edits/reads inline? Delegate it (for example, "write tests for X" or "update all callers of Y").

When not to delegate

• Single-file, single-location lookup/edit: do it directly.
• Scope still ambiguous? Resolve it first (ask or decide). Never hand a subagent an underspecified prompt: state the objective, the output format, which tools/sources to use, and what's out of scope.
• Destructive or high-blast-radius operations (push, deletion, force operations): keep them in the main thread under confirm-first. Never delegate them.

Parallel orchestration

Before spawning agents:

• Define ownership for every agent (files or scope). Concurrent writers must own disjoint sets; if overlap is unavoidable, isolate work with worktrees instead of racing the working tree.
• Delegate by cognitive locality, not task count. Merge work that shares a subsystem, files, conventions, or mental model. Each additional agent pays the orientation cost again.
• Specify required skills. Subagents do not inherit skills automatically. Reference the skill file instead of restating it inline.
• Subagent producing large or structured output (generated code, reports, extracted data)? Instruct it to write to a file and return a reference. Routed through the orchestrator instead, it's copied twice (produced, relayed) and then sits in context for the rest of the session whether it's needed again — the depletion cost and the dilution cost, paid at once.

Prefer 2-4 agents per wave. More than 4 independent subtasks? Group by cognitive locality until the wave count fits; don't spawn one agent per subtask past that point. Treat 5+ ungrouped agents as a signal to consolidate.

Subagents inherit the current model unless explicitly changed. Use cheaper models for mechanical work (search, scaffolding, structural checks). Reserve the primary model for tasks requiring equivalent reasoning quality.

Forbid repo-wide Git operations (stash, checkout, reset, clean) in subagent prompts. Use scoped alternatives instead (for example, test --filter <name>).

Background tasks: wait for completion notifications. If asked for status, answer from what is already known. Don't call TaskOutput; it may return the full raw transcript, and repeated polling multiplies context cost.

Guideline: Delegate to minimize main-thread context while preserving cognitive locality. Parallelism is a tool, not the objective.

Other cost-saving habits

Confirm well-documented library or framework behavior through reasoning. Cite the documentation when appropriate, and mark conclusions as inference when certainty matters. Reserve execution for undocumented, surprising, or project-specific behavior.

When using tools that forward the full conversation transcript (for example, advisor or critic calls), batch multiple open decisions into fewer, earlier calls. Cost scales with transcript length, so the same call is cheaper earlier than later.

Global Claude Code (CLAUDE.md) rules for subagent delegation economics: when to delegate vs. do work inline, how to size a parallel batch safely, and how to avoid orchestrator-side waste (e.g. polling background agents for status). Distilled from a real session post-mortem where 4-way parallel delegation was one or two agents too fine, and the orchestrator's own status-check polling cost more tokens than the delegation itself.

Note on numbers: thresholds like "2-4 agents per wave" or "~3 files" are not universal constants — they're what fit the kind of work I was doing (codebase size, module granularity, task shape) when I wrote this. Tune them up or down for your own repo and workflow rather than treating them as fixed rules.

Usage: paste the section(s) below into your own ~/.claude/CLAUDE.md (or project CLAUDE.md, or a particular folder) and adjust thresholds to your codebase's granularity.

This is not the whole global CLAUDE.md file, but the section just related to Subagent delegation and cost economy.

I've created a compressed version of this CLAUDE.md file. Reason: A CLAUDE.md/AGENT.md files are loaded with every turn. So its size incurs a constant cost, not just a one-time cost. A file about “Context Economy” should itself be economical.

The prose explains the "why" well, which makes the rules easier to understand and more robust in borderline cases. However, this explanatory benefit is limited to specific instances – namely, when an unclear case actually arises. The cost of the longer version, on the other hand, is an ongoing expense because the file is loaded in its entirety into the context during every single interaction.

Therefore, I'm using imperative bullet points instead of paragraphs; provide explanations only for counterintuitive rules and eliminate redundancy. The result is about one-third of the length while maintaining the same level of compliance. The long version remains a valuable reference.

# Subagent Delegation & Context Economy

**Principle:** Protect the main thread. Delegate for reasoning quality, not parallelism.

## Delegate when
- Reading >~3 files or unfamiliar territory → Explore subagent with a tight question.
- Large file → grep, then Read with offset/limit (never read whole).
- Sibling files → read one fully, grep the rest.
- Independent subtasks → one agent each, single message.
- Nontrivial change (core logic, security, >1 file) → fresh agent verifies correctness.
- Self-contained subtask with clear deliverable + >~3 inline edits/reads.

## Don't delegate when
- Single-file, single-location edit → do it directly.
- Scope ambiguous → resolve first; never send underspecified prompts (state objective, output format, tools, out-of-scope).
- Destructive/high-risk ops (push, delete, force) → main thread, confirm-first.

## Orchestration
- Concurrent writers own disjoint files; use worktrees on overlap.
- Group by cognitive locality, not task count.
- 2–4 agents per wave; consolidate if 5+.
- Specify skills (not inherited); reference skill files.
- Large output → write to file, return a reference.
- Cheaper models for mechanical work; primary model for reasoning.
- Forbid repo-wide Git ops in subagent prompts; use scoped alternatives.
- Background tasks: await notifications; don't poll `TaskOutput`.

## Cost habits
- Confirm documented behavior by reasoning + citation; execute only for undocumented/project-specific cases.
- Batch decisions into fewer, earlier transcript-forwarding calls.