my-git

Multi-Agent Branch Strategy

English

When developing with multiple agents in parallel, the core is isolating tasks, clarifying ownership, and finally having humans perform integration.

Branch Naming

ai/task-parser-refactor      # one clear task
ai/experiment-parser-a       # approach A to the same problem
ai/experiment-parser-b       # approach B to the same problem
ai/review-parser-refactor    # cleanup branch prepared for review

Before merging experimental branches, reorganize them into normal business branches:

feat/parser-error-handling
fix/parser-empty-input

Recommended Process

One branch per agent, paired with one worktree directory per branch.
One clear task per branch, with boundaries cut along directories or modules.
Independent commits and validation for each branch.
Humans compare the results and choose which solution to keep.
Organize commits before merging, and rename the experimental branch into a business branch.

Comparing Experimental Branches

Two agents each produced a solution. First check what each branch changed relative to the main line:

git log --oneline main..ai/experiment-parser-a
git diff main...ai/experiment-parser-a    # three dots: only the branch's own changes
git diff main...ai/experiment-parser-b

Then compare the two solutions directly:

git diff ai/experiment-parser-a..ai/experiment-parser-b
git range-diff main ai/experiment-parser-a ai/experiment-parser-b

git range-diff aligns the two branches commit by commit, which works well when the two solutions have similar structure.

Do not decide on diffs alone. Run the same test commands on both branches and record the results in the task notes or PR description as the basis for the decision.

Integrating the Winning Solution

When solution A wins as a whole, turn it into a business branch:

git switch -c feat/parser-error-handling ai/experiment-parser-a
git rebase main

When you only need part of solution B, pick by commit:

git cherry-pick <commit-sha>

Or pick by file:

git restore --source ai/experiment-parser-b -- src/parser/recover.ts
git add src/parser/recover.ts
git commit

When Two Agents Touch the Same File

Prevention first: cut task boundaries so agent scopes do not overlap, and let only one task touch files such as route tables, dependency manifests, and shared configuration.

When a collision still happens, handle it in order:

Merge one branch first.
Rebase the other branch onto the latest main line: git rebase main.
Conflicts are decided by humans. You can ask the agents to explain the intent of each side, but a human picks the outcome.
After resolving conflicts, rerun the branch’s validation before sending it to review.

Cleaning Up Losing Branches

# Tag first if you want to preserve the state for later reference
git tag archive/ai-experiment-parser-b ai/experiment-parser-b

# Delete the local branch and its worktree
git branch -D ai/experiment-parser-b
git worktree remove ../wt-parser-b

# If it was pushed, delete the remote branch as well
git push origin --delete ai/experiment-parser-b

When closing the draft PR of a losing branch, state why it lost, so similar future tasks have a record to consult.

Avoid

Multiple agents writing to the same workspace.
Multiple agents modifying the same set of files simultaneously.
Letting agents merge public branches themselves.
Accepting results without looking at the diff.
Leaving experimental branches uncleaned until the repository fills up with dead ai/ branches.

Extended Reading

This site is open source. Improve this page.