Agent Teams Best Practices

Problem: Your Claude Code agent team spins up and immediately starts burning tokens without producing usable output. Teammates overwrite each other's files. The lead rolls up its sleeves instead of coordinating. Tasks sit in "in progress" forever. These are fixable, and the patterns below were forged from community reports and months of real iteration since the feature shipped.

Quick Win: Flip on delegate mode (Shift+Tab) and hand every teammate explicit file boundaries in the spawn prompt. Those two tweaks alone kill the most common team failures.

Note: This is a sibling guide to the Agent Teams overview. Head there first if you have not set up a team yet. For the knobs and dials, see Advanced Controls.

Give Teammates Enough Context

Load task-specific detail into the spawn prompt. Project context (CLAUDE.md, MCP servers, skills) arrives automatically, but the lead's conversation history does not travel with the teammate. Point at specific files, acceptance criteria, and constraints. A tight spawn prompt cuts the back-and-forth dramatically.

A floppy prompt like "review the auth module" makes the teammate hunt through the codebase, figure out what matters, and guess at priorities. That exploration burns tokens and clock time. A specific prompt removes the ambiguity:

The shape is simple: what to do, where to do it, what to focus on, and what the deliverable should look like. Teammates that know their scope upfront finish faster and ship better work. If you are coming from subagent patterns, the rule is identical, but the stakes are higher. Each teammate is now a full context window.

Size Tasks for Teammates

Too small and the coordination tax eats the gain. Too large and teammates grind away with no check-ins, risking lost effort. The sweet spot is a self-contained unit with a clean deliverable: a function, a test file, a review doc.

Aim for 5-6 tasks per teammate. That keeps everyone moving and lets the lead reassign work when someone stalls. If the lead is not slicing work finely enough, tell it to break the pieces smaller. A teammate carrying one giant task has no natural checkpoint. A teammate with 5-6 focused tasks reports in after each one, giving you room to steer.

Avoid File Conflicts

Two teammates editing the same file means silent overwrites. This is the single biggest rule for implementation work. Split tasks so each teammate owns a distinct set of files. Spell out directory boundaries in the spawn prompt.

If the repo does not split naturally into independent directories, create the split in your decomposition. Rather than "refactor the API layer" across three teammates, assign "refactor the user endpoints in src/api/users/" to one and "refactor the billing endpoints in src/api/billing/" to another. Explicit ownership prevents the silent overwrites that torch entire teammate sessions.

For projects where shared files cannot be avoided, mark them as "coordinate before editing" in your CLAUDE.md and let the lead sequence access through the task list.

Use Delegate Mode

Turn delegate mode on (Shift+Tab) the moment a team starts. Without it, the lead sometimes snatches tasks meant for teammates, muddying who owns what. Delegate mode restricts the lead to coordination-only tools, so it stays on orchestration instead of implementation. For the full walkthrough and config options, see the delegate mode guide.

Start with Research Tasks

New to agent teams? Begin with tasks that have clean boundaries and no code writing: PR reviews, library research, bug investigation, or module audits against a specific checklist. These show the payoff of parallel exploration without the coordination headaches of parallel implementation.

Research tasks are also forgiving. When a teammate wanders down an unproductive path, you lose tokens, not code. Implementation mistakes are harder to undo, especially once multiple teammates have layered changes on top of each other.

Once team dynamics feel natural, graduate to implementation tasks. Same patterns apply, but the stakes climb and file ownership boundaries matter much more.

Monitor Actively

Use Ctrl+T to peek at progress and redirect approaches that are not landing. Leaving a team running unattended too long stacks up the wasted-effort risk, especially if one teammate locks onto a dead end.

Treat agent teams like a supervised workflow. You are the project manager. The lead coordinates, but you make the strategic calls: when to redirect, when to spawn a replacement, and when to shut down a stuck teammate. Think of it as managing a distributed crew of contractors. Regular check-ins catch problems before they compound.

Team Size Matters

In practice, 3-5 teammates is the real sweet spot. More teammates equals more coordination tax, more token spend, and more chances for crossed wires. The lead's context fills faster tracking 8 teammates than 3. Communication cost scales with team size, because every broadcast lands in every teammate's window.

If the task genuinely demands more than 5 parallel workers, break it into phases instead. Run a 3-teammate team for phase one, clean up, then run another 3-teammate team for phase two. Sequential phases with smaller teams produce cleaner results than one giant team wrestling with everything at once.

Plan Mode Behavior

