用 Git Worktree 并行跑多个 Coding Agent

我在使用 coding agents 时一直碰壁。在一个仓库里跑一个 Claude Code 或 Codex 会话效果很好，但一旦想同时推进两个任务——一个终端做登录，另一个做支付——它们就开始互相踩踏。同一个工作目录、同一份检出的分支、两个进程同时编辑同一个文件。混乱。

解决方案其实是一个 Git 功能，已经存在多年了：git worktree。它允许你从同一个仓库创建多个工作目录。每个文件夹有自己检出的分支，但它们共享同一套 objects、commits 和分支列表。

从主 checkout 目录执行：

git worktree add ../integration -b integration main
git worktree add ../feature-login -b feature/login main
git worktree add ../feature-payments -b feature/payments main

最终目录结构大致如下：

project/
├── main/               → branch main
├── integration/        → branch integration
├── feature-login/      → branch feature/login
└── feature-payments/   → branch feature/payments

现在每个 agent 都有了自己的文件夹。一个 worktree 对应一个终端，一个终端对应一个 agent，没人碰别人的文件：

cd feature-login    # agent 1 works here
cd feature-payments # agent 2 works here, at the same time

令我惊讶的是：不需要 push，不需要 pull

我的第一反应是：agent 完成登录后，push 分支，然后我把它 pull 到 integration 分支。这是团队协作养成的习惯。

但在这里完全没必要。所有 worktree 都属于同一台机器上的同一个仓库，所以 Git 在本地已经知道每一个分支。当 agent 1 完成后：

cd feature-login
git add .
git commit -m "feat: implement login"

...integration worktree 可以直接合并它：

cd ../integration
git merge feature/login
git merge feature/payments
npm test

不需要 git push，也不需要 git pull。目录不同，但 feature/login 和 integration 是同一个仓库的不同分支。当 integration 变绿后：

cd ../main
git merge integration

你甚至不需要等 worktree 删除后才能合并它的分支。两个文件夹可以同时存在。Git 唯一拒绝的是同一个分支同时在两个 worktree 中检出——而这恰恰是多个 agent 并行工作时需要的保护机制。

功能完成时，不要直接 rm -rf：

git worktree remove ../feature-login
git branch -d feature/login

git worktree remove 会删除文件夹并清理 Git 的内部注册表。如果你已经手动删除了文件夹，git worktree prune 会帮你事后修复记录。

一个完整任务的周期是这样的：

git worktree add ../feature-login -b feature/login main   # create
cd ../feature-login                                       # agent works, commits
cd ../integration && git merge feature/login && npm test  # integrate
git worktree remove ../feature-login                      # discard workspace
git branch -d feature/login                               # discard branch

那么 GitHub 在哪里发挥作用？

对于在同一台机器上协作的 agents 来说：没有任何作用。Git 本身才是通信机制。

GitHub 在人类介入时才发挥作用——PR、review、CI、审计追踪：

cd feature-login
git push -u origin feature/login   # open a PR from this

如果你想让 integration 合并远程分支的内容而不是本地分支：

git fetch origin
git merge origin/feature/login

我现在把它看作两个独立的层面。本地：worktree → commit → 合并到 integration → 测试。远程：push → PR → review → CI。第二个层面是给人的；第一个层面才是 agents 实际工作的地方。

真正让我下定决心的一点是：integration agent 从不从其他 agent 复制代码，从不读取它们的文件夹，甚至不知道它们的存在。它只知道它们的分支名。Git 一直是消息总线。

附加说明：当每个 agent 都想要 port 3000 时

Worktree 隔离的是文件和分支，而不是运行时。一旦两个 agent 都运行 npm run dev 和 Playwright 测试套件，它们都会抢占 :3000、同一份测试数据库，而且每个 headless 浏览器都会占用大量 RAM。

我目前采用的解决方案很无聊：在创建时通过 env 文件为每个 worktree 分配独立端口，Playwright 读取它作为 baseURL：

echo "PORT=3101" > ../feature-login/.env.local
echo "PORT=3102" > ../feature-payments/.env.local

但端口只是问题的一个方面。隔离测试数据库、让三个浏览器套件不会耗尽机器资源，以及决定是否应该只有 integration worktree 才能运行 E2E 测试——这些都值得单独写一篇文章。下一篇就是这个。