这篇讲什么
在同一个项目里同时跑 Cursor agent、Claude Code、Codex，听起来威力很大，实际上也确实是——但前提是你已经解决了四个硬问题：workspace 归属、共享约定、分支纪律、合并顺序。这篇是真正能在一个 repo 里跑 2-3 个 agent 而不互相踩的实战手册。
这篇适合谁看
单 agent 已经吃不下你项目的重度用户：脚手架交给 Codex、refactor 给 Claude Code、行内 edit 给 Cursor。也适合两人小团队、各自用不同 agent 的场景。
什么时候适合用
单个 agent 的上下文窗口在你 codebase 上反复爆炸；想让一个 agent review 另一个 agent 写的代码；或者 feature 的不同部分天然适合不同工具（长上下文 refactor 给 Claude Code、快速脚手架给 Codex）。
开始前准备
- 选一份 repo 约定文档——
CLAUDE.md放根目录，2026 年所有主流 agent 都认；再AGENTS.md做软链指到同一份文件，这样所有工具都能找到。 - 用 git worktree，不要在同一个 checkout 里切分支。
git worktree add ../proj-refactor refactor给每个 agent 一个独立的文件系统目录——避免文件锁冲突最便宜的办法。 - 把 agent 角色写下来。“Cursor 做当前文件的行内 edit、Claude Code 做多文件 refactor、Codex 做脚手架和 migration。” 这里漂了就是混乱的起点。
- 确认所有 agent 都尊重
.gitignore、对secrets/、infra/、migrations/只读或无权限。
具体步骤
- 一个 agent 一个角色，写下来。 review / refactor / 脚手架 / 写测试。不允许 agent 跨线自由发挥。
- 一个 agent 一个 worktree。 用
git worktree add给每个 agent 一个独立目录。它们就没法同时编辑同一文件。 - 共享的
CLAUDE.md/AGENTS.md放 repo 根，软链或复制。命名、lint、禁区路径的唯一权威依据。 - 通过 PR 协调，不要通过 working tree。 每个 agent 自己开 PR；你按合理顺序 merge。不要让两个 agent 推到同一分支。
- 共享文件强制轮流。 如果
config/app.ts正在被 Cursor 改，别的 agent 在那个 PR 合掉之前都不许碰。这是写在文档里的规则，不是默契。 - 最后做一遍人工 review 的合并测试 再合到
main。各自的测试都过，合在一起照样可能崩。
一个具体的 3-agent 配置
~/proj/main # 主 worktree，只允许人改
~/proj/refactor # Claude Code，分支：refactor/auth
~/proj/scaffold # Codex，分支：scaffold/billing
~/proj/inline # Cursor，分支：feature/checkout-ui
三个 worktree 共用的 CLAUDE.md：
- Lint: 提交前 pnpm lint 必须过
- 禁区: infra/、migrations/、.env*
- 强制 conventional commits
- 开 PR；不自合人来 review、合并；agent 永远不能 git push 到 main。
真正可行的角色分工
- Claude Code： 大型 refactor、多文件上下文、跨 codebase 重命名、架构变更。强项：“读 30 个文件，再改 8 个”。
- Cursor agent： 你正在看的那个文件里的行内 edit、小 bug fix、UI 微调。强项：“我就在这儿，修一下”。
- Codex： 新模块脚手架、migration、boilerplate、依赖升级。强项：“去把那个新东西生成出来”。
- Aider / OpenAI O 系： 写测试、枚举边界。强项：“这玩意还能怎么挂”。
项目不是特别小，就别让一个 agent 把这 4 件事都干了。
建议的操作流程
分角色 -> 每个 agent 一个 worktree -> 共享 CLAUDE.md -> 同一文件一次一个 agent -> 每个 agent 开 PR -> 人按顺序 merge -> 最后合并测试一遍。预期第一周慢一点，第三周大约提速 2 倍。
FAQ
- 两个 agent 能同时改同一文件吗？: 不行，即使用了 worktree 也会撞到难解决的 merge 冲突。锁文件。
- 必须用 worktree 吗，分支不行？: worktree 错误率低得多。多个 agent 共享一个 checkout，是”莫名其妙的未提交改动”的标准来源。
- 我用
CLAUDE.md，队友用 Codex 怎么办？:AGENTS.md -> CLAUDE.md软链，两个工具都能读到同一份内容。2025 年底业界基本统一到这个约定。 - 哪个 agent 来 review 其他 agent 的 PR？: 用一个 “review agent” 角色（通常是 Claude Code 加
/review命令），但合并前必须人工签字。 - 两个 agent PR 冲突怎么办？: 手动解；不要让 agent 去解一段它本来没写的代码冲突。
- 单人开发值得这么搞吗？: 项目 2 万行以内基本不值——协调开销大于并行收益。
容易踩的坑
- 两个 agent 在同 workspace 同时跑——一小时内必入 merge 地狱。
- 没有共享约定文档——每个 agent 各自发明命名、lint、import 风格。
- 让 agent 自合 PR——你唯一的人工 checkpoint 被绕过。
- 同分支、多 agent——必有 force-push 或丢 commit。
- 角色分工太模糊（“你做 feature、你写测试”）——overlap 你发现不了，直到冲突。
- 跳过最后的合并测试——各自 CI 绿不等于合在一起跑得动。