Day 37

Agent Teams — Roles & Handoffs

Claude Code // Day 37

Multiple full Claude sessions.
Talking to each other.
Self-coordinating.

Specialized team patterns. Split scope, define handoffs, prevent collisions. Each teammate is a full instance with peer-to-peer messaging.

Experimental

Feature Status

Peer-to-Peer

Messaging Model

Shared Task List

Coordination Layer

01 // Critical Distinction

Subagents vs Agent Teams

These are not the same thing. Most people confuse them.

Subagents

Stable Feature

dashed red = no communication

Fan-out from one parent session
Return results only, no peer comms
Parent decides, children execute
Cheaper: lightweight spawned processes
One-way: parent sends task, child returns result
Good for parallelizable, independent tasks

Agent Teams

Experimental

dashed green = peer-to-peer messaging

Each teammate is a full Claude session
Talk to each other directly (peer-to-peer)
Self-coordinate through shared task list
Can challenge, review, build on each other's work
Higher cost: each teammate = full instance
Good for complex, interdependent work

02 // Setup

How to Enable Agent Teams

Agent teams require an experimental flag. The API may change without warning in future releases.

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

What "experimental" means

1. The feature works and is usable in production workflows
2. The API surface (env var name, spawning syntax) may change
3. You need to explicitly opt in — it will not activate by default
4. Cost implications are real: each teammate is a full Claude instance

03 // The Architecture

How Agent Teams Actually Work

You talk to the lead session. The lead assigns work to teammates. Teammates talk to each other. Everyone sees the shared task list.

You

Your Terminal

Primary interface

Lead Session

Coordinator

Orchestrates work

Teammate A

Backend

Full Claude session

Teammate B

Frontend

Full Claude session

Teammate C

Tests

Full Claude session

Shared Task List

1. Build API routes [ A ]

2. Create components [ B ]

3. Write test suite [ C ]

4. Integration tests [ -- ]

Lead assigns

Peer-to-peer

Active session

04 // Spawning a Team

Actual Prompts That Work

The key pattern: define each teammate's role, scope, and the lead's coordination responsibility.

Example 1: Research Team

// Prompt to Claude Code with teams enabled

Create a team to investigate our auth system:

Teammate A: Investigate how auth handles token refresh.
  Look at middleware, JWT lifecycle, edge cases.

Teammate B: Investigate OAuth utilities and third-party
  provider integration. Map all entry points.

Teammate C: Devil's advocate. Find why this will
  fail in production. Race conditions, token expiry
  during requests, session conflicts.

Lead: Synthesize all findings into a single
  implementation plan with priorities.

Why this works: Each teammate has a clear scope. Teammate C's adversarial role forces the others to defend their findings. The lead synthesizes — it does not do the work itself.

Example 2: Full-Stack Feature Build

Build the user notification feature as a team:

Teammate A (Backend): Create the notification
  API routes, database schema, and webhook handlers.
  Share your API contract with Teammate B when ready.

Teammate B (Frontend): Build notification
  components: bell icon, dropdown, mark-as-read.
  Wait for Teammate A's API contract before wiring.

Teammate C (QA): Write tests for both backend
  and frontend. Review A and B's implementations
  for edge cases. Challenge assumptions.

Lead: Coordinate delivery order. Ensure A
  shares contracts before B starts integration.
  Final review of all three outputs.

The peer communication matters here. Teammate A shares API contracts with B directly. Teammate C reviews both in real time. This is something subagents cannot do.

Example 3: Security Audit

Security audit the application. Four specialists:

Teammate A (Auth): Audit all authentication
  flows. Password handling, session management,
  token storage. Report vulnerabilities.

Teammate B (AuthZ): Audit authorization logic.
  Role checks, permission boundaries, privilege
  escalation vectors.

Teammate C (Data): Audit data handling. SQL
  injection, XSS, input validation, output encoding,
  file uploads, serialization.

Teammate D (Infra): Audit infrastructure config.
  CORS, CSP headers, rate limiting, error exposure,
  dependency vulnerabilities.

Lead: Compile all findings into a severity-ranked
  report. Cross-reference findings between teammates
  to find compound vulnerabilities.

Example 4: Board of Directors (Business Use)

Evaluate whether we should add a freemium tier.
Create a board of directors:

Teammate A (Technical): What would it take to
  build? Infrastructure costs, feature gating,
  usage metering. Give honest estimates.

