Your SOUL.md is dialed in. Your AGENTS.md is tight. You've got hooks enforcing your rules and a MEMORY.md that's actually learned something. You did the work.

And your agent is still slow on the hard stuff. It burns through context halfway into a real task, starts forgetting what it read twenty minutes ago, and the quality drops off a cliff right when you need it most.

The problem isn't your configuration anymore. The problem is that you're asking one agent to be a researcher, an implementer, a reviewer, and a test-writer, all sharing the same context window. That's not an agent. That's a one-person startup doing every job badly because there's no one else to do them.

The last six issues were about configuring one agent well. This one is about knowing when one isn't enough, and how to factor the work the same way you factored the config.

Here's the mechanical reason a single agent hits a wall. A code reviewer doesn't need the full design exploration that produced the implementation. A test-writer doesn't need the product-strategy conversation that justified the feature. But in a single session, all of it piles into the same context window (design notes, implementation, review feedback, test output), and the model's attention spreads thinner with every token.

This is context rot, and it's why your agent gets dumber as a task gets longer. You can't prompt your way out of it. The fix is structural: give each kind of work its own clean context.

Claude Code gives you two primitives for that. They solve related problems and people constantly confuse them, so here's the clean distinction.

Subagents are isolated workers inside one session. Each gets its own context window, its own tool permissions, and its own model. The main agent hands off a bounded task, the subagent does it, and only the result comes back, not the 40,000 tokens of reasoning it took to get there. Subagents can't talk to each other. They report to the main agent and that's it. Defined as markdown files in .claude/agents/.

Agent Teams scale that up. Instead of workers reporting to one boss, you get multiple independent Claude Code sessions. One acts as the team lead, the rest are teammates that work in parallel, communicate directly with each other, and coordinate through a shared task list. It's experimental (enable it with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, needs Claude Code v2.1.32 or later).

The short version: subagents are a crew that reports to you. Agent Teams are a crew that talks amongst themselves.

Most tasks need neither. Be honest about that before you go further: multi-agent is the wrong tool for maybe 95% of what you do. Here's the decision framework that actually holds up:

Independent tasks → subagents. Review this diff, write tests for that module, audit the staged changes for security issues. No dependencies between them, no need to coordinate. Spin up workers, collect results.

Dependent, coordinated tasks → Agent Teams. A refactor where the API change has to land before the tests update before the consolidated PR. Cross-layer work where a frontend change and a backend change need to stay in sync. The teammates need to see each other's work.

Everything else → one agent. If the task fits in one context window and doesn't split cleanly, a single session is faster, cheaper, and easier to debug.

Subagents aren't only about context hygiene. They're about not paying Opus prices to run grep.

Every subagent can run a different model. The pattern that's emerged (and it's the most practical thing in this issue) is to tier by model:

One team with tiered models runs roughly 40% cheaper than all-Opus, with almost no quality loss on the worker tasks. Search and grep don't need a frontier model's reasoning. They need speed and a low bill. Lock the model into each subagent's frontmatter and commit it to the repo, so nobody on your team quietly defaults everything back to the most expensive option.

Do not go multi-agent to fix a bad agent. If your single agent produces mediocre output, five of them produce five times the mediocrity, and now it's spread across five context windows you have to debug, at five times the token cost. The orchestration overhead is real, the token burn is real, and the experimental tooling is genuinely buggy.

The shift here is from conductor to orchestrator. As a conductor, you guide one agent in real time. As an orchestrator, you stop writing prompts mid-task and start writing specs, decomposing work, and verifying output. That's a different skill, and it only pays off once the underlying agent already works. Make one work first. Then scale the work, not the mess.

Here's a copy-paste pack: three subagents that turn "review my code" into a real pipeline. Drop each file into .claude/agents/ in your project, restart your session (or create them through /agents to skip the restart), and Claude will route to them automatically, or call them by name.

Note the deliberate choices: the reviewer and auditor have no write access. They flag; they don't fix. Only the test-writer can touch files. That's scoped permissions doing governance for free. And note the model tiering: sonnet for the workers, opus for the security judgment that actually warrants it.

.claude/agents/code-reviewer.md:

.claude/agents/test-writer.md:

.claude/agents/security-auditor.md:

Two notes. First: if you omit the tools line, a subagent inherits every tool the main session has, including your MCP connectors, so whitelist deliberately when you want tight control. Second: up to 10 subagents can run in parallel, so this crew can review, test, and audit at the same time instead of single-file.

What it does: Coordinates multiple independent Claude Code sessions. One session is the lead. It decomposes the work, assigns tasks through a shared task list, and synthesizes results. Teammates run in their own context windows, work in parallel, and message each other directly. Unlike subagents, you can talk to an individual teammate without going through the lead.

Setup difficulty: Low to enable, high to use well. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your settings.json or environment, confirm you're on v2.1.32 or later, and you're in. Using it without wasting hours of compute is the hard part.

Verdict: Genuinely useful for a narrow set of jobs: research where teammates investigate different angles and challenge each other's findings, debugging with competing hypotheses tested in parallel, and cross-layer features where frontend, backend, and tests each get an owner. When the work is truly parallel and independent, it's faster than anything a single session can do.

Watch out for: It uses dramatically more tokens than one session. You will hit your usage limits fast. The coordination is still rough around the edges: session resumption, task handoff, and clean shutdown all have known issues. And because you have fewer chances to redirect a team mid-task than a single agent, a vague initial spec can send the whole crew off building the wrong thing for an hour. Spend your time on the prompt before you spend your tokens on the work.

Rating: Promising, not production. Use it for research and parallel investigation today. Hold off on betting a deadline on it.

The model race got quiet, so everyone pivoted to the harness race. Subagents, teams, orchestrators, agent views: the tooling is multiplying fast, and it's easy to read all of it as "throw more agents at the problem."

It isn't. Every multi-agent setup I've watched fail had the same root cause: someone scaled out an agent that didn't work yet. Orchestration doesn't add competence. It multiplies whatever competence is already there, and if that number is negative, you just bought yourself a more expensive, harder-to-debug failure.

The order matters. Configure one agent until it's genuinely good. Then, and only then, factor the work across several. The craft is in the sequence, not the headcount.

See you next week.

Michael