| name | using-git-worktrees |
| description | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification |
使用 Git Worktrees
概述
Git worktree 创建共享同一仓库的隔离工作空间，允许同时在多个分支上工作而无需切换。
核心原则： 系统的目录选择 + 安全验证 = 可靠的隔离。
开始时宣布： "我正在使用 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 偏好：
未找到 worktree 目录。我应该在哪里创建 worktrees？
1. .worktrees/（项目本地，隐藏）
2. ~/.config/superpowers/worktrees/<project-name>/（全局位置）
你偏好哪个？
安全验证
对于项目本地目录（.worktrees 或 worktrees）
创建 worktree 前必须验证目录被忽略：
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
如果未被忽略：
按照 Jesse 的规则"立即修复坏掉的东西"：
- 在 .gitignore 中添加适当的行
- 提交更改
- 继续创建 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
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
3. 运行项目设置
自动检测并运行适当的设置：
if [ -f package.json ]; then npm install; fi
if [ -f Cargo.toml ]; then cargo build; fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi
if [ -f go.mod ]; then go mod download; fi
4. 验证干净的基线
运行测试以确保 worktree 以干净状态开始：
npm test
cargo test
pytest
go test ./...
如果测试失败： 报告失败，询问是继续还是调查。
如果测试通过： 报告就绪。
5. 报告位置
Worktree 已在 <full-path> 就绪
测试通过（<N> 个测试，0 失败）
准备好实施 <feature-name>
快速参考
| 情况 | 操作 |
|---|
.worktrees/ 存在 | 使用它（验证被忽略） |
worktrees/ 存在 | 使用它（验证被忽略） |
| 两者都存在 | 使用 .worktrees/ |
| 两者都不存在 | 检查 CLAUDE.md → 询问用户 |
| 目录未被忽略 | 添加到 .gitignore + 提交 |
| 基线测试期间失败 | 报告失败 + 询问 |
| 没有 package.json/Cargo.toml | 跳过依赖安装 |
常见错误
跳过忽略验证
- 问题： Worktree 内容被跟踪，污染 git status
- 修复： 创建项目本地 worktree 前始终使用
git check-ignore
假设目录位置
- 问题： 造成不一致，违反项目约定
- 修复： 遵循优先级：现有 > CLAUDE.md > 询问
在失败的测试下继续
- 问题： 无法区分新 bug 和预先存在的问题
- 修复： 报告失败，获得明确许可后再继续
硬编码设置命令
- 问题： 在使用不同工具的项目上失败
- 修复： 从项目文件自动检测（package.json 等）
示例工作流
你：我正在使用 using-git-worktrees 技能来设置隔离的工作空间。
[检查 .worktrees/ - 存在]
[验证被忽略 - git check-ignore 确认 .worktrees/ 被忽略]
[创建 worktree：git worktree add .worktrees/auth -b feature/auth]
[运行 npm install]
[运行 npm test - 47 通过]
Worktree 已在 /Users/jesse/myproject/.worktrees/auth 就绪
测试通过（47 个测试，0 失败）
准备好实施 auth 功能
红旗
绝不：
- 在不验证目录被忽略的情况下创建 worktree（项目本地）
- 跳过基线测试验证
- 在测试失败且未询问的情况下继续
- 在不明确时假设目录位置
- 跳过 CLAUDE.md 检查
始终：
- 遵循目录优先级：现有 > CLAUDE.md > 询问
- 为项目本地目录验证目录被忽略
- 自动检测并运行项目设置
- 验证干净的测试基线
集成
被调用：
- brainstorming（步骤 4）—— 当设计被批准且实施随之进行时 —— 必需
- subagent-driven-development —— 必需：在执行任何任务前
- executing-plans —— 必需：在执行任何任务前
- 需要隔离工作空间的任何技能
配合：
- finishing-a-development-branch —— 工作完成后清理 —— 必需
