using-git-worktrees

Git Worktree の使用

概要

Git worktree を使用すると、同じリポジトリを共有する分離されたワークスペースを作成でき、ブランチを切り替えずに複数のブランチで同時に作業できます。

基本原則： ディレクトリを体系的に選択し、安全性を確認することで、確実に分離できます。

開始時に宣言： 「using-git-worktrees スキルを使用して、分離されたワークスペースをセットアップします。」

ディレクトリの選択プロセス

次の優先順位に従ってください。

1. 既存のディレクトリを確認する

# Check in priority order
ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

見つかった場合： そのディレクトリを使用します。両方存在する場合は、.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/<project-name>/ (global location)

Which would you prefer?

安全性の確認

プロジェクト内のディレクトリ（.worktrees または worktrees）の場合

worktree を作成する前に、ディレクトリが ignore 対象であることを必ず確認してください。

# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

ignore 対象でない場合：

Jesse のルール「問題はすぐに修正する」に従います。

1. .gitignore に適切な行を追加する
2. 変更をコミットする
3. worktree の作成に進む

重要な理由： worktree の内容を誤ってリポジトリにコミットするのを防ぎます。

グローバルディレクトリ（~/.config/superpowers/worktrees）の場合

プロジェクトの外部にあるため、.gitignore の確認は不要です。

作成手順

1. プロジェクト名を検出する

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

2. Worktree を作成する

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

# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. プロジェクトをセットアップする

適切なセットアップ方法を自動検出して実行します。

# Ruby on Rails (primary)
if [ -f Gemfile ]; then bundle install; fi

# Rails + SQLite: populate development databases in the worktree.
# Delegates to the using-sqlite-worktrees skill. The helper reads database.yml
# from the MAIN working tree (where populated DBs live), so we cd back to main
# before invoking it. See failure contract below.
if [ -f Gemfile ] && [ -f config/database.yml ] && grep -q "adapter: sqlite3" config/database.yml; then
  WORKTREE_PATH="$(pwd)"
  MAIN_WORKTREE="$(git worktree list --porcelain | awk '/^worktree/ {print substr($0,10); exit}')"
  (cd "$MAIN_WORKTREE" && ruby "${CLAUDE_PLUGIN_ROOT}/skills/using-sqlite-worktrees/scripts/create_sqlite_worktree.rb" "$WORKTREE_PATH")
  SQLITE_EXIT=$?
  if [ $SQLITE_EXIT -ne 0 ]; then
    echo "SQLite worktree setup failed — skipping db:test:prepare and baseline tests."
    echo "Investigate the output above before continuing."
    exit $SQLITE_EXIT
  fi
fi

if [ -f Gemfile ] && [ -f config/database.yml ]; then bin/rails db:test:prepare; fi

# 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 がクリーンな状態で開始できることを確認します。

# Ruby on Rails (primary)
bin/rails test

# Other project types
npm test      # Node.js
cargo test    # Rust
pytest        # Python
go test ./... # Go

テストに失敗した場合： 失敗を報告し、続行するか調査するかを尋ねます。

テストに合格した場合： 準備完了と報告します。

5. 場所を報告する

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

クイックリファレンス

状況	対応
.worktrees/ が存在する	使用する（ignore 対象であることを確認）
worktrees/ が存在する	使用する（ignore 対象であることを確認）
両方存在する	.worktrees/ を使用する
どちらも存在しない	CLAUDE.md を確認 → ユーザーに尋ねる
ディレクトリが ignore 対象でない	.gitignore に追加してコミットする
ベースラインテストに失敗する	失敗を報告して尋ねる
package.json/Cargo.toml がない	依存関係のインストールをスキップする
Rails + SQLite プロジェクト	db:test:prepare の前に using-sqlite-worktrees に委任する
using-sqlite-worktrees が失敗する	セットアップを中止し、テストをスキップして「DB setup incomplete」と報告する

よくある間違い

ignore の確認を省略する

• 問題： worktree の内容が追跡対象になり、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 bundle install]
[Run bin/rails db:test:prepare]
[Run bin/rails test - 47 passing]

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

注意すべき兆候

絶対に行わないこと：

• ignore 対象であることを確認せずに worktree を作成する（プロジェクト内の場合）
• ベースラインテストの確認を省略する
• 尋ねずに、テストに失敗した状態で続行する
• 判断が曖昧なときに、ディレクトリの場所を決めつける
• CLAUDE.md の確認を省略する

必ず行うこと：

• ディレクトリの優先順位に従う：既存のディレクトリ > CLAUDE.md > ユーザーに尋ねる
• プロジェクト内の場合、ディレクトリが ignore 対象であることを確認する
• プロジェクトのセットアップ方法を自動検出して実行する
• テストがクリーンなベースラインであることを確認する

連携

次から呼び出されます：

• brainstorming（フェーズ 4）- 設計が承認され、実装に進む場合に必須
• subagent-driven-development - タスクを実行する前に必須
• executing-plans - タスクを実行する前に必須
• 分離されたワークスペースを必要とするすべてのスキル

次と組み合わせます：

• finishing-a-development-branch - 作業完了後のクリーンアップに必須
• using-sqlite-worktrees - Rails + SQLite が検出された場合、bundle install の後、db:test:prepare の前に委任することが必須