掘金热榜《一个项目五个 AI 同时干活,Claude Code 怎么让它们不互相打架》讨论了 Agent 并行开发中的目录隔离问题:五个 Claude Code 会话即使同时运行,只要共用同一个仓库根目录,就会共享工作文件、索引、分支切换和未提交状态。
并行任务应遵循“一项任务、一个分支、一个 worktree”。发现多个 Agent 共用目录时,先暂停任务并盘点改动,再为每个任务建立独立工作区;如果已经发生合并冲突,则先根据 git status 判断当前处于 merge、rebase 还是 cherry-pick,再决定解决、回滚还是继续。git worktree 只能隔离工作目录,不能消除最终合并时的代码冲突。
多个 Agent 是不是正在共用同一个工作目录?
不要采信 Agent 自述的“当前分支”或“已经隔离”,直接在实际终端执行:
pwd
git rev-parse --show-toplevel
git worktree list
git -C "/path/to/worktree" status --short
git rev-parse --show-toplevel 返回的是当前 Git 工作区根目录。多个终端如果得到相同路径,说明它们正在读写同一套文件、索引和未提交改动。
还可以检查两个路径是否属于同一个仓库:
git rev-parse --git-common-dir
git rev-parse --git-dir
同一个仓库的不同 worktree 会共享部分 Git 数据,因此 git-common-dir 相同是正常的;判断文件是否隔离,要看 --show-toplevel 和 git worktree list 中的实际路径。
如果多个 Agent 共用同一目录,不要直接执行 git reset、git clean、批量 stash 或删除文件。先记录每个 Agent 的任务、分支和改动,否则很难判断某段代码属于谁。git stash 也不是可靠的隔离边界,因为多个 worktree 共享同一个仓库的 stash 列表;一个 Agent 执行 stash pop,可能取走另一个 Agent 的记录。
哪些改动不应该交给多个 Agent 同时处理?
worktree 隔离的是目录,不会自动判断两个任务是否修改了同一条业务链路。开始并行前,应先建立“任务—分支—目录—允许修改路径”的对应关系:
| 任务对象 | 并行策略 | 原因 |
|---|---|---|
| 不同模块、没有共同依赖的文件 | 可以并行 | 合并时通常改动较小 |
| 同一个文件或同一组接口 | 串行,或只允许一个负责人 | 即使目录分开,最终仍可能发生内容冲突 |
| 依赖清单和锁文件 | 源码合并后统一生成 | 两个分支生成的锁文件可能对应不同依赖树 |
| 自动生成代码 | 由唯一负责人重新生成 | 直接合并生成物容易覆盖或产生漂移 |
| 数据库 schema 与迁移 | 严格串行 | 还涉及执行顺序、兼容窗口和共享数据库 |
| 同一个开发端口、测试库或外部服务 | 串行 | worktree 隔离不了进程和外部资源 |
两个任务即使没有修改完全相同的文件,也可能修改同一个接口的生产者和消费者。例如一个任务调整请求结构,另一个任务仍按旧结构调用它。这种情况不会产生 Git 冲突标记,却属于语义冲突。使用独立 worktree 时,两个任务修改同一文件,最终合并仍然会冲突。
git worktree add 怎么为每个任务创建独立目录?
先更新并确认基线,再为每个任务创建名称唯一的分支和目录:
git fetch origin
git worktree add ../repo-feature-a -b feature/task-a origin/main
git worktree add ../repo-feature-b -b feature/task-b origin/main
git worktree list
这里的 origin/main 只是示例,实际应替换成项目使用的远程仓库和基线分支。worktree 拥有各自的工作文件和索引,但共享 Git 对象数据;因此可以同时运行多个 Claude Code,而不必不断切换主目录里的分支。
如果目标分支已经存在,不要再次使用 -b,可以改为:
git worktree add ../repo-feature-a feature/task-a
同一个分支通常不能同时被两个 worktree 检出,所以分支名和目录名都要保持唯一。如果命令提示分支已被使用,应先通过 git worktree list 查清它绑定了哪个目录,不要为了绕过错误而删除现有 worktree。
主工作区里的未提交改动不会自动进入新 worktree。常见的安全做法有三种:把确认过的改动提交到专用 WIP 分支;导出补丁;或者单独复制未跟踪文件。补丁必须写到 worktree 之外:
git status --short
git diff HEAD --binary > ../repo-main-wip.patch
git ls-files --others --exclude-standard
补丁不包含未跟踪文件,列表中的文件需要逐个确认并复制。若基线一致,应用前先检查补丁能否干净应用:
git -C ../repo-feature-a apply --check /absolute/path/to/repo-main-wip.patch
git -C ../repo-feature-a apply /absolute/path/to/repo-main-wip.patch
.env 等被 Git 忽略的文件不会出现在普通补丁中,也不会因为创建 worktree 自动出现。应在每个目录中单独配置或安全复制,注意不要把凭据提交进仓库。依赖目录同样需要分别安装,因为 node_modules、虚拟环境等通常也是各目录独立的状态。
claude --worktree 或桌面 Agent 视图会自动隔离任务吗?
先检查当前安装版本实际提供的参数:
claude --version
claude --help
只有帮助信息明确列出时,再使用相应入口:
claude --worktree
部分教程列出了 claude --worktree 和 -w,但这些选项属于版本相关行为,不能根据文章直接推断当前版本一定支持。 一篇针对 Claude Code v2.1.139 的解读称,后台任务会自动进入 .claude/worktrees/;这同样应当作为该版本的观察结果,而不是所有版本的通用保证。
手工建立 worktree 后,直接进入对应目录启动:
cd ../repo-feature-a
claude
启动后仍要立即核对:
pwd
git rev-parse --show-toplevel
git branch --show-current
git worktree list
自动入口、手工创建的 worktree 和桌面 Agent 视图不要未经检查就混用,否则可能出现“目录已经隔离,但 Agent 不知道”或“又额外创建了一个 worktree”的情况。
开发过程中怎么知道每个 Agent 改了什么?
在各目录中定期检查状态、差异和提交边界:
git -C ../repo-feature-a status --short
git -C ../repo-feature-a diff --stat
git -C ../repo-feature-a diff --check
git -C ../repo-feature-a log --oneline --decorate -n 5
git -C ../repo-feature-a branch --show-current
status --short 能看到已暂存、未暂存和未跟踪文件;diff --stat 用来判断改动范围;diff --check 可以发现空白错误以及残留的冲突标记;log 则用于确认 Agent 是否把其他任务的提交带进了当前分支。
提交时只暂存本任务负责的路径:
git -C ../repo-feature-a add -- path/to/owned/file
git -C ../repo-feature-a diff --cached --stat
git -C ../repo-feature-a commit -m "feat: implement task-a"
不要让 Agent 在已经分配好的 worktree 中随意切换到另一个任务分支。目录虽然分开了,分支和提交边界仍然可能串线。
为什么 worktree 已经分开,合并时还是冲突?
因为 worktree 解决的是“开发期间互相覆盖文件”,并没有解决“多个分支最终要变成同一份代码”。不同 worktree 最终仍要通过 merge、rebase 或 cherry-pick 汇合。
| 冲突来源 | 可能表现 | 处理重点 |
|---|---|---|
| 修改同一文件的同一区域 | 内容冲突 | 理解双方意图后手工合并 |
| 两个分支新增同名文件 | add/add 冲突 | 决定保留哪个实现,或重新命名 |
| 一个分支删除文件,另一个继续修改 | modify/delete 冲突 | 明确文件最终是否仍应存在 |
| 一个分支重命名,另一个修改旧路径 | rename/delete 等冲突 | 同时确认旧路径和新路径的最终状态 |
| 同时修改依赖清单或锁文件 | 内容冲突或依赖树不一致 | 合并源码后统一重新生成 |
| 同时修改生成代码 | 文本冲突或生成结果漂移 | 以源文件为准重新生成 |
| 同时新增数据库迁移 | 文件冲突、编号冲突或执行顺序冲突 | 串行设计并验证迁移顺序 |
| 接口与调用方分别修改 | Git 可能完全不报冲突 | 做语义审查和集成测试 |
| 分支基线过旧 | 冲突范围异常扩大 | 先更新基线再重新集成 |
基线过旧时,可以先查看当前分支与远程基线的分叉:
git merge-base HEAD origin/main
git log --oneline --left-right HEAD...origin/main
问题往往不是 worktree 失效,而是两个任务在不同的代码基础上各自前进。越晚更新基线,最终需要人工辨认的差异越多。
Git 报告未合并文件后,先看哪些信息?
先看仓库状态,再定位未合并路径:
git status
git diff --name-only --diff-filter=U
git ls-files -u
git diff
不要一看到冲突标记就全部删除。git ls-files -u 会显示冲突文件的暂存阶段:
git show :1:path/to/file
git show :2:path/to/file
git show :3:path/to/file
阶段 1 是共同基线,阶段 2 是当前一侧,阶段 3 是待合并的一侧。普通 merge 中,“当前一侧”通常是当前分支,“待合并的一侧”是正在合入的分支;但在 rebase 和 cherry-pick 中,ours 与 theirs 的具体含义会变化,所以必须结合 git status 判断当前操作,不能把一次 merge 的结论直接套用到 rebase。
git merge --abort、git rebase --abort 和 git cherry-pick --abort 该用哪个?
只执行与当前状态对应的一组命令:
| 当前操作 | 放弃本次操作 | 解决后继续 |
|---|---|---|
| merge | git merge --abort |
git merge --continue |
| rebase | git rebase --abort |
git rebase --continue |
| cherry-pick | git cherry-pick --abort |
git cherry-pick --continue |
git status 是主要判断依据。如果发现基线选错、冲突范围异常扩大,或者任务方向已经改变,应先 abort,再更新基线重试,不要在残缺状态上继续叠加修改。
abort 会回到本次操作开始前的状态,已经写入冲突文件的人工处理也可能丢失。值得保留的解决结果应先复制到 worktree 外,或至少保存一份差异:
git diff --binary > ../conflict-resolution.patch
如果仓库同时显示多个操作状态,应结合 git status 和 git log 判断最近启动的是哪一个流程,不要连续尝试所有 abort 命令。
冲突文件怎么改,ours 和 theirs 能不能直接选?
ours 和 theirs 表示当前操作中相对的两侧,并非始终对应固定分支:
| 操作 | ours |
theirs |
|---|---|---|
| merge | 当前分支 | 正在合入的分支 |
| rebase | 正在变基到的上游分支 | 正在重放的提交 |
| cherry-pick | 当前分支 | 被挑选的提交 |
只有确认整份文件应该采用其中一侧时,才使用:
git restore --ours -- path/to/file
git restore --theirs -- path/to/file
git add path/to/file
git diff --cached
整文件选择很适合生成文件或确实互斥的实现,但不适合双方都修改了同一个业务模块的情况。此时应同时查看基线、当前版本和待合并版本,手工保留双方仍有效的逻辑。
如果冲突结果应当删除文件,应明确暂存删除:
git rm path/to/file
需要让 Claude Code 协助时,先限制它只分析,不允许它擅自清理仓库:
只分析当前冲突,不要执行 git reset、git checkout --ours/--theirs、
git clean,也不要删除未跟踪文件;请说明冲突双方的意图、风险、
建议的合并方式和需要补充的测试。
这样得到的是供人审查的合并建议,Agent 不会直接替你清理仓库或落盘破坏性改动。
两个 Agent 都改了锁文件、生成代码或数据库迁移怎么办?
这类文件应指定唯一负责人,或者等源码合并完成后再统一生成。依赖锁文件必须基于最终依赖树重新生成,不能因为 ours 或 theirs 少了一处冲突就认为结果正确。生成代码也应从最终源码重新生成,再检查生成物是否与源码一致。
数据库迁移的问题更复杂。除了文件内容冲突,还涉及迁移编号、执行顺序、旧版本兼容和回滚路径。多个 Agent 即使位于不同 worktree,如果同时连接同一个开发数据库,目录隔离也阻止不了运行时竞争。迁移应串行设计、串行执行,并按项目实际部署流程验证。
合并顺序怎么安排,才能减少下一轮冲突?
先让每个任务分支更新到共同基线,再按依赖关系逐个集成。通常先合并基础接口和数据结构,再合并依赖这些接口的功能:
git fetch origin
git -C ../repo-feature-a status --short
git -C ../repo-feature-a rebase origin/main
git switch main
git merge feature/task-a
rebase 会重写分支提交历史。如果这些提交已经推送并被其他成员使用,应先遵循团队约定,不能擅自改写共享历史。另一种统一策略是 cherry-pick,但不要让不同分支混用 merge、rebase 和 cherry-pick 而没有记录。
main 分支应由指定的主 worktree 持有。如果它已经在另一个 worktree 中检出,在功能目录执行 git switch main 会被 Git 拒绝;这不是 Agent 故障,也不应通过删除 worktree 强行绕过。
每次只集成一个任务,并立即运行项目已有的测试、lint 和构建命令。只有当前合并通过验证后,再接收下一项任务。否则多个分支一次性合入,出现问题时很难判断是哪项变更引入的。
任务失败后,怎么保留成果再删除 worktree?
优先保留提交。提交已经保存在分支上,即使删除 worktree 也不会消失。未提交内容则应先导出到 worktree 外:
git -C ../repo-feature-a status --short
git -C ../repo-feature-a diff HEAD --binary > ../repo-feature-a.patch
git -C ../repo-feature-a ls-files --others --exclude-standard
git -C ../repo-feature-a log --oneline --decorate -n 5
补丁仍然不包含未跟踪和被忽略的文件。未跟踪文件需要逐个复制;.env 等敏感文件应单独、安全地保存,不要为了“保住成果”直接提交。确有必要时,也可以先创建 WIP 提交,再删除工作目录。
确认成果已经提交、合并或备份后,再移除 worktree:
git worktree remove ../repo-feature-a
git worktree list
git worktree prune
git branch -d feature/task-a
正常执行 git worktree remove 时,Git 会清理对应的管理记录;git worktree prune 主要用于移除已经失效的登记项。不要手工删除 .git/worktrees 下的内容,也不要用强制删除或直接 rm -rf 绕过检查。
git branch -d 只会删除已经合并的分支。如果它提示分支尚未合并,应先保留分支或完成备份,不要立即改用强制删除。
Claude Code 的 worktree 报错为什么和普通 Git 冲突不一样?
如果日志显示 git 被改写成了 lean-ctx -c,随后又被 worktree guard 拒绝,这属于 hook 改写问题,而不是 Git 本身无法创建 worktree。
相关 issue 的报告环境是 lean-ctx 3.11.0 和 macOS,Claude Code 的 PreToolUse Bash hook 会把 git 调用包装起来。后续修复 #2208 让以下配置跳过整个 hook rewrite:
excluded_commands = ["git"]
这样 git 会按原命令执行,同时仍保留原有的 allowlist 检查。 排查时应确认安装版本是否包含该修复;如果没有,可先在普通终端验证 Git 本身是否正常:
git status
git worktree list
直接执行正常、只有 Claude Code 中的 git 失败,就应继续检查 hook 配置和版本,而不是重建 worktree。具体配置文件位置应以当前 lean-ctx 版本的说明为准。
session_search 返回零结果也可能是另一个相关问题。oh-my-claudecode 的 issue 记录了 4.15.0 中从仓库子目录启动时,session_search 错把 worktree 根目录折叠,导致所有查询返回 totalMatches: 0,但 transcript 实际存在;该问题由 #3335 修复。 升级前可以先从仓库根目录启动:
git rev-parse --show-toplevel
cd /absolute/path/to/repository/root
如果仍需检索旧记录,可以直接搜索已知 transcript。这个现象属于 oh-my-claudecode 扩展,不应误判为 Claude Code 本身丢失了会话。
桌面端自动创建 worktree 时也要核对路径和分支。Claude Code 仓库曾有 issue 报告桌面端在缺少提示的情况下自动创建 worktree,并提醒可能造成数据损失;现有 issue 答复没有给出适用于所有版本的修复细节,因此不能因为 issue 已关闭就推断当前环境一定安全。
每次让桌面 Agent 写入前,先自行检查:
git worktree list --porcelain
git status --short
确认实际目录、分支和未提交改动,再允许 Agent 继续执行。
worktree 仍然解决不了哪些问题?
worktree 解决的是工作文件、索引、分支和未提交状态之间的目录级串扰。它不会自动解决同一文件的语义冲突、接口设计分歧、数据库迁移顺序、共享端口和测试库竞争,也不会替团队决定多个任务应该按什么顺序集成。
五个 Agent 可以并行执行五个任务,但任务边界、串行关口和最终合并不能交给模型临时决定。流程应保持为:先核对实际工作目录,再维护任务与分支的映射;冲突出现后先判断 Git 操作状态;能够回滚时先保留成果再处理;最后逐个集成并验证。













暂无评论内容