Use Agent Teams for Complex Multi-Part Tasks

Agent Teams go beyond parallel sessions. One agent acts as team lead while teammates work independently and communicate with each other.

How It Works

Define agents in .claude/agents/:

# .claude/agents/frontend-dev.md
---
name: frontend-dev
description: "Handles UI components and styling"
allowed-tools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"]
model: claude-sonnet-4-6
---

Focus on React components in src/components/.
Coordinate with backend-dev for API contracts.
Run `npm run test:ui` to verify changes.

Team Lead Pattern

Start a main session as the team lead:

I need to add a new user settings page. Coordinate this:
- Frontend agent: build the settings UI components
- Backend agent: add the /api/settings endpoints
- Test agent: write e2e tests for the full flow

Use agent teams. Each agent should share their API contract
decisions with the others.

The lead agent:

1. Breaks down the task
2. Delegates to specialized agents
3. Ensures agents coordinate on shared interfaces
4. Merges results and resolves conflicts

When to Use Agent Teams

• Tasks that span multiple modules (frontend + backend + tests)
• Large refactors touching many files
• Tasks where agents need to share decisions (API contracts, schemas)

When NOT to Use

• Simple single-file changes
• Tasks where agents don’t need to communicate. Use plain subagents or worktrees instead