How to Fix Merge Conflicts Created by Coding Agents
Prevent parallel-agent conflicts where you can, and resolve the rest with rebase discipline and reviewed agent help.
Goal
Reduce merge conflicts from parallel coding agents, and resolve the conflicts that remain without merging the wrong side of a change.
Why conflicts rise with parallel agents
Conflicts increase when several writers edit related files against moving bases. Agents amplify that pattern:
- they finish branches quickly, so more branches sit waiting for review
- they often touch shared entry points, configs, and generated files
- they continue from stale bases unless something rebases them
Two agents in one checkout also create false conflicts: interleaved edits that look like merge problems but are really shared-filesystem collisions. Isolate agents first. See Git Worktrees for AI Coding Agents.
Prevention patterns
One task, one branch, one working copy. Do not run two agents in the same directory.
Agree on shared contracts before parallel work. If two tasks need the same interface, define it in a lower stack layer or merge it first.
Keep tasks small and bounded. Broad agent prompts wander into shared files and raise collision odds.
Rebase early. A conflict against last week's main is harder than a conflict against yesterday's.
git fetch origin
git rebase origin/main
Stack dependent work. If B needs A's schema, make B target A instead of inventing the schema twice.
Rebase discipline
Resolve conflicts on the branch that will merge next. For stacks, fix the lowest conflict first:
git switch auth/schema
git rebase origin/main
# resolve, test, push
git switch auth/service
git rebase auth/schema
# resolve, test, push
During conflict resolution:
git status
# edit conflicted files
git add path/to/file
git rebase --continue
Abort when the conflict shows the task no longer makes sense on the new base:
git rebase --abort
Restarting the agent on current main can be cheaper than preserving a small obsolete patch. Compare old and new intended behavior before discarding work.
Agent-assisted resolution
You can ask an agent to resolve conflicts, but you must review the result. Provide:
- the intended behavior after merge
- which side owns the correct contract when both changed
- tests that must pass after resolution
Example prompt shape:
Rebase onto origin/main and resolve conflicts in src/api/routes.ts.
Keep the pagination response shape from origin/main.
Keep the new auth middleware from this branch.
Add or update tests for an authenticated paginated list request.
Do not resolve unrelated files by deleting them.
In Treq, conflicted files appear in the workspace review UI. You can attach resolution instructions and send them to an agent. Treq blocks merge while unresolved conflicts remain. See Changes and Reviews.
Treq angle
Treq reduces avoidable conflicts through workspace isolation and auto-rebase of dependent workspaces. It does not remove semantic conflicts when two tasks change the same contract. Those still need a human decision about which behavior wins.
When a bookmark conflict appears after remote updates, resolve it from the bottom of the stack upward, then let dependents rebase. See Workspaces.
Common failure cases
Accepting both sides blindly. The file compiles and still implements two contradictory behaviors. Re-read the conflicted region against the task.
Resolving generated lockfiles by hand incorrectly. Prefer regenerating the lockfile after resolving package manifests.
Force-pushing a bad resolution. Run tests before --force-with-lease.
Leaving upper stack layers conflicted while reviewing them. Fix lower layers first or the upper review is fiction.