是什么
Worktrees 利用 git worktree 机制为每个并行 Claude Code 会话提供独立的工作目录和分支，共享同一仓库历史。这样多个会话可以同时编辑文件而不互相干扰，是并行开发的文件隔离层。
核心机制
创建 Worktree 会话：claude --worktree <name> 在 .claude/worktrees/<name>/ 下创建独立 checkout，分支名为 worktree-<name>。
基础分支选择：
- 默认从
origin/HEAD（远程默认分支）创建，保证干净起点 - 设置
worktree.baseRef: "head"从本地 HEAD 创建（携带未推送的提交） - 传入 PR 号：
claude --worktree "#1234"从该 PR 的 HEAD 创建
复制 gitignored 文件：.worktreeinclude 文件（.gitignore 语法）指定哪些被 gitignore 的文件（如 .env）在创建 worktree 时自动复制进去。
Subagent 隔离：在 Subagent frontmatter 中设置 isolation: worktree，每个 Subagent 自动获得独立 worktree，完成后自动清理（无变更时）。
清理规则：
- 无未提交变更/未追踪文件/新提交：自动删除 worktree 和分支
- 有变更：提示保留或删除
- 非交互式（
-p）：不自动清理，需手动git worktree remove
关键细节
- 创建命名 worktree：
claude --worktree feature-auth - 自动生成名称：
claude --worktree（如bright-running-fox） - 从 PR 创建：
claude --worktree "#1234" - 建议将
.claude/worktrees/加入.gitignore - 孤立的 Subagent worktree 在启动时自动清理（超过
cleanupPeriodDays且无变更） - 手动清理：
git worktree list+git worktree remove <path>
关联
- agents — 四种并行方式对比，Worktrees 是文件隔离层
- sub-agents —
isolation: worktree配置 - agent-view — Agent View 自动为后台会话创建 worktree
实践要点
- Agent View 的后台会话自动使用 worktree，无需手动配置
.worktreeinclude解决.env等配置文件不在 worktree 中的问题- 删除 Agent View 会话会同时删除其 worktree（含未提交变更），删前先 push
- 非 git 仓库中的并行会话直接写入工作目录，无法隔离，避免并行编辑相同文件
- 可通过
WorktreeCreateHook 完全自定义 worktree 创建逻辑（支持非 git VCS）