---
title: "How to split a big task across several AI coding agents · Cork"
description: "Split a large coding task across parallel AI agents: land contracts first, cut units by file ownership, pick /batch, agent teams or worktrees, land in order."
canonical: "https://corkcli.com/blog/split-big-task-across-multiple-ai-coding-agents"
last_updated: "2026-10-03"
published: "2026-10-03"
author: "Kevin Vera"
---

# How to split a big task across several AI coding agents

Split a large coding task across parallel AI agents: land contracts first, cut units by file ownership, pick /batch, agent teams or worktrees, land in order.

By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 7 min read

To split a big task across several AI coding agents, first fix the shared contracts (types, interfaces, function signatures) in one small change, then cut the rest into self-contained units that each own a distinct set of files, run one agent per unit in its own worktree, and land the results one at a time with a rebase and a test run. The split is where parallel agent work succeeds or fails: units that share files or depend on each other's unfinished code turn a speedup into a merge cleanup.

## Step 1: decide whether the task should be split at all

Parallel agents are not free. Claude Code's docs say agent teams "add coordination overhead and use significantly more tokens than a single session," and that "for sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective."

Good candidates for splitting:

- **Mechanical changes across many files**: a migration, a rename, an API version bump.
- **Independent features or modules** that meet at a known interface.
- **Cross-layer work** where frontend, backend, and tests can each be owned by a different agent.
- **Research and review** with distinct lenses (security, performance, test coverage).

Poor candidates: a tricky bug in one module, a refactor whose shape you do not know yet, or anything where step 2 depends on what step 1 discovers.

## Step 2: land the contracts first

Most parallel-agent breakage comes from two agents building against different ideas of the same interface. Remove that ambiguity before fan-out:

1. Have one agent (or you) write the shared types, interfaces, and function signatures, with stub implementations.
2. Merge that change to the main branch.
3. Start every parallel agent from the commit that contains it.

Now each agent builds against the same signatures, and anything that changes them is visible as a deliberate change rather than a surprise at merge time.

## Step 3: cut units by file ownership

Write the plan as a table before starting any agent. Each unit names its goal, the files it owns, and what it must not touch:

| Unit | Owns | Must not touch | Done when |
|---|---|---|---|
| API handlers | `src/api/orders/*` | `src/types/*` | Handler tests pass |
| Data layer | `src/db/orders.ts`, migrations | `src/api/*` | Migration and repo tests pass |
| UI | `web/orders/*` | `src/*` | Component tests pass |
| Tests for merged code | `tests/orders/*` | Source files | New tests pass on main |

Rules of thumb:

- **No file on two rows.** If two units need the same file, either merge the units or move that file's change into the contracts step.
- **Right-size the units.** Claude Code's agent teams guidance: too small and "coordination overhead exceeds the benefit," too large and agents "work too long without check-ins." It suggests 5 to 6 tasks per teammate and starting with 3 to 5 teammates.
- **Give each unit a check.** A test command per unit lets each agent verify its own work before you see it.

## Step 4: choose how to run the agents

Claude Code gives you three ways, and the right one depends on how much you want to steer.

**`/batch` for large mechanical changes.** The bundled `/batch` skill "researches the codebase, decomposes the work into 5 to 30 independent units, and presents a plan. Once approved, spawns one background subagent per unit in an isolated worktree. Each subagent implements its unit, runs tests, and publishes its change." It needs a git repository.

```text
/batch migrate src/ from JavaScript to TypeScript
```

**Agent teams when units need to talk.** A lead session creates a shared task list and teammates claim tasks, with dependencies that block a task until its prerequisites complete. Teammates share one checkout, so the docs' rule matters: "Break the work so each teammate owns a different set of files." Agent teams are experimental; enable them with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.

**Parallel sessions you drive yourself.** One terminal per unit, each in its own worktree:

```bash
claude --worktree orders-api
claude --worktree orders-db
claude --worktree orders-ui
```

Each creates `.claude/worktrees/<name>/` on a branch named `worktree-<name>`. By default worktrees branch from the repository's default branch on the remote, which is what you want after landing the contracts in step 2. If the contracts are only on your local branch, set `worktree.baseRef` to `"head"` in settings so worktrees start from your current `HEAD`.

For subagents you define yourself, add `isolation: worktree` to the frontmatter so each runs in a temporary worktree:

