用途:指导在编码任务中何时以及如何创建 Git worktree。核心原则是“仅在必要时创建,并为每个创建的 worktree 配好清理路径”,worktree 是并发检出另一份 Git 历史的例外手段,而非通用安全措施。
主要能力与流程:
- 环境检测:变更前记录仓库根、HEAD、分支/游离状态、暂存/未暂存/未跟踪路径、进行中的 Git 操作,并运行 git worktree list --porcelain;区分托管/非托管/未知工作区语义。遇到未解决冲突、进行中的 merge/rebase/cherry-pick/revert/bisect 或无法解释的游离 HEAD 应停止。不自动 stash、reset、clean、广泛暂存或提交。
- 必要性判断:仅当另一分支需保持检出、无关脏状态阻碍安全切换、或用户/仓库权威明确要求时,才创建一个任务自有 worktree。任务复杂度、规划、TDD、子代理或分支名本身不构成理由;同一任务的子代理共享一个工作区。
- 安全放置:仅在目标目录已被忽略(git check-ignore)时沿用仓库约定,不得仅为托管 worktree 而修改 .gitignore;否则使用仓库外任务专属临时目录。
- 最小检出:优先复用已有分支;仅在需要独立历史时新建分支。托管主机应使用其原生 Worktree/Handoff 生命周期,并回读任务工作区、默认 cwd、worktree 根、HEAD/分支状态四项后置条件。仅在确认非托管时才用 shell 回退:git worktree add <exact-path> <branch> 或 git worktree add -b <branch> <exact-path> <start-point>,不使用 force 标志。
- 基线与清理:只运行项目明确要求的安装步骤,不凭清单文件推断安装依赖;运行最小基线验证。报告路径、分支、起始 HEAD、基线结果、负责人与清理触发条件,创建协调者负责至清理完成或显式移交。
适用场景:需要并发检出、脏状态阻碍切换、或仓库政策要求隔离的编码任务。
限制与红线:不得仅因任务改代码就创建 worktree;不得为创建 worktree 而改 .gitignore;不得盲目安装依赖;不得每个子代理建一个 worktree;不得把 Git 回读、路径前缀或命令级 workdir 当作托管任务绑定证据;不得例行执行全局 prune 或强制清理;不得删除脏、未跟踪、锁定、用户所有或归属不明的资源。具体托管主机契约与项目政策细节暂未提供。