一、worktree隔离模式概述
子代理（Subagents）是Claude Code中用于并行处理任务的强大机制。在多子代理协作场景中，如果多个子代理同时读写同一工作目录的文件，会产生文件冲突、修改覆盖等问题。worktree隔离模式通过为每个子代理创建独立的Git工作树，从根本上解决了这一问题。
独立工作环境
每个子代理在独立的Git工作树中工作，拥有完全隔离的文件系统视图
避免文件冲突
多个子代理同时修改同一文件时不会互相干扰，各自拥有独立的副本
独立分支管理
每个子代理有自己的分支和目录，修改互不影响，完成后可单独合并
自动清理回收
任务完成后可自动清理工作树和分支，不留垃圾文件
二、EnterWorktree创建隔离
EnterWorktree工具是进入worktree隔离模式的入口，它为当前子代理创建一个新的Git工作树并切换到该工作树中。
EnterWorktree(name="my-feature")
# 创建一个名为 my-feature 的新工作树
# 自动创建新分支并切换到该分支
# 工作树目录位于 .claude/worktrees/my-feature/
参数说明：
- name（可选）：工作树名称，用于标识。每个"/"分隔的段可包含字母、数字、点、下划线和短横线，最长64字符。不提供则自动生成随机名称。
- path（可选）：指定已存在的worktree路径进入。必须是在当前仓库`git worktree list`中注册的路径。与name互斥。
创建成功后，子代理的当前工作目录自动切换到新worktree中，后续所有文件操作都在隔离环境中进行。
三、隔离模式下的工作流
进入worktree隔离模式后，子代理的工作流发生显著变化：
- 自由读写：子代理在worktree中自由读写文件，不受主工作目录的限制
- 不影响主目录：所有修改仅影响当前worktree，主工作目录的文件保持不变
- 多代理并行：多个子代理可以同时工作在不同的worktree中，彼此完全隔离
- 分支管理：通过Git分支管理不同的修改，每个worktree默认基于当前HEAD创建新分支
最佳实践：在分配子代理任务时，提前规划好每个子代理的worktree名称和分支策略，确保不同子代理处理不同功能模块，避免后续合并时的冲突。
四、ExitWorktree退出清理
ExitWorktree工具用于退出worktree隔离模式，将子代理的工作目录恢复为主代理的原始目录。
| 参数 | 说明 | 适用场景 |
|---|
| keep | 保留工作树和分支供后续使用 | 任务未完成，需要后续继续工作 |
| remove | 删除工作树和分支 | 任务已完成，进行清理回收 |
| discard_changes | 丢弃未提交的修改强制删除 | 任务废弃或有冲突无法正常删除 |
注意：当使用remove操作时，如果worktree中有未提交的文件或未合并的提交，ExitWorktree会拒绝删除并列出变更内容。此时需与用户确认后，再使用discard_changes=true参数强制删除。
退出后，子代理的当前目录恢复为调用EnterWorktree之前的位置，所有worktree相关的环境信息被清除。
五、worktree使用场景
worktree隔离模式在以下场景中尤为适用：
并行功能开发
不同子代理开发不同功能模块，每人拥有独立的worktree和分支，互不干扰
并行Bug修复
在不同worktree中修复不同Bug，每个修复独立测试和验证，避免相互影响
实验性修改
在不影响主代码的情况下尝试新方案，即使失败也不会影响主线代码
代码审查
在隔离环境中审查和测试PR，安全运行和验证后再合并到主分支
核心原则：当多个子代理需要同时工作时，始终为每个子代理创建独立的worktree。这不仅避免了文件冲突，还通过Git分支机制提供了完整的版本管理能力，是Claude Code多代理协作的最佳实践。