用 Git worktree 隔离并行编程 Agent

多个 AI agent 同时改代码，最先出问题的可能不是模型能力，而是它们正在修改同一个目录。一个 agent 尚未写完的代码，会进入另一个 agent 的构建和测试，接着引发误判和相互覆盖。

这篇文章给出的办法是：用 git worktree 为每个任务分配独立工作目录，再补齐环境初始化、任务划分和合并验证。它值得读的地方，是把 Claude Code、Codex、Cursor 的入口和容易遗漏的边界放在了一起：目录隔离只是开始，最后仍要有人负责把结果拼起来。

独立目录能解决覆盖，为什么还不能放心并行

终端开两个窗口、聊天开两个标签页，都没有改变文件共享的事实。agent 通常默认自己读文件、改代码、运行测试期间，工作目录不会被别人修改。两个会话共用 checkout，这个前提就失效了。

git worktree 为同一个仓库提供多个工作目录。每个目录拥有自己的工作文件，同时共享提交、分支等 Git 元数据。一边产生的新提交，另一边可以立即访问；尚未提交的文件修改则各自独立。

但它隔离不了目录之外的资源。两个开发服务器仍可能争用一个端口，两个迁移任务仍可能操作同一个本地数据库。需要并行启动应用，就要为各自环境配置不同端口或数据库；应用只能运行一个实例时，原文建议把 Codex 会话交回主工作目录测试。

另一个常见坑是 .env 消失。新 worktree 是一次新的检出，通常只有受 Git 跟踪的内容，忽略的配置文件和 node_modules 不会自动出现。

有了独立工作目录，不代表已经有了可运行的开发环境。

三个工具都能创建 worktree，但接手范围不同

以下行为来自原文引用的官方文档，核对日期为 2026-10-22。原文没有给出客户端版本号，具体入口应按文中描述理解。

Claude Code 使用 claude --worktree feature-auth，也支持缩写 -w。它会创建 .claude/worktrees/feature-auth/，分支名为 worktree-feature-auth。从 PR 启动可以运行 claude --worktree "#1234"，其中 #1234 要加引号。仓库需要至少有一次提交，并应将 .claude/worktrees/ 加入 .gitignore。

被忽略的配置可以写进根目录 .worktreeinclude，采用 .gitignore 的匹配语法，例如 .env、.env.local、config/secrets.json。Claude Code 只复制同时匹配规则且被 Git 忽略的文件，依赖仍需单独安装。

基线也要看清：默认从远程默认分支创建，通常是 main。希望包含当前本地未推送的提交，需要设置 "worktree": {"baseRef": "head"}；这里不接受任意分支名，指定其他已有分支要使用 Git。

Claude Code 还支持在 .claude/agents/ 的自定义子 agent frontmatter 中加入 isolation: worktree。不过这种子 agent 的指令来自主对话，不能指望其分支上不同的 CLAUDE.md 自动生效。目录隔离也不等于全部设置隔离：多数配置下，Bash 的持久批准记录仍写入主目录的 .claude/settings.local.json，项目级插件也会跨 worktree 加载。

Codex 这一节介绍的是 ChatGPT desktop app，以及通过移动端控制已连接电脑的使用方式。新聊天选择 Worktree，可以指定起始分支，也能把当前分支未暂存的修改带进去。目录位于 $CODEX_HOME/worktrees，初始处于 detached HEAD，即尚未挂在普通分支上的提交状态。

完成后可以选择 Create branch here，继续提交、推送和创建 PR；也可以用 Hand off 把聊天转到 Local。初始化脚本由 Local environments 管理，配置放在项目根目录 .codex，可纳入版本管理。应用也支持 .worktreeinclude，并会复制被忽略的 AGENTS.override.md。这些复制行为仅针对应用管理的 worktree。

Codex CLI 则需要自己创建目录，再用 codex --cd ../app-auth 启动。

Cursor 的 Agents Window 提供创建、审查和合入入口，IDE 内可以使用 /worktree、/apply-worktree 和 /delete-worktree。/best-of-n sonnet,gpt,composer fix the flaky logout test 会让多个模型分别处理同一任务，最终由人选中一个结果应用，不会自动融合答案。

下面这段配置解决 Cursor 新目录缺依赖和 .env 的问题：

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

注意 $ROOT_WORKTREE_PATH 指向主工作目录；配置文件是 .cursor/worktrees.json。setup-worktree 接受命令数组或脚本路径，也支持 setup-worktree-unix、setup-worktree-windows 覆盖项。失败时查看 Output 面板的 Worktrees Setup。原文还转述 Cursor 的建议：不要用符号链接共享依赖，可以考虑 pnpm、bun 或 uv。

分开写代码之后，还要设计怎么合回来

混用工具时，直接使用 Git 更容易理解各自边界。下面这段为两个任务建立相邻目录，再分别启动 Claude Code 和 Codex：

git worktree add ../app-auth -b agent/auth
git worktree add ../app-billing -b agent/billing
cp .env ../app-auth/ && cp .env ../app-billing/
git worktree list

cd ../app-auth && claude          # terminal 1
cd ../app-billing && codex        # terminal 2

注意两个 cd 分别在两个终端执行，并且两个目录都要安装依赖后再相信测试结果。目录放在仓库旁边，也就不需要额外加入主仓库的 .gitignore。

真正难的是任务边界。认证中间件与金额舍入适合分开；重构 API 与新增接口则可能同时改变同一套约定。一边重命名函数，另一边新增对旧函数名的调用，Git 甚至可能无冲突合并，随后构建才失败。

原文建议先把共享类型、schema、路由约定合入 main，再从同一基线开工。翻译表、路由表、changelog 等集中追加的文件，也应让各任务先生成独立片段，最后统一汇总，并检查重复或缺失项。

分支各自通过测试，只能说明各自成立，不能证明合并结果成立。

因此要指定一个集成人，由人或一个固定会话负责合并、解决冲突，再运行完整测试集。共同的验证命令和完成标准放进已提交的 AGENTS.md，由 CLAUDE.md 导入，避免不同工具各用一套规则。

收尾同样有工具差异。Claude Code 退出时会检查目录：干净的未命名会话自动清理，命名会话先询问；存在修改或新提交时询问保留还是删除，保留后可用 claude --worktree <name> --resume 返回。非交互式 -p 运行不会自动清理。

Codex 默认保留最近 15 个受管理 worktree，置顶、运行中或永久 worktree 不会被自动删除，删除前还会保存快照。Cursor 默认每台机器保留 25 个，由 cursor.worktreeMaxCount 和 cursor.worktreeCleanupIntervalHours 控制；原文特别提醒，外部用 Git 创建的 worktree 也可能进入清理范围。

手动删除使用 git worktree remove <path>。存在修改或未跟踪文件时会被拒绝，应先提交需要保留的内容，再决定是否加 --force。删除目录不会删除分支，分支需另用 git branch -d 清理。同一分支也不能同时在两个 worktree 中检出，但可以在主目录直接运行 git merge agent/auth 合入它。

我的判断

这套建议最可靠的部分，是把文件隔离、环境准备和集成验证分开讨论。对已经适合拆分的任务，worktree 比反复切分支更方便：每个 agent 都能保留自己的修改、依赖和测试现场。

不过，文章更接近文档整理与工程经验，没有提供作者团队的任务样本、冲突率、耗时或成本对照。不能据此得出「多开几个 agent 就能按比例提速」的结论。/best-of-n 也是候选方案比较，不能直接算成并行吞吐提升。

使用前提是任务能够拆开，初始化可以重复执行，而且有人承担最终集成。如果几个任务都围绕同一套组件接口或公共类型展开，先串行确定契约可能更省事。端口和数据库能否独立，也要结合项目判断，worktree 不会替团队完成这些准备。

能拿来做什么

• 给前端或 Node 项目整理一次可重复的初始化流程，明确依赖安装、环境文件、端口和数据库配置，再接入所用工具的 worktree 初始化入口。
• 并行 AI 编程先挑文件交集较少的任务；涉及公共类型或路由约定时，先提交共享改动，再分配独立 worktree。
• 把验证命令和完成标准提交到 AGENTS.md，让各 agent 按同一规则交付，并由固定集成人对合并结果运行完整测试集。
• 任务结束后检查提交、分支和 worktree 的保留状态，尤其留意 Codex 的 15 个、Cursor 的 25 个默认清理规则。