Scale Claude Code with Subagents, Agent Teams, and Git Worktrees

Quick answer

Use a subagent when isolated context or specialized tools improve one bounded task. Use an agent team only when multiple independent tasks benefit from peer coordination. Use Git worktrees to give simultaneous editing sessions separate directories and branches. Parallelism helps only when ownership and integration are explicit.

Anthropic documents custom subagents separately from agent teams: a subagent returns results to the caller, while teammates run independent sessions and can communicate.

Delegate a bounded subtask

Good delegation includes output shape and limits:

Delegate a read-only security review of the password-reset flow. The subagent
may read auth code and tests but must not edit. Return only concrete findings
with file/line evidence, exploit scenario, severity, and the smallest mitigation.

Poor delegation—“review security”—creates open-ended reading and noisy conclusions.

Create specialized subagents

A custom subagent can specify a focused role, tools, model, and instructions. Useful roles include:

• Read-only codebase archaeologist.
• Test-failure investigator.
• Database migration reviewer.
• Accessibility auditor.
• Documentation verifier.

Restrict tools to the job. A reviewer rarely needs deployment credentials or file mutation.

Decide whether parallelism is real

Parallelize when tasks have low coupling:

• Research API behavior while another agent maps local integration.
• Review separate packages with independent ownership.
• Run browser validation while another agent checks server logs.

Stay sequential when tasks share a design decision, edit the same files, or depend on a migration contract not yet settled.

Isolate edits with worktrees

git worktree add ../app-auth -b feature/auth
git worktree add ../app-tests -b feature/auth-tests

Each session starts in its own worktree. Assign file and outcome ownership. Do not have two agents edit the same migration, lockfile, or central type definition without a merge plan.

Before integration:

1. Each worker runs focused verification.
2. Review each diff independently.
3. Integrate in dependency order.
4. Resolve conflicts based on accepted design, not newest timestamp.
5. Run the full combined verification suite.

Team lead prompt

Coordinate three independent tracks: API implementation, UI integration, and
test-plan review. First define shared contracts and file ownership. Workers must
not edit outside assigned paths without asking. Require evidence-based handoffs.
After integration, run combined tests and review cross-track assumptions.

Failure modes

• Duplicate work because boundaries are vague.
• Conflicting edits to shared files.
• Main context filled with raw worker transcripts.
• Workers assuming different schemas or acceptance criteria.
• Each branch passes alone while integration fails.
• Token cost exceeds the sequential task.

FAQ

How many agents should I run?

Use the fewest that map to genuinely independent work. More agents increase coordination and integration cost.

Are subagents automatically safer?

Context isolation helps, but tool permissions still matter. Give each subagent the minimum capabilities needed.

Do worktrees replace review?

No. They isolate filesystem state. You still need contract alignment, diff review, and combined verification.