using-git-worktrees

Git Worktree の使用

概要

作業が分離されたワークスペースで行われるようにします。プラットフォーム標準の worktree ツールを優先してください。標準ツールが利用できない場合に限り、手動で git worktree を使用します。

基本原則： まず既存の分離状態を確認します。次に標準ツールを使い、最後に git に切り替えます。ハーネスに逆らわないでください。

開始時に伝えること： 「using-git-worktrees スキルを使って、分離されたワークスペースを設定します。」

ステップ 0：既存の分離状態を確認する

何かを作成する前に、すでに分離されたワークスペース内にいるか確認してください。

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

サブモジュールの確認： GIT_DIR != GIT_COMMON は git サブモジュール内でも成立します。「すでに worktree 内にいる」と判断する前に、サブモジュール内ではないことを確認してください。

# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
git rev-parse --show-superproject-working-tree 2>/dev/null

GIT_DIR != GIT_COMMON の場合（サブモジュールではない場合）： すでにリンクされた worktree 内にいます。ステップ 2（プロジェクトのセットアップ）に進んでください。別の worktree を作成してはいけません。

ブランチの状態とともに報告します。

• ブランチ上にいる場合：「すでに <path> の分離されたワークスペース内にいます。ブランチは <name> です。」
• Detached HEAD の場合：「すでに <path> の分離されたワークスペース内にいます（Detached HEAD、外部で管理されています）。完了時にブランチを作成する必要があります。」

GIT_DIR == GIT_COMMON の場合（またはサブモジュール内の場合）： 通常のリポジトリをチェックアウトした状態です。

ユーザーは指示の中で、すでに worktree の希望を示していますか？示していない場合は、worktree を作成する前に同意を求めてください。

「分離された worktree を設定しましょうか？現在のブランチを変更から保護できます。」

すでに表明されている希望があれば、確認せずに従ってください。ユーザーが同意しない場合は、現在の場所で作業し、ステップ 2 に進んでください。

ステップ 1：分離されたワークスペースを作成する

方法は 2 つあります。次の順番で試してください。

1a. 標準の Worktree ツール（推奨）

ユーザーは分離されたワークスペースを希望しています（ステップ 0 で同意済み）。worktree を作成する方法はすでにありますか？EnterWorktree、WorktreeCreate のような名前のツール、/worktree コマンド、または --worktree フラグなどが考えられます。利用できる場合はそれを使い、ステップ 2 に進んでください。

標準ツールはディレクトリの配置、ブランチの作成、クリーンアップを自動的に処理します。標準ツールが使えるのに git worktree add を使うと、ハーネスから認識も管理もできないファントム状態が発生します。

標準の worktree ツールが利用できない場合に限り、ステップ 1b に進んでください。

1b. Git Worktree による代替手段

ステップ 1a を適用できない場合に限り使用してください — 標準の worktree ツールが利用できない場合です。git を使って手動で worktree を作成します。

ディレクトリの選択

次の優先順位に従ってください。ユーザーが明示した希望は、常に確認できたファイルシステムの状態より優先されます。

1. worktree ディレクトリに関する希望が指示に記載されているか確認します。 ユーザーがすでに指定している場合は、確認せずにその場所を使用してください。

2. 既存のプロジェクト内 worktree ディレクトリを確認します。

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

   見つかった場合はそれを使用します。両方ある場合は .worktrees を優先します。

3. ほかに指示がない場合は、プロジェクトのルートにある .worktrees/ を既定の場所とします。

安全性の確認（プロジェクト内ディレクトリのみ）

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

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

ignore 対象ではない場合： .gitignore に追加して変更をコミットしてから、続行してください。

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

Worktree の作成

# Determine path based on chosen location
path="$LOCATION/$BRANCH_NAME"

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

サンドボックスで失敗した場合の代替手段： git worktree add が権限エラー（サンドボックスによる拒否）で失敗した場合は、サンドボックスによって worktree の作成がブロックされたため、代わりに現在のディレクトリで作業することをユーザーに伝えてください。その後、現在の場所でセットアップとベースラインテストを実行します。

ステップ 2：プロジェクトのセットアップ

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

# 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

ステップ 3：クリーンなベースラインを確認する

ワークスペースがクリーンな状態で開始できることを確認するため、テストを実行します。

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

テストが失敗した場合： 失敗内容を報告し、続行するか調査するかを尋ねてください。

テストが成功した場合： 準備完了と報告してください。

報告

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

ステップ 4：ワークツリーを終了する（作業が完了したら）

機能開発が完了したら、EnterWorktree に対応するネイティブの ExitWorktree ツールを使ってクリーンアップします。ワークツリーを削除することも、保持したり変更を破棄したりすることもでき、ハーネスの状態をきれいに元に戻します。

git worktree remove よりもこちらを優先してください。ここで git を使うと、作成時に避けたのと同じ、ハーネスから見えず管理もできない幽霊状態が残ります。

ネイティブの終了ツールが利用できない場合に限り、git worktree remove を使ってください。

クイックリファレンス

状況	対応
すでにリンクされたワークツリー内にいる	作成をスキップする（ステップ 0）
サブモジュール内にいる	通常のリポジトリとして扱う（ステップ 0 のガード）
ネイティブのワークツリーツールが利用可能	それを使う（ステップ 1a）
ネイティブツールがない	Git のワークツリーで代替する（ステップ 1b）
.worktrees/ が存在する	それを使う（無視対象であることを確認）
worktrees/ が存在する	それを使う（無視対象であることを確認）
両方存在する	.worktrees/ を使う
どちらも存在しない	指示ファイルを確認してから、既定の .worktrees/ を使う
ディレクトリが無視対象でない	.gitignore に追加してコミットする
作成時に権限エラーが発生する	サンドボックスで代替し、現在の場所で作業する
ベースライン実行中にテストが失敗する	失敗を報告して確認を求める
package.json／Cargo.toml がない	依存関係のインストールをスキップする
機能開発が完了し、クリーンアップする	ネイティブの ExitWorktree を使う（ステップ 4）

よくある自己正当化

言い訳	実際のところ
「ワークツリー内にいないのは明らかだから、確認する必要はない」	ステップ 0 を実行してください。ハーネスが作成した隔離環境とサブモジュールは、目視ではどちらも見誤る可能性があります。判定コマンドで確認できます。
「ネイティブツールを探すより、git worktree add のほうが早い」	EnterWorktree などのネイティブツールは、配置、ブランチ、クリーンアップを管理します。それを迂回するのは最大の間違いです。ハーネスから見えず管理もできない幽霊状態が作られます。
「ワークツリーディレクトリはきっとすでに無視対象だ」	git check-ignore を実行してください。ワークツリーディレクトリが無視対象でないと、ツリー全体がリポジトリにコミットされます。
「ディレクトリ名は何でもいい」	明示された指示が既存のプロジェクト内ディレクトリに優先し、既存のプロジェクト内ディレクトリは .worktrees/ の既定値に優先します。
「ワークスペースは新しいから、ベースラインテストは後回しでいい」	ベースラインが不安定だと、後で発生したすべての失敗の原因が曖昧になります。今すぐテストを実行してください。失敗があっても続行するかどうかは、人間のパートナーが判断します。