I run several agents on separate branches; when I merge, either two functions doing the same job show up or the same file conflicts. Should I design the shared interface first and only then start the agents?
I don't make agents write a shared interface up front and queue behind it: they all start at once, each in its own worktree. At merge time, the same piece written separately by two agents, or a conflict on the same lines, tells me where the shared piece lives; I move it into one file right then and delete the copy in the same commit.
beforethe agent that used the shared piece waited until the agent writing it had landed
afterall start at once · the copy was folded into one place 6 min 43 s after landing · 3,393 agent-branch commits land on main per week
don't make your agents write a shared interface up front; run them all at once on their own branches, list the pieces two branches wrote under the same name or that conflict before merging, move each into one file and delete the copyText for your agent · 30 lines
Situation: you run several agents at the same time on separate branches (git worktrees). When you merge, either two functions that do the same job show up, written by two agents, or the same file conflicts. The common advice is "write the shared interface first, then start the agents."
Why: where the shared piece lives isn't known up front; it shows up at merge time. An interface written up front ties one agent's work to another agent landing first; in my setup that ordering made the agent that used the piece wait until the agent writing it had landed, and once I dropped it they all started at once. A function two agents wrote under the same name, or a conflict on the same lines, is the shared piece itself: in my setup the copy the second agent wrote was folded into one place and deleted 6 min 43 s after the merge. A copy costs one merge pass; waiting costs every agent's turn.
Do:
1. Each agent works on its own branch in its own worktree; don't open a separate up-front task for the shared interface, start the agents at the same time.
2. Write the script that scans the branches side by side before merging, at the project root as .agents/twins.sh (needs git 2.38 or newer: git --version); the file is the block below:
for r in "$@"; do git rev-parse -q --verify "$r^{commit}" >/dev/null || { echo "no branch: $r"; exit 1; }; done
for b in "$@"; do git diff --no-color --no-ext-diff -U0 "HEAD...$b" -- . | sed -nE 's/^\+([a-z]+[[:space:]]+)*(function|const)[[:space:]]+([A-Za-z_][A-Za-z0-9_]*).*/\3/p' | sort -u | sed "s|\$| $b|"
done | while read -r n b; do git grep -qE "(function|const)[[:space:]]+$n([^A-Za-z0-9_]|$)" HEAD -- . || echo "$n $b"; done \
| awk '{n[$1]++; w[$1]=w[$1]" "$2} END {for (k in n) if (n[k]>1) print "same name: " k " ·" w[k]}' | sort
i=0
for a in "$@"; do i=$((i+1)); j=0
for c in "$@"; do j=$((j+1)); [ $j -le $i ] && continue
r=$(git merge-tree --write-tree --name-only "$a" "$c") && continue
echo "conflict: $a ↔ $c · $(printf '%s\n' "$r" | awk 'NR>1 && $0=="" {exit} NR>1 {printf "%s%s", s, $0; s=" "}')"
done
done
3. Run it when the agents are done, at the project root with the base branch (the branch the agents started from, e.g. main) checked out: sh .agents/twins.sh <branch-1> <branch-2> … The script prints two kinds of lines: "same name" (a name that isn't in the base but that two or more branches newly define with function or const on an unindented line) and "conflict" (a pair of branches that don't merge, and the files that conflict).
4. Merge the branches into the base one by one; resolve the files on a "conflict" line by hand in that merge. Once all have landed, for each "same name" line whose copies do the same job, keep the one that behaves right, delete the others and point their callers at the one kept.
5. Add two lines to the instruction file your agent reads every session (Claude Code: CLAUDE.md · Codex: AGENTS.md):
Don't ask for an up-front interface for a shared piece or wait for another agent; write what you need on your own branch.
Before merging, with the base branch checked out, run sh .agents/twins.sh followed by the name of every branch about to merge; the printed pieces that do the same job are moved into one file and the copy is deleted.
Verify (at the project root, as one command: it tests the script in a throwaway repo it creates and deletes at the end, and doesn't touch your branches):
- sh -c 's=$1; d=$(mktemp -d) && cd "$d" || exit 9; g() { git -c user.name=t -c user.email=t@t -c commit.gpgsign=false -c core.hooksPath=/dev/null "$@"; }; g init -q -b main; printf "export function stamp() {}\nexport function slugifyAll() {}\nexport function legacy() {}\n" > base.ts; g add -A; g commit -qm base; for b in a b c; do g branch $b; done; printf "export function stamp() {}\nexport function slugifyAll() {}\n" > base.ts; g commit -qam advance; g checkout -q c; for f in c c2; do printf "export function other() {}\n" > $f.ts; done; g add -A; g commit -qm c; for b in a b; do g checkout -q $b; k="function slugify(s) { return s }"; [ $b = b ] && k="const slugify = (s) => s"; printf "export $k\nexport function stamp() {\n const r = 1\n}\n" > $b.ts; for f in shared side; do printf "x = $b\n" > $f.txt; done; g add -A; g commit -qm $b; done; g checkout -q main; sh "$s" a c b; sh "$s" a d b; cd /; rm -rf "$d"' _ "$PWD/.agents/twins.sh"
- → exactly these three lines: "same name: slugify · a b" · "conflict: a ↔ b · shared.txt side.txt" · "no branch: d".
Don't:
- Make agents write the shared interface up front and wait for it to land: the merge shows which piece is shared, and an interface written in advance often sits in the wrong place.Also in: If you work with many agents