using git worktrees

用途

该技能用于创建隔离的 Git worktree 工作区。Git worktree 共享同一仓库，但提供独立的工作目录，使开发者可以同时在多个分支上工作而无需来回切换。其核心原则是：系统化的目录选择 + 安全校验 = 可靠的隔离。

技能启动时会声明：“I'm using the Using Git Worktrees skill to set up an isolated workspace.”

目录选择流程

按以下优先级顺序执行：

ls -d .worktrees 2>/dev/null     # 首选（隐藏）
ls -d worktrees 2>/dev/null      # 备选

若找到则使用该目录；若两者都存在，优先使用 .worktrees。

检查 CLAUDE.md：

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

若其中指定了偏好，则直接使用，不再询问。

询问用户：若既无目录也无 CLAUDE.md 偏好，则询问用户选择：

.worktrees/（项目内，隐藏）
~/.config/superpowers/worktrees/<project-name>/（全局位置）

安全校验

对于项目内目录（.worktrees 或 worktrees），创建 worktree 前必须校验 .gitignore：

grep -q "^\.worktrees/$" .gitignore || grep -q "^worktrees/$" .gitignore

若未包含，则按“立即修复损坏之处”的原则，向 .gitignore 添加相应行、提交该变更，然后继续创建 worktree。这一步至关重要，可防止 worktree 内容被意外提交到仓库。

对于全局目录（~/.config/superpowers/worktrees），因完全位于项目之外，无需校验 .gitignore。

创建步骤

检测项目名称：

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

创建 worktree：

case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/superpowers/worktrees/*)
    path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

运行项目初始化，自动检测并执行相应命令：

Node.js：若存在 package.json，执行 npm install
Rust：若存在 Cargo.toml，执行 cargo build
Python：若存在 requirements.txt，执行 pip install -r requirements.txt；若存在 pyproject.toml，执行 poetry install
Go：若存在 go.mod，执行 go mod download

验证干净基线，运行测试确保 worktree 起始状态正常（如 npm test、cargo test、pytest、go test ./...）。若测试失败，报告失败并询问是继续还是排查；若通过，报告就绪。
报告位置：

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

快速参考

情况	操作
.worktrees/ 存在	使用它（校验 .gitignore）
worktrees/ 存在	使用它（校验 .gitignore）
两者都存在	使用 .worktrees/
两者都不存在	检查 CLAUDE.md → 询问用户
目录不在 .gitignore 中	立即添加并提交
基线测试失败	报告失败并询问
无 package.json/Cargo.toml	跳过依赖安装

常见错误

跳过 .gitignore 校验：会导致 worktree 内容被跟踪、污染 git status。修复：创建项目内 worktree 前始终 grep .gitignore。
假设目录位置：会造成不一致、违反项目约定。修复：遵循优先级——已有目录 > CLAUDE.md > 询问。
在测试失败时继续：无法区分新缺陷与既有问题。修复：报告失败并获取明确许可后再继续。
硬编码初始化命令：在采用不同工具的项目上会失效。修复：从项目文件（package.json 等）自动检测。

示例工作流

You: I'm using the Using Git Worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify .gitignore - contains .worktrees/]
[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

红线

绝不：在未校验 .gitignore 的情况下创建项目内 worktree；跳过基线测试验证；在测试失败时未经询问就继续；在目录位置不明确时自行假设；跳过 CLAUDE.md 检查。

始终：遵循目录优先级（已有 > CLAUDE.md > 询问）；对项目内目录校验 .gitignore；自动检测并运行项目初始化；验证干净的测试基线。

集成

被以下调用：skills/collaboration/brainstorming（第 4 阶段）、任何需要隔离工作区的技能。

搭配使用：skills/collaboration/finishing-a-development-branch（清理）、skills/collaboration/executing-plans（实际工作在此进行）。