using-git-worktrees

Git Worktree の使用

概要

git worktree を使用して、並行開発タスク用の独立した作業ディレクトリを作成できます。これにより、競合を起こさずに複数のブランチを同時にチェックアウトできます。このスキルでは、ディレクトリの選択からセットアップの検証まで、決定的な複数フェーズのプロセスを適用し、作業を開始する前にすべての worktree が本番環境で使える状態であることを確認します。

使用するタイミング

• 現在の作業に影響しない新しい機能ブランチを開始するとき
• 複数のタスク（バグ修正と機能開発など）を同時に進めるとき
• テストやコードレビュー用のクリーンな環境を作成するとき
• 開発を続けながら、テストやビルドなどの長時間実行プロセスを実行するとき

フェーズ 1：worktree ディレクトリの選択

[HARD-GATE] ディレクトリの選択を省略しないでください。優先順位を確認せずに既定のパスを想定しないでください。

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

優先度 1：タスクに一致する既存の worktree

タスク用の worktree がすでに存在するか確認します。

git worktree list

一致する worktree がある場合は、それを使用します。重複して作成しないでください。

優先度 2：CLAUDE.md の worktree ディレクトリのヒント

プロジェクトの CLAUDE.md に設定済みの worktree ディレクトリがあるか確認します。

# Example CLAUDE.md entry
worktree-directory: ../worktrees

指定されている場合は、そのディレクトリの下に worktree を作成します。

優先度 3：ユーザーに確認する

ヒントが設定されておらず、明確な慣例もない場合は、worktree の作成場所をユーザーに確認します。妥当な既定値を提案してください。

../worktrees/<project-name>/<branch-name>

停止 — 先に進む前に、worktree ディレクトリをユーザーに確認してください。

ディレクトリ選択の判断表

条件	対応
このブランチ用の worktree がすでに存在する	既存の worktree に移動する
CLAUDE.md に worktree-directory がある	設定されたパスを使用する
プロジェクトに既存の worktree がある	同じ親ディレクトリの配置パターンを使用する
慣例が見つからない	ユーザーに確認し、../worktrees/<project>/<branch> を提案する
ユーザーがリポジトリのルート内のパスを指定する	警告する — .gitignore に追加する必要があります

フェーズ 2：安全性の確認

[HARD-GATE] すべての安全性チェックに合格するまで、worktree を作成しないでください。

.gitignore の対象範囲を確認する

worktree ディレクトリがリポジトリのルート内にある場合は、.gitignore に含まれていることを確認します。

# Check if the worktree path would be tracked
git check-ignore <worktree-path>

無視対象になっていない場合は、ユーザーに警告し、.gitignore への追加を提案します。

作業ツリーがクリーンであることを確認する

問題の原因となる可能性がある未コミットの変更がないか確認します。

git status --porcelain

作業ツリーがクリーンでない場合は、ユーザーに知らせ、どのように進めるか確認します。

• 先に変更をコミットする
• 変更をスタッシュする
• そのまま進める（worktree の作成自体は安全です）

別の worktree にブランチが存在しないことを確認する

git worktree list

ブランチを複数の worktree で同時にチェックアウトすることはできません。すでにチェックアウトされている場合は、代わりにその既存の worktree に移動します。

安全性チェックの判断表

チェック	結果	対応
パスがリポジトリ内にあり、.gitignore に含まれていない	FAIL	先に .gitignore に追加する
別の worktree にブランチがある	FAIL	既存の worktree を使用する
作業ツリーがクリーンでない	WARN	ユーザーに知らせ、希望を確認する
パスがすでに存在する（worktree ではない）	FAIL	別のパスを選ぶ
すべてのチェックに合格	PASS	フェーズ 3 に進む

フェーズ 3：worktree の作成

# For a new branch
git worktree add <path> -b <branch-name> <base-branch>

# For an existing branch
git worktree add <path> <existing-branch>

worktree を作成した場所の完全なパスを必ずユーザーに伝えます。

Worktree created at: /absolute/path/to/worktree
Branch: feature/my-feature
Base: main

停止 — セットアップに進む前に、worktree が正常に作成されたことを確認してください。

フェーズ 4：プロジェクトのセットアップと自動検出

worktree の作成後、プロジェクトのセットアップコマンドを検出して実行します。

セットアップ検出の判断表

