I killed a $47 token budget in nineteen minutes the first time I enabled Claude Code agent teams: four agents on one codebase, all editing the same layout file, an orchestrator that never flagged the conflict, and a final state worse than where I started. That failure taught me more than any documentation did, because it revealed the actual skill behind agent teams. It is not spawning agents. It is designing work so agents cannot collide, and gating their output so confidence never substitutes for correctness. Multi-agent Claude Code is now how my real production batches run, and this guide is the setup and the rules that turned it from an expensive demo into infrastructure.
Agent teams versus subagents: get this distinction right first
Claude Code has two multi-agent mechanisms, and confusing them is the first budget-burner.
Subagents are workers spawned by your main session. Each gets its own context window, executes its task, and reports back to the parent. Critically, subagents do not talk to each other; all coordination flows through the orchestrator. This makes them ideal for divisible work: research fan-outs, batch processing, parallel exploration.
Agent teams are the experimental step further: a team lead session coordinates teammates that also have their own context windows but can communicate with each other directly, claim tasks from a shared list, and message peers about their findings. That peer channel is the feature, and also the risk: communication is capability, and capability without structure is how four agents end up editing one file.
My honest usage split after a year: the overwhelming majority of my multi-agent work runs on the subagent pattern with file-based contracts, because most divisible work needs no peer chatter. Teams earn their complexity when workers genuinely need to react to each other mid-task, a debugging session with competing hypotheses, or a build where the API shape is being negotiated between a backend and frontend worker as they go.
The setup, start to first run
Agent teams ship disabled by default. Enable them with an environment variable, either in your shell or in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Restart Claude Code and you can ask the session to create a team in natural language: describe the goal, the roles you want, and how the work divides. The lead session decomposes the work, spawns teammates, and coordinates. You remain the human in the loop above the lead. (The feature requires a paid plan, and because it is experimental, expect the surface to shift; the flag and behavior here match the current official docs as of this writing.)
That is genuinely all the mechanical setup there is, which is exactly the trap. The flag takes thirty seconds; the discipline below is what decides whether your first run resembles my $47 story.
The five rules that came from real money
1. Partition ownership before spawning anything
Every worker gets resources nobody else owns: specific files, specific IDs, specific directories. My content batches assign each worker an explicit list of post IDs and output paths namespaced to it. For code, give each teammate its own module, or go further and give each its own git worktree so isolation is enforced by the checkout, not by hope. If two workers must touch one resource, that resource becomes its own serialized task. This single rule prevents the entire failure class that ate my first budget.
2. Scope the brief, especially the evidence
Vague briefs produce confident invention. When my rewrite workers each received an assigned evidence source ("ground this in that file") rather than an open mandate ("make this good"), fabrication collapsed to near zero. Write each teammate's brief as: the goal, the inputs it may use, the outputs it must produce, and what it must not touch. The last clause is the one everyone skips and the one that pays most.
3. Plan first, then execute with a small team
Have the lead produce a decomposition you approve before any teammate spawns. Then start with two or three workers, not seven. Team overhead grows with every member (coordination messages, duplicated context, your own attention), and my experience matches the arithmetic: three well-scoped agents outperform six overlapping ones on both cost and output quality. Scale only after a clean run at the current size.
4. Mix models by role
Not every seat deserves the most expensive model. My batches run stronger models where judgment concentrates (writing, review, architecture) and cheaper, faster ones on mechanical slices (inventory, extraction, formatting checks). The lead should usually be your strongest model, because decomposition errors are the most expensive kind: every worker inherits them.
5. Gate the exit with code, not vibes
Nothing ships straight from a team. Every one of my runs ends at a deterministic verifier script: structure checks, link validation, banned-pattern scans, minimum quality scores. The reason the gate must be code: agents running the same model make correlated mistakes, so an agent reviewing agents shares their blind spots. My verifier has rejected work that read fluently and was wrong in ways I would have missed on item 40 of 100. Details of that architecture are in my agent swarm post.
Cost control that actually works
Teams multiply token spend by design, so shape the workload: lean per-worker context (task-scoped, never whole-project dumps), batch sizes that finish before any worker's window degrades, and durable state in a manifest file so a dead session never wastes the tokens that preceded it. During my longest batch project, sessions died at usage limits mid-run more than once; because progress lived in a JSON manifest updated after each unit of work, recovery cost one file read. The wider economics, including why fat contexts are billed to you repeatedly, are in the token limits and context hygiene post.
Budget expectation-setting from my logs: a well-scoped multi-agent batch costs meaningfully more than a solo session and returns more than the difference on divisible work. An unscoped one costs multiples and returns rework. The variable is the scoping, not the feature.
Use cases, ranked by how well they have paid me
- Batch content operations. The best fit I have found: many independent units, clear per-unit evidence, deterministic verification. This is how large rewrite and audit projects run on my own site.
- Corpus research fan-outs. Ten workers reading slices of a dataset no single context could hold, each emitting structured findings. Pure win; no peer communication needed, so plain subagents suffice.
- Parallel implementation across modules. Genuinely good when ownership boundaries are real (backend/frontend/tests), which is where teams' peer messaging starts earning its cost.
- Competing-hypothesis debugging. Two workers arguing different theories about one bug surfaces evidence faster than one worker anchoring on its first idea. Small, cheap, underrated.
- Review with specialized lenses. Security, performance, and style passes in parallel. Useful, with the caveat that agent reviewers complement the deterministic gate, never replace it.
The pattern across all five: the more independent the units and the more checkable the output, the better teams perform. Work that is deeply entangled or has no objective check is where multi-agent setups quietly become expensive noise. For the fuller management layer, roles, escalation, anti-sameness engineering, see the AI workforce post, and for the play-by-play of a full production run there is the agent teams playbook.
Start here, not where I started
Enable the flag, then deliberately do not build the seven-agent dream team. Pick one divisible task you understand deeply, spawn three workers with partitioned ownership and scoped briefs, and write the verifier before the workers. When the gate catches its first confident mistake, you will have learned the real lesson of agent teams cheaper than I did: the orchestration is the product, and the agents are just labor.
If you are standing up multi-agent Claude Code for a real team and want the setup designed around your codebase and your failure modes instead of a generic template, reach out through my contact page and tell me what you are trying to parallelize. I have made the expensive mistakes already; you do not need to repeat them.
