After this, you'll be able to describe the stale context coordination problem, implement branch-per-agent isolation with merge gates, and design a shared state file for your project.
Before you start
You'll want a working sense of Manage the Money before this lesson, since branch-per-agent isolation has real per-branch compute costs you need to budget for.
The idea
You dispatch two agents in parallel. Agent A is adding a new field to your User type. Agent B is writing a service that reads from that type. Both finish. Both pass their own tests. You merge both branches and the build breaks: Agent B is reading a field that Agent A renamed mid-run. Neither agent made a mistake. They just did not know about each other.
This is the stale context problem. Agent B started from the codebase as it existed at dispatch time. Agent A changed it. Agent B had no way to know. The fix is infrastructure, not better prompting.
Branch-per-agent isolation is the first layer. Each agent works on its own branch from main at dispatch time. When an agent finishes, its branch goes through a merge gate: a CI check that catches type errors, test failures, and interface conflicts before the branch lands in main. This contains the blast radius but does not eliminate semantic conflicts.
The second layer is a shared state file. Here is what it looks like in practice:
```json { "schema_version": "1.2.0", "updated_at": "2026-04-26T09:14:00Z", "shared_interfaces": { "User": "src/models/User.ts@sha256:a3f9", "AuthToken": "src/models/AuthToken.ts@sha256:b12c" }, "in_flight_tasks": [ { "task_id": "feat-user-avatar", "agent_id": "agent-01", "branch": "agent/feat-user-avatar", "claimed_paths": ["src/models/User.ts", "src/services/UserService.ts"], "started_at": "2026-04-26T09:10:00Z", "estimated_done": "2026-04-26T09:30:00Z", "conflict_flag": false } ], "last_known_good_commit": "c7e81f2" } ```
Agents read this file at startup. If their planned paths overlap with a claimed path, they abort and report back before making any changes. A coordinator agent (or your CI pipeline) writes the claim entries and clears them on merge.
Semantic conflicts are the hard ceiling. Two agents may make logically incompatible changes that each pass their own tests. Handling that requires either serializing conflicting tasks or investing in integration tests that catch the combined behavior. The shared state file catches the mechanical conflicts. The integration tests catch the rest.
Try it (22 min)
Watch out for
Paste this into Claude:
I want to set up branch-per-agent isolation and a shared state file for my project. Here is my current project layout: [describe your project's main source directories and the kinds of tasks you run in parallel, e.g. 'src/api/ for endpoints, src/services/ for business logic, running 3-4 agents in parallel on different features']. Help me: (1) Write the git commands to create an agent branch from main at dispatch time and how to clean it up after merge. (2) Design a shared state file schema (JSON) that tracks: in-flight tasks, claimed file paths, current shared interface versions, and a timestamp. (3) Write the instructions an agent should receive at startup to read the state file and check for path conflicts before beginning work. (4) Describe the merge gate checks that should run before any agent branch lands in main.
What good looks like:
Go deeper (25 min)
Paste this into Claude:
Design a state file schema specifically for your project. Open your current codebase and list: (1) The top 5-8 directories or modules that agents most commonly modify. (2) The 2-3 shared interfaces (types, API contracts, database schemas) that would cause semantic conflicts if two agents changed them simultaneously. (3) The claim format: what information does an agent write when it claims a path? Include: agent ID, task ID, claimed paths, start time, estimated duration. Then write a short function (or ask Claude to write it) that checks a new claim against the existing state file and returns a conflict list.
What good looks like:
When this breaks
Claude can do it for you
Say to Claude: 'Design a shared state file schema for my project. My main modules are: [list modules]. Include: claimed paths, in-flight task IDs, shared interface versions, and a conflict-check function. Then write the agent startup instruction that reads this file and aborts if its planned paths are already claimed.'
You can now
Design a shared state file with claimed paths and in-flight task IDs, wire the agent startup instruction that reads it, and demonstrate one conflict scenario the schema catches before merge.
Key takeaways
Stale context is an infrastructure problem. Branch-per-agent contains the blast radius. A shared state file prevents the semantic conflicts branch isolation cannot catch.