Git Worktrees 用于为并行开发创建隔离工作区,使多个分支能够在不同目录中同时检出,从而在不暂存改动、不切换上下文、不污染主工作区的前提下推进工作。该技能提供结构化的 worktree 创建流程,并带有安全校验步骤。
用途与触发时机:适合开始不应影响主工作区的功能开发、同时推进多个特性、在隔离环境中测试改动、在继续其他工作的同时运行长时间任务,以及在不打断当前工作的情况下评审 PR。对于快速单文件修复、无需隔离的改动,或主工作区本身已干净的情况,不必使用 worktree。
目录选择优先级:创建前先检查是否已有 .worktrees/(隐藏,优先)或 worktrees/(可见)目录,两者都存在时优先 .worktrees/;其次查看 CLAUDE.md 或项目文档中的 worktree 位置约定与项目规范;若均未找到,则询问用户偏好,选项包括项目内的 .worktrees/(推荐,须加入 .gitignore)、项目内的 worktrees/(可见,须加入 .gitignore),或外部位置(如 ~/worktrees/project-name/)。
安全校验:在项目内创建 worktree 前,必须先确认所用目录已被忽略,例如执行 git check-ignore -q .worktrees 或 git check-ignore -q worktrees;返回 0 表示已正确忽略。若未被忽略,应先把对应目录加入 .gitignore、提交该改动,再继续创建,以免误提交 worktree 内容而产生包含重复代码的庞大混乱提交。
创建流程:第一步检测项目信息,包括项目名(basename $(git rev-parse --show-toplevel))、当前分支与默认分支;第二步创建 worktree,支持为新分支(git worktree add <worktree-path> -b <branch-name>)、已有分支(git worktree add <worktree-path> <existing-branch>)或指定基线(git worktree add <worktree-path> -b <branch-name> origin/main)三种方式;第三步自动检测项目类型并执行相应初始化,如存在 package.json 则安装依赖(按锁文件选择 npm、yarn 或 pnpm),存在 Cargo.toml 执行 cargo build,存在 requirements.txt 执行 pip install -r requirements.txt(有虚拟环境时在其中执行),存在 Gemfile 执行 bundle install,存在 go.mod 执行 go mod download;第四步运行基线测试确认初始状态干净,若测试失败则提示可能原因(缺少依赖、需要环境配置、基线分支已有失败),并给出排查修复、知情继续或中止创建三种选择;第五步报告就绪状态,包含位置、分支、基线、测试结果,以及进入与返回主工作区的路径。
日常管理:可用 git worktree list 列出全部 worktree;用 git worktree remove <worktree-path> 移除,有改动时可加 --force 强制移除;用 git worktree prune 清理目录已不存在的过期条目。
与工作流集成:在 plan 阶段,计划获批后可先创建 worktree、执行初始化、验证基线测试,再在隔离环境中开始实现;也可由 implementing-plans 在实现前提供 worktree 隔离选项,通过 /rpikit:git-worktrees 直接调用,并与 finishing-work 配合处理实现后的清理(本地合并则清理,创建 PR 则保留以供评审周期使用,放弃则清理),writing-plans 也可能为高风险改动指定 worktree 隔离。
项目内与外部位置:项目内 worktree 便于集中查找相关工作、随项目删除而清理,但需确保被 gitignore 且占用项目磁盘空间;外部 worktree 无需管理 gitignore、与项目结构分离、可经受项目目录变化,但分散在文件系统中且容易忘记清理。
需要避免的做法:未验证 gitignore 就创建项目内 worktree;跳过依赖安装;跳过基线测试;基线测试失败仍继续;使用含糊的 worktree 位置而不询问用户(默认 .worktrees/);不阅读 CLAUDE.md 中的项目约定;工作合并或放弃后遗留过期 worktree;对小型修复等无需隔离的改动过度使用 worktree。
清理检查项:移除前确认工作已合并或有意放弃、无未提交改动(或明确丢弃)、已合并的工作对应分支已删除、worktree 中无运行中的进程。