AI AI Tools Guidebook
AI Tool Tutorials

Multi-Agent Coding Workflow

Use Cursor + Claude Code + Codex together - without conflicts.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

What this covers

Running Cursor agent mode, Claude Code, and Codex in the same project sounds powerful and often is - but only if you’ve solved the four hard problems: workspace ownership, shared conventions, branch discipline, and merge order. This guide is the actual playbook for using two-to-three coding agents in one repo without them stomping each other’s edits.

Who this is for

Power users who’ve outgrown single-agent flows and started farming out work in parallel: scaffolding in Codex, refactoring in Claude Code, inline edits in Cursor. Also useful for two-person teams where each developer uses a different agent.

When to reach for it

When a single agent’s context window keeps blowing up on your codebase, when you want one agent reviewing what another agent wrote, or when different parts of a feature legitimately want different tools (Claude Code for long-context refactors, Codex for fast scaffolds).

Before you start

  • Pick one repo convention document - CLAUDE.md at root works for every major agent in 2026; alias AGENTS.md to the same file via a symlink so all tools find it.
  • Use git worktrees, not branches in the same checkout. git worktree add ../proj-refactor refactor gives each agent its own filesystem - the cheapest way to prevent file lock fights.
  • Define agent roles in writing. “Cursor does inline edits in the open file, Claude Code does multi-file refactors, Codex does scaffolds and migrations.” Drift here is where chaos starts.
  • Make sure all agents respect your .gitignore and have read-only access (or no access) to secrets/, infra/, and migrations/.

Step by step

  1. One role per agent, written down. Review / refactor / scaffold / test-writing. Don’t let an agent freelance into another’s lane.
  2. One agent per worktree. Use git worktree add so each agent has its own dir. They can’t accidentally edit the same file at the same time.
  3. Shared CLAUDE.md / AGENTS.md at repo root, symlinked or duplicated. Single source of truth for naming, lint, do-not-touch paths.
  4. Coordinate via PRs, not via the working tree. Each agent opens a PR; you merge in the order that makes sense. Never have two agents pushing to the same branch.
  5. Lock turn-taking on shared files. If config/app.ts is being edited by Cursor, no other agent touches it until that PR merges. This is a written rule, not a vibe.
  6. Run one human-reviewed test pass at the end before merging into main. Each agent’s tests can pass individually while the combined diff breaks.

A concrete 3-agent setup

~/proj/main         # main worktree, human only
~/proj/refactor     # Claude Code, branch: refactor/auth
~/proj/scaffold     # Codex, branch: scaffold/billing
~/proj/inline       # Cursor, branch: feature/checkout-ui

CLAUDE.md (in all three):
- Lint: pnpm lint must pass before commit
- Do not touch: infra/, migrations/, .env*
- Conventional commits required
- Open PR; do not merge yourself

The human reviews and merges; agents never git push to main.

Role split that actually works

  • Claude Code: large refactors, multi-file context, codebase-wide renames, architectural changes. Strong at “read 30 files, then edit 8.”
  • Cursor agent: inline edits in the file you’re already looking at, small bug fixes, UI tweaks. Strong at “I’m here, fix this.”
  • Codex: scaffolds new modules, migrations, boilerplate, dependency upgrades. Strong at “go generate the new thing.”
  • Aider / OpenAI O-series: test writing, edge-case enumeration. Strong at “what could break this.”

Don’t have one agent do all four jobs unless your project is tiny.

role assignment -> one worktree per agent -> shared CLAUDE.md -> one agent at a time per file -> each agent opens a PR -> human merges in order -> final combined test pass. Expect this to feel slower in the first week and ~2x faster by week three.

FAQ

  • Can two agents work on the same file at the same time? - No, even with worktrees, you’ll get merge conflicts that are painful to resolve. Lock the file.
  • Do I need worktrees, or can I just use branches? - Worktrees are dramatically less error-prone. One git checkout shared between agents is how you end up with mystery uncommitted changes.
  • What if my repo has CLAUDE.md but my teammate uses Codex? - Symlink AGENTS.md -> CLAUDE.md so both tools find the same content. Tools converged on this convention in late 2025.
  • Which agent reviews PRs from the others? - Use a “review agent” role (often Claude Code with a /review slash command) but always require human sign-off before merge.
  • How do I handle merge conflicts between two agent PRs? - Resolve manually; don’t let an agent resolve a conflict in code it didn’t author originally.
  • Is this worth it for a solo developer? - If your project is under ~20k lines, probably not. The coordination overhead beats the parallelism.

Common mistakes

  • Two agents on the same workspace simultaneously - merge hell within an hour.
  • No shared conventions doc - each agent invents its own naming, lint, and import style.
  • Letting agents merge their own PRs - bypasses the only human checkpoint you have.
  • Same branch, multiple agents - guaranteed force-push or lost commits.
  • Vague role assignment (“you do features, you do tests”) - agents will overlap and you won’t notice until conflicts.
  • Skipping the final combined test pass - per-agent green CI doesn’t mean the combined diff works.

Tags: #AI coding #Tutorial

Related Articles