When to Run a Team of AI Agents (and When Not To)
More agents is not more output. Here's the test for when to split work, how to set up your first subagent today, and when to graduate to a full agent team.
- #agents
- #orchestration
- #claude-code
Headcount is not the goal; throughput is. I tell that to new managers and it's just as true for AI: adding agents only helps when the work is genuinely parallel. Here's how I decide, and exactly how to set it up.
Step 1 — Run the org-chart test
Before you spawn anything, write your task as steps and mark which ones depend on another step's output.
- If most steps connect (the API shape decides the frontend, the schema decides the API) → run one session. Splitting dependent work just adds a coordination tax.
- If three or more steps are truly independent (research five libraries; review one PR for security, performance, and tests) → parallelize.
That's the whole call. "Find everything about X" splits cleanly; "build this feature in order" does not.
Step 2 — Start with one subagent (do this today)
A subagent runs in its own context window and reports a summary back to you — cheaper than a team, and the right first step. Create one file, .claude/agents/code-reviewer.md (or run /agents → Library → Create new agent):
---
name: code-reviewer
description: Reviews a diff for bugs, security, and missing tests. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
---
You are a senior reviewer. Read the diff and report issues by severity
(CRITICAL / SHOULD-FIX / NIT), each with file:line and a concrete fix.
Check correctness, security, and whether tests cover the change. No praise padding.
Claude delegates to it automatically when a task matches the description. Commit it to .claude/agents/ and your whole repo gets the same reviewer.
Step 3 — Graduate to an agent team only when workers must talk
Subagents report back; an agent team is separate sessions that share a task list and message each other — use it only when workers need to debate, not just report. It's experimental, so enable it in settings.json:
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
Then just ask in plain language: "Spawn three teammates to review PR #142 — one on security, one on performance, one on tests." Start with 3–5 teammates, and start with research/review, not parallel code edits.
Try this today
Create the code-reviewer subagent above and run it on your next change. Don't touch agent teams until you hit work that genuinely needs the agents to argue with each other.
Sources
Keep reading
More guides like this one.
Build Your First AI Agent (Without the Hype)
An agent is not a magic autonomous worker. It is a loop with tools and a goal. Build a real one this week by starting with the smallest version that does something useful.
The AI Skill Worth Learning Now: Context Engineering
Prompt engineering was never really a job, and the models got good enough to do it for you. The skill that's actually sticking is context engineering. Here's what it is and how to start.
Context Engineering: The Skill That Outgrew Prompting
Clever prompts were the 2024 skill. The 2026 skill is managing what the model can see — its instructions, tools, history, and data — as a finite budget. Here is the shift, in plain terms.