你让 Claude Code 干「修 billing bug」，让 Codex 干「重构 billing 结构」——同时、同分支。两个都动了 src/billing.ts。现在 git 报 merge 冲突、两个 agent 都不清楚谁的改动是”对”的、测试套件挂了，因为两 agent 的测试假设的是不同的文件状态。
并行 agent 要 scope 分隔。没有的话它们读同文件、做不同决定、产生冲突——而两个 agent 都不该 resolve——agent 调和 merge 你会拿到两边的最差版本。修法：提前分派不相交的文件路径、用 git worktree 隔离 working tree、冲突当刻意的人为步骤解决。
常见原因
按命中率从高到低：
1. 并行跑前没分 scope
两个 agent 在同分支开干、task scope 重叠。各自读共享文件的原状、按自己解读改、最后 merge 时才发现重叠。
如何判断：两个近期 commit 或在跑分支都动同文件——重叠是结构性的，不是运气。
2. Task 看着独立其实有隐性耦合
「修 billing bug」和「重构 billing 结构」听着不相交——其实都要 billing.ts。独立是名义上的。
如何判断：grep -l "billing" src/**/*.ts 显示很多共享文件——同概念的 task 通常重叠。
3. 两 agent 共享一个 working tree
同 repo、同分支、两个终端 session——第二个 agent 读到第一个 agent 中途状态、迷惑、覆盖。
如何判断：一个终端的 edit 在另一个终端写时出现/消失——文件 mtime 交错。
4. 后台长跑 agent + 前台 edit
你设了 Claude Code 干长 task，然后开始手动 edit（或开另一个 agent）。后台 agent 最终写入和你新 edit 撞。
如何判断：之前 stall 或长跑 agent 在你做了别的之后完事——它的输出覆盖了你的新工作。
5. 一个 agent 靠”猜”resolve 了冲突
真冲突后你让其中一个 agent 修——它挑了一个方向，另一个 agent 的 intent 丢了——resolution 看着干净但另一个 task 的逻辑没了。
如何判断：git log 显示 agent 做的 “resolve conflict” commit——合并后文件不代表任意一支的完整 intent。
6. 共享 CLAUDE.md / 配置造成假阳性冲突
两 agent 都为不同原因更新了 CLAUDE.md 或 package.json——不同行但 git 自动 merge 不了，因为靠太近。
如何判断：冲突在配置 / 文档文件里、不是代码——每个 agent 的添加都合理、只是物理上撞了。
最短修复路径
按收益从高到低。Step 1 止血，Step 2 防再发。
Step 1：立刻停两个 agent
停 Claude Code 和 Codex（或哪两个）。
merge resolve 之前**不要**重启任一个。任一 agent 继续跑都会加重冲突。
Step 2：人为 resolve 冲突
# 看冲突有哪些
git status
git diff --name-only --diff-filter=U # 只冲突文件
# 每个冲突文件打开手动挑
# **不要**让 agent merge——agent 在这里猜很危险每个冲突决定：
- 一个方向明显对——留它、弃另一个
- 两个都要——小心地手动合
- 拿不准——整文件回退、重 plan
完成：
git add <resolved-files>
git commit -m "resolve conflict between feature-X and feature-Y"Step 3：下次并行先 plan 不相交 scope
Agent A 只动：src/billing/
Agent B 只动：src/auth/
任一 agent 需要动 scope 外：
- 停
- 等另一 agent 完事
- 再顺序做不相交文件路径 = 不可能冲突——开始前 plan。
Step 4：用 git worktree 隔离并行工作
# 主项目给一个 agent
cd ~/projects/myapp
# 另一个 agent 独立 worktree
git worktree add ../myapp-agent2 feature/auth
# 每个 agent 在自己的 working tree + 分支上每个 worktree 有独立磁盘文件——两 agent 同时写不会撞。Merge 作为刻意步骤：
git checkout main
git merge feature/billing
git merge feature/auth
# 剩余冲突手动 resolveStep 5：永远不让 agent resolve 冲突
再厉害的 agent 挑一个方向时也丢另一边的 intent——agent 看代码不看为什么写——resolve 需要理解两边 intent，人能、agent 不能。
**不要** prompt 任一 agent「resolve 这个 merge conflict」。
改成：手动 resolve，再用现在干净状态重 prompt 各 agent。Step 6：共享配置文件人工协调
CLAUDE.md、package.json、.eslintrc——多 agent 可能想动的文件。两种办法：
- 禁 agent 改它们（「只人改 CLAUDE.md」）
- 或时间协调——一次一个 agent 改
# CLAUDE.md
## Agent 不许并行改的文件
- 本文件（CLAUDE.md）
- package.json（engines、scripts）
- .eslintrc、tsconfig.json
- migrations/
一时间最多一个 agent 动这些。预防建议
- 并行前 plan 不相交文件 scope——重叠 = 注定冲突
- 任何并行 agent + 手动编辑都走 git worktree——独立 working tree 不会撞
- 禁 agent resolve merge 冲突——merge 是刻意的人为步骤
- 共享配置文件（CLAUDE.md、package.json）一次一个写者
- 顺序往往比并行安全——scope 真不重叠才并行
- task 看着独立时先 grep 共享文件验证——名字会骗人
相关阅读
标签: #排查 #Claude Code #排查 #误改