实战指南：利用 Git Worktrees 实现同仓库多 AI Agent 并行开发

如果你在同一个代码仓库上运行多个 AI 编程智能体（Agents），你可能遇到过这种情况：智能体 A 正在修改 src/auth.rs，而智能体 B 恰好也在修改 src/auth.rs。结果一个覆盖了另一个，而且没人注意到这一点，直到测试失败------或者更糟，直到生产环境崩溃。

解决办法其实出奇地简单，而且早在 2015 年就已经存在于 Git 中了：那就是 worktrees（工作树） 。

Git Worktrees 是什么

一个 Git worktree（工作树） 是一个连接到同一个代码仓库的独立工作目录。每个工作树都有自己独立的分支、独立的暂存区以及磁盘上独立的源文件------但它们都共享同一个 .git 历史记录。

你可以把它理解为一种轻量级的克隆（cloning） ，但它不会复制整个仓库的数据。

bash 复制代码

# 主仓库
~/project/          # 为两个智能体创建两个工作树
git worktree add ~/project/.agents/agent-1 -b agent-1/task-auth
git worktree add ~/project/.agents/agent-2 -b agent-2/task-tests

# 现在你拥有三个工作目录了：
~/project/                    # main
~/project/.agents/agent-1/    # branch: agent-1/task-auth
~/project/.agents/agent-2/    # branch: agent-2/task-tests

每个智能体都在自己的工作目录和自己的分支上工作。它们可以同时编辑相同的文件而不会产生冲突------冲突只需要在合并时解决，即当一个智能体的分支被合并到主分支时。

分步指南：手动工作树工作流

为每个智能体创建一个worktree

bash 复制代码

mkdir -p .agents
git worktree add .agents/agent-1 -b agent-1/task-refactor-auth
git worktree add .agents/agent-2 -b agent-2/task-add-api-tests
git worktree add .agents/agent-3 -b agent-3/task-fix-css-bug

每个命令都会创建一个新目录，并在基于当前 HEAD 的新分支上进行全新的检出。

将每个智能体指向其工作树

在每个智能体自己的目录中启动它：

bash 复制代码

# Terminal 1
cd .agents/agent-1
claude-code   # or codex, aider, etc.
# Give it the task: "Refactor the auth module to use JWT"

# Terminal 2
cd .agents/agent-2
codex
# Give it the task: "Add integration tests for the REST API"

# Terminal 3
cd .agents/agent-3
aider
# Give it the task: "Fix the CSS layout bug in the dashboard"

每个智能体只能看到自己的工作目录。它可以读取任何文件、编辑任何内容、运行任何命令------而不会影响其他智能体。

合并前请先运行测试

当智能体提示完成后，请验证：

bash 复制代码

cd .agents/agent-1
cargo test   # or npm test, pytest, etc.
echo $?      # 0 = tests pass, merge it

这是很多人都会跳过的关键一步。智能体往往会在代码刚编译成功、而测试依然失败时就言之凿凿地宣布大功告成。在接收智能体的工作成果前，请务必完整运行一遍测试套件。

合并到主分支

bash 复制代码

cd ~/project        # back to main worktree
git merge agent-1/task-refactor-auth

如果发生冲突（比如 Agent-2 也修改了 Agent-1 改动过的文件），Git 会提示你。请干净利落地一次性解决它，而不是让多个 Agent 在并行工作时默默地互相覆盖代码。

专业提示：一次只合并一个分支。 如果你先合并了 Agent-1，再合并 Agent-2，那么第二次合并时，系统就会把 Agent-1 的改动视为主分支（main）的一部分。这种串行（序列化）的方法可以让你逐步捕获冲突，而不是等所有冲突堆到一起爆发。

Clean up

bash 复制代码

git worktree remove .agents/agent-1
git branch -d agent-1/task-refactor-auth

或者直接把这个 worktree 留给下一个任务用：

bash 复制代码

cd .agents/agent-1
git checkout main
git pull
git checkout -b agent-1/task-next-thing

复用速度更快 ------ 毕竟创建一个新的工作树（worktree）需要检出（checkout）整个工作区，在大项目仓库中这通常需要耗费几秒钟的时间。

为什么这比单纯使用分支效果更好

你可能会想"直接用分支不就行了" ------ 你只说对了一半。分支确实能处理版本控制，但如果没有独立的工作树（Worktrees），所有的 Agent 就会共享同一个工作目录。这意味着：

不同 Agent 之间会出现 git stash （暂存）冲突
一个 Agent 未提交的改动会出现在另一个 Agent 的环境中
构建产物（Build artifacts）和缓存会陷入混乱

而 Worktrees 为每个 Agent 提供了一个物理上相互隔离的目录。不再有频繁切换 stash 的烦恼，不再会因为其他 Agent 做到一半的"脏工作区"而受影响，也不会发生共享构建缓存被污染的情况。

实践中的上限

通过这种方式，我曾同时并行运行过 3 到 5 个 Agent。超过 5 个之后，代码库本身就会成为瓶颈 ------ 并发改动太多，导致无法进行干净的合并（Clean merges）。最佳的平衡点取决于你的代码库结构：

松耦合 模块（微服务、独立功能）： 5 个以上 Agent 也能正常协作。
紧耦合 代码库（共享状态、存在大量跨文件依赖）： 最多 2 到 3 个 Agent。
边界清晰的 Monorepo（单体大仓库）： 取决于任务与模块边界的匹配程度。

自动化实现

虽然手动操作这套工作流也行得通，但规模扩大后就会变得非常繁琐。你需要为每个 Agent、每个任务重复进行以下操作：创建 Worktree、启动 Agent、检查测试结果、串行合并、清理环境。

而 Batty 将这整个闭环实现了自动化。它会为每个 Agent 创建持久化的 Worktree，从 Markdown 格式的看板中分发任务，在合并前运行测试，并通过文件锁（File lock）来串行化处理并发合并。此外，Agent 会在 tmux 窗格中运行，方便你直观地观测它们的工作进展。

arduino 复制代码

cargo install batty-cli
batty init --template pair    # 1 architect + 1 engineer
batty start --attach

"但这种底层模式 ------ 即工作树隔离（Worktree isolation）、测试把关（Test gating）以及串行合并（Serialized merges）------ 适用于任何工作流。即使只是写一个最简单的 Shell 脚本来自动创建 Worktree 并在最后执行 git merge，也远比让多个 Agent 在同一个目录下互相死磕强得多。

快速参考

csharp 复制代码

# Create worktree
git worktree add <path> -b <branch-name>

# List worktrees
git worktree list

# Remove worktree
git worktree remove <path>

# Prune stale worktree references
git worktree prune

核心观点： 文件系统层面的隔离，比单纯依赖分支层面的隔离更简单、也更可靠。而 Git worktrees 恰好能让你鱼与熊掌兼得。该功能自 Git 2.5（2015 年）发布以来就一直很稳定，但大多数开发者却从未接触过它。

如果你正在运行多个 Agent，且还没有尝试过 worktrees，那么这将是你能做出的、唯一一个最具影响力的改变。

原文：dev.to/battyterm/h...