claude subagents: When to Use One Agent vs Many (A Practical Setup Guide)

If you build with Claude, you have probably wondered whether to split work across claude subagents or keep everything in one agent. Anthropic recently published guidance on exactly this question, and the short answer is: start with one main agent plus skills, and add subagents only when you have a clear reason. Here is what the sources say and how to apply it.

What Anthropic's guide says

In Building agents: When to fold subagents into your main agent loop, Anthropic's Applied AI team writes that across several enterprise deployments, "a single agent with skills frequently outperformed both the one-prompt-for-everything design and the subagent design on quality, and often at a lower cost and latency per task."

A few points from the same article:

• One customer that compared its multi-agent setup against a single agent loop saw roughly 2x faster runtime with the single loop.
• Skills and tool search use progressive disclosure: the agent sees short descriptions and loads the full content only when needed, which removes a main reason teams split work into subagents.
• Group tools by user intent, because past roughly 30-50 tool definitions, tool choice tends to degrade.
• A common mistake is giving every team its own subagent, so the architecture copies the org chart.

The guide is clear that subagents still have a place. Use them when:

1. A single agent hits measurable performance loss from context bloat.
2. Several tasks can run in parallel with fresh context windows you can throw away afterwards.
3. One agent struggles to pick the right tools, or the system prompt has conflicting instructions.

What the Claude Code docs add

The official Claude Code subagents docs say each subagent runs in its own context window with its own system prompt, tool access and permissions, and returns a summary to the main conversation. They also note that subagents send their own requests, which count toward the same usage limits.

The docs recommend staying in the main conversation when the task needs back-and-forth, when phases like planning, building and testing share a lot of context, for quick changes, and when latency matters. Subagents fit when the task produces verbose output you don't need in your main context, when you want to restrict tools, or when the work is self-contained and can return a summary.

A small example setup

Per the docs, subagents are Markdown files with YAML frontmatter. Put project ones in .claude/agents/ (or ~/.claude/agents/ for all your projects). Only name and description are required. Here is a read-only research helper, the kind of self-contained job the guidance supports:

---
name: log-researcher
description: "Reads long log files and test output, then reports only the errors and likely causes. Use when output is large."
tools: Read, Grep, Glob
model: haiku
---

You are a log analyst. Find errors, group them by cause,
and return a short summary with file paths and line numbers.
Do not edit any files.

Everything else, such as your normal coding, writing or customer workflow steps, can stay in the main agent, with repeatable procedures moved into skills.

A simple decision checklist

• Steps depend on each other or share context? One main agent.
• Lots of noisy output (logs, test runs, document reading)? A subagent that returns a summary.
• Independent research paths? Parallel subagents.
• Need a strictly read-only helper? A subagent with limited tools.
• Same instructions reused everywhere? A skill, not a new subagent.

Anthropic's own advice is to measure: build a small eval (even 10 good examples), fold in one subagent at a time, and keep it as a subagent only if the folded version scores worse.

More research-based AI news and guides at ainews.useaifix.com, and automation help at useaifix.com.