worktree

工作树隔离

先选择分支。工作区设置会使用当前角色，并在调用方的隔离权限范围内直接使用工具。它不需要模型工作线程或路由解析。之后的任何工作线程调度都遵循 shared/references/model-preview.md，并使用调用方已批准的快照，不再重新解析，也不额外创建工作线程。

确保当前工作在隔离的工作区中进行，不要影响用户的主检出目录。大多数编码工具现在会在会话开始时默认创建工作树，因此请先检测是否已经隔离。

常见的调用方是需要隔离的用户。实施工作流也可能在计划确定了相互独立的任务后提出隔离需求。创建可撤销的工作树属于实施请求的范围。基于提交的集成仍需单独授权。除此之外，implement-and-review 使用单个顺序式工作树任务流。

操作顺序：检测现有隔离 -> 优先使用工具链原生工作树工具 -> 回退到普通 git。绝不要创建工具链无法识别的工作树。

两种模式，由调用方的需求决定：

• 新建工作（默认）。 未指定特定引用——从基准分支（主干）创建一个新分支。
• 隔离现有引用。 调用方指定要隔离处理的引用——PR 头引用、现有分支或提交。将工作树关联到该引用，而不是创建新分支。这种模式有一条不可违背的 git 规则：一个分支一次只能在一个工作树中检出。 如果指定的引用已在某处检出（最常见的情况是它是主检出目录中的当前分支），请勿为其创建第二个工作树——报告该引用已在 <path> 处检出，然后让调用方决定如何处理（在原处工作；或者，只有在必须使用独立干净工作树时，才在同一提交处创建一个 分离 工作树）。绝不要让同一分支出现在两个工作树中。

以下步骤（检测 -> 原生工具 -> git 回退）适用于两种模式；模式只会改变检出的内容以及向调用方报告的信息。

步骤 0：检测现有隔离

创建任何内容之前，请检查当前目录是否已经是一个关联工作树。将解析后的绝对 git 目录与解析后的绝对公共 git 目录进行比较——先分别将它们解析为绝对路径，再比较，而不要比较原始的 git rev-parse 输出。Git 会根据当前目录混用绝对路径和相对路径（从普通检出目录的子目录运行时，--git-dir 会返回绝对路径，而 --git-common-dir 可能返回相对路径），因此直接比较字符串会错误地得出“已隔离”的结论：

git rev-parse --absolute-git-dir                     # absolute git dir for this worktree
(cd "$(git rev-parse --git-common-dir)" && pwd -P)   # absolute shared (common) git dir

如果两个绝对路径相同，则这是普通检出目录——继续步骤 1。

如果两者不同，则当前目录位于关联工作树或子模块中。请区分二者：

git rev-parse --show-superproject-working-tree

• 输出非空 -> 当前目录位于子模块中；将其视为普通检出目录，并继续步骤 1。
• 输出为空 -> 当前目录已经位于隔离工作树中。报告工作树路径（git rev-parse --show-toplevel）和当前分支。不要创建另一个工作树——从工作树创建工作树会落在错误的目录中，并且创建当前工作树的工具链无法看到它。然后在原处工作：在新建工作模式下，继续在此处工作；在隔离现有引用模式下，在此处检出该引用（除非它已经是当前分支），而不是嵌套创建工作树。

步骤 1：优先使用工具链原生工作树工具

如果工具链提供原生工作树功能，请使用它，然后停止。在 Claude Code 中，这是 EnterWorktree 工具；其他工具链可能提供 /worktree 命令或 --worktree 标志。原生工具会放置、跟踪并清理工作树，使工具链能够管理它。私自运行 git worktree add 会创建工具链无法看到、无法切换到或无法清理的幽灵状态。

步骤 2：Git 回退方案

仅当没有原生工具且步骤 0 未发现现有隔离环境时执行。

