i wrote about when parallel subagents beat regular skills and how the parent should keep shared writes serial. this post is the simpler rule underneath that pattern.
only one agent should make file edits in a single repository at a time.
that sounds conservative until you watch what happens when you break it. two agents, two unrelated files, no obvious overlap, and both still get worse at the job. the problem is not git merge conflicts alone. the problem is that agents do not snapshot the repo once and freeze it. they keep scanning for context while the tree is moving.
quick answer
treat each repository as having one write lane. let many agents read and analyze in parallel if the units are independent, but keep all file mutations on one agent at a time, usually the parent conversation that launched the work.
if agent a is editing a model file in one folder and agent b is editing metadata in another, agent b may still re-read shared config, search the repo for patterns, or infer conventions from files agent a is actively changing. the reads interleave with the writes. each agent builds a plan from a repo state that stops being true before the plan finishes.
the fix is boring and effective. workers stay read-mostly. one agent applies edits serially. finish the write lane before you open a second one.
who this is for
- people running parallel subagents or multiple cursor chats against the same codebase
- teams that noticed "correct but wrong" suggestions after concurrent agent sessions
- builders who want parallel speed on reviews without paying for parallel confusion on writes
why this matters
an agent's plan is only as good as the repo snapshot it believes it has. that belief is fragile.
while an agent works, it searches, re-opens files, follows imports, checks conventions, and compares against neighboring examples. that is a feature. it is how the agent grounds advice in the actual codebase instead of generic patterns.
but the same behavior becomes a bug when another agent is writing at the same time. the repo is a moving target. a config file changes mid-review. a new export appears while a worker is still reasoning from the old module layout. a parent dispatches two writers and each assumes the other's changes either already landed or never will.
the failure modes are predictable.
- stale context: agent b reads version 1, agent a writes version 2, agent b proposes edits against version 1
- duplicated or conflicting edits: two agents "fix" the same convention in different ways because each inferred a different baseline
- phantom dependencies: an agent plans around a file that another agent renamed, deleted, or never finished creating
- overconfident summaries: each agent reports success against its local view while the combined result is incoherent
none of this requires both agents to touch the same path. shared config, search results, import graphs, and convention scans are enough coupling.
reads in parallel, writes in series
this is the split i use in practice.
| activity | concurrency |
|---|---|
| standards review across independent folders | parallel read-only workers |
| documentation drift audit by doc area | parallel read-only workers |
| sanity check by category | parallel read-only workers |
| scaffolding or editing files in one repo | one writer at a time |
| shared config, lockfiles, catalog indexes | parent applies serially after aggregation |
| git staging, commits, pushes | one agent, human-gated |
parallelism buys wall-clock time when the work is analysis against a stable tree. serial writes keep the tree stable enough for analysis to mean something.
if you already use the pattern from my parallel subagents post, this is the same boundary with the guardrail turned up. workers analyze. the parent decides and applies. do not hand multiple agents write access to the same repo and assume file separation is enough.
what about different files in different folders?
different paths are not different universes.
agents routinely cross folder boundaries to learn how the repo works. they read shared configuration, follow references, compare naming across layers, and search for prior work. a worker assigned to "folder x only" still pulls context from folder y when y is where the canonical example lives.
so "agent a owns sql, agent b owns yml" is not a safe split by itself if both repos share conventions, generated artifacts, or a catalog that lists both. the write lane is the repository, not the file glob you wished you had assigned.
the safe exceptions are narrow.
- truly separate repositories with no shared build or release surface
- read-only parallel audits where no worker mutates anything
- one writer plus several readers, with readers forbidden from applying patches
everything else gets the single-writer rule.
how this fits multiple chats, cloud agents, and multitask
the constraint is operational, not philosophical. however many agents you use, count active writers per repo, not open tabs.
practical habits that work for me:
- one editing conversation per repo unless the previous write pass is fully landed and verified
- background review is fine if it stays read-only and you treat its output as provisional until the write lane is free
- do not mix a local write session with a cloud agent editing the same repo even on different branches if both can touch working tree state you care about
- queue the next write instead of overlapping it. reviews can run while you wait. writes should not
if you use worktrees to isolate concurrent experiments, treat each worktree as its own repo surface for this rule. one writer per worktree still holds. the goal is to stop interleaved mutation and re-scanning on the same logical codebase.
a simple decision table
| situation | allowed |
|---|---|
| three subagents review five folders, no edits | yes, parallel |
| one parent edits while subagents review | yes, if subagents are read-only and you accept provisional findings |
| two agents edit different files in one repo | no |
| two agents edit two repos that share a release contract | treat as one write surface unless you truly isolate them |
| parent aggregates findings, then applies patches itself | yes, this is the default good pattern |
| trivial one-line fix while a large agent job runs | still no if the large job can write. finish or pause one lane |
closing
parallel agents are good at doing the same trusted review many times at once. they are bad at sharing a write lane they cannot see changing in real time.
so i keep the concurrency on reads and the discipline on writes. one repository, one agent mutating files at a time. let everyone else look, compare, and report back. when it is time to change the tree, pick a single agent, apply the edits, verify, and only then open the lane again.
that is less exciting than letting five agents "each take a corner," and it is much closer to what actually happens when five agents are all trying to learn the same repo at once.
faq
can two agents edit if they use different branches?
only if their working surfaces are fully isolated and you accept that each agent still will not see the other's in-flight edits. for most local agent workflows, that isolation is weaker than it looks. i still default to one writer.
is read-only parallel work safe while another agent writes?
mostly yes, with one caveat. treat review output as provisional until the write lane closes. a read-only worker may analyze files that change before the parent aggregates results.
does this mean i cannot use parallel subagents at all?
no. use them for read-mostly work such as reviews, audits, and sanity checks. keep the write lane in the parent. see the parallel subagents guide for the full pattern.
what if the edits really are in completely unrelated packages?
if there is no shared config, no shared catalog, no cross-package search path, and no release step that combines them, you might get away with parallel writes. i still queue writes anyway because the exceptions are rarer than they feel in the moment.
how does this relate to guardrails?
guardrails define what an agent is allowed to do. this rule defines what you should let multiple agents do at the same time within those permissions. i keep both. see the guardrails i actually use with ai agents for the wider kit.
Top comments (0)