When you push a whole project through a single conversation, everything shares one context window. The research you did at the start gets squeezed out by the code you wrote in the middle, and by the end Claude is politely guessing at decisions it made an hour ago. A team fixes that by giving each worker its own head. In Claude's words, a subagent is a specialised assistant that "handles specific types of tasks in its own isolated context window" and returns only a summary, so the exploration never clogs up your main thread (Claude Code subagents docs).
So the win is not raw speed. It is that each agent holds exactly one job, with nothing else competing for its attention, and you get a clean summary instead of ten thousand words of scrollback.
Four is the number that keeps working for me. Enough separation that nobody is doing two jobs, few enough that they are not tripping over the same files. Anthropic's own guidance lands in the same place: start with three to five and scale only when the work genuinely runs in parallel (agent teams docs).
curl -fsSL https://claude.ai/install.sh | bash. On Windows PowerShell run irm https://claude.ai/install.ps1 | iex. If terminals are not your thing, Claude Code also runs in the browser at claude.ai/code and as a desktop app, and everything below works the same way there (all the ways to run it).cd into the folder you want the work to happen in, then type claude and log in when it prompts you. Everything the team builds lands in that folder, so make it a fresh one for a new project.This is the one I paste. The plan-first paragraph matters more than it looks: making Claude name the roles and the file boundaries before it spawns anything is what stops two agents rewriting each other's work.
I want you to run this project as a team of agents instead of doing all of it yourself in one context window. Here is the whole job: [describe the entire project in three to five sentences, for example "build a five page marketing site for a Melbourne pilates studio, warm and minimal, with a class timetable and a booking page, and write all the real copy, no lorem ipsum"].
Before you spawn anything, write me a one page plan first. Name each agent, the single job it owns, the exact files or sections it is allowed to write to, and what it has to hand back when it is done. I want four of them: a researcher (competitors, positioning, proof points, anything factual the copy will rest on), a copywriter (every word a human reads, in the brand voice at the bottom of this message), a builder (file structure, components, responsive layout, and it uses the copy exactly as written rather than rewriting it), and a QA reviewer (dead links, mobile layout, accessibility, and any claim the copy makes that the research does not actually support). No two agents may write to the same file. Show me the plan and wait for my yes.
Once I approve, spawn them and give each one everything it needs inside its own spawn prompt, because they do not see this conversation and they do not inherit your history. Run the researcher first, hand its notes to the copywriter and the builder, and run the QA reviewer last on the assembled result. While they work, keep the shared task list updated so I can see what is claimed, in progress and done.
When they finish, you are the lead: merge the pieces into one working build, resolve any contradictions between them yourself rather than bouncing the question back to me, and then give me three things: the finished build, a short summary of what each agent actually did, and a list of every decision you made on my behalf that I should sanity check.
Brand voice, audience and constraints: [paste yours here, or write "ask me five questions first" if you want Claude to interview you before it starts].Describing the same four roles every time gets old fast. A subagent definition is a small markdown file that holds a role permanently, and Claude picks it up on its own when a matching task shows up. Put them in .claude/agents/ inside the project (shared with anyone who has the folder) or in ~/.claude/agents/ so they follow you into every project you ever open.
You do not write these by hand. Ask Claude to write them:
Turn the four roles we just used into permanent subagent definitions so I never have to describe this team again. Create one markdown file per role in ~/.claude/agents/ named researcher.md, copywriter.md, builder.md and qa-reviewer.md.
Each file needs YAML frontmatter with a lowercase hyphenated name, a description written so you will reach for it automatically (say what the agent does AND when it should be used, because that description is the trigger), the tools it actually needs, and a model. Give the researcher and the QA reviewer read-only tools so they cannot quietly edit my files.
Under the frontmatter, write the system prompt for that role in the second person, covering what it owns, what it must never touch, the format it hands work back in, and its quality bar. Base all four on how we just worked, then show me the finished files and tell me how to check they loaded.Here is the shape of what comes back, so you know what you are looking at when it lands:
---
name: copywriter
description: Writes all user-facing copy in the brand voice. Use when a build needs headlines, body copy, buttons or error text written or rewritten.
tools: Read, Grep, Glob, Write
model: sonnet
---
You own every word a human will read on this build.
Rules:
1. Work from the researcher's notes. Never invent a statistic, a testimonial or a client name.
2. Match the brand voice file exactly. Sentence case, no em dashes, no filler.
3. Write into copy/ only. Never touch the component or layout files.
4. Hand back a single file with every string, labelled by where it goes.Use the qa-reviewer subagent to check the booking page. Full field reference is in the subagents docs.Normal subagents report back to you and never talk to each other. There is an experimental mode called agent teams where they do: teammates share a task list, message each other directly, and challenge each other's findings. It is genuinely useful when the answer is contested, like a bug with three plausible causes. As the docs put it, with several investigators actively trying to disprove each other, "the theory that survives is much more likely to be the actual root cause" (agent teams).
It is off by default. Turn it on in your settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}"0" to go back. Both are documented in the agent teams page.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS setting, but three to five is where the good results live.The reel opened with Kimi K2.6, the open weight model from Moonshot AI that can coordinate up to 300 sub-agents across roughly 4,000 steps in one run (reported here). It is a real and impressive number. It is also not the thing standing between you and a finished project. Almost nobody has a task that genuinely splits 300 ways, and coordination overhead grows faster than the work does, which is why the advice on both sides is the same: a handful of well briefed agents beats a crowd. You do not need to switch tools for this workflow, you need to stop giving one chat five jobs.