一句话总结
在一个 repo 里跑两三个编程 agent，前提是把它们在文件系统层面隔离开。2026 年的配方是：每个 agent 一个 git worktree（让它们物理上碰不到同一个文件）、根目录放一份共享的 AGENTS.md 管约定、每个 agent 写死一个角色、全程走 PR 合并且由人控制顺序。少做任何一步，一小时内你就会撞上 merge 冲突、端口冲突（EADDRINUSE），或者被悄悄覆盖。
你真正要解决的四个问题
同一个项目里跑多个 agent 听起来威力很大，确实也是 —— 但前提是你解决了四个具体问题：
- workspace 归属 —— 此刻谁有权改哪些文件。
- 共享约定 —— 命名、lint、禁区路径的唯一权威来源。
- 分支与合并纪律 —— agent 绝不能推到同一分支，更不能推到
main。 - 运行时隔离 —— 端口和数据库分开，避免并行的 dev server 互相卡死。
这篇就是把这四件事全处理掉的手册。它默认你已经能熟练用单个 agent，现在想把工作并行分出去：脚手架交给 Codex、refactor 给 Claude Code、行内 edit 给 Cursor。两人小团队、各自用不同 agent 的场景同样适用。
先说现实上限：大多数团队觉得 2 到 4 个并行 agent 还能管得住。再多，你拆任务、审输出、解合并的时间就会吃掉并行带来的收益。
第一步 —— 用 git worktree 隔离，别切分支
git worktree 会把一个分支检出到独立目录，跟同一个仓库共享历史，于是每个 agent 拿到一份私有的文件系统。两个 agent 在编辑途中根本没法锁住或覆盖同一个文件。
# 在主 checkout 里执行
git worktree add ../proj-refactor refactor/auth
git worktree add ../proj-scaffold scaffold/billing
git worktree add ../proj-inline feature/checkout-ui
git worktree list # 确认三个新目录为什么不直接在一个 checkout 里切分支？因为共享一个 working tree 正是”莫名其妙的未提交改动”和”打了一半的 diff、没人认账”的标准来源。
注意每个 worktree 要装自己的依赖。node_modules 不共享，所以每个 worktree 都要跑一次 npm ci --prefer-offline（或你的包管理器对应命令）。如果某个 agent 升了依赖，合并前要在其他 worktree 里重装，否则会撞上 package-lock.json 冲突。
第二步 —— 根目录放一份 AGENTS.md，再桥接进 Claude Code
2026 年这个约定基本定型了，但命名没完全统一，所以这个细节要弄对：
AGENTS.md是开放标准（现由 Linux Foundation 维护，6 万多个 repo 在用）。Codex、Cursor、Copilot、Gemini CLI、Aider、Windsurf、Zed 都原生读它。- Claude Code 读的是
CLAUDE.md，不是AGENTS.md—— 这在 Anthropic 2026 年中的文档里明确写了。如果一个 repo 只有AGENTS.md，Claude Code 会一条项目指令都不加载，而且不报错。
所以把 AGENTS.md 当唯一权威来源，再桥接进 Claude Code。最干净的桥接是在 CLAUDE.md 里写一行 import：
<!-- CLAUDE.md -->
@AGENTS.md
# Claude 专属的备注写在 import 下面Claude Code 会在会话开始时展开 @AGENTS.md。（在 macOS/Linux 上用 ln -s AGENTS.md CLAUDE.md 软链也行，但 import 在 Windows 上更省事，还能加 Claude 专属规则。）这和老版”先放 CLAUDE.md”的建议正好相反 —— AGENTS.md 才是其他工具早就在认的标准。
为什么这值得在意：在 agentic coding 的评测里，没有项目上下文文件的 agent 把任务做对的概率大约 30%；放上一份像样的上下文文件后，能跳到大约 90%。一份共享的 AGENTS.md 是你能上的最便宜的可靠性升级。
一份三个 agent 都得遵守的最小 AGENTS.md：
# AGENTS.md
## 构建与测试
- 安装: npm ci
- Lint（提交前必须过）: pnpm lint
- 测试: pnpm test
## 约定
- 强制 Conventional Commits
- 只用具名导出，不用默认导出
## 禁区
- infra/ migrations/ .env* secrets/
## 流程
- 开 PR。不自合。不推 main。第三步 —— 每个 agent 写死一个角色
角色一漂就是混乱的起点。把分工写下来，不允许 agent 跨线自由发挥。按各工具截至 2026 年 6 月的强项来分：
| Agent | 强在哪 | 用来干 | 别让它干 |
|---|---|---|---|
| Claude Code（Opus 4.7 / Sonnet 4.6，1M 上下文） | “读 30 个文件，改 8 个” | 大型 refactor、跨 codebase 重命名、架构变更 | 一行小修改 |
| Cursor agent（Sonnet 4.6 / GPT-5.5 / Composer 2.5） | “我就在这儿，修一下” | 行内 edit、小 bug fix、UI 微调 | 横跨多文件的大 refactor |
| Codex（GPT-5.5） | “去把那个新东西生成出来” | 脚手架、migration、boilerplate、依赖升级 | 隐蔽的跨切面逻辑 |
| Aider | ”这玩意还能怎么挂” | 写测试、枚举边界 | 从零起架构 |
支撑”refactor 默认给 Claude Code”的基准：Opus 4.7 在 SWE-bench Verified 上 87.6% 领先（Gemini 3.1 Pro 80.6%），SWE-bench Pro 上 64.3%（GPT-5.5 58.6%）。GPT-5.5 在 Terminal-Bench 2.0 上以 82.7% 领先，这也是 Codex 在命令驱动的脚手架上很强的原因之一。除非项目真的很小，否则别让一个 agent 把这四件事全包了。
第四步 —— 隔离运行时：端口和数据库
这步大多数教程会跳过，偏偏它制造的故障最难看。如果三个 agent 各自在默认端口跑 npm run dev，第二、第三个会以 EADDRINUSE 直接挂掉，后台测试还可能卡死或污染一个共用的本地数据库。
给每个 worktree 自己的端口和数据库。别软链 .env —— 复制一份，再加一个 worktree 级别的 .env.local 覆盖：
# 在 ~/proj-scaffold/.env.local 里
PORT=3002
DATABASE_URL=postgres://localhost:5433/app_scaffold一个简单约定：app 端口 3000–3009、数据库端口 5432–5441，每个 worktree 偏移一位。把它写进 setup 脚本，让每个新 agent 自动拿到下一个空闲端口。
一个具体的 3-agent 配置
~/proj/main # 主 worktree，只允许人改
~/proj/refactor # Claude Code，分支：refactor/auth， PORT=3001
~/proj/scaffold # Codex， 分支：scaffold/billing， PORT=3002
~/proj/inline # Cursor， 分支：feature/checkout-ui， PORT=3003每个 worktree 带同一份 AGENTS.md（外加一个 import 它的 CLAUDE.md）。人来 review、合并；agent 永远不能 git push 到 main。Cursor 3.2（2026 年 4 月 24 日发布）已经能从它的 Agents Window 把 worktree 这步自动化 —— 当你把一个 agent 移进 worktree 时，它会替你建好隔离的 checkout，并提供一键把完成的 worktree 提到前台供 review 的按钮。
第五步 —— 用 PR 协调，锁住共享文件
- 一个 agent 一个 PR。 每个 agent 自己开 PR；你按合理顺序 merge。绝不让两个 agent 推到同一分支 —— 那必然导致 force-push 或丢 commit。
- 共享文件强制轮流。 如果
config/app.ts正在 Cursor 的 worktree 里被改，别的 agent 在那个 PR 合掉之前都不许碰。这是写进文档的规则，不是默契。 - 跨 agent 的冲突自己解。 别让某个 agent 去解一段它本来没写的代码冲突 —— 它没有上下文，只会瞎猜。
- 合到
main前做一遍人工 review 的合并测试。 各自的 CI 都绿，不代表合在一起的 diff 还跑得动。
推荐的端到端流程
分角色 → 每个 agent 一个 worktree → 共享 AGENTS.md（+ CLAUDE.md import）→ 隔离端口/DB → 同一文件一次只给一个 agent → 每个 agent 开 PR → 人按顺序 merge → 最后合并测试一遍。
预期第一周会觉得更慢，到第三周 worktree 加 PR 的节奏成肌肉记忆后，大约能提速 2 倍。
容易踩的坑
- 两个 agent 挤一个 workspace —— 一小时内必入 merge 地狱。
- 没有共享约定文档 —— 每个 agent 各自发明命名、lint、import 风格。
- 只有
AGENTS.md、没给CLAUDE.md桥接 —— Claude Code 会零项目上下文地静默运行。 - 让 agent 自合 PR —— 绕过你唯一的人工 checkpoint。
- 同分支、多 agent —— 必有 force-push 或丢 commit。
- 共用端口/数据库 ——
EADDRINUSE崩溃加测试被污染。 - 跳过最后的合并测试 —— 各自 CI 绿不等于合在一起跑得动。
FAQ
两个 agent 能同时改同一文件吗？ 不行。就算用了独立 worktree，对同一文件的并发编辑也会产生很难手解的 merge 冲突。在那个 PR 合掉前，把文件锁给一个 agent。
真的需要 worktree 吗，分支不行？ worktree 错误率低得多。多个 agent 共享一个 checkout，正是”莫名其妙未提交改动”的经典来源。截至 2026 年，Cursor 3.2 和 Claude Code 都直接支持 worktree。
我的 repo 有 AGENTS.md，但队友用 Claude Code 怎么办？
加一行内容为 @AGENTS.md 的 CLAUDE.md（或把 CLAUDE.md 软链到 AGENTS.md）。Claude Code 不原生读 AGENTS.md，没有这个桥接它就拿不到任何项目指令。
该让哪个 agent 来 review 其他 agent 的 PR？
可以设一个专门的”review agent”角色（通常是 Claude Code 加 /review 命令）做第一遍，但合并前必须人工签字。
并行 agent 的现实上限是多少？ 对多数团队是 2 到 4 个。Cursor 技术上能在一个问题上跑到 8 个 agent 并自动选最优，但超过一小撮之后，协调和 review 的开销涨得很快。
单人开发值得这么搞吗？ 项目 2 万行以内一般不值 —— 协调开销大于并行收益。它在更大的 codebase 上才划算，前提是工作能沿 feature 或领域边界真正拆开。