Orchestrate Claude Code Agent Teams and Git Worktrees Without Merge Chaos

Quick answer

Parallelize only work that has separable ownership and a stable integration contract. A lead should define the shared goal, dependency graph, file/component boundaries, interface version, verification, and merge order before teammates edit. Give each agent its own Git worktree for independent branches, checkpoint at contract boundaries, and run integration tests after every merge. Anthropic's agent teams guide and worktree guidance cover current orchestration features.

Decide whether parallelism helps

Good candidates:

• independent research questions;
• separate packages behind an agreed interface;
• platform-specific implementations from a shared spec;
• test expansion across independent areas;
• implementation plus independent review;
• documentation and migration tooling after behavior stabilizes.

Poor candidates:

• one root cause not yet understood;
• many agents editing the same central file;
• rapidly changing shared types;
• a small task whose coordination exceeds implementation;
• external mutations without a single accountable owner.

Estimate coordination cost explicitly. More agents do not guarantee shorter completion.

Write a team contract

Goal: add idempotent order cancellation.
Shared contract: CancellationResult v1 in packages/contracts; lead owns changes.
Agent A: domain state machine + unit tests; owns packages/orders-domain/**.
Agent B: API adapter + contract tests; owns services/orders-api/** after v1 lands.
Agent C: read-only adversarial review of race conditions and authorization.
No agent edits shared contract, migrations, lockfile, or CI without lead approval.
All return changed files, commands/results, assumptions, and merge dependencies.
Merge: contract -> domain -> API -> review fixes -> full verification.

Interfaces are not stable merely because a type file exists. Freeze semantics and error behavior before fan-out.

Use one worktree per editing branch

git worktree add ../orders-domain -b feature/orders-domain
git worktree add ../orders-api -b feature/orders-api
git worktree list

Run repository setup and a clean baseline in each. Do not share mutable build output, local databases, ports, or caches unless the tools support concurrency. Give each worktree distinct service ports and test namespaces when necessary.

Worktrees isolate files, not remote credentials or external systems. Two agents can still collide in a cloud account or database.

Integrate continuously

The lead should:

1. Review every return against the contract.
2. Inspect commits/diffs for scope and user-owned changes.
3. Merge or cherry-pick in dependency order.
4. Resolve contract conflicts centrally rather than allowing silent divergence.
5. Run focused tests after each integration.
6. Run full type, build, integration, and browser/security checks at the end.
7. Request a fresh adversarial review of the integrated result.

Do not accept “my branch passes” as system-level proof.

Recover from team failure

If two agents overlap, stop both and select one authoritative implementation. If a shared interface changes, broadcast the versioned contract and rebase dependent plans before more edits. If an agent stalls, retrieve its evidence and branch state rather than restarting blindly. Preserve partial work only if it passes review and reduces remaining risk.

Mastery lab

Implement a small vertical feature with three roles: contract/domain, adapter/UI, and adversarial review. Use separate worktrees, explicit ownership, and staged integration. Track conflicts, duplicate investigation, test failures after merge, context cost, and wall time. Repeat sequentially and compare whether parallelism actually helped.

FAQ

Do agent teams automatically prevent file conflicts?

No. Orchestration helps coordination; explicit ownership, worktrees, and integration discipline prevent most conflicts.

Should every teammate use the same model?

No. Match the model to task complexity while keeping a consistent contract and review standard.

Who owns final correctness?

The lead/integrator and accountable human. Distributed work does not distribute away responsibility.