Team Composition Patterns

Best practices for composing multi-agent teams, selecting team sizes, choosing agent types, and configuring display modes for Claude Code's Agent Teams feature.

When to Use This Skill

Deciding how many teammates to spawn for a task

Choosing between preset team configurations

Selecting the right agent type (subagent_type) for each role

Configuring teammate display modes (tmux, iTerm2, in-process)

Building custom team compositions for non-standard workflows

Team Sizing Heuristics

Complexity

Team Size

When to Use

Simple

1-2

Single-dimension review, isolated bug, small feature

Moderate

2-3

Multi-file changes, 2-3 concerns, medium features

Complex

3-4

Cross-cutting concerns, large features, deep debugging

Very Complex

4-5

Full-stack features, comprehensive reviews, systemic issues

Rule of thumb

Start with the smallest team that covers all required dimensions. Adding teammates increases coordination overhead.

Preset Team Compositions

Review Team

Size

3 reviewers

Agents

3x

team-reviewer

Default dimensions

security, performance, architecture

Use when

Code changes need multi-dimensional quality assessment

Debug Team

Size

3 investigators

Agents

3x

team-debugger

Default hypotheses

3 competing hypotheses

Use when

Bug has multiple plausible root causes

Feature Team

Size

3 (1 lead + 2 implementers)

Agents

1x

team-lead

+ 2x

team-implementer

Use when

Feature can be decomposed into parallel work streams

Fullstack Team

Size

4 (1 lead + 3 implementers)

Agents

1x

team-lead

+ 1x frontend

team-implementer

+ 1x backend

team-implementer

+ 1x test

team-implementer

Use when

Feature spans frontend, backend, and test layers

Research Team

Size

3 researchers

Agents

3x

general-purpose

Default areas

Each assigned a different research question, module, or topic

Capabilities

Codebase search (Grep, Glob, Read), web search (WebSearch, WebFetch)

Use when

Need to understand a codebase, research libraries, compare approaches, or gather information from code and web sources in parallel

Security Team

Size

4 reviewers

Agents

4x

team-reviewer

Default dimensions

OWASP/vulnerabilities, auth/access control, dependencies/supply chain, secrets/configuration

Use when

Comprehensive security audit covering multiple attack surfaces

Migration Team

Size

4 (1 lead + 2 implementers + 1 reviewer)

Agents

1x

team-lead

+ 2x

team-implementer

+ 1x

team-reviewer

Use when

Large codebase migration (framework upgrade, language port, API version bump) requiring parallel work with correctness verification

Agent Type Selection

When spawning teammates with the Task tool, choose

subagent_type

based on what tools the teammate needs:

Agent Type

Tools Available

Use For

general-purpose

All tools (Read, Write, Edit, Bash, etc.)

Implementation, debugging, any task requiring file changes

Explore

Read-only tools (Read, Grep, Glob)

Research, code exploration, analysis

Plan

Read-only tools

Architecture planning, task decomposition

agent-teams:team-reviewer

All tools

Code review with structured findings

agent-teams:team-debugger

All tools

Hypothesis-driven investigation

agent-teams:team-implementer

All tools

Building features within file ownership boundaries

agent-teams:team-lead

All tools

Team orchestration and coordination

Key distinction

Read-only agents (Explore, Plan) cannot modify files. Never assign implementation tasks to read-only agents. Display Mode Configuration Configure in ~/.claude/settings.json : { "teammateMode" : "tmux" } Mode Behavior Best For "tmux" Each teammate in a tmux pane Development workflows, monitoring multiple agents "iterm2" Each teammate in an iTerm2 tab macOS users who prefer iTerm2 "in-process" All teammates in same process Simple tasks, CI/CD environments Custom Team Guidelines When building custom teams: Every team needs a coordinator — Either designate a team-lead or have the user coordinate directly Match roles to agent types — Use specialized agents (reviewer, debugger, implementer) when available Avoid duplicate roles — Two agents doing the same thing wastes resources Define boundaries upfront — Each teammate needs clear ownership of files or responsibilities Keep it small — 2-4 teammates is the sweet spot; 5+ requires significant coordination overhead