怎么防止多 Agent 并行开发时的代码冲突？
防止多 Agent 并行开发时的代码冲突，核心思路不是让它们“协同”得更好，而是让它们在工作时物理隔离，在完成后有序合并。根据当前主流工具（如 Cursor、AI21 Maestro）的实践经验，最有效的方案是“物理工作区隔离 + 角色分工 + 统一合并审查”。
🛠️ 方案一：物理工作区隔离（最推荐，Git Worktree 模式）
这是目前最成熟、最主流的方案。Cursor、AI21 Maestro、GitHub Copilot 等都在采用类似思路。
核心原理：不为每个 Agent 创建不同的文件夹，而是利用git worktree为同一个仓库创建多个独立的、并行的工作目录。每个 Agent 拥有完全独立的文件系统和分支，从根本上杜绝了文件冲突。
实现步骤：
为每个任务创建独立工作区：
# 在主仓库目录下执行gitworktreeadd../repo-feature-auth-bfeature/authgitworktreeadd../repo-feature-api-bfeature/apigitworktreeadd../repo-bugfix-login-bfix/login执行后，你会得到三个独立的目录，分别对应不同的分支，互不干扰。
分配任务：
让 Agent A 修改../repo-feature-auth/目录下的文件，Agent B 修改../repo-feature-api/目录。它们可以同时运行，就像操作不同的项目一样。合并与清理：
当 Agent 完成任务后，在其工作区内提交代码，然后推送到远程仓库。# 在 Agent 工作区内gitadd.gitcommit-m"feat: implement auth module"gitpush origin feature/auth最后，通过正常的 Pull Request 流程进行代码审查和合并。合并后可以删除 worktree：
gitworktree remove../repo-feature-auth
优势：
- 彻底隔离：没有文件锁竞争，不会出现“两个 Agent 改同一个文件”的情况。
- 成本极低：Worktree 共享 Git 对象数据库，几乎不占用额外磁盘空间。
- 原生支持：不依赖任何第三方工具，纯 Git 原生功能。
适用场景：绝大多数后端、前端、全栈项目。
🧩 方案二：职责与角色分工（架构层，Planner-Worker 模式）
如果多个 Agent 不可避免地要修改同一份代码（例如，一个修前端、一个修后端，但最终要合并到同一个main分支），就需要在架构上做文章。
核心原理：不再让所有 Agent 平起平坐，而是引入一个“总指挥”（Planner）角色来拆解任务、分配工作；引入“执行者”（Worker）角色只负责具体实现。
实现架构：
Planner（规划者）：
- 职责：接收用户需求，分析代码库结构，将大任务拆解成多个互不重叠的小任务（例如：“重构
user/auth.py文件”、“添加utils/logger.py”）。 - 关键：Planner 必须确保拆解出的任务修改的文件集合是不相交的。
- 职责：接收用户需求，分析代码库结构，将大任务拆解成多个互不重叠的小任务（例如：“重构
Workers（执行者）：
- 职责：每个 Worker 只领取一个任务，在其分配的独立工作区（可以是 Worktree 或临时分支）内工作。
- 关键：Worker 只对自己负责的代码块进行修改，不关心全局。
Reviewer（评审者）：
- 职责：在 Workers 完成任务后，Reviewer 负责合并所有变更，并进行集成测试，确保整体功能正常。
工具支持：
- dataplane：一个 Node.js 库，内置了“Stream”机制，可以自动管理基于分支的工作流、冲突检测和级联变基（Cascade Rebase），适合需要编程控制多 Agent 流程的场景。
- CCG-Workflow：一个开源 CLI 工具，实现了“Claude 做规划、Codex/Gemini 做执行”的分工模式，并强制外部模型只能输出建议，由主模型执行，安全性很高。
适用场景：大型重构、跨模块功能开发，或需要严格控制代码质量的场景。
⚡ 方案三：轻量级文件锁协同（Beep-Boop 信号模式）
如果你的 Agent 数量不多（例如 2-3 个），且无法使用 Worktree，可以使用基于文件的“信号量”机制。
核心原理：Agent 在修改某个目录或文件前，先“插旗”（创建一个标记文件，如boop.txt），完成后再“拔旗”（删除标记，创建beep.txt）。其他 Agent 看到“旗子”就会绕路。
实现工具：
- Beep-Boop MCP Server：这是一个基于 Model Context Protocol（MCP）的服务器，专门为此设计。Agent 可以通过 MCP 协议调用
check_status查看目录是否被占用，调用update_boop锁定目录，调用end_work释放。
优势：简单直观，不依赖 Git 高级功能。
劣势：手动管理锁容易出错（如 Agent 忘记释放锁），且在高并发下会成为瓶颈。
适用场景：小型项目、快速原型验证，或 Agent 数量很少（<5个）的场景。
📊 方案对比与选择建议
| 方案 | 核心机制 | 隔离级别 | 并发能力 | 复杂度 | 推荐场景 |
|---|---|---|---|---|---|
| Git Worktree | 物理目录隔离 | ⭐⭐⭐⭐⭐ (最高) | ⭐⭐⭐⭐⭐ (极强) | ⭐⭐ (低) | 首选，适用于绝大多数项目 |
| Planner-Worker | 角色分工 + 任务拆解 | ⭐⭐⭐⭐ (高) | ⭐⭐⭐⭐ (强) | ⭐⭐⭐⭐ (较高) | 大型项目、需要严格流程控制 |
| 文件锁 (Beep-Boop) | 目录级信号量 | ⭐⭐ (低) | ⭐⭐ (弱) | ⭐ (极低) | 小型实验、快速测试 |
⚠️ 关键注意事项
- 避免共享状态：确保每个 Agent 的环境（环境变量、配置文件、依赖包版本）都是可复现且隔离的。否则，即使代码不冲突，运行环境也会“漂移”导致问题。
- 不要把 Diff 审查当作可选项：无论采用哪种方案，最终合并前都必须有人或 Reviewer Agent 进行审查。并行不是目的，输出高质量的、可合并的代码才是。
- 从“少”开始：不要一上来就跑 10 个 Agent。先从 2-3 个开始，跑通 Worktree 流程，再逐步增加并发数。Cursor 团队的经验表明，20 个 Agent 的吞吐量可能还不如 3 个精心协调的 Agent。
总结一下：首选 Git Worktree 方案，它简单、可靠、成本低。只有当 Worktree 无法满足（例如必须实时修改同一文件）时，再考虑引入 Planner-Worker 架构或文件锁机制。