1. 从仓库根目录运行。 下方的 .worktrees/ 和 .gitignore 路径均相对于仓库根目录，而技能会从用户当前目录运行，该目录可能是某个子目录——因此先切换到根目录：cd "$(git rev-parse --show-toplevel)"。否则，.worktrees/<branch> 和对 .gitignore 的修改会落在子目录中（例如 src/.worktrees/...、src/.gitignore），而不是仓库根目录。
2. 根据工作描述选择有意义的分支名称（例如 feat/login、fix/email-validation）——避免使用含义不明的自动生成名称。选择一个基准分支（默认：origin 的默认分支，否则为 main）。
3. 创建任何内容之前，确保 .worktrees/ 已被 git 忽略，以免工作树内容被提交：检查 git check-ignore -q .worktrees/——末尾要带斜杠，这样即使目录尚不存在，也会遵循现有的、仅针对目录的 .worktrees/ 规则（不带斜杠的 git check-ignore .worktrees 会漏掉这条规则，并错误地将配置正确的仓库标记为有未提交更改）。如果该目录未被忽略，则在 .gitignore 中添加一行 .worktrees/。
4. 尽力刷新基准分支，同时不影响当前检出：git fetch origin <from-branch>。此操作失败不应中止流程——如果出现错误（没有 origin 远程、远程名称不同，或分支仅存在于本地），不要中止；继续下一步并使用本地引用。
5. 创建工作树——命令取决于模式：
   • 新建工作： git worktree add -b <branch-name> .worktrees/<branch-name> origin/<from-branch>（如果 origin/<from-branch> 不存在，则使用本地的 <from-branch> 引用）。此操作会从基准分支创建一个新分支。
   • 隔离现有引用： 直接检出该引用，而不是创建分支——对于现有分支或标签，使用 git worktree add .worktrees/<slug> <target-ref>。对于 PR，请在本地分支上检出（绝不要使用分离的 FETCH_HEAD——那样会使修复循环的提交成为孤立提交，而无法更新 PR）：git fetch origin pull/<n>/head:pr-<n>，然后运行 git worktree add .worktrees/pr-<n> pr-<n>。（如果要恢复对 PR 的推送跟踪，则先以分离状态创建工作树——git worktree add --detach .worktrees/pr-<n>——然后进入该目录并运行 gh pr checkout <n>；此方法适用于 fork，也适用于来自 fork 的 PR。）如果 git 报告该引用已在其他位置检出，请遵循 两种模式 下的“已检出”规则——不要强行创建第二个工作树。
6. 切换到该工作树：cd .worktrees/<branch-name>（或 .worktrees/<slug>）。

如果 git worktree add 因沙盒或权限错误而失败，请使用主机的常规权限申请或提权流程执行相同操作。保留所请求的引用和隔离环境。仅在获得所需权限后重试；已有创建工作树的权限并不意味着可以绕过主机控制。

如果权限申请被拒绝、无法申请，或获准重试后仍然失败，请报告阻碍。只有在需要更改所请求的工作区或放弃隔离环境之前，才询问用户如何决定。除非用户明确批准在当前检出目录中工作，否则不要改动它。条件允许时，继续进行其他已授权的工作。

其他工作树操作

直接使用 git——无需包装器：

git worktree list                          # list worktrees
git worktree remove .worktrees/<branch>    # remove a worktree
cd .worktrees/<branch>                     # switch to a worktree
cd "$(git rev-parse --show-toplevel)"      # return to the current checkout root

何时创建工作树

仅在尚未处于隔离环境中且需要单独工作区时创建（步骤 1/2）：

• 在保持当前检出目录可供其他工作使用的同时，审查或修复 PR
• 无需频繁切换分支，即可并行处理多个功能

如果单项工作可以在当前检出目录的分支上完成，则不要创建工作树——如果步骤 0 显示你已处于工作树中，更绝不要创建。

故障排除

“Worktree 已存在”：该路径已被占用。请切换到该路径（cd .worktrees/<branch>），或先将其移除（git worktree remove .worktrees/<branch>），然后再重新创建。

“无法移除 Worktree：它是当前 Worktree”：请先 cd 到 Worktree 外，再运行 git worktree remove。

---

改编自 compound-engineering-plugin（MIT）。请参阅 NOTICE。