01 · The setup

Agent Teams is experimental, behind a feature flag. Requires Claude Code v2.1.32 or later. Check your version with claude --version. If you're behind, run claude update.

Option A — environment variable

Quick and dirty for this shell session only:

$ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
$ claude
# ✓ Agent Teams enabled

To persist across sessions, drop it in your shell rc file:

$ echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.zshrc
$ source ~/.zshrc

Option B — settings.json

Cleaner if you already use a settings file. Edit ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

02 · The model-strategy

The single biggest mistake people make: using one model for the whole team. Cost balloons, capability is wasted, and you end up with five expensive specialists doing junior-level work.

The pattern that actually works:

• Opus for the lead. The lead does the hard cognitive work — breaking down the problem, assigning ownership, resolving conflicts, synthesizing results. This is where reasoning matters most. Pay for it once.
• Sonnet for the teammates. Teammates execute on a clearly-scoped task. Sonnet is more than enough to write a REST endpoint, build a login flow, or render a component. You'd be wasting Opus on this.
• Haiku for the docs/test agent. If you have a slot for documentation or simple test scaffolding, Haiku handles it for pennies. Don't pay Sonnet rates to write a README.

How to specify this in your prompt:

> Spawn a team of 5. Use Opus for the lead.
> Use Sonnet for the api / auth / ui agents.
> Use Haiku for the docs agent.

Typical cost reduction vs. all-Opus: 3–4× cheaper. Output quality stays the same — sometimes better, because Opus isn't bottlenecking on grunt work.

03 · Five prompt templates

Copy, paste, adapt. Each one is structured the same way: scope · roles · model strategy · ownership rules. Skip any of those and you get the chaos prompt from slide 7.

> Build a SaaS feature for [feature name]:
> · API endpoints with auth + validation
> · React UI with form handling
> · Vitest unit + integration tests
> · OpenAPI docs
>
> Spawn a team of 5:
> · api-agent: owns /api/* files
> · auth-agent: owns /lib/auth/* and middleware
> · ui-agent: owns /components/* and /app/*
> · test-agent: owns /__tests__/* — run after others
> · docs-agent: owns /docs/openapi.yml
>
> Opus = lead. Sonnet = api/auth/ui. Haiku = docs.
> No agent touches files outside its ownership.

> Investigate [problem statement] across our codebase.
>
> Spawn a team of 4 researchers, each on a different angle:
> · agent-1: trace the request path (frontend → API)
> · agent-2: trace data flow (DB queries, mutations)
> · agent-3: trace auth/permission checks
> · agent-4: check logs + error patterns
>
> All read-only. No file edits.
> Lead synthesizes findings into a single root-cause hypothesis
> with proposed fix + risk assessment.

> Refactor [pattern] across the following services:
> · service-a (own context)
> · service-b (own context)
> · service-c (own context)
>
> Spawn 3 specialists, one per service. No cross-talk.
> Each agent: refactor → run tests → commit on branch.
>
> Lead reviews each branch, merges in order, resolves conflicts.

> Source: [paste blog post / brief / transcript]
>
> Spawn 5 content agents:
> · newsletter-agent: 800-word newsletter draft
> · x-agent: 8-tweet thread, no emojis
> · linkedin-agent: 1,200-word thought piece
> · ig-agent: 9-slide carousel script
> · yt-agent: 60-sec short script + thumbnail copy
>
> All match the brand voice in the source.
> No copy-paste between agents — each adapts to its platform.

> Bug: [paste reproduction steps + error]
>
> Spawn 3 debugger agents. Each tests a different hypothesis:
> · agent-1: race condition in [suspected module]
> · agent-2: state mutation in [suspected store]
> · agent-3: env / config drift between environments
>
> Each writes a minimal failing test that proves or disproves
> their hypothesis. Read-only on source files.
>
> Lead reviews evidence, picks winner, proposes the fix.

04 · The four gotchas

The mistakes you'll make if nobody warns you. I made all four.

05 · When the team is wrong

This is the slide everyone else skips, so it gets a section here too. Don't use a swarm when:

• The work is sequential — step 2 depends on step 1's output. Parallel kills you.
• Everything lives in one file — five agents editing the same file is merge hell guaranteed.
• The job is small — spawn overhead is real. A 10-line fix doesn't need a team meeting.
• Tokens are tight — five agents burn five times the budget. Solo runs cheaper when they work.

Knowing when not to use it is the actual skill. Anyone can spawn five agents. Knowing when one is enough is what makes you faster than the people who swarm everything.