インジケーターファイル	エコシステム	セットアップコマンド
pnpm-lock.yaml	Node.js（pnpm）	pnpm install
yarn.lock	Node.js（yarn）	yarn install
package-lock.json	Node.js（npm）	npm install
package.json（ロックファイルなし）	Node.js（npm）	npm install
pyproject.toml + tool.poetry	Python（poetry）	poetry install
pyproject.toml（poetry なし）	Python（pip）	pip install -e .
setup.py	Python（pip）	pip install -e .
requirements.txt	Python（pip）	pip install -r requirements.txt
go.mod	Go	go mod download
Cargo.toml	Rust	cargo build
Gemfile	Ruby	bundle install
composer.json	PHP	composer install

複数のエコシステム

プロジェクトが複数のエコシステムを使用している場合（例：Go バックエンドと Node.js フロントエンド）、検出された各エコシステムのセットアップを、適切なサブディレクトリで実行します。

環境ファイル

プロジェクトに .env.example または .env.template がある場合：

# Copy environment template if .env does not exist in worktree
cp .env.example .env  # then inform user to update values

フェーズ 5：クリーンなベースラインテストの検証

[HARD-GATE] ベースラインテストに合格するか、失敗が確認されるまで、作業を進めてはいけません。

作業を始める前に、プロジェクトのテストスイートを実行して、クリーンなベースラインを確立します。

# Use the project's test command
# Node.js: npm test / yarn test / pnpm test
# Python: pytest / python -m pytest
# Go: go test ./...
# Rust: cargo test

目的：

• 作業ツリーが正しくセットアップされていることを確認します
• 変更を加える前に、すべてのテストに合格することを確認します
• この時点以降のテスト失敗は、既存の問題ではなく、変更によって発生したものだと判断できます

ベースラインテストに失敗した場合：

• 失敗についてユーザーに報告します
• ベースラインの状況が把握できるまで、作業を進めてはいけません
• ベースブランチにテストを先に修正する必要のある問題がある可能性があります

フェーズ 6：場所の報告

作業ツリーの場所を、必ずユーザーにはっきりと報告します。

Worktree ready:
  Path:    /Users/dev/worktrees/myproject/feature-auth
  Branch:  feature/auth-refactor
  Base:    main
  Setup:   npm install (completed)
  Tests:   24 passed, 0 failed

クリーンアップのパターン

マージまたは作業完了後

# Remove the worktree
git worktree remove <path>

# If files remain (dirty worktree), force removal
git worktree remove --force <path>

# Prune stale worktree references
git worktree prune

すべての作業ツリーを一覧表示する

git worktree list

ロックされた作業ツリーの処理

誤って削除されないよう作業ツリーがロックされている場合：

# Unlock before removing
git worktree unlock <path>
git worktree remove <path>

アンチパターン／よくある間違い

アンチパターン	問題である理由	代わりに行うこと
同じブランチ用に作業ツリーを重複して作成する	Git では許可されておらず、時間の無駄になります	まず git worktree list を確認します
.gitignore を設定せずにリポジトリ内に作業ツリーを作成する	作業ツリーのファイルが未追跡として表示されます	パスを .gitignore に追加します
作業ツリーで依存関係のインストールを省略する	依存関係の不足により、ビルドやテストが失敗します	必ずプロジェクトのセットアップを実行します
ベースラインテストの実行を省略する	既存の失敗と新たな失敗を区別できません	作業を始める前にテストを実行します
作業ツリー間で環境変数が同じだと思い込む	.env ファイルは作業ツリー間で共有されません	.env をコピーして設定します
マージ後に古い作業ツリーを放置する	ディスク容量を浪費し、git worktree list が分かりにくくなります	ブランチの作業完了後に作業ツリーを削除します
未コミットの作業がある作業ツリーを強制削除する	データが永久に失われます	先にコミットするか、スタッシュします

連携ポイント

スキル	連携内容
finishing-a-development-branch	作業ツリーでの作業完了後、これを使ってマージするか PR を作成します
dispatching-parallel-agents	真の分離を実現するため、エージェントを個別の作業ツリーで実行します
verification-before-completion	作業ツリーを離れる前に作業内容を検証します
self-learning	作業ツリーのディレクトリ設定を確認するため、CLAUDE.md を確認します
planning	作業ツリーの作成は、多くの場合、計画を実行する最初のステップです

スキルの種類

RIGID — このプロセスに正確に従ってください。すべてのフェーズを順番に完了する必要があります。安全性の確認を省略してはいけません。ベースラインテストの検証を省略してはいけません。ディレクトリを確認せずに作業ツリーを作成してはいけません。