AI 工程

Git Worktree:让多个 AI 助手同时为你写代码的正确姿势

关键词: Git · Worktree · AI开发 · 并行开发 · 效率提升

小明的困境

上周，小明遇到一个棘手的需求:给现有系统加一个用户认证模块。他想到一个办法:既然 Claude 的架构设计能力强，Codex 的代码生成速度快，为什么不让它们同时干活,最后对比选最好的?

想法很美好,现实很骨感。一个小时后，他的项目文件夹变成了这样:

project/
├── auth.ts        # 被改了 4 次，不知道最后是谁的版本
├── auth_v2.ts     # Claude 重写的版本
├── auth_final.ts  # Codex 重写的版本
└── auth_backup.ts # 小明自己的备份

代码互相覆盖，上下文一团糟，两个 AI 生成的代码混在一起，根本没法对比。小明花了 3 个小时整理代码，最后还是不确定用哪个版本。

这个问题有解吗？有。答案就藏在 Git 的一个"冷门"功能里。

传统方案为什么不行?

在聊解决方案前，先看看常见做法的问题。

方案 1:同一分支轮流用

# 1. 先让 Claude 写
claude "实现用户认证"
git commit -m "Claude 版本"

# 2. 再让 Codex 写
codex "实现用户认证"
# 💥 代码被覆盖了!

问题:第二个 AI 会覆盖第一个的代码，无法对比。

方案 2:创建多个分支

git checkout -b claude-auth
# Claude 写代码

git checkout -b codex-auth
# Codex 写代码

# 想同时查看两个版本?
# 得来回切分支，太麻烦!

问题:频繁切换分支，心智负担大。想同时运行两个 AI?做不到。

方案 3:手动复制目录

cp -r project project-claude
cp -r project project-codex

问题:复制了两份完整代码(包括 .git 目录)，占用磁盘空间翻倍。而且不在 Git 管理范围内，无法用 git diff 对比。

Git Worktree:专业选手的武器

什么是 Git Worktree?

用人话说:它能让你为同一个 Git 仓库的不同分支，创建多个独立的工作目录。

project/
├── main/          # 主目录 (main 分支)
├── wt-claude/     # Claude 专属目录 (claude-auth 分支)
└── wt-codex/      # Codex 专属目录 (codex-auth 分支)

核心特点:

  • 三个目录共享同一个 .git 仓库(节省磁盘)
  • 每个目录关联不同分支(物理隔离)
  • 可以同时打开多个目录(真正并行)

为什么它是最优解?

对比传统方案:

方案切分支同时运行磁盘占用用 git diff 对比
普通分支❌ 频繁切换❌1倍✅
手动复制✅✅2倍+❌
Git Worktree✅✅1.1倍✅

实测数据(一个 300MB 的 Node.js 项目):

  • 手动复制:占用 620MB (完整复制两份)
  • Worktree:占用 330MB (只多了源码,共享 node_modules 和 .git)

省了近 300MB，还能用所有 Git 命令。

实战:让 Claude 和 Codex 并行干活

第一步:准备基线分支

# 1. 创建需求文档
mkdir -p docs
cat > docs/task-auth.md << 'EOF'
# 用户认证模块需求

## 功能要求
- 支持邮箱密码登录
- JWT token 验证
- 密码必须 bcrypt 加密

## 技术约束
- 使用 TypeScript
- 不允许修改 docs/ 目录
- 所有代码放在 src/auth/ 下
EOF

# 2. 创建基线分支
git checkout -b feature/auth-base
git add docs/task-auth.md
git commit -m "feat: 添加认证模块需求文档"

重点:需求文档必须在基线分支创建，确保两个 AI 看到的需求完全一致。

第二步:创建两个 Worktree

# 为 Claude 创建工作目录
git worktree add ../wt-claude ai/claude-auth

# 为 Codex 创建工作目录
git worktree add ../wt-codex ai/codex-auth

# 查看当前 worktree 列表
git worktree list

输出:

/path/to/project         (main)
/path/to/wt-claude       (ai/claude-auth)
/path/to/wt-codex        (ai/codex-auth)

第三步:分别启动 AI(关键)

打开两个终端窗口:

终端 1 - Claude

cd ../wt-claude

# 启动 Claude
claude
> "请阅读 docs/task-auth.md 并实现用户认证模块"

终端 2 - Codex

cd ../wt-codex

