Run AI Coding Agents in Parallel Without Merge Chaos
Tomohiro Iida · Published August 14, 2026 · Updated August 23, 2026
Two coding agents can generate code faster than one. That does not mean the repository moves forward twice as fast. As implementation becomes parallel, integration, verification, and final judgment become the bottleneck. The operating rule in this article is simple: parallelize implementation, but serialize integration into main.
This article focuses on multiple agents working in the same repository. For the broader split between ChatGPT as design support, Claude Code as implementation, Codex as an independent reviewer, and a human as the final integrator, see the related role-separated development article.
How Netsujo separates design, implementation, audit, and final judgment
Conclusion: implementation can be parallel; integration should be sequential
Key takeaways
- Parallelize only tasks whose completion criteria can be judged independently.
- Give every task one branch, one worktree, one base commit, and an explicit file boundary.
- A worktree isolates files and Git working state; it does not automatically isolate API contracts, databases, ports, test data, caches, or merge order.
- Use a Task Contract to define allowed paths, prohibited paths, acceptance criteria, and stop conditions before an agent edits the repository.
- Merge one pull request at a time in dependency order, update the remaining branches from main, and rerun verification.
The slowest stage determines effective development throughput
Agentic development has three operational stages. Adding agents increases implementation capacity, but review and integration capacity do not increase automatically. When pull requests arrive faster than they can be integrated, the result is inventory: branches based on older commits, duplicated assumptions, and more expensive conflict resolution.
| Stage | Work | Typical bottleneck |
|---|---|---|
| Implementation | Code, tests, and documentation | Ambiguous tasks and incomplete repository context |
| Integration | Combining changes into one valid state | Dependencies, ownership, and merge order |
| Verification | Deciding whether the combined state is correct | Test scope, review capacity, and runtime environments |
The useful metric is not how many agents were active. It is how much verified change reached main, how long integration took, and how much rework was required.
Four conflicts must be managed separately
| Conflict | Does Git detect it? | Example | Primary control |
|---|---|---|---|
| Text conflict | Usually | Two branches edit the same component or configuration lines | Worktrees, file ownership, merge or rebase |
| Contract conflict | Usually not | The API returns a nested object while the UI expects flat fields | Shared types, API contracts, contract tests |
| Runtime conflict | No | Two worktrees migrate the same database or use the same test tenant | Separate ports, databases, namespaces, and fixtures |
| Integration-order conflict | No | A UI depending on a new API is merged before that API exists in main | Dependency map and one integration owner |
A clean Git merge is not proof that the combined system is valid. The most damaging conflicts often occur between assumptions in different files or between processes using shared infrastructure.
Choose tasks by dependency, not by agent capability
- Good parallel candidates
- Independent pages or components, tests for an already fixed contract, documentation, logging, read-only investigation, and changes in separate packages or services.
- Parallel after a contract is fixed
- Frontend and backend work, a shared component and its consuming screen, a data model and validation, or implementation and end-to-end tests.
- Prefer sequential work
- The same database migration, core authentication and authorization, large shared-type changes, repository-wide renames, dependency upgrades with one lockfile, or a refactor whose direction is still undecided.
- Can each task be judged complete without waiting for the other task?
- Can the files or directories likely to change be predicted before work starts?
- Can one task finish without changing the other task’s assumptions?
If any answer is unclear, change the split or run the tasks sequentially. Forcing a dependency-heavy task into parallel work creates more integration work than implementation time saved.
Use four layers of isolation
- Workspace isolation
- Each agent works in a separate Git worktree instead of sharing uncommitted files and generated output in one checkout.
- Change-responsibility isolation
- Each task lists allowed and prohibited paths. Shared contracts, authentication, migrations, and package files have an explicit owner.
- Runtime isolation
- Development ports, databases, queue prefixes, object-storage prefixes, test users, and external sandbox namespaces are separated where possible.
- Integration-authority isolation
- Implementation agents prepare commits and pull requests. One integration owner decides merge order, conflict meaning, and release readiness.
Git worktree separates working directories, not every shared resource
Git worktree lets one repository have multiple linked working trees so more than one branch can be checked out at the same time. A practical rule is one task, one branch, and one worktree. A detached worktree is also useful for read-only review or experiments.
- Update the base first: git fetch origin, git switch main, and git pull --ff-only.
- Create a UI worktree: git worktree add ../project-wt-goal-ui -b feat/goal-ui origin/main.
- Create an API worktree: git worktree add ../project-wt-goal-api -b feat/goal-api origin/main.
- Create a detached review worktree: git worktree add --detach ../project-wt-goal-review origin/main.
- Inspect active worktrees with git worktree list and remove completed ones with git worktree remove followed by git worktree prune.
Claude Code supports starting an isolated session with the --worktree or -w option. The Codex app also provides built-in worktree support for multiple agents on the same repository. These features reduce file collisions, but application-level resources still need separate controls.
A worktree is a fresh checkout. Gitignored environment files may not be present, and a shared local database or staging project remains shared unless you deliberately separate it.
Give every agent a Task Contract
The contract should constrain the task before code is generated. The most important section is often what the agent must not change. Broad instructions such as “improve related areas as needed” erase ownership boundaries and let one agent enter another task’s scope.
| Field | Purpose |
|---|---|
| Task ID and objective | Give the work one traceable purpose |
| Base commit | Record the exact repository state the agent assumed |
| Allowed paths | Define where edits are expected |
| Prohibited paths | Protect shared contracts, migrations, authentication, package manifests, or lockfiles |
| Dependent contract | Fix API shapes, events, error formats, and null handling |
| Acceptance criteria | Make completion independently testable |
| Verification commands | Specify lint, typecheck, focused tests, build, or E2E checks |
| Stop conditions | Require the agent to report instead of silently expanding scope |
| Completion report | Return commit SHA, changed files, checks run, remaining risks, and deviations |
Before editing, ask the agent to list planned files. At completion, compare that list with git diff --name-only origin/main...HEAD. Unexpected files should be formally added to scope, reverted, split into another pull request, or treated as a dependency—not left as an undocumented extra improvement.
Isolate the runtime environment as deliberately as the files
| Resource | Example isolation |
|---|---|
| Development server | Use ports such as 3001 and 3002 |
| Database | Use separate database names, schemas, or tenant IDs |
| Redis or queues | Use a task-specific prefix or namespace |
| Object storage | Use a separate bucket prefix |
| Test users | Use agent-a and agent-b fixtures |
| External APIs | Use separate sandbox projects or idempotency keys |
| Temporary files | Write inside the task worktree |
When a shared resource cannot be separated, add a lock. For example, only one task may migrate a shared staging database at a time. Refusing to parallelize an unsafe resource is part of a correct parallel operating model.
Subagents and worktrees solve different problems
| Need | Primary mechanism |
|---|---|
| Separate investigation context or specialist roles | Subagent or custom agent |
| Edit multiple implementations at the same time | Git worktree |
| Keep API and type assumptions consistent | Task Contract and shared contract |
| Control what reaches main | Pull request, CI, branch protection, integration owner |
Creating more subagents does not automatically separate their file systems. When agents can write concurrently, workspace isolation must be explicit.
Serialize integration in dependency order
- Merge the shared type or API-contract pull request first.
- Start implementation branches from the same recorded base commit.
- Review each pull request against its Task Contract and changed-file boundary.
- Merge one pull request, then update the remaining branches from main.
- Rerun typecheck, tests, build, and any high-risk checks after the update.
- Remove merged worktrees and delete obsolete branches so the active state stays visible.
Completion time is not merge order. A frontend pull request that depends on a new API must wait even if it was finished first. The integration owner keeps main valid at every step.
Do not make Claude Code and Codex race to implement the same task
Unless comparison is the experiment, two implementations create another selection and integration task. A more efficient default is to let one agent implement and another review the final diff without write access. Findings normally return to the original implementation owner for correction, keeping ownership legible.
| Role | Responsibility | Write authority |
|---|---|---|
| Integration owner | Task split, shared contracts, merge order, release decision | Main and shared contracts |
| Implementation agent A | One independent feature | Dedicated worktree |
| Implementation agent B | A separate feature or test scope | Dedicated worktree |
| Review agent | Diff review, regression and security findings | Read-only by default |
| CI | Lint, typecheck, tests, and build checks | Decision signal only |
Make main a technical gate rather than a reminder
- Require pull requests instead of direct pushes to main.
- Require relevant status checks to pass.
- Require review conversations to be resolved.
- Restrict direct pushes and assign CODEOWNERS for high-risk paths.
- Decide deliberately between strict checks that require an up-to-date branch and looser checks that reduce rebuilds but permit more integration risk.
Use cheap checks early and expensive checks near integration. Focused lint, tests, and typecheck can run during implementation; broader tests, build, E2E, authorization checks, and migration verification should run before high-risk changes merge.
Limit work in progress before adding another agent
Fast implementation makes it easy to start more tasks while existing pull requests wait. That is usually the wrong response. Waiting branches age, their base commits diverge, and later integration becomes more expensive.
- For one integration owner, keep no more than two tasks in implementation.
- Keep no more than two pull requests waiting for review.
- Allow only one high-risk change at a time.
- When the limit is reached, integrate current work before starting new work.
Minimum operating rules
- One task, one branch, one worktree.
- Record the base commit for every task.
- Define allowed paths, prohibited paths, and stop conditions.
- Give shared contracts, authentication, and database migrations one owner.
- Separate databases, ports, fixtures, and external sandbox namespaces.
- Do not let implementation agents push directly to main.
- Require a completion report with the commit, changed files, checks, and unresolved risks.
- Separate implementation and review authority.
- Use one integration owner and merge in dependency order.
- Update remaining branches after every merge and rerun verification.
- Delete completed worktrees and obsolete branches.
Frequently asked questions
Does a worktree eliminate conflicts?
No. It separates working directories and Git state. API contracts, shared types, databases, ports, external services, and merge order still need explicit controls.
Can frontend and backend work run in parallel?
Yes, after the request shape, response shape, error format, authorization conditions, and null handling are fixed. If the contract is still moving, sequential work usually produces less rework.
How many agents should run at once?
Use the number the integration owner can review and merge without growing a backlog. Hardware and model limits are not the operational limit; review and integration throughput are.
Official references
Git: git-worktree documentation
Anthropic: Run parallel Claude Code sessions with worktrees
OpenAI: Introducing the Codex app
GitHub: About protected branches
Product features and official documentation references were checked on 14 August 2026.
Netsujo supports AI implementation, proof-of-concept design, and the operating controls that determine where agents may act and where human judgment remains mandatory.
Discuss an AI implementation and governance designAI agent development and operations incident log
The same work item, different chat names
Claude Code specification-driven development
A one-person, four-project Claude Code operating record
Solo development with AI agents and the concentration of judgment（日本語）
Continue the series
Previous: #08 Cutting CI cost almost removed the safety checks
Next: #10 A green deploy is not production verification
Back to all 12 episodes of the AI Agent Development Incident Log