Plan mode inside agent teams has two important behaviors that are not obvious from the docs.

Plan mode is re-evaluated every turn, not just once. When a teammate runs in plan mode, it stays there for its entire lifetime. Every action it takes is filtered through the read-only constraint. That makes plan mode great for design-only roles and initial task shaping, but bad for execution.

A teammate's mode is fixed at spawn time. Once launched, you cannot flip a teammate from plan to default. If you need a transition from planning to execution, spawn a fresh teammate in default mode and hand off the plan. Do not try to "switch" an existing teammate out of plan mode.

This shapes team design. Use plan-mode teammates for architecture and review roles where a read-only perspective is the whole point. Use default-mode teammates for any role that needs to write code or modify files. For a plan-then-implement flow, reach for the plan approval feature instead. That lets a default-mode teammate plan first and build after approval.

Clear Rules Produce Clear Reports

With solid rules in CLAUDE.md, teammates self-report exactly what they did without the lead stepping in. A teammate finishing a cleanup task against a well-written CLAUDE.md returns something like: "Removed 27 console.log across 3 files. Kept all 12 console.error and 2 console.warn in component-page.js. Verified zero console.log remaining in my assigned files."

No lead intervention needed. Clear rules in, clear reports out.

This pattern falls out naturally when your CLAUDE.md lists specific verification criteria. Instead of "clean up logging," the teammate already knows "verified" means running grep for leftover instances and confirming error-level logging survived. For more on shaping CLAUDE.md for teams, see CLAUDE.md mastery and the CLAUDE.md optimization section in Advanced Controls.

Troubleshooting

Common issues and their fixes, drawn from community reports and release notes:

If your issue is not on this list, check which Claude Code version you are running. Many early pain points were resolved across the v2.1.33 through v2.1.45 releases.

Current Limitations

Agent Teams is experimental. These constraints are worth knowing before you commit to a team-based workflow:

• No session resumption: In-process teammates are not restored when using /resume or /rewind. After resuming, the lead may try to message teammates that no longer exist. Tell it to spawn replacements.
• Task status can lag: Teammates sometimes forget to mark tasks as completed, blocking dependent work. Check manually if something looks stuck.
• Slow shutdown: Teammates finish their current request or tool call before shutting down. This can take time if a teammate is mid-implementation.
• One team per session: A lead manages one team at a time. Clean up the current team before starting another.
• No nested teams: Teammates cannot spawn their own teams. Only the lead manages the team hierarchy.
• Fixed lead: The session that creates the team stays the lead for its lifetime. You cannot promote a teammate or transfer leadership.
• Permissions set at spawn: All teammates start with the lead's permission settings. You can change individual modes after spawning, but not at spawn time.
• Split panes require tmux or iTerm2: Split-pane mode is not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.

Being straight about these rough edges matters. Agent Teams is a powerful feature with visible seams. Developers who learn the workarounds now are the ones ready when Anthropic sands them down.

Recent Fixes

Since the initial Agent Teams launch in v2.1.32, Anthropic has shipped several important fixes. If you tried agent teams early and got burned, check whether your issue was resolved:

v2.1.33:

• Added TeammateIdle and TaskCompleted hooks for quality gate enforcement
• Added Task(agent_type) spawn restrictions to control which subagent types can be spawned
• Added persistent memory field for agents with user, project, and local scopes
• Fixed tmux teammate sessions to correctly send and receive messages
• Fixed plan mode warnings in team contexts

v2.1.34:

• Fixed crash when agent teams setting changed between renders

v2.1.41:

• Fixed wrong model identifier for teammates on Bedrock/Vertex/Foundry
• Added speed attribute to OTel events for fast mode observability

v2.1.45:

• Fixed teammates failing on Bedrock/Vertex/Foundry by propagating API provider environment variables to tmux sessions
• Fixed skills invoked by subagents incorrectly appearing in main session after compaction

Hitting issues? Update Claude Code to the latest version. The team ships fixes on a fast cadence and agent teams is under active development.

Related Guides

This guide is the operational playbook. For the rest of the picture:

• Agent Teams overview for the feature fundamentals and architecture
• Advanced Controls for display modes, delegate mode, hooks, and token cost management
• Use Cases and Prompt Templates for copy-paste prompts across 10+ real-world scenarios
• End-to-End Workflow for the complete 7-step pipeline from brain dump to validated production code
• Sub-agent best practices for when a full team is overkill and focused subagents are the right fit