worktrees

工作树

为功能开发提供独立工作区，并确保起点经过验证且干净。优先顺序：检测现有隔离环境 → 使用运行环境原生工作区工具 → 手动回退到 git worktree。切勿与运行环境对抗。

步骤 0 — 检测并征求同意

检查你是否已在关联工作树中：

GIT_DIR=$(cd "$(git rev-parse --git-dir)" && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" && pwd -P)

• GIT_DIR != GIT_COMMON → 很可能是关联工作树，但要先排除子模块：如果 git rev-parse --show-superproject-working-tree 输出了路径，说明你在子模块中——将其视为普通检出。否则你已经处于隔离环境中：报告路径和分支，跳过创建，进入步骤 2。
• GIT_DIR == GIT_COMMON → 普通检出。如果用户明确表达了对工作树的偏好，就直接遵从。如果没有，请询问：“要我在独立工作树中进行设置，以免改动你当前的分支吗？”如果用户拒绝 → 就地工作，进入步骤 2。

完成条件：你已确定自己属于这三种情况中的哪一种；如果要创建工作树，也已征得同意。

步骤 1 — 创建工作区

1a. 优先使用原生工具。 如果运行环境提供工作区/工作树机制（例如名为 EnterWorktree 的工具、/worktree 命令或 --worktree 标志），请使用它并进入步骤 2。原生工具会自行管理位置、分支和清理；同时手动创建工作树会留下运行环境无法识别的幽灵状态。仅当不存在原生工具时，才使用后备方案。

1b. Git 后备方案。 按优先级选择目录：

1. 用户明确指定的目录——始终优先
2. 仓库根目录中已有的 .worktrees/
3. 已有的 worktrees/（若两者都存在，则优先 .worktrees/）
4. 两者都不存在 → 创建 .worktrees/

将所选目录赋给 $DIR，并在以下每条命令中使用它——只有命令遵循上述优先级，这份优先级列表才有实际意义：

DIR=.worktrees   # or DIR=worktrees if that existing dir was selected above

在项目目录内创建任何内容之前，你必须确认该目录已被 git 忽略。将此条目保留为未提交的工作树更改——git 会立即遵循它；而在此处提交 .gitignore 会向用户的当前分支写入提交，这恰恰违背了这项技能承诺不触碰当前分支的原则：

git check-ignore -q "$DIR" || printf '%s/\n' "$DIR" >> .gitignore

然后创建并进入工作树：

git worktree add "$DIR/<branch-name>" -b "<branch-name>"

如果因沙箱/权限错误导致创建失败，请告知用户并改为就地工作。

完成条件：你已进入工作区（或已说明无法进入的原因）。

步骤 2 — 安装依赖项

根据锁定文件/清单自动检测包管理器并运行安装命令：pnpm-lock.yaml → pnpm，bun.lock* → bun，yarn.lock → yarn，package-lock.json/裸 package.json → npm，Cargo.toml → cargo build，uv.lock → uv，poetry.lock → poetry，requirements.txt → pip，go.mod → go mod download。没有清单 → 跳过。

步骤 3 — 干净基线

使用 docs/agents/project.md 中的命令运行测试套件（文件缺失 → 说明情况，建议使用 setup-repo，并使用对应生态的默认测试运行器）。

• 基线通过 → 继续。
• 基线失败 → 停止并在继续前询问用户。从失败的基线开始，会导致无法判断哪些是你引入的问题，哪些是已有问题。

报告

Workspace ready at <absolute path> (branch <name>)
Baseline: <N> tests passing, 0 failures
Ready to start <task>.

红线——绝不可

• 步骤 0 已发现你在工作树中时，仍然创建工作树
• 原生工具存在时，仍使用 git worktree add
• 未检查忽略规则就创建项目内的工作树目录
• 跳过基线测试，或基线失败后未经询问就继续