Teammate B (Commercial): Revenue impact. Will
  freemium cannibalize paid? Conversion benchmarks
  from similar SaaS. Market data.

Teammate C (Risk): What could go wrong? Abuse
  vectors, support load, brand dilution, competitor
  response.

Teammate D (Customer): How will current customers
  react? Perception of value change. Churn risk.

Lead: Moderate the discussion. Force disagreements
  to surface. Produce a go/no-go recommendation
  with conditions.

This is not about code. Agent teams work for strategic decisions too. Each teammate brings a perspective that challenges the others. The lead forces synthesis.

05 // Navigation

Once your team is running, you need to know how to talk to each member.

Cycle Between Teammates

Press Shift + Down to cycle through teammates. Each press moves focus to the next active session.

Direct Message Any Teammate

You can message any teammate directly. Not just the lead. Useful when you want to give specific instructions or override a direction.

Split Mode (tmux)

Each teammate can run in its own tmux pane. See all sessions simultaneously. Best for monitoring parallel work.

Combined Mode

All teammates share the lead terminal. Output interleaved. Simpler setup, harder to follow with more than 2 teammates.

06 // Shared State

The Task List

The shared task list is the coordination layer. Visible to every teammate. How agents self-organize without constant human intervention.

Shared Task List

1. Design database schema[ A ] done

2. Build API endpoints[ A ] working

3. Create React components[ B ] working

4. Write unit tests[ C ] assigned

5. Integration tests[ -- ] unclaimed

6. Final review[ -- ] unclaimed

Lead Creates

The lead session defines and populates the task list based on the overall goal.

Teammates Self-Assign

Unclaimed tasks can be picked up by any teammate. Self-organizing when roles overlap.

Visible to All

Every teammate sees the full list. No information silos. Everyone knows who is doing what.

07 // Decision Framework

Teams vs Subagents: When to Use Which

Click through the questions to get a recommendation.

Do workers need to communicate with each other?

08 // Cost Reality

What Agent Teams Actually Cost

No sugarcoating. Each teammate is a full Claude instance. A 4-person team costs roughly 4x a single session.

The Math

1 teammate = 1 full Claude session (same context window, same token usage, same cost per token). A 4-person team running for 30 minutes each = cost of 4 individual 30-minute sessions running in parallel.

Use Case	Complexity	Peer Comms Needed?	Verdict
Parallel file edits (independent)	Low	No	Subagents
Code generation + tests (same feature)	Medium	Nice to have	Either
Full-stack feature (API + UI + tests)	High	Yes	Teams
Security audit (multiple domains)	High	Yes	Teams
Linting / formatting batch	Low	No	Subagents
Architecture review	High	Critical	Teams
Data migration scripts	Medium	Minimal	Subagents
Competing hypotheses (debug)	High	Essential	Teams

09 // Real Prompts

5 Ready-to-Use Team Configurations

Copy, adapt to your codebase, run. Each is a complete prompt.

1. Client Build Team (AY Automate Pattern)

We are building [CLIENT_NAME]'s automation system.
Stack: n8n + Supabase + Claude API.

Teammate A (n8n Architect): Design the n8n
  workflow. Nodes, triggers, error handling, webhook
  endpoints. Export as JSON when done.

Teammate B (Database): Design and create the
  Supabase schema. Tables, RLS policies, functions.
  Share schema with A for webhook payloads.

Teammate C (Integration): Write the glue code.
  API adapters for client's existing tools. Test
  each integration endpoint independently.

Teammate D (Documentation): Document everything
  as it is built. Handoff doc, SOP, architecture
  diagram. Ask other teammates for details.

Lead: Coordinate build order. B delivers schema
  first, then A builds workflows against it, C
  integrates in parallel. D documents throughout.

2. Competing Bug Hypotheses

We have a bug: [DESCRIBE BUG]. Users report [SYMPTOM].
It happens [WHEN]. We suspect [AREA] but are not sure.

Teammate A: Hypothesis 1 -- the bug is in the
  authentication middleware. Investigate token
  validation, session handling, middleware order.

Teammate B: Hypothesis 2 -- the bug is in the
  database query layer. Investigate connection
  pooling, query timeouts, race conditions.

Teammate C: Hypothesis 3 -- the bug is in the
  frontend state management. Investigate stale
  state, cache invalidation, optimistic updates.

Lead: Let all three investigate independently for
  the first pass. Then facilitate a debate. Each
  teammate must argue why their hypothesis is correct
  and challenge the others. Produce a ranked list
  of most-likely root causes with evidence.

