Use Claude Code agent teams for parallelizable work where teammates need to communicate with each other. See docs/agent-teams.md for the full reference.
- User explicitly requests it — always honor a direct request to create an agent team.
- Cross-layer implementation — changes spanning frontend, backend, and tests where each layer can be owned independently.
- Competing hypothesis debugging — multiple theories to investigate in parallel, especially when adversarial debate would surface the root cause faster.
- Parallel review — reviewing a PR or codebase from multiple lenses (security, performance, coverage) simultaneously.
- Independent module development — building 3+ modules with no shared files, where parallel execution saves significant time.
- Sequential or dependent work — tasks that must happen in order. Use a single session.
- Same-file edits — two teammates editing the same file causes overwrites. Use a single session or subagents.
- Simple focused tasks — when only the result matters and no inter-worker discussion is needed. Use subagents.
- Token-constrained work — each teammate is a separate Claude instance. Use subagents for lower cost.
- 3-5 teammates is the default. Scale up only when the work genuinely benefits.
- 5-6 tasks per teammate keeps everyone productive without excessive context switching.
- File ownership must be exclusive — break work so each teammate owns a different set of files. Never assign two teammates to the same file.
- Spawn prompts must include full context — teammates do NOT inherit the lead's conversation history. Include all task-specific details in the spawn prompt.
- Require plan approval for risky changes — use plan mode for teammates touching critical paths (auth, data, config).
- The lead delegates, not implements — if the lead starts doing work itself, tell it to wait for teammates.
- Only the lead cleans up — teammates must not run cleanup. Shut down all teammates before the lead cleans up the team.