Claude Code Worktree — Git 隔离让并行 Agent 互不打扰
每个 Claude Code 会话或子代理拿到自己的 git worktree，文件改动彼此不可见；完成无残留即自动清理。本指南覆盖工具、配置、并行模式与坑。
Worktree 是什么、为什么重要
git worktree 是同一仓库下挂出的额外工作目录，拥有独立的 working tree 与 branch，但共享 .git history 与 remote。Claude Code 把每个并行会话或子代理挂到独立 worktree 上，A 会话写功能 X、B 会话修 bug Y，文件读写完全不互相覆盖。共享 git 元数据保证 commit/push/log 一致。
EnterWorktree 工具与 isolation 配置
在 Claude Code 中你可以直接说 "work in a worktree"，模型用 EnterWorktree 工具新建 worktree。也可以在 custom subagent 的 frontmatter 加 isolation: worktree，让该 subagent 每次被 dispatch 时自动拿到隔离 worktree。v2.1.x 起后台 session（background agents）也支持 worktree bg isolation，长时任务不再阻塞主开发分支。
/team-build 并行多 Agent 模式
当用 /team-build 一次性 dispatch 多个 agent 时，每个 agent 自动拿到 worktree 隔离，可以在重叠领域并行而不冲突。例：3 个 agent 同时 a) 重写 auth 模块、b) 加单元测试、c) 写迁移脚本——文件层互不打扰，最后人工 merge。这是 worktree 在 agent 工程上的核心价值。
自动清理、常见坑与与团队规范的配合
退出 worktree 时若无 commit / 无 untracked 文件，worktree 与临时 branch 自动删除；有改动则保留，路径与 branch 名在结果中返回。常见坑：1) branch 命名冲突（agent 用相同 slug）；2) uncommitted 残留拒清；3) 与 worktree-from-origin-main 工作流配合时要先 fetch origin。建议团队约定固定 branch prefix（如 wt/agent-<name>-<timestamp>）避免冲突。
FAQ
Worktree 跟普通 git branch 有什么本质区别？
Branch 是 commit 的指针，要切换工作树就得 checkout（覆盖文件）。Worktree 是独立的工作目录，多个 branch 同时存在于不同物理路径，互不覆盖。多 agent 并行刚需。
Subagent worktree 会污染主 repo 吗？
不会。worktree 路径独立，git 元数据通过 .git/worktrees/<id> 管理。无 commit 退出时整个 worktree + 临时 branch 自动删除，主 repo 干净。
国内用 Claude Code 能用 worktree 吗？
Worktree 是 git 自带功能与 Claude Code 客户端能力，本地执行不受网络限制。模型推理通过 QCode 通路接入 Claude，整体体验与境外一致。