architecture
Agent Teams: Roles & Coordination
Designing teams of specialized Claude Code agents. How to split scope, define handoffs, and keep agents from stepping on each other.
Agent Teams: Roles & Coordination
Agent teams are Claude Code’s experimental feature that lets you run multiple full Claude sessions simultaneously (each with its own context, tools, and agency), all talking to each other in real time. This is not the same as subagents. This is a coordinated team of peers that can challenge, review, and build on each other’s work.
Enable it with a single env flag, define roles upfront, and let the team self-organize through a shared task list. The result: complex, interdependent work that would take a single session hours can finish in a single coordinated pass.
Subagents vs Agent Teams
Most people confuse these. Here is the difference that matters.
Subagents
Stable Feature- 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- 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
Five Core Roles
Effective teams assign each member a role that is mutually exclusive in scope. Overlap creates collision; gaps create dropped work.
Orchestrates the team. Receives your instructions, breaks the goal into tasks, assigns work to teammates, monitors the shared task list, and synthesises all outputs into the final deliverable. The lead does not do deep implementation work; it coordinates.
Owns: Task list · Assignment decisions · Final synthesis · Handoff sequencing
Implements the primary artefact: API routes, database schema, core logic, workflow nodes. Has the deepest context on the domain it owns. Shares contracts and interfaces with other builders so they can integrate without waiting.
Owns: Implementation · API contracts · Data models · Core logic
Reads the builder’s output in real time and challenges assumptions. Not a passive reader: it actively pokes holes, identifies edge cases, and requests revisions before work is considered done. This is the role that most justifies using teams over subagents.
Owns: Code review · Assumption challenges · Edge case identification · Revision requests
Writes and runs tests, acts as devil’s advocate, and hunts for failure modes that the builder is too close to see. May be assigned a specific hypothesis (e.g., “prove this will fail under load”) to create productive tension.
Owns: Test suite · Failure mode analysis · Competing hypotheses · Production readiness
Takes the finished outputs from builders, wires them together, runs integration checks, and prepares the final artefact for delivery. Often doubles as the documentation author, capturing what was built for handoff.
Owns: Integration · End-to-end tests · Documentation · Handoff package
Preventing Dropped Work
Most team failures happen at handoff boundaries: Teammate B starts integrating before Teammate A has finished the API contract, or QA writes tests against an interface that is about to change. These rules prevent that.
Contract-First
Any teammate that produces an interface (API route, schema, exported function) must share the contract with dependent teammates before those teammates begin implementation. Explicit, not assumed.
Announce Blockers Early
If a teammate is blocked waiting for another’s output, it should say so immediately on the shared task list rather than idling or guessing. The lead re-sequences accordingly.
Mark Tasks Atomic
Each task on the shared list should be completable independently. If two tasks are truly interdependent, merge them into one task assigned to the teammate who owns the dependency.
Reviewer Gate
No task moves from ‘working’ to ‘done’ without passing through the reviewer role. Even if the reviewer is the same teammate, the explicit step surfaces issues before they cascade.
Enabling Agent Teams
// settings.json (project or user-level)
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}- 1. Feature works and is usable in production workflows
- 2. API surface (env var name, spawning syntax) may change
- 3. Must explicitly opt in; will not activate by default
- 4. Cost is real: each teammate = full Claude instance
How to Split Work Without Collisions
The two most common failure modes in agent teams are scope overlap (two teammates edit the same file) and scope gap (nobody owns a critical piece). Apply these rules before you start.
Split by layer, not by feature
Assign one teammate to the database layer, one to the API layer, one to the UI layer. Do not assign one teammate to ‘the notifications feature’ end-to-end; that creates overlap with every other teammate who touches notifications.
Name the files each teammate owns
In your prompt, explicitly state which directories or files belong to each teammate. Overlapping file ownership = guaranteed merge conflict. When in doubt, give ownership to the teammate with the deepest context on that layer.
One teammate per external interface
If the work involves a third-party API (Stripe, Supabase, Resend), assign exactly one teammate to own that interface. Others call it through the contract that teammate exposes; they do not reach the external API directly.
The lead owns nothing except the task list
If the lead starts implementing features alongside coordinating, it will lose track of the team state. The lead’s job is orchestration. Enforce this in your prompt explicitly: ‘Lead: coordinate only, do not write implementation code.’
Unclaimed tasks go to the lead
If a task appears on the shared list and no teammate claims it within a reasonable window, the lead must either assign it explicitly or escalate to you. Unclaimed tasks are the most common source of gaps.
Full-Stack Feature Build
The notification feature. Four roles, explicit contracts, a reviewer gate, and a lead that coordinates delivery order without writing a line of implementation code.
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. Files: app/api/notifications/**, prisma/schema.prisma Teammate B (Frontend): Build notification components: bell icon, dropdown, mark-as-read. Wait for Teammate A's API contract before wiring. Files: components/notifications/**, hooks/use-notifications.ts Teammate C (QA): Write tests for both backend and frontend. Review A and B's implementations for edge cases. Challenge assumptions. Do not start until A shares contracts. Files: __tests__/notifications/** Lead: Coordinate delivery order. Ensure A shares contracts before B starts integration. Final review of all three outputs. Do not write implementation code.
Shared Task List
Teams vs Subagents: When to Use Which
| 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 |
What Will Go Wrong (And How to Prevent It)
Agent teams are powerful but expensive. The failure modes are predictable. Know them before you run your first team.
Lead starts implementing
Explicitly state in your prompt: 'Lead: coordinate only, do not write implementation code.' If the lead starts coding, it loses track of teammate progress and the coordination layer collapses.
No explicit file ownership
Name the directories each teammate owns in the prompt. Without this, two teammates will edit the same file simultaneously. The last write wins and the other’s work is lost.
Starting integration before contracts are shared
Add explicit blocking language: 'Teammate B: wait for Teammate A’s API contract before wiring.' Without this, B will assume an interface that A hasn’t finalised and build against the wrong shape.
Running a team for simple parallel work
If the tasks are independent and don’t need peer communication, use subagents. Four full Claude sessions for work that doesn’t require collaboration is 4x the cost with 0x the benefit.
Vague role definitions
Each teammate needs a scope boundary, not just a name. 'Teammate A: backend' is not enough. 'Teammate A: owns app/api/** and prisma/schema.prisma, no other files' is a scope boundary.
Not monitoring the shared task list
Check the task list periodically. Unclaimed tasks are early warning signs of coordination failure. If tasks are sitting unclaimed for more than a few cycles, the team is stuck.
Want this running in your stack?
AY Automate builds agent systems, RAG pipelines, and Claude Code setups for production teams.