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 を作成する前に、ディレクトリが無視対象になっていることを必ず確認します。

# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q -- "$LOCATION/"

無視対象になっていない場合：

承認済みの外部 worktree の保存場所を優先します。プロジェクト内への保存が必要な場合は、具体的な ignore の変更を提案し、リポジトリのコミットポリシーに従います。無関係なコミットを自動作成してはいけません。

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

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

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

ホストが管理する worktree 作成／アーカイブ API を提供している場合は、それを優先します。作成前に、明示的に意図されたベースコミットを特定して記録します。現在の HEAD とリモートのデフォルトは異なる選択肢です。ブランチ名とパスの値を検証し、既存の未コミットの変更を保持します。

作成手順

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="$HOME/.config/superpowers/worktrees/$project/$BRANCH_NAME"
    ;;
esac

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

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

セットアップ前に、指定したベースに対応する AGENTS.md、メンテナー向けドキュメント、パッケージ／ロックファイル、ライフサイクル／ビルドスクリプトを確認します。以下は実行するコマンド一式ではなく、代替の例です。不明なコードを自動実行せず、ロックされた依存関係と、プロジェクトで承認されたセットアップ方法を使用してください。

# Node.js
if [ -f package-lock.json ]; then npm ci --ignore-scripts; 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 がクリーンな状態で開始することを確認するため、テストを実行します。

# Examples - use project-appropriate command
npm test
cargo test
pytest
go test ./...

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

テストが成功した場合： 準備完了と報告します。

5. 場所を報告する

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

クイックリファレンス

状況	対応
.worktrees/ が存在する	使用する（無視対象か確認）
worktrees/ が存在する	使用する（無視対象か確認）
両方存在する	.worktrees/ を使用する
どちらも存在しない	CLAUDE.md を確認 → ユーザーに尋ねる
ディレクトリが無視対象ではない	外部パスを優先するか、範囲を限定した ignore の変更を提案する
ベースラインテストが失敗する	失敗を報告して確認する
package.json/Cargo.toml がない	依存関係のインストールをスキップする

よくある間違い

無視対象かどうかの確認を省略する

• 問題： 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 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

注意すべき兆候

絶対に行わないこと：

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

必ず行うこと：

• ディレクトリの優先順位に従う：既存のディレクトリ > CLAUDE.md > ユーザーに尋ねる
• プロジェクト内の場合は、ディレクトリが無視対象であることを確認する
• 指定したベースの手順／スクリプトを確認し、承認されたプロジェクトのセットアップ方法を使用する
• クリーンなテストベースラインを確認する

統合

呼び出し元：

• ブレインストーミング（フェーズ 4）— 設計が承認され、実装に進む場合は必須です
• 分離されたワークスペースを必要とするあらゆるスキル

組み合わせて使用：

• 開発ブランチの終了 — 作業完了後のクリーンアップに必須です
• プランの実行またはサブエージェント駆動開発 — このワークツリー内で作業します

使用するタイミング

このスキルは、概要で説明されているワークフローやアクションを実行する場合に適用できます。

制限事項

• タスクが上記の範囲に明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認してください。