668K Line Codebase Multi-Agent Orchestration - Solving File Conflicts

Put three AI agents on a 668K-line codebase and within minutes you will see the first file conflict. Agent A edits a shared utility file while Agent B is reading it. Agent C runs a build and gets compilation errors from Agent A's half-finished changes. Everyone is stepping on everyone.

This is the core problem of multi-agent development at scale: file-level race conditions.

Directory Ownership

The simplest coordination model is directory ownership. Each agent gets exclusive write access to specific directories:

• Agent 1 owns src/auth/ and src/api/
• Agent 2 owns src/ui/ and src/components/
• Agent 3 owns src/workers/ and scripts/

No agent writes to another agent's directories. If Agent 2 needs a change in src/api/, it requests it from Agent 1 through a coordination mechanism - a shared task queue, a file-based message, or a central orchestrator.

This eliminates most conflicts but requires upfront planning about task decomposition.

File-Level Locking

When directory ownership is too coarse, use file-level locks. Before editing a file, an agent acquires a lock (a .lock file or an entry in a shared lock registry). Other agents skip that file or wait.

The key rules:

• Lock timeout - No lock should last more than 5 minutes. If an agent crashes mid-edit, stale locks should not block everyone.
• Lock granularity - Lock individual files, not entire directories.
• Read vs write locks - Multiple agents can read simultaneously. Only writes need exclusive access.

Git Worktrees

For larger changes, give each agent its own git worktree. They work on separate branches in isolated directory trees. No file conflicts are possible because they are literally editing different copies of the codebase.

The merge step happens after each agent finishes its task. Merge conflicts still happen, but they are handled in a controlled way rather than as live file corruption.

Build Coordination

The sneakiest conflict is the shared build. If all agents trigger builds from the same working directory, build artifacts from one agent's changes corrupt another agent's test results. Use separate build output directories or stagger builds with a build queue.

At scale, agent coordination is more important than agent capability.

Fazm is an open source macOS AI agent. Open source on GitHub.

More on This Topic

• Git Worktree Isolation for Multi-Agent Development
• Managing Parallel Claude Agents - Tracking and Coordination
• Multi-Codebase Claude Code Workflow