使用 Git Worktrees

概述

Git worktrees 可创建共享同一仓库的隔离工作区，从而无需切换分支即可同时在多个分支上开展工作。

核心原则：系统化的目录选择 + 安全性验证 = 可靠的隔离。

起始时需声明：“我正在使用 using-git-worktrees 技能来设置一个隔离工作区。”

目录选择流程

按以下优先级顺序执行：

1. 检查已存在的目录

# 按优先级顺序检查
ls -d .worktrees 2>/dev/null     # 首选（隐藏目录）
ls -d worktrees 2>/dev/null      # 备选

若发现任一目录存在：直接使用该目录；若两者均存在，则以 .worktrees 为准。

2. 检查 CLAUDE.md

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

若其中明确指定了偏好路径：直接采用，无需额外询问。

3. 向用户询问

若既无现有目录，CLAUDE.md 中也未指定偏好路径：

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees// (global location)

Which would you prefer?

安全性验证

针对项目本地目录（.worktrees 或 worktrees）

必须在创建 worktree 前验证目标目录是否已被忽略：

# 检查目录是否被忽略（尊重本地、全局及系统级 .gitignore）
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

若未被忽略：

依据 Jesse 的规则“立即修复损坏的事物”：

1. 向 .gitignore 添加对应条目
2. 提交该变更
3. 继续执行 worktree 创建

为何关键：防止意外将 worktree 内容提交至仓库。

针对全局目录（~/.config/superpowers/worktrees）

无需进行 .gitignore 验证——该路径完全位于项目之外。

创建步骤

1. 推断项目名称

project=$(basename "$(git rev-parse --show-toplevel)")

2. 创建 worktree

# 确定完整路径
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/superpowers/worktrees/*)
    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# 使用新分支创建 worktree
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. 运行项目初始化

自动识别并运行对应初始化流程：

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

4. 验证干净基线

运行测试，确保 worktree 起始状态干净：

# 示例命令（请根据项目实际选用）
npm test
cargo test
pytest
go test ./...

若测试失败：报告失败详情，并询问是否继续或先排查问题。

若测试通过：报告就绪状态。

5. 报告位置

Worktree ready at 
Tests passing ( tests, 0 failures)
Ready to implement 

快速参考

常见错误

跳过忽略验证

• 问题：worktree 内容被 Git 跟踪，污染 git status 输出
• 修复：创建项目本地 worktree 前，始终使用 git check-ignore 验证

主观假定目录位置

• 问题：导致不一致，违反项目约定
• 修复：严格遵循优先级：已有目录 > CLAUDE.md > 用户询问

在测试失败时继续推进

• 问题：无法区分新增缺陷与既有问题
• 修复：报告失败详情，并获得用户明确许可后再继续

硬编码初始化命令

• 问题：在使用不同工具链的项目中失效
• 修复：基于项目文件（如 package.json 等）自动识别并执行

示例工作流

You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run npm install]
[Run npm test - 47 passing]

Worktree ready at /Users/jesse/myproject/.worktrees/auth
Tests passing (47 tests, 0 failures)
Ready to implement auth feature

危险信号（Red Flags）

绝不允许：

• 未验证项目本地 worktree 目录是否被忽略即创建
• 跳过基线测试验证
• 未经询问即在测试失败时继续推进
• 在路径不明确时主观假定目录位置
• 跳过对 CLAUDE.md 的检查

必须做到：

• 严格遵循目录选择优先级：已有目录 > CLAUDE.md > 用户询问
• 对项目本地目录，务必验证其是否被 .gitignore 忽略
• 自动识别并运行项目初始化流程
• 验证测试基线是否干净

集成说明

调用方：

• brainstorming（第 4 阶段）——设计方案获准且即将进入实现阶段时，必需
• subagent-driven-development —— 执行任何任务前，必需
• executing-plans —— 执行任何任务前，必需
• 任何需要隔离工作区的技能

配套技能：

• finishing-a-development-branch —— worktree 工作完成后，必需用于清理