Codex Worktree 隔离开发实战：多任务并行不冲突

用 Codex 同时推进多个任务时，最容易踩的坑不是”该不该并行”（这部分可参考 Codex 多 Agent 任务拆分边界），而是并行任务共享同一个工作目录导致的互相干扰：一个任务切了分支，另一个任务的改动跟着变了基线；一个任务在跑测试，另一个任务改了同样的文件导致测试结果不可信。Git Worktree 是解决这个问题的标准方案。本文给出实战流程。

一、问题的本质：单一工作目录无法承载并行

一个 Git 仓库的工作目录在同一时刻只能处于一个分支状态。如果你想让 Codex 同时做两件事——比如一个任务修 Bug、另一个任务加新功能——用同一个目录会遇到：

分支互相覆盖：任务 A 切到 fix-login，任务 B 的改动还没提交，会被要求先处理，或者干脆被弄混
依赖状态不一致：任务 A 装了新依赖，node_modules 或虚拟环境变了，任务 B 的测试可能因为这次依赖变更而失败，但原因和任务 B 本身无关
未提交改动的隐性丢失风险：切换分支时如果有未 stash 的改动，容易在忙乱中被覆盖

Git Worktree 的思路是：同一个仓库的 .git 数据只保留一份，但允许同时检出多个独立的工作目录，每个目录对应一个分支，互不干扰。

二、基础命令流程

# 在主仓库目录下，为新任务创建一个独立 worktree
git worktree add ../myrepo-fix-login fix-login

# 如果分支还不存在，直接从当前分支创建新分支
git worktree add -b fix-login ../myrepo-fix-login

# 查看当前所有 worktree
git worktree list

执行后，../myrepo-fix-login 是一个完整独立的工作目录，有自己的文件状态，但和主仓库共享同一份 Git 历史。这时可以让 Codex 在这个独立目录里工作，和主目录里的其他任务完全隔离。

三、给 Codex 分配 worktree 的实战模式

实际使用中，推荐按”一个任务一个 worktree”的方式组织：

# 任务规划阶段：先列出本轮要并行的任务
# 1. fix-login    修复登录 Bug
# 2. add-export   加导出功能
# 3. refactor-api 重构 API 层

# 逐个创建独立 worktree
git worktree add -b fix-login ../proj-fix-login main
git worktree add -b add-export ../proj-add-export main
git worktree add -b refactor-api ../proj-refactor-api main

然后分别在三个目录里启动 Codex 会话（或者用支持多会话并行的界面同时开三个任务）。每个会话的改动、依赖安装、测试运行都发生在各自目录里，互不影响。

一个容易忽略的细节：如果项目依赖需要编译或有大量依赖包（比如 node_modules、Python 虚拟环境），每个 worktree 默认都要重新安装一遍，会比较慢。可以用符号链接共享不涉及冲突的依赖目录，或者用 pnpm 这类支持全局 store 的包管理器减少重复下载。

四、任务完成后的合并与清理

并行任务做完之后，合并回主分支的流程和普通分支合并没有区别，但清理 worktree 需要额外一步，直接删除目录是不够的：

# 在对应 worktree 里确认改动已提交并合并
cd ../proj-fix-login
git add -A && git commit -m "fix: resolve login redirect loop"
cd ../proj  # 回到主仓库
git merge fix-login

# 清理 worktree（不要直接 rm -rf 目录）
git worktree remove ../proj-fix-login

# 如果目录已经被手动删除，用这个命令清理残留的元数据引用
git worktree prune

直接用 rm -rf 删除 worktree 目录而不执行 git worktree remove，会在主仓库的 .git/worktrees/ 下留下悬空引用，虽然不会导致数据损坏，但会让 git worktree list 输出变得混乱，长期积累后不容易看清当前到底有哪些活跃的并行任务。

五、和分支策略的配合

Worktree 隔离的是工作目录，不是分支管理策略，两者要配合好才不会乱：

每个 worktree 对应的分支名要能直接反映任务内容，方便几天后回头看还能对上号
长期不用的 worktree 要及时清理，避免同一个仓库积累几十个 worktree 目录，占用磁盘且难以维护
如果任务之间有依赖关系（比如任务 B 需要基于任务 A 的改动），不适合简单并行，应该退回串行执行，或者等任务 A 合并到 main 后，任务 B 的 worktree 再从更新后的 main 创建

六、什么场景不需要 Worktree

不是所有并行场景都值得上 Worktree。如果多个任务修改的是完全独立的模块、且不涉及依赖或配置变更，直接在同一目录下用 Codex 的多文件并行编辑能力可能更省事——Worktree 隔离带来的价值主要体现在任务会切分支、装依赖、跑独立测试这类有状态副作用的场景。轻量级的纯代码编辑任务，引入 Worktree 反而增加了不必要的目录管理开销。

七、相关阅读

多任务并行调用 AI 编程工具时，API 稳定性和并发限速容易成为瓶颈，YoTradeApi 提供国内可直连的中转服务，支撑多个 Codex 会话同时稳定运行。