# 启动 Codex
codex
> "请阅读 docs/task-auth.md 并实现用户认证模块"

纪律:

  • 两个 AI 不能共享对话历史
  • 输入的 prompt 必须一致
  • 不要在一个 Worktree 里跑两个 AI

第四步:代码对比与决策

等两个 AI 都完成后:

# 1. 查看差异
git diff ai/claude-auth..ai/codex-auth

# 2. 查看具体文件的差异
git diff ai/claude-auth..ai/codex-auth -- src/auth/login.ts

# 3. 使用可视化工具
# VS Code: 安装 GitLens 插件，右键 "Compare with Branch"
# 或命令行
git difftool ai/claude-auth ai/codex-auth

第五步:评审代码质量

不要只看"能不能跑"。用这个清单:

架构层面(权重最高)

  • 模块边界清晰吗?
  • 未来加功能方便吗?
  • 有明显的技术债吗?

可读性

  • 30 秒能看懂核心流程吗?
  • 函数命名像人写的吗?
  • 注释恰到好处吗?(不多不少)

抽象是否恰当

  • 有"为了优雅而优雅"的过度设计吗?
  • 抽象有真实的复用价值吗?

错误处理

  • 异常被吞掉了吗?
  • 边界条件考虑了吗?
  • 错误信息对用户友好吗?

终极问题

"6 个月后,这段代码我还愿意维护吗?"

第六步:合并优胜方案

假设 Claude 的版本更好:

# 切回主分支
git checkout main

# 合并 Claude 的代码
git merge ai/claude-auth

# 推送到远程
git push origin main

想混合两个版本?手动 cherry-pick:

# 从 Codex 分支挑选某个 commit
git cherry-pick <commit-id>

第七步:清理现场

# 删除 worktree
git worktree remove wt-claude
git worktree remove wt-codex

# 删除临时分支(可选)
git branch -D ai/claude-auth
git branch -D ai/codex-auth

进阶技巧

1. 一键创建 Worktree 的脚本

每次手动创建太麻烦?写个脚本:

#!/bin/bash
# 文件名: ai-worktree.sh

set -e

TASK=$1

if [ -z "$TASK" ]; then
  echo "用法: ./ai-worktree.sh <任务名>"
  echo "示例: ./ai-worktree.sh auth"
  exit 1
fi

echo "🚀 创建 AI 并行开发环境: $TASK"

# 创建基线分支
git checkout -b feature/${TASK}-base

# 创建两个 worktree
git worktree add ../wt-claude ai/claude-${TASK}
git worktree add ../wt-codex ai/codex-${TASK}

echo "✅ 完成!"
echo "👉 Claude 目录: ../wt-claude"
echo "👉 Codex 目录: ../wt-codex"

使用:

chmod +x ai-worktree.sh
./ai-worktree.sh auth

2. 锁定需求文档(防止 AI 乱改)

# 方法 1: 设置文件为只读
chmod -w docs/task.md

# 方法 2: Git 忽略变更
git update-index --skip-worktree docs/task.md

3. 批量清理 Worktree

# 查看所有 worktree
git worktree list

# 批量删除(小心使用!)
git worktree list | grep 'wt-' | awk '{print $1}' | xargs -I {} git worktree remove {}

4. 移动 Worktree 位置

# 移动 worktree 到新位置
mv ../wt-claude ~/projects/wt-claude

# 修复 Git 引用
git worktree repair

常见问题与解决

问题 1: 依赖安装冲突

现象: 两个 Worktree 的 node_modules 版本不一致。

原因: Worktree 不共享 node_modules 等目录。

解决:

# 方法 1: 每个 worktree 独立安装
cd wt-claude && npm install
cd wt-codex && npm install

# 方法 2: 使用 pnpm(自动硬链接)
pnpm install  # 在两个目录都执行

问题 2: 端口被占用

现象: 两个 AI 同时启动开发服务器,端口冲突。

解决:

# wt-claude/.env
PORT=3000

# wt-codex/.env
PORT=3001

问题 3: 删除 Worktree 报错

现象: git worktree remove 提示 "worktree contains modified or untracked files"。

解决:

# 方法 1: 强制删除
git worktree remove wt-claude --force

# 方法 2: 先清理再删除
cd wt-claude
git reset --hard
cd ..
git worktree remove wt-claude

问题 4: Worktree 路径丢失

现象: 移动过目录后,Git 找不到 worktree。

