给 AI 编码代理用 Git worktree：一份实用指南
只要你在同一个仓库里跑第二个编码代理，就需要用 git worktree。两个代理挤在一个文件夹里，会改同一批文件、跑到对方还没写完的改动，最后留给你一堆没人说得清的 diff。而 worktree 一条命令就能解决这个问题。本文讲清楚相关命令，以及当你手上有好几个 worktree 之后容易出问题的五个地方。
worktree 到底是什么
worktree 就是同一个仓库的第二个工作文件夹。它和主检出共用仓库的历史和对象，但有自己的文件，也有自己检出的分支。只要你不提交、不合并，一边的改动永远不会出现在另一边。
对代理来说，这意味着：一个任务、一个 worktree、一个代理。每个代理都在自己那份文件副本上干活，最后你像合并同事的分支一样把它们的成果合进来。
命令
# 新建一个分支和对应文件夹，放在当前检出目录旁边
git worktree add -b fix-login ../myapp-fix-login
# 让代理在这个目录里干活
cd ../myapp-fix-login
claude # 或者：codex、gemini
# 查看所有 worktree
git worktree list
# 分支合并之后
git worktree remove ../myapp-fix-login
git branch -d fix-login
# 如果你手动删除了 worktree 文件夹
git worktree prune
同一分支在同一时间只能在一个 worktree 中检出。如果 Git 拒绝并提示「already checked out」，说明该分支已经在另一个 worktree 中；给新任务单独开一个分支即可。
五个常见问题及修复方法
1. .env 文件不在
Worktree 只包含被跟踪的文件。密钥、本地配置以及所有被 .gitignore 忽略的内容都留在主检出目录中。可以写一个简短的脚本，创建 worktree 时顺便把这些文件拷过去：
#!/bin/sh
# 用法: ./new-task.sh fix-login
set -e
dir="../$(basename "$PWD")-$1"
git worktree add -b "$1" "$dir"
cp .env "$dir/" 2>/dev/null || true
2. 依赖没有安装
node_modules、虚拟环境和构建缓存都是按文件夹隔离的。智能体执行的第一条命令会因为依赖缺失而失败，直到它自行安装。两种解决办法：在指令文件（CLAUDE.md、AGENTS.md）中告诉智能体先安装依赖；使用带共享存储的包管理器（pnpm、uv、Bun），这样全新安装只需几秒钟。
3. 端口冲突
两个 worktree 同时跑开发服务器，都想用 3000 端口。从环境变量读取端口，为每个 worktree 设置不同的值，比如写在该 worktree 的 .env 里。
4. 数据库和容器冲突
两个 worktree 运行同一份 Docker Compose 文件时，会共享容器名和卷，导致一个智能体的迁移数据落到另一个的数据库里。为每个 worktree 设置 COMPOSE_PROJECT_NAME，或者让每个 worktree 指向各自的数据库名。
5. Worktree 堆积
一个被遗忘的 worktree 就是一个被遗忘的分支，外加一块磁盘空间。每周结束时运行 git worktree list，把已合并的清理掉。删除之前先确认没有未提交的改动（git -C <folder> status），也没有未推送的提交——```bash
git branch -d fix-login
如果是手动删除了 worktree 文件夹
git worktree prune
```
同一分支同一时间只能被一个 worktree 检出。如果 git 提示“already checked out”，说明该分支还在另一个 worktree 里；给新任务单独开一个分支就好。
五个容易出问题的地方，以及对应的解法
1. 忘了带上 .env
worktree 里只有被 git 跟踪的文件。密钥、本地配置，以及所有写在 .gitignore 里的东西，都还留在主检出目录里。可以写一个短脚本，创建 worktree 时顺手把它们复制过去：
```sh