2026年8月31日

using-git-worktrees 技能——无需与运行环境对抗的隔离工作区

using-git-worktrees 技能如何在功能开发前搭建干净、隔离的工作区——以及为什么它会在动手之前先检查是否已有隔离。

直接在工作分支上开始实现,是产生无法追溯状态的可靠方式。using-git-worktrees 技能提供了一套结构化流程,在任何功能开发开始之前搭建隔离工作区。其核心原则是:先检测已有隔离,优先使用原生工具而非回退到 git,并且绝不与运行环境对抗。

第 0 步——创建之前先检测

第一个动作始终是检测,而不是创建。两条 shell 命令即可确定状态:比较 GIT_DIR 与 GIT_COMMON_DIR 可揭示当前目录是否已经是链接工作树。如果两者不同,说明工作区已经隔离——不会创建新的工作树。这里还有一个子模块防护:在 git 子模块内部也会出现相同的路径差异,因此该技能会检查 git rev-parse --show-superproject-working-tree 以区分这两种情况。

如果当前目录未隔离,且用户尚未表明偏好,该技能会在继续之前征求同意。如果用户拒绝,则继续在原处工作。

原生工具优先

当需要隔离时,该技能会检查运行时是否已提供工作树机制——名为 EnterWorktree 的工具、/worktree 命令或 --worktree 标志。如果存在,就使用它。原生工具会自动处理目录放置、分支创建和清理。在原生工具可用时使用 git worktree add,会产生运行时无法追踪的幻影状态。

只有在不存在原生工具时,该技能才回退到手动创建 git 工作树。目录选择遵循优先级:现有的项目本地目录(.worktrees/ 或 worktrees/),然后是全局目录(~/.worktrees/project/),然后是说明中声明的偏好,最后是项目根目录下默认的 .worktrees/。

创建前的安全检查

对于项目本地目录,该技能会在创建任何内容之前运行 git check-ignore。如果该目录尚未被忽略,就将其加入 .gitignore 并先提交该更改。这可以防止工作树内容被跟踪并污染 git 状态。~/.worktrees/ 下的全局目录位于任何仓库之外,无需忽略验证。

设置与基线

工作区存在后,该技能会从清单文件自动检测项目的包管理器或构建工具,并运行相应的安装命令。然后运行项目的规范测试命令。如果测试失败,它会报告失败并询问是否继续——在基线失败的情况下工作,将无法区分新的回归与既有的问题。

using-git-worktrees 技能在功能开发开始时以及执行计划之前被调用。当基线测试意外失败时,它会自然地与systematic-debugging 技能衔接。关于 Datarim 的整体工作流,请参阅什么是 Datarim。