```markdown
---
name: unit-worker
description: Implements one unit of a planned parallel change and runs its tests
isolation: worktree
---

Implement only the files your unit owns. Run the unit's test command and report results.
```

Outside Claude Code, Cursor runs parallel agents in its Agents Window with worktrees it creates and manages, and reads setup commands from `.cursor/worktrees.json`.

## Step 5: land units one at a time

Worktrees stop agents from overwriting each other's files while they work. They do not make the branches compatible. Land in dependency order, and make every later unit rebase onto what already landed:

```bash
git fetch origin
git rebase origin/main
# run the full test suite, not just the unit's tests
git push origin HEAD
```

Running the full suite after each rebase catches the conflicts git cannot see, such as a unit calling a function another unit renamed. If your host supports it, a merge queue does the same check automatically: GitHub's merge queue verifies each pull request "when applied to the latest version of the target branch and any pull requests already in the queue."

## How Cork helps

A clean split prevents most collisions, but agents still drift outside their rows, rename things mid-task, and discover shared files nobody planned for. Cork handles what the plan did not foresee. Cork is the [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) for multiplayer coding agents: it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned.

For this problem specifically:

- **Briefing:** each unit's agent is handed the exact signatures, callers and recent changes of the code it is about to touch, including the contracts you landed first.
- **Live awareness and [semantic lint](https://corkcli.com/blog/semantic-lint):** if one unit renames or re-signatures a symbol another unit uses, the other agent hears it on its next step and is checked against the change.
- **[Write gate](https://corkcli.com/blog/write-gate):** an edit against code another agent is changing right now is held until your agent has their version.
- **Landing:** `git push` becomes one step that rebases onto teammates' commits, reruns the tests and pushes, which is step 5 done for every unit.

Install it once for every repo on the machine:

```bash
curl -fsSL https://corkcli.com/install.sh | sh
```

## Frequently asked questions

### How many AI agents should work on one task?

Start small. Claude Code's docs suggest 3 to 5 teammates for most agent team workflows and note that "three focused teammates often outperform five scattered ones." Add agents only when units are truly independent.

### What is the /batch command in Claude Code?

A bundled skill that plans a large change as 5 to 30 independent units and, once you approve, runs one background subagent per unit in its own worktree. Each one implements its unit, runs tests, and publishes its change.

### Should parallel agents share one checkout or use worktrees?

Use worktrees when agents run long or touch nearby code; they isolate uncommitted edits. A shared checkout is workable only with strict file ownership or a write gate that holds conflicting edits.

### Why do branches from parallel agents still conflict?

Because isolation ends at merge time. Two agents can each produce a correct branch that breaks the other, for example by renaming a function the other still calls. Land one at a time and run the full suite after each rebase.

## Sources

- <https://code.claude.com/docs/en/agent-teams>
- <https://code.claude.com/docs/en/commands>
- <https://code.claude.com/docs/en/worktrees>
- <https://code.claude.com/docs/en/sub-agents>
- <https://cursor.com/docs/configuration/worktrees>
- <https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue>

## Related reading

- [Parallel AI coding agents on a team: how to split who works on what](https://corkcli.com/blog/split-work-parallel-ai-coding-agents-team): How a team splits work across parallel AI coding agents: slice by code ownership, name shared files, one branch per agent, small tasks, and live coordination.
- [Claude Code agent teams vs separate sessions on one repo](https://corkcli.com/blog/claude-code-agent-teams-vs-separate-sessions): Claude Code agent teams vs separate sessions on one repo: how each works, token cost, same-file conflicts, worktrees, and when to pick which (October 2026).
- [How to stop Claude Code agents from overwriting each other's changes](https://corkcli.com/blog/stop-claude-code-agents-overwriting-changes): Why parallel Claude Code agents overwrite each other's edits, and how to stop it with worktrees, file ownership, deny rules, PreToolUse hooks and a write gate.
- [How to onboard an engineer when AI agents write half the code](https://corkcli.com/blog/onboard-engineers-ai-coding-agents): Onboard a new engineer on a codebase where AI agents write much of the code: agent instruction files, guardrails, ownership, and a first week plan that works.

[All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt)

This page in HTML: https://corkcli.com/blog/split-big-task-across-multiple-ai-coding-agents