For Claude Code agent teams, the reliable pattern is simple: enable the experimental mode, give each teammate a distinct set of files, and verify the actual changed paths before dependent work starts. Treat task ownership as scheduling, not filesystem isolation, and keep one writer per file at a time. The agent-team documentation does not describe a way to give each teammate its own worktree, so file ownership—not an invented isolation setting—is the boundary for named teammates.
Set up Claude Code agent teams by file ownership
Agent teams are experimental and disabled by default. The orchestration documentation says to enable them by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json or the environment:
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
That is the documented configuration value, not a complete CLI invocation. The page does not specify a separate command for launching a team, so check the current documentation before building a launcher around assumptions.
Once enabled, one session acts as the team lead. It coordinates the work, assigns tasks, and synthesizes the results, while each teammate works independently in its own context window and can communicate directly with the other teammates. A named Agent tool call launches a teammate when agent teams are enabled, unless the call is a fork or passes isolation on that call itself. Those exceptions matter: adding a name does not guarantee that a named teammate will be created in every call shape. The team orchestration page explains the behavior but does not provide a complete shell template for every launch case.
Keep the first plan small. The documentation recommends starting with 3-5 teammates for most workflows and suggests 5-6 tasks per teammate. Treat those as planning recommendations rather than expected throughput or enforced defaults.
Before any teammate starts, write an ownership map that names the exact files or directories assigned to each teammate. Do not assign broad labels such as “backend” if two people would then edit the same configuration, schema, test helper, or shared entry point. Split those paths again or keep the shared file with the lead.
This is the central conflict rule: two teammates editing the same file can overwrite each other, so the documented solution is to break the work so each teammate owns a different set of files. See the agent-team conflict guidance. A task can be assigned cleanly and still overlap another task at repository level unless its file boundary is explicit.
Use the shared task list to control scheduling. It has three states—pending, in progress, and completed—and a pending task with unresolved dependencies cannot be claimed until those dependencies are complete. Task claiming uses file locking so two teammates cannot claim the same task simultaneously, according to the same orchestration documentation.
Do not confuse that task-claim lock with repository-file isolation. It prevents two teammates from claiming one task at the same time; it does not make two edits to the same path safe. Your ownership map still has to keep those paths disjoint.
Each teammate receives the lead’s spawn prompt, but the lead’s conversation history does not carry over. Make the prompt self-contained: name the owned paths, list paths the teammate must not edit, identify task dependencies, define the completion evidence, and state what the teammate should return to the lead. The agent-team documentation confirms the prompt/history boundary.
In our setup, many coding-agent sessions share one working directory, so an uncommitted change there belongs to every session rather than only the session that made it. We therefore treat the ownership map as a hard routing rule and allow one writer per file at a time. For a shared file, our operating rule is to re-read it, compute the complete new content, write that content to a temporary file, and rename it over the original. We also keep one short startup instructions file as the entry point: it says what to do and how to know it is done, then routes to detailed documents instead of repeating every rule.
Filesystem isolation belongs to a different execution boundary. The Claude Code worktree documentation says that running each Claude Code session in its own worktree prevents edits in one session from touching files in another. It also says subagents can run in their own worktrees, either by asking Claude to “use worktrees for your agents” or by making isolation permanent for a custom subagent.
For a custom subagent, the following key-value line goes in the file frontmatter:
isolation: worktree
Use that option when the execution unit is actually a custom subagent. It does not turn the lead’s named teammates into separate worktree-backed sessions.
Check the work actually stayed separated
Check team formation, task state, repository paths, and the final result separately. Spawning several teammates only proves that coordination started; it does not prove that their edits remained disjoint.
First, confirm that every active task has one owner and that no unresolved dependency remains. The lead should be able to explain which teammate owns each path without relying on assumptions about module boundaries.
Next, compare the ownership map with the repository’s actual changed paths after each meaningful batch of work. Every changed path should belong to exactly one active writer. If two teammates touched the same path, pause and inspect the content even if the final diff appears plausible. A clean final diff can conceal one teammate overwriting another teammate’s earlier edit.
Use completion gates when they fit your workflow. The documented TaskCompleted hook runs when a task is being marked complete; exiting with code 2 prevents completion and sends feedback. That behavior is defined in the agent-team documentation. It gives the lead a way to reject a premature completion rather than immediately releasing dependent work.
In our own operating practice, a new verification gate is exercised once with a case that must fail. Otherwise, a copied check can report success without testing anything relevant. We also treat an agent summary, exit code 0, green build, and HTTP 200 as signals rather than final proof. In one of our own incidents, build and HTTP checks stayed green while a CSS class collision made headings collapse and overlap. Reading the rendered result exposed what those checks had missed.
The documented mechanisms do not provide one consolidated audit command covering configuration, task state, changed-path ownership, and user-visible output. Check the current product documentation if you need to automate any of those layers, and keep your repository check separate from the final result check.
Where it breaks
Agent teams stop being a good fit when the task topology does not match the repository’s edit topology. The agent-team documentation says a single session or subagents are more effective for sequential tasks, same-file edits, or work with many dependencies. In those cases, adding teammates adds coordination paths without creating safe parallel writers.
Task status can also lag. Teammates sometimes fail to mark tasks as completed, which blocks every dependent task. That makes the TaskCompleted gate useful, but it does not remove the need to inspect the task list and changed paths yourself.
Teammates cannot spawn their own teammates; only the lead manages the team. Nested expansion is therefore unavailable, and the lead’s assignment and synthesis work becomes part of the capacity limit rather than something every teammate can route around.
Coordination and token use are the other limits. Agent teams add coordination overhead and use significantly more tokens than a single session. The separate cost documentation says token usage is roughly proportional to team size because each teammate runs its own context window. A larger team can shorten some independent work while making review, handoffs, and synthesis more expensive.
Shared working directories add a separate failure mode that Claude Code cannot infer from task ownership. In one of our shared-tree incidents, a plain commit swept in files staged by other sessions. A path argument was not enough because the working copy of the same file also contained someone else’s edits. Our rule is to commit only our own lines. In a shared tree, we build the commit in a temporary index from HEAD using read-tree, update-index, write-tree, commit-tree, and update-ref, then reset the real index for those paths.
The practical boundary is therefore straightforward: use named teammates for independent work on distinct file sets, keep one writer per file, make dependencies explicit, and verify actual changes before downstream tasks begin. Do not substitute task locks, prompts, or a general worktree workflow for file ownership.