How to Manage Multiple Coding Agents in One Repository
A tool-agnostic operating model for using Claude Code, Codex, Cursor, Copilot, and other coding agents in one repository without duplicated rules, conflicting edits, or unverifiable handoffs.
How to Manage Multiple Coding Agents in One Repository
Managing multiple coding agents in one repository means giving every tool the same durable operating contract while assigning each active task a separate scope, owner, validation path, and evidence handoff.
Claude Code, Codex, Cursor, Copilot, and other agents can work in the same codebase. The hard part is not making each tool read more context. It is preventing five copies of the same rule, two agents changing the same contract, and one integration branch where nobody can explain what is actually proven.
The reliable model has three layers:
- Shared repository truth — architecture, boundaries, source-of-truth ownership, validation, and accepted decisions.
- Tool-specific adapters — only the commands or behavior unique to Claude Code, Codex, Cursor, or another interface.
- Task-local coordination — current outcome, write scope, dependencies, integration order, and evidence.
This guide focuses on operating several coding-agent tools around one repository. If you first need to compare the file formats themselves, read AGENTS.md vs CLAUDE.md vs Cursor Rules vs Copilot instructions.
The real failure is duplicated authority
Teams often introduce a second agent by copying the first agent’s instructions:
AGENTS.md
CLAUDE.md
.cursor/rules/project.mdc
.github/copilot-instructions.mdAt first, all four files say approximately the same thing. Then the test command changes. A generated client moves. One file gets updated, two keep the old command, and another adds a contradictory exception.
Now the repository has no instruction problem; it has an authority problem. The answer depends on which tool opened the task.
A multi-tool repository should instead answer one question for every important fact:
Where does this fact become true, and which file owns it?
Examples:
| Fact | Canonical owner | Agent files should do |
|---|---|---|
| Package boundaries | docs/architecture.md | Link to the map |
| Generated-file ownership | generator docs or source-of-truth map | State the boundary and link |
| Validation commands | scripts/validate-* plus a validation matrix | Invoke the commands |
| Approval gates | root AGENTS.md or governance policy | Repeat only a short non-negotiable summary if required |
| Accepted architectural choice | docs/decisions/ | Link from the affected subsystem instructions |
| Tool-specific model or command behavior | tool-specific config | Own it locally |
| Current task scope | task packet or work ledger | Read it; do not promote it to permanent instructions |
The repository carries facts. Tool files adapt those facts to an interface. Task packets carry temporary intent.
A precedence model that does not depend on the tool
Do not assume every agent reads instruction files in the same order. Products change, wrappers add context, and nested rules may behave differently.
Define your own semantic precedence instead:
1. Safety and authority policy
2. Current accepted task packet
3. Closest scoped repository instruction
4. Root repository router
5. Linked architecture, decision, and validation sources
6. Tool-specific adapter
7. User preference that does not contradict 1–6The tool-specific adapter is deliberately low in the stack. It may explain how to invoke a capability, but it should not redefine project architecture or weaken an approval boundary.
A root AGENTS.md can make the contract explicit:
## Instruction authority
- This file owns cross-tool repository workflow and safety boundaries.
- The current task packet owns outcome, scope, and acceptance criteria.
- Scoped AGENTS.md files may narrow rules for their directories.
- Architecture and decision records own technical facts they describe.
- Tool-specific files may add interface behavior but must not override these sources.
- When sources disagree, stop and report the conflict instead of guessing.That final rule matters. Silent conflict resolution is how instruction drift turns into a bad change.
One canonical core, thin tool adapters
A practical multi-tool layout looks like this:
AGENTS.md # shared router and authority
packages/api/AGENTS.md # scoped API rules
packages/web/AGENTS.md # scoped frontend rules
docs/architecture.md # system and ownership map
docs/decisions/ # accepted non-obvious choices
docs/tasks/active/ # current task packets and state
scripts/validate-api # executable proof
scripts/validate-web
CLAUDE.md # Claude-specific delta only
.cursor/rules/tooling.mdc # Cursor-specific delta only
.github/copilot-instructions.md # Copilot-specific delta onlyThe adapters should be small enough to audit in one screen.
Example CLAUDE.md:
# Claude Code adapter
Follow `AGENTS.md` and the nearest scoped `AGENTS.md` as the repository contract.
Claude-specific behavior:
- use the repository's existing plan file for work spanning multiple subsystems
- use the documented browser command for UI verification
- do not duplicate architecture or validation rules hereExample Cursor rule:
---
description: Cursor-specific interaction defaults
alwaysApply: true
---
Follow AGENTS.md for repository-wide rules and validation.
Use the existing component generator instead of creating boilerplate manually.
Do not restate shared project conventions in this file.A thin adapter answers, “What does this tool need that the shared contract cannot express?” If the answer is nothing, you may not need the file.
Separate durable context from live coordination
Shared instructions do not prevent concurrent conflicts. Two agents can obey the same rules and still edit the same migration, rename the same interface, or produce branches that cannot be integrated safely.
Durable context and live coordination solve different problems:
| Layer | Lifetime | Examples | Question answered |
|---|---|---|---|
| Repository contract | Months | AGENTS.md, architecture, validation | How does work happen here? |
| Decision memory | Months or years | ADRs, compatibility records | Why must this constraint remain? |
| Task envelope | Hours or days | outcome, scope, acceptance, proof | What must this task accomplish? |
| Work ledger | Minutes or hours | claimed files, dependencies, state | Who is changing what now? |
| Evidence handoff | Integration lifetime | commands, results, residual risks | What is actually proven? |
Do not put “Agent A owns src/auth.ts today” in AGENTS.md. Do not put “never edit generated clients” only in a temporary task note. Store each fact at its natural lifetime.
The multi-agent repository loop
The agents do not coordinate by reading each other’s chat transcripts. They coordinate through repository-visible scopes, state, commits, and evidence.
Write task packets that make overlap visible
A multi-agent task packet needs more than a goal. It should identify the write surface and integration contract before work begins.
Before writing individual packets, use Task Decomposition for Multiple Coding Agents to stabilize shared contracts and turn the requested outcome into a producer-consumer graph. The graph determines which packets are truly ready and which must remain blocked.
# Task A — add avatar upload API
## Outcome
The API accepts JPEG or PNG avatars up to 2 MB.
## Write scope
- `packages/api/src/avatar/**`
- `packages/api/tests/avatar/**`
## Read-only dependencies
- `packages/contracts/avatar.ts`
- `docs/decisions/0017-media-storage.md`
## Do not change
- generated clients
- web UI
- authentication middleware
## Produces for downstream work
- final request/response contract
- error codes
- fixture examples
## Validation
- `scripts/validate-api avatar`
## Handoff
Report changed paths, contract delta, command output, and residual risks.Task B can depend on Task A’s contract. Task C can depend on Task B’s generated client. That creates an integration order:
A: API contract
-> B: regenerate client
-> C: update UI consumer
-> Integrator: combined validationIf all three agents start from an imagined future contract, parallelism creates rework. Parallel execution is useful only where dependencies permit it.
Use branches or worktrees as conflict boundaries
Concurrent writing should not happen in one mutable checkout. Give every writer an isolated branch or worktree:
worktrees/task-avatar-api branch agent/avatar-api
worktrees/task-avatar-client branch agent/avatar-client
worktrees/task-avatar-ui branch agent/avatar-uiIsolation does not eliminate semantic conflicts, but it makes them observable. Each branch has a stable diff, test result, and handoff.
Define one integrator before work begins. The integrator owns:
- dependency and merge order
- resolution of overlapping changes
- combined validation after integration
- rejection of stale or unsupported assumptions
- the final evidence handoff
“Everyone can merge their own branch” is not parallelism. It is distributed integration risk.
Keep a repository-visible work ledger
For two or three tasks, a small Markdown ledger is enough:
| Task | Owner/tool | Write scope | Depends on | State | Evidence |
|---|---|---|---|---|---|
| avatar-api | Claude Code | packages/api/src/avatar/** | — | verifying | task packet |
| avatar-client | Codex | generated/client/** | avatar-api contract | blocked | — |
| avatar-ui | Cursor | packages/web/avatar/** | generated client | queued | — |The ledger should record coordination state, not duplicate task details. Link to task packets and commits.
A state model can remain simple:
queued -> claimed -> working -> verifying -> ready -> integrated
\-> blocked
\-> abandonedRequire a reason and next dependency for blocked. Require evidence for ready. This prevents “done” from meaning “the agent stopped typing.”
Define validation at worker and integration levels
One agent’s focused tests do not prove the combined candidate.
Use two levels:
Worker proof
Each agent runs the narrowest checks that cover its claim:
| Worker change | Required proof |
|---|---|
| API contract | focused contract and service tests |
| Generated client | regeneration produces a clean diff; client compile passes |
| UI consumer | component tests and typecheck |
| Documentation | build, link, and command smoke checks |
Integration proof
The integrator runs checks that cross task boundaries:
- API contract against the regenerated client
- frontend build against the integrated types
- end-to-end or smoke flow for the user-visible outcome
- repository-wide static checks affected by shared interfaces
- clean working tree after generators and formatters
This is the validation contract pattern: each completion claim maps to executable evidence, and the proof gets broader as changes combine.
Standardize the evidence handoff
Tool-generated prose varies. The handoff format should not.
## Outcome
What behavior now works?
## Scope
Which task packet and write boundary were used?
## Changed
Paths and contract changes, not a file-by-file narration.
## Evidence
- command — result
- command — result
## Assumptions
What upstream or downstream state did this work rely on?
## Not run
Which relevant checks were omitted, and why?
## Residual risk
What should the integrator or reviewer inspect?
## Commit
Stable commit or patch identifier.The handoff is an API between workers and integrator. A Claude Code handoff and a Codex handoff should be equally reviewable.
Detect drift mechanically
Instruction consistency should not depend only on quarterly memory.
A lightweight audit can check:
- every tool adapter links to root
AGENTS.md - no adapter contains canonical validation commands that belong elsewhere
- paths referenced by instructions exist
- required validation scripts are executable
- no two instruction files declare different owners for the same generated path
- task packets include outcome, scope, acceptance, validation, and handoff sections
Not every semantic conflict is machine-detectable. The goal is to catch cheap drift early and leave architectural judgment to review.
Useful maintenance triggers include:
- a command or package layout changes
- a source-of-truth owner moves
- a new generated artifact is introduced
- an approval boundary changes
- a tool adds or removes instruction-file support
- the same correction appears in two sessions
When one of these happens, update the canonical owner first. Then inspect adapters only for affected links or tool-specific behavior.
Common anti-patterns
One giant universal instruction file
A 1,000-line root file gives every tool every rule for every package. Discovery becomes reading, local relevance disappears, and conflicts hide in volume. Use a root router plus scoped instructions and linked sources.
A complete instruction copy per tool
This feels explicit but creates four maintenance surfaces. Shared facts belong once. Adapters should remain deltas.
Letting agents self-assign overlapping scopes
Agents optimize the task they can see. They do not automatically protect an integration plan that was never written. Assign write boundaries and dependencies before execution.
Treating branches as the coordination system
Branches isolate diffs. They do not communicate outcome, ownership, dependency, or proof. Pair branches with task packets and a work ledger.
Merging in completion order
The first finished branch may depend on a contract that has not stabilized. Integrate in dependency order, not notification order.
Asking every worker to run everything
Full-suite validation on every small branch wastes time and can still miss cross-branch contracts. Use focused worker proof and broader integration proof.
Adding orchestration before repository reliability
A queue can make bad tasks run faster. Multiple agents amplify unclear boundaries, weak validation, and stale context. Prove one representative task in a clean single-agent session before multiplying execution.
A safe adoption sequence
Step 1: Establish the shared contract
Start with root routing, explicit authority, source-of-truth links, and validation commands. The AGENTS.md template provides a practical base.
Step 2: Make existing adapters thin
Compare CLAUDE.md, Cursor rules, Copilot instructions, and other tool files. Move shared facts to canonical repository sources. Leave links and true tool-specific deltas.
Step 3: Introduce a task envelope
Choose one task with a clear outcome and write boundary. Record dependencies, forbidden overlap, acceptance criteria, and proof.
Step 4: Add a second agent on a non-overlapping task
Use a separate worktree. Make the dependency and integration order explicit. Do not begin with two agents editing the same subsystem.
Step 5: Standardize handoffs and integration proof
Require the same evidence format from both tools. Run the combined candidate through the repository’s validation contract.
Step 6: Repair the repository from observed failures
Record the first wrong decision. Was the task ambiguous, the source-of-truth map missing, the adapter stale, the ownership boundary unclear, or the validation incomplete? Repair the narrowest durable controller and rerun in a clean session.
For a broader migration sequence, see How to Migrate an Existing Repository to a Coding-Agent Harness.
Multi-agent repository readiness checklist
Before running several coding-agent tools in parallel:
- root instructions declare shared authority and conflict behavior
- tool-specific files contain deltas, not copied project rules
- architecture and generated-file ownership have canonical sources
- each active task has a bounded write scope
- dependencies and integration order are explicit
- concurrent writers use separate branches or worktrees
- one integrator owns overlap and combined validation
- worker checks map to local claims
- integration checks cover cross-task contracts
- every ready branch has an evidence handoff
- repeated corrections become repository repairs
- a fresh agent can find the right controller without a corrective prompt
A repository that cannot satisfy this checklist is not ready for more agents. Add coordination only after the operating contract is discoverable and testable.
The repository is the coordination surface
The durable unit of multi-agent work is not a chat, model, or vendor-specific config file. It is a repository-visible contract connected to bounded tasks and executable proof.
Use one canonical core. Keep tool adapters thin. Separate temporary ownership from permanent context. Integrate in dependency order. Require every tool to hand back evidence in the same format.
That design lets teams change models and interfaces without rebuilding the operating system around the codebase. It also lets a failure improve the next session: the correction moves into the repository layer that should have controlled the decision in the first place.
repository-harness provides a starting structure for shared AGENTS.md routing, bounded work, validation, and evidence-based handoffs across Claude Code, Codex, Cursor, and other coding agents.
Related pages
- How to Integrate Changes from Multiple Coding Agents Safely
- How to Resolve Merge Conflicts Between Coding Agents
- Git Worktrees for Multiple Coding Agents
- Coding-Agent Handoff Template
- AGENTS.md vs CLAUDE.md vs Cursor Rules vs Copilot Instructions
- How to Prepare Your Repository for Claude Code
- How to Prepare Your Repository for Codex
- Repository Harness Patterns
- Coding-Agent Failure Modes
- Context Engineering for Coding Agents
- How to Audit a Repository for Agent-Readiness
- repository-harness on GitHub
FAQ
Can Claude Code, Codex, Cursor, and Copilot use the same repository?
Yes. Keep durable repository facts, boundaries, and validation commands in one canonical cross-tool layer such as AGENTS.md and linked project documentation. Use tool-specific files only for capabilities or interface behavior unique to that tool. Coordinate concurrent work through explicit scopes, ownership, integration order, and evidence-based handoffs.
Which instruction file should be the source of truth for multiple coding agents?
Use root AGENTS.md as the shared routing and operating contract when your tools support it. Put detailed architecture, decisions, and validation contracts in linked repository documents and scripts. CLAUDE.md, Cursor rules, Copilot instructions, and similar files should contain only tool-specific deltas rather than copies of the shared rules.
How do I prevent instruction drift across coding-agent tools?
Declare one owner for each fact, make tool-specific files link to canonical sources, prohibit duplicated shared rules, and run a small consistency check in CI. Review instruction files when commands, architecture, generated paths, safety boundaries, or supported tools change.
How do I stop two coding agents from editing the same files?
Give each task an explicit file or subsystem ownership boundary, record active work in a shared task ledger, and define an integration order before execution. Use separate branches or worktrees for concurrent writers. Overlap should be planned and owned by one integrator, not discovered after both agents finish.
Should every coding agent run the full test suite?
No. Each worker should run focused checks that cover its changed contract, while the integrator runs the combined validation required for the merged candidate. The repository should map change categories to focused checks, broader checks, and any manual or runtime evidence.
Do multiple coding agents require an orchestration platform?
No. Start with repository-native coordination: canonical instructions, bounded task packets, separate worktrees, a shared task ledger, validation contracts, and evidence handoffs. Add orchestration only when the repository already supports reliable single-agent work and coordination overhead has become the bottleneck.
What is the safest way to introduce a second coding-agent tool?
Run the new tool on one representative low-risk task using the existing shared repository contract. Record the first wrong decision, add only the smallest tool-specific delta required, verify the result in a clean session, and compare evidence quality before expanding its scope.