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.
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.