Two agents on one file is one agent overwriting the other

Splitting roles means cutting into non-overlapping areas, not dividing for numbers

Published2026-05-31
Read2 min read
TypeField notes
TL;DR

Multiple agents collide not because there are many, but because their roles overlap. Role-splitting that works cuts the task into separate areas: each agent its own part, boundaries sharp enough that two never touch the same spot. Wherever roles overlap, one agent will quietly overwrite the other.

You open two agents to move faster: one handles the processing, one handles the display. Both, to do their jobs, edit the same shared file. The first finishes. The second opens that very file — from the version before the first's change — does its part, and overwrites. The first's work evaporates, quietly, with no error raised.

Neither one is wrong. Their two roles overlap at one point, and that point is enough to break things.

01Overlap is where accidents live

When two agents have two separate desks and both may touch the same thing, you don't have two collaborators — you have two people writing over each other without noticing. They can't see each other's desks (that reason again), so neither knows what the other just touched.

So the first job of splitting roles isn't "what does this one do," it's drawing boundaries so the areas don't intersect:

Overlapping roles

Agent A: "handle processing" — edits shared file
Agent B: "handle display" — edits it too
B overwrites A, quietly

Separate roles

Agent A: may touch only the processing area
Agent B: may touch only the display area
The shared bit: one owns it, others read-only

The hinge is that last line: the shared thing must have a single owner. One agent may change it; the others may only read, and to change it they propose through the owner. A thing everyone can change is a thing that will get changed into chaos.

02Tight roles are easy to check, big roles get lost

There's a double benefit to cutting roles tight: not only do you avoid collisions, each piece also fits on one agent's desk. Remember — an agent carrying too large a job overflows its desk and drops things. A tight role sits fully on the desk, it does it cleanly, and you can review that piece in one sitting.

The test of a well-split role: you can describe it in one sentence ("this one only does X, only touches Y"), and you can point to exactly what it must not touch. If a role's boundary is fuzzy — "roughly handles this part" — that's exactly where it'll spill into another's area, and the accidents begin.

End of pieceCluster 03 · 2/4
The author

craftagent is the notebook of someone still building — told over coffee, each story wrapped around a lesson paid for in full.