When four coding agents get the same ticket for a new field, all four will edit the shared model file. Each needs the field there, and none was told the file is off limits. Whether the work can run in parallel at all comes down to a list you can write before any of them starts: which paths each worker may change, with no path on two lists.
Agents sharing a repo have the problem that led me to argue for exactly one writer per lakehouse table, with files in place of tables. Reads are free. Writes need an owner, and nothing in the agent runner can work one out from a ticket.
A parallel run buys wall-clock time with tokens, and only on a task that’s already split. The planner’s first output is a plan a script can check. Code comes later.
Disjoint writes and frozen interfaces
Each piece of the split is a lane, with one worker per lane. A task is parallel when two things hold. The lanes have disjoint write sets, so no file is written by more than one lane, though reads can overlap freely. And anything the lanes share, such as a type or an API schema, is fixed before any worker starts.
If a worker can change something another worker builds on, that’s a race. You find it as a merge conflict if you’re lucky and as a quiet mismatch if you’re not.
A manifest, then a stubs commit
The planner, an agent or a person, reads the task and writes lanes.yml. Each lane gets the paths it may write, the frozen interfaces it uses, a done check and a token budget. The manifest stays with the planner, outside every worktree, so no worker can widen its own globs.
That’s also the go/no-go point. If the planner can’t fill in the write globs without two lanes sharing a path, give the task to one agent. Splitting one file between two lanes doesn’t rescue it. Git may merge the halves cleanly, but a path check can’t see which half a lane touched.
Next, the shared interfaces land as one commit on the base branch, with real signatures and placeholder bodies. One agent or one person makes it, never a worker. Each worker then gets its own git worktree on a branch from that commit, and its own short-lived credential, scoped as in the post on a coding agent’s blast radius.
For an invented task, it looks like this.
# lanes.yml for an invented task
task: INV-212-refund-status
base_commit: "9c41e7a" # the stubs commit; every lane branches from here
frozen_interfaces:
- id: status_enum
path: billing/invoice/refund_status.py
- id: invoice_field
path: billing/invoice/model.py
- id: api_schema
path: api/schemas/invoice.json
lanes:
- id: migration
writes: ["db/migrations/**", "tests/db/**"]
uses: [status_enum, invoice_field]
done_check: make test T=tests/db
token_budget: 300000
- id: api
writes: ["api/handlers/invoices/**", "tests/api/invoices/**"]
uses: [status_enum, invoice_field, api_schema]
done_check: make test T=tests/api/invoices
token_budget: 500000
- id: export
writes: ["jobs/nightly_export/**", "tests/jobs/nightly_export/**"]
uses: [status_enum, invoice_field]
done_check: make test T=tests/jobs/nightly_export
token_budget: 400000
- id: admin
after: [api] # branches from the api lane's finished work
writes: ["admin/invoices/**", "tests/admin/invoices/**"]
uses: [status_enum, api_schema]
done_check: make test T=tests/admin/invoices
token_budget: 400000
A path check on every lane’s diff
An instruction to stay in scope is a request. CI is where it becomes a rule. The scope guard diffs a lane’s branch against the commit it started from and fails on any path outside its write globs. The frozen interfaces aren’t in anyone’s writes, so a worker that tidies up the enum fails here too.
#!/usr/bin/env python3
"""Usage: scope_guard.py lanes.yml LANE_ID [START_COMMIT]
START_COMMIT defaults to base_commit. A lane with `after` passes the commit it branched from."""
import subprocess
import sys
from fnmatch import fnmatchcase # "*" also matches "/", so "dir/**" covers every level
import yaml # PyYAML
def main(manifest_path, lane_id, start=None):
with open(manifest_path) as f:
manifest = yaml.safe_load(f)
lane = next((item for item in manifest["lanes"] if item["id"] == lane_id), None)
if lane is None:
sys.exit(f"no lane {lane_id!r} in {manifest_path}")
base = start or manifest["base_commit"]
out = subprocess.run(["git", "diff", "--name-only", "--no-renames", "-z", base, "HEAD"],
capture_output=True, text=True, check=True).stdout
outside = [p for p in out.split("\0") if p and not any(fnmatchcase(p, g) for g in lane["writes"])]
for path in outside:
print(f"{lane_id}: {path} is outside this lane's write globs")
return 1 if outside else 0
if __name__ == "__main__":
sys.exit(main(*sys.argv[1:4]))
Keep --no-renames. Without it, moving a file out of a protected path shows up as only its new name.
Lanes that pass go to one integration step, which merges them in manifest order, runs the full suite and, if that’s green, opens a single pull request.
Refund status, run twice
Both runs below are hypothetical, numbers included. The task adds a refund status to an invoice service, touching a database migration, an API field, the nightly export and an admin screen.
The naive run hands four agents the task description. All four edit the shared invoice model and the API schema. Three of the merges conflict. The export agent writes partially_refunded where the others wrote partial_refund, and its own tests pass because its fixtures agree with it. Two lanes get redone.
The split run commits the RefundStatus enum, the model field and the schema entry first, which takes one agent eight minutes. Migration, API and export then run in parallel. The admin lane waits for the API lane, because it depends on behavior the field’s type doesn’t show, like which status changes the API refuses.
| Naive run | Split run | |
|---|---|---|
| Workers editing shared files | 4 | 0 |
| Merge conflicts | 3 | 0 |
| Lanes redone | 2 | 1 |
| Tokens vs. one agent | 4.1x | 2.6x |
| Speedup vs. one agent | 1.0x | 1.5x |
The split run’s one redo was the migration lane, which burned its budget on a flaky test. It’s the shortest lane, so the rerun still beat the admin lane. It cost tokens, not time, and no interface moved.
The API and admin lanes run back to back, so together they set the wait, and extra workers can’t shorten it. Every worker also learns the repo from scratch, a cost the lone agent paid once. The good run still costs 2.6 single runs, for a wait about a third shorter.
When the stubs weren’t frozen after all
Count redos, and why each one happened. If more than one lane in five is redone because an interface changed, the stubs were a first draft, and more agents will only mean more redos. When an interface must move, the uses lists show which lanes go back. Asking the stubs author for a failing test against each interface helps, because it forces the shape to be decided.
Then do the accounting against one agent: cost per merged change and wall-clock time, on the same tasks run both ways. The replay set from the harness post works here if you pick merged PRs that touched several areas. Sometimes the trade is worth it, like a fix that has to ship today. Decide with both numbers in front of you.
Go or no-go, before any worker starts
A no to the first question settles it.
- Can every file the task will change be assigned to exactly one lane?
- Is everything two lanes share, down to the enum values, already in the stubs commit?
- Can each lane’s done check pass without code from the other lanes?
- Does any lane need another lane’s behavior, beyond its shape? It runs after, and the pair sets the wait.
- Is each lane big enough to be worth a fresh context that has to learn the repo?
- Do you have a single-agent baseline, in tokens and time, for tasks like this?
Tasks that pass all six are usually small and repetitive: a new field that shows up in four places, or one dependency bump across several services. A refactor rarely passes, because its whole point is to change the code every lane would read.