This is where teams shine over subagents. The debate step. Teammates challenging each other's conclusions produces better results than any individual investigation.

3. Content Strategy Team

Plan next week's LinkedIn content for AY Automate.
Target: founders and operations leaders at 10-80
person companies.

Teammate A (Researcher): Analyze our last 30
  posts. What performed? What patterns emerge?
  Pull engagement metrics. List top 5 themes.

Teammate B (Writer): Draft 5 posts using the
  themes A identifies. Use Walid's voice: direct,
  results-focused, no fluff, specific metrics.

Teammate C (Critic): Review B's drafts. Grade
  each 1-10 on hook strength, value density, and
  CTA clarity. Suggest specific rewrites for
  anything below 7.

Lead: Coordinate flow. A delivers research first.
  B writes based on A's findings. C reviews. Final
  output: 5 polished posts with publish schedule.

4. Security Audit Team

Security audit the application. Four specialists:

Teammate A (Auth): Audit all authentication
  flows. Password handling, session management,
  token storage. Report vulnerabilities.

Teammate B (AuthZ): Audit authorization logic.
  Role checks, permission boundaries, privilege
  escalation vectors.

Teammate C (Data): Audit data handling. SQL
  injection, XSS, input validation, output encoding,
  file uploads, serialization.

Teammate D (Infra): Audit infrastructure config.
  CORS, CSP headers, rate limiting, error exposure,
  dependency vulnerabilities.

Lead: Compile all findings into a severity-ranked
  report. Cross-reference findings between teammates
  to find compound vulnerabilities.

5. Architecture Review Team

Review the architecture of [SYSTEM] before we
scale from [CURRENT] to [TARGET] users.

Teammate A (Performance): Identify bottlenecks.
  Database queries, N+1 problems, missing indexes,
  unoptimized loops, memory leaks.

Teammate B (Scalability): What breaks at 10x
  load? Connection limits, queue saturation, cache
  eviction, rate limit headroom.

Teammate C (Maintainability): Code quality. Dead
  code, circular dependencies, test coverage gaps,
  documentation debt, unclear abstractions.

Teammate D (Cost): Infrastructure cost projection
  at target scale. Database sizing, compute needs,
  API call volumes, third-party service costs.

Lead: Synthesize into a prioritized action plan.
  What must be fixed before scaling? What can wait?
  What is fine as-is? Produce a timeline estimate.

10 // Knowledge Check

Quiz: Agent Teams

Test what you learned.

Question 1 of 4

What environment variable enables agent teams?

ACLAUDE_AGENT_TEAMS_ENABLED

BCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

CENABLE_AGENT_TEAMS

DCLAUDE_TEAMS_MODE

The correct answer is CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS. It must be set to "1" in the env object of your settings.json. The "experimental" prefix signals this feature may change.

Question 2 of 4

How do teammates communicate with each other (not through the lead)?

AThey write to shared files on disk

BThey cannot — all communication goes through the lead

CPeer-to-peer messaging — direct messages between sessions

DThrough a shared database

The correct answer is peer-to-peer messaging. This is the defining feature of agent teams vs subagents. Teammates send direct messages to each other without routing through the lead.

Question 3 of 4

What is the main difference between agent teams and subagents?

ATeams use a different model than subagents

BTeams are cheaper because they share context

CTeams are full sessions that can communicate peer-to-peer and self-coordinate

DTeams can only run sequentially, subagents run in parallel

The correct answer is full sessions with peer-to-peer communication and self-coordination. Subagents are lightweight workers that return results to a parent. Teams are full Claude sessions that can talk to each other and self-organize.

Question 4 of 4

How do you cycle between teammates in the terminal?

ATab key

BCtrl+T

CShift+Down

D/switch command

The correct answer is Shift+Down. Each press cycles focus to the next active teammate session. You can also message any teammate directly without cycling.

0/4

Correct Answers

Day 36: Agent Swarms — Coordinate Multiple Agents

Day 38: Context Engineering Mastery

Agent Teams — Roles & Handoffs

Subagents vs Agent Teams

Subagents

Agent Teams

How to Enable Agent Teams

How Agent Teams Actually Work

Actual Prompts That Work

Moving Between Teammates

The Task List

Teams vs Subagents: When to Use Which

What Agent Teams Actually Cost

5 Ready-to-Use Team Configurations

Quiz: Agent Teams