并行运行多个Claude Code代理：worktrees看不见的坑

并行运行多个 Claude Code 代理，正在成为不少开发者提升 AI 编程吞吐量的默认操作。Git worktree 让每个代理拥有独立的工作目录，看起来把冲突问题彻底解决了。但 Dev.to 作者 Nick Woodhead 在一篇实战复盘里指出：worktree 只能隔离文件系统，隔离不了那些藏在代码仓库之外的东西。这篇分析拆解他提到的盲区，并讨论并行代理真正需要的基础设施。

Git worktree 解决了什么，又遗漏了什么

Worktree 的机制很直白：同一个仓库可以检出多个工作目录，每个目录挂在不同分支上。代理 A 在 ../repo-feature-a 里改代码，代理 B 在 ../repo-feature-b 里干活，两者的暂存区、HEAD、未提交改动互不干扰。

这在单机单代理时代已经够用，因为人是串行工作的。但当你同时跑三四个 Claude Code 会话时，问题就从"文件冲突"转移到"环境冲突"。Nick Woodhead 的核心观点是：worktree 是一层文件系统隔离，而代理运行时依赖的东西，大部分不在文件系统这一层。

端口、数据库与本地服务

最典型的例子是本地开发服务器。两个代理同时执行 npm run dev，第二个会撞上端口占用。数据库更是重灾区：如果两个代理跑的是同一套迁移脚本，或者一个在写测试数据、另一个在读，worktree 完全无能为力，因为它们连的是同一个 localhost:5432。

Redis、消息队列、Docker 容器名冲突，都属于同一类问题。worktree 给每个代理一个干净的代码树，却共享同一台机器的网络命名空间和运行时。

环境变量与凭证

第二个盲区是配置。.env 文件通常被 gitignore，worktree 新建时不会自动带上，代理可能因此读到错误的默认值，或者干脆启动失败。更隐蔽的是凭证：多个代理共用同一套 API key 或云账号，配额、速率限制、账单归属都会纠缠在一起。

Nick Woodhead 提到，这类问题的麻烦之处在于它们不报编译错误，而是表现为间歇性失败，排查成本远高于一次 git 冲突。

代理之间的"视野"问题

标题里的 "what worktrees cannot see" 还有一层含义：代理看不到彼此在做什么。Worktree 隔离越彻底，代理越不知道另一个分支上已经有人改了同一个接口。合并时的语义冲突——两个代理各自合理地修改了同一段逻辑——在运行期完全隐形，只在最后 review 时爆出来。

Git worktree 是 Git 自 2.5 版本引入的功能，允许同一个仓库同时检出多个工作目录，每个目录对应不同的分支或提交。与传统的 git clone 不同，worktree 共享底层的 .git 对象数据库和引用，因此磁盘占用更小、创建速度更快，且分支管理集中在一处。执行 git worktree add ../repo-feature-a feature-a 即可在指定路径创建新工作树并检出对应分支。每个工作树拥有独立的 HEAD、索引（暂存区）和工作区文件，但共享远程配置、钩子和对象存储。这一机制原本用于支持开发者同时处理多个分支而无需反复切换，如今被借用来为并行运行的 AI 代理提供文件系统层面的隔离。

语义冲突（semantic conflict）指两个分支的修改在文本层面不冲突、能够顺利合并，但在程序语义上相互矛盾的情况。例如代理 A 将某函数参数从位置参数改为关键字参数，代理 B 在同一函数的另一处调用中按旧签名传参，Git 合并时两者位于不同行、不会产生冲突标记，但合并后的代码在运行时会报错。在并行代理场景中，语义冲突尤其危险，因为每个代理都在独立上下文中做出"局部合理"的决策，缺乏对另一分支意图的感知。传统的 CI 和单元测试可以捕获一部分此类问题，但覆盖率和反馈延迟往往不足以在合并前暴露全部风险，因此跨分支的语义 review 成为必要环节。

从隔离文件到隔离环境

如果 worktree 只是一半答案，另一半是什么？作者给出的方向是把隔离下沉到更完整的运行时层。

容器或虚拟机级别的隔离

每个代理跑在自己的容器里，端口、依赖、数据库实例全部独立。代价是启动开销和资源占用，但对于长时间运行的代理会话，这个成本可以接受。Dev Container 或轻量 VM 是常见选择。

Dev Container（Development Container）是一种将开发环境完整定义在容器中的实践，通常通过 devcontainer.json 声明基础镜像、依赖安装、端口转发和环境变量。配合 VS Code 或 Claude Code 等工具，开发者可以在容器内获得与宿主机隔离的工具链和运行时。对于并行代理，每个代理启动独立容器意味着端口、数据库客户端、语言运行时版本互不干扰，且容器销毁后环境状态不会残留。轻量虚拟机（如 Lima、Multipass）提供更强的内核级隔离，适合需要运行 Docker-in-Docker 或对安全边界要求更高的场景，代价是启动延迟和内存占用高于容器。

命名空间化的本地资源

更轻量的做法是给每个代理分配资源前缀：不同的端口段、不同的数据库 schema、不同的 Docker compose project name。这需要项目本身支持参数化配置，改造量不小，但对已有项目更友好。

代理间的协调层

作者还提到，除了隔离，还需要某种共享状态让代理知道彼此的存在。比如一个简单的任务登记表，记录哪个代理正在改哪些模块，避免两个代理同时动同一个接口。这层协调可以很简陋——一个锁文件甚至一份 Markdown 清单都行——关键是别让代理在完全信息孤岛里工作。

值得现在就做的事

并行代理的收益是真实的：多个任务同时推进，等待时间被摊薄。但 worktree 带来的"已经隔离好了"的错觉，会让团队低估环境层的复杂度。

Nick Woodhead 的实践建议可以归纳为几点：启动代理前先明确资源分配表；把 .env 和本地服务的初始化纳入代理的启动脚本；为每个代理会话设定清晰的文件或模块边界；以及在合并前做一次跨分支的语义 review，而不只是看 git 是否冲突。

这些做法都不新鲜，新鲜的是它们现在需要为"非人类协作者"重新设计一遍。当并行运行的不再是你自己的几个终端，而是几个会自主执行命令的代理时，隔离的粒度必须跟着变。

常见问题

worktree 能防止代理互相覆盖代码吗？ 能。worktree 隔离的是工作目录和 git 状态，代码层面的覆盖冲突基本不会发生。

那为什么还会冲突？ 冲突转移到了环境层：端口、数据库、环境变量、凭证配额。这些资源在 worktree 之间是共享的。

最少需要做哪些改造？ 给每个代理分配独立的端口和数据库 schema，确保 .env 随会话初始化，并建立一个轻量的模块占用登记。