解决:

# 修复所有 worktree 引用
git worktree repair

# 或手动指定路径
git worktree repair /new/path/to/worktree

最佳实践总结

分支命名规范

# 推荐格式
ai/<工具名>-<任务名>

# 示例
ai/claude-auth
ai/codex-payment
ai/gpt4-refactor

工作流检查清单

开始前:

  • 需求文档已创建在基线分支
  • 两个 AI 的 prompt 一致
  • Worktree 目录结构清晰

开发中:

  • 两个 AI 没有共享上下文
  • 每个 AI 只在自己的目录工作
  • 定期 commit(方便回滚)

完成后:

  • 用评审清单对比代码质量
  • 做出明确的技术决策
  • 清理临时 worktree 和分支

团队协作建议

如果团队多人使用这个方法:

  1. 统一脚本: 把创建 worktree 的脚本加入仓库
  2. 文档化: 在 README 说明 worktree 用途
  3. 定期清理: 每周五清理无用的 worktree
  4. 命名规范: 团队统一分支命名格式

什么时候不适合用 Worktree?

也要说实话:

❌ 不推荐的场景

  • 超小改动: 改 1-2 个文件,用普通分支更快
  • 非 Git 项目: 没有版本控制的项目
  • 单纯代码补全: AI 只是辅助补全,不是生成完整方案
  • 磁盘空间极度紧张: 虽然 Worktree 省空间,但还是会多占一些

✅ 最适合的场景

  • 方案对比: 需要比较不同 AI 的实现方案
  • 并行开发: 同时让多个 AI 实现不同功能模块
  • 重构评估: 让 AI 提供多个重构方案供选择
  • 学习研究: 对比不同 AI 的代码风格和设计思路

快速上手清单

复制这个清单,开始你的第一次 AI 并行开发:

# 1. 准备需求文档
mkdir -p docs
vim docs/task.md  # 写清楚要做什么

# 2. 创建基线分支
git checkout -b feature/task-base
git add docs/task.md
git commit -m "feat: 添加需求文档"

# 3. 创建两个 worktree
git worktree add ../wt-claude ai/claude-task
git worktree add ../wt-codex ai/codex-task

# 4. 分别启动 AI
# 终端 1: cd ../wt-claude && claude
# 终端 2: cd ../wt-codex && codex

# 5. 对比代码
git diff ai/claude-task..ai/codex-task

# 6. 合并优胜方案
git checkout main
git merge ai/claude-task  # 假设 Claude 更好

# 7. 清理现场
git worktree remove wt-claude
git worktree remove wt-codex
git branch -D ai/claude-task ai/codex-task

避坑指南

坑 1: 忘记切换目录

# ❌ 错误:在主目录启动两个 AI
cd project
claude "实现功能"
codex "实现功能"   # 会覆盖 Claude 的代码!

# ✅ 正确:在各自的 worktree 启动
cd wt-claude && claude
cd wt-codex && codex

坑 2: 需求文档不一致

# ❌ 错误:在不同 worktree 修改需求
cd wt-claude
vim docs/task.md  # 加了新需求

cd wt-codex
vim docs/task.md  # 加了不同的需求

结果: 两个 AI 做的是不同的事,无法对比。

解决: 需求文档锁定在基线分支,或设为只读。

坑 3: 忘记定期 commit

现象: AI 写了半天代码,突然崩溃了,所有代码丢失。

避免:

# 每完成一个小功能就 commit
git add .
git commit -m "feat: 完成登录接口"

坑 4: 直接删除 worktree 目录

# ❌ 错误
rm -rf ../wt-claude  # Git 会认为 worktree 还在

# ✅ 正确
git worktree remove wt-claude  # 先用 Git 命令删除

总结

Git Worktree 不是什么新技术,但它解决了一个真实的痛点:让多个 AI 助手并行工作,互不干扰,产出可对比的高质量代码。

核心要点回顾:

  1. 物理隔离 > 逻辑隔离: 不要指望 prompt 能约束 AI
  2. 独立目录: 每个 AI 一个专属 worktree
  3. 统一需求: 确保输入一致,输出才可比
  4. 人工决策: 你是最终的架构裁判
  5. 定期清理: 用完就删,保持仓库整洁

试试看,下次让 AI 写代码时,别再让它们互相打架了。用 Worktree,给每个 AI 一个独立的舞台,你只需要在台下做好评委。

参考资料: