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

A developer outlines rules for delegating tasks to subagents in a Claude-powered coding workflow, emphasizing context economy and reasoning quality over parallelism. The guidelines cover batch sizing, model routing, skill propagation, and avoiding context pollution from status polling.

Principle: Protect the main thread. Optimize for its context economy. Delegate to preserve reasoning quality, not to maximize parallelism. 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. - 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" . - 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. 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. 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.