using-git-worktrees

使用 Git 工作树

概述

使用 git worktree 创建隔离的工作目录，以便并行处理开发任务；多个分支可同时检出，互不冲突。此技能会从选择目录到验证设置，强制执行确定性的多阶段流程，确保每个工作树在开始任何工作前都已准备就绪，可用于生产环境。

适用场景

• 开始一个不应干扰当前工作的新功能分支
• 同时处理多个任务（修复错误 + 开发功能）
• 创建干净的环境来进行测试或代码审查
• 运行耗时较长的进程（测试、构建），同时继续开发

阶段 1：选择工作树目录

[HARD-GATE] 不要跳过目录选择。检查优先级之前，不要假定默认路径。

严格按以下优先级顺序操作：

优先级 1：查找与任务匹配的现有工作树

检查任务是否已有对应的工作树：

git worktree list

如果存在匹配的工作树，请使用该工作树。不要创建重复项。

优先级 2：CLAUDE.md 中的工作树目录提示

检查项目的 CLAUDE.md，查看是否配置了工作树目录：

# Example CLAUDE.md entry
worktree-directory: ../worktrees

如果已指定，请在该目录下创建工作树。

优先级 3：询问用户

如果未配置提示，且没有明显的惯例，请询问用户应在哪里创建工作树。建议一个合理的默认路径：

../worktrees/<project-name>/<branch-name>

停止 — 继续操作前，先与用户确认工作树目录。

目录选择决策表

条件	操作
此分支已有工作树	切换到现有工作树
CLAUDE.md 中有 worktree-directory	使用配置的路径
项目已有工作树	使用相同的父目录模式
未找到惯例	询问用户，并建议使用 ../worktrees/<project>/<branch>
用户指定的路径位于仓库根目录内	发出警告 — 必须将其添加到 .gitignore

阶段 2：安全验证

[HARD-GATE] 所有安全检查通过前，不要创建任何工作树。

检查 .gitignore 是否涵盖

如果工作树目录位于仓库根目录内，请确保该目录已列入 .gitignore：

# Check if the worktree path would be tracked
git check-ignore <worktree-path>

如果未被忽略，请提醒用户，并建议将其添加到 .gitignore。

验证工作区是否干净

检查是否存在可能引发问题的未提交更改：

git status --porcelain

如果工作区不干净，请告知用户并询问如何继续：

• 先提交更改
• 暂存更改
• 仍然继续（创建工作树本身是安全的）

验证分支是否已存在于另一个工作树中

git worktree list

一个分支不能同时在两个工作树中检出。如果该分支已检出，请切换到对应的现有工作树。

安全检查决策表

检查项	结果	操作
路径位于仓库内，但未列入 .gitignore	失败	先添加到 .gitignore
分支已存在于另一个工作树中	失败	使用现有工作树
工作区不干净	警告	告知用户并询问其偏好
路径已存在（但不是工作树）	失败	选择其他路径
所有检查均通过	通过	继续执行阶段 3

阶段 3：创建工作树

# For a new branch
git worktree add <path> -b <branch-name> <base-branch>

# For an existing branch
git worktree add <path> <existing-branch>

务必告知用户工作树创建后的完整路径：

Worktree created at: /absolute/path/to/worktree
Branch: feature/my-feature
Base: main

停止 — 继续设置前，先确认工作树已成功创建。

阶段 4：项目设置与自动检测

创建工作树后，检测并运行项目的设置命令。

设置检测决策表

指示文件	生态系统	设置命令
pnpm-lock.yaml	Node.js（pnpm）	pnpm install
yarn.lock	Node.js（yarn）	yarn install
package-lock.json	Node.js（npm）	npm install
package.json（无锁文件）	Node.js（npm）	npm install
pyproject.toml + tool.poetry	Python（poetry）	poetry install
pyproject.toml（无 poetry）	Python（pip）	pip install -e .
setup.py	Python（pip）	pip install -e .
requirements.txt	Python（pip）	pip install -r requirements.txt
go.mod	Go	go mod download
Cargo.toml	Rust	cargo build
Gemfile	Ruby	bundle install
composer.json	PHP	composer install

多个生态系统

如果项目使用多个生态系统（例如，Go 后端搭配 Node.js 前端），请在相应的子目录中为检测到的每个生态系统运行设置命令。

环境文件

如果项目中有 .env.example 或 .env.template：

# Copy environment template if .env does not exist in worktree
cp .env.example .env  # then inform user to update values

阶段 5：干净基线测试验证

[HARD-GATE] 在基线测试通过或失败情况得到确认之前，不要进行任何工作。

在开始任何工作之前，运行项目的测试套件，建立干净的基线：

# Use the project's test command
# Node.js: npm test / yarn test / pnpm test
# Python: pytest / python -m pytest
# Go: go test ./...
# Rust: cargo test

目的：

• 确认工作树已正确设置
• 确认所有测试在进行更改前均通过
• 此后出现的任何测试失败均由你的更改导致，而非既有问题

如果基线测试失败：

• 向用户报告失败情况
• 在了解基线情况之前，不要继续工作
• 基础分支可能存在需要先处理的测试故障

阶段 6：报告位置

始终向用户清楚报告工作树的位置：

Worktree ready:
  Path:    /Users/dev/worktrees/myproject/feature-auth
  Branch:  feature/auth-refactor
  Base:    main
  Setup:   npm install (completed)
  Tests:   24 passed, 0 failed

清理模式

合并或完成工作后

# Remove the worktree
git worktree remove <path>

# If files remain (dirty worktree), force removal
git worktree remove --force <path>

# Prune stale worktree references
git worktree prune

列出所有工作树

git worktree list

处理已锁定的工作树

如果工作树已锁定（以防止意外删除）：

# Unlock before removing
git worktree unlock <path>
git worktree remove <path>

反模式／常见错误

反模式	错误原因	应采取的做法
为同一分支创建重复的工作树	Git 不允许这样做；浪费时间	先检查 git worktree list
在仓库内创建工作树但未添加到 .gitignore	工作树文件会显示为未跟踪文件	将路径添加到 .gitignore
在工作树中跳过依赖项安装	缺少依赖项会导致构建／测试失败	始终运行项目设置
跳过基线测试运行	无法区分既有故障与新故障	开始工作前运行测试
假定工作树具有相同的环境变量	工作树之间不会共享 .env 文件	复制并配置 .env
合并后留下过时的工作树	浪费磁盘空间，也会让 git worktree list 的输出变得混乱	分支完成后删除工作树
强制删除含有未提交工作的工作树	会永久丢失数据	先提交或暂存更改

集成点

技能	集成方式
finishing-a-development-branch	在工作树中完成工作后，使用此技能进行合并或创建 PR
dispatching-parallel-agents	在独立的工作树中运行 Agent，实现真正的隔离
verification-before-completion	离开工作树前验证工作
self-learning	检查 CLAUDE.md 中对工作树目录的偏好
planning	创建工作树通常是执行计划的第一步

技能类型

RIGID — 严格按照此流程执行。必须按顺序完成每个阶段。不要跳过安全检查。不要跳过基线测试验证。未确认目录前，不要创建工作树。