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 Agent 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

Read/search/Bash plus TaskList/TaskGet/TaskUpdate/SendMessage

Code review with structured findings

agent-teams:team-debugger

Read/search/Bash plus TaskList/TaskGet/TaskUpdate/SendMessage

Hypothesis-driven investigation

agent-teams:team-implementer

Read/Write/Edit/search/Bash plus TaskList/TaskGet/TaskUpdate/SendMessage

Building features within file ownership boundaries

agent-teams:team-lead

Read/search/Bash plus Agent Teams coordination 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

Troubleshooting

**A teammate was spawned as Explore but needs to write files.**

Explore and Plan are read-only agents. Change the subagent_type to general-purpose or an appropriate specialized agent type. Never assign implementation tasks to read-only agents.

The team is growing too large and coordination is slowing everything down.

Each additional teammate adds communication overhead. Consolidate roles: can one agent cover two dimensions? A 4-person team doing 6 independent tasks is usually better served by 3 agents covering 2 tasks each.

tmux mode is not showing panes.

Ensure tmux is installed and a session is already running before spawning teammates. The in-process mode works without tmux and is suitable for CI or scripted environments.

Two reviewers are flagging the same issues.

The review dimensions overlap. Redefine each reviewer's focus area: one on correctness/logic, one on security, one on performance/scalability. Overlapping coverage wastes tokens and produces duplicate findings.

**A team-lead is spawning teammates but they are not receiving tasks.**

Verify that the lead is using the Agent tool to spawn teammates and passing complete context in the prompt. Teammates start fresh with no prior conversation history — they need all relevant information in their initial prompt.

Related Skills

• parallel-feature-development — Decompose work streams and assign file ownership once the team is composed

• team-communication-protocols — Establish messaging norms and shutdown procedures for the assembled team