using-git-worktrees

Git Worktree の使用

概要

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

基本原則： ディレクトリを体系的に選択し、安全性を検証することで、信頼性の高い分離を実現します。

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

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

1. 必要な workree のパスを「/」として決定します。
2. すでにその場所にいますか？ そこは git worktree ですか？ そうであれば、その旨を報告して終了します。
3. 間違った worktree にいる場合は、その旨を報告して終了します。
4. 次の優先順位で親 worktree ディレクトリを特定します。
   • 既存の worktree の親ディレクトリ
   • AGENTS.md の設定
   • ユーザーのプロンプト
5. プロジェクト内のディレクトリが .gitignore に含まれていることを確認します。
6. worktree を作成し、セットアップを実行して、クリーンなベースラインを検証します。

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

# Check in priority order
ls -d "../$(git rev-parse --path-format=absolute --git-common-dir | xargs dirname).worktrees" 2>/dev/null      # Alternative

見つかった場合： そのディレクトリを使用します。

2. AGENTS.md を確認する

grep -i "worktree.*director" AGENTS.md 2>/dev/null

設定が指定されている場合： 尋ねずにその設定を使用します。

3. ユーザーに尋ねる

ディレクトリが存在せず、AGENTS.md に設定もない場合：

No worktree directory found. Where should I create worktrees?

1. ../$(basename "$(git rev-parse --show-toplevel)").worktrees (project-local, hidden)
2. ~/.locals/share/<project-name>.worktrees/ (global location)

Which would you prefer?

作成手順

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

project=$(git rev-parse --path-format=absolute --git-common-dir | xargs dirname)

2. Worktree を作成する

# Create worktree with new branch
path="../${project}.worktrees/${feature_name}"
mkdir -p "$path"
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

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

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

# if Justfile
if [ -f Justfile ]; then just setup; fi

# if Mise
if [ -f .mise.toml ]; then mise setup; exit 0; fi

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

# Examples - use project-appropriate command
# if Justfile
if [ -f Justfile ]; then just test; fi

if [ -f .mise.toml ]; then
  mise check
  exit 0
fi

npm test
cargo test
pytest
go test ./...

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

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

5. 場所を報告する

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

クイックリファレンス

状況	対応
worktree がまだない	../<projectname>.worktrees/ を使用
どちらも存在しない	AGENTS.md を確認 → ユーザーに尋ねる
ディレクトリが .gitignore にない	すぐに追加してコミットする
ベースラインのテストが失敗	失敗内容を報告して尋ねる
package.json/Cargo.toml がない	依存関係のインストールをスキップする

よくある間違い

ディレクトリの場所を決めつける

• 問題： 一貫性が損なわれ、プロジェクトの規約に違反します。
• 修正： 優先順位に従います：既存の場所 > AGENTS.md > 尋ねる

テストが失敗した状態で続行する

• 問題： 新しいバグと既存の問題を区別できません。
• 修正： 失敗内容を報告し、続行する明示的な許可を得ます。

セットアップコマンドを固定する

• 問題： 異なるツールを使用するプロジェクトで動作しなくなります。
• 修正： プロジェクトファイル（package.json など）から自動検出します。

ワークフローの例

You: I'm using the using-git-worktrees skill to set up an isolated workspace.

[Check ../<projectname>.worktrees/ - exists]
[Create worktree: git worktree add ../<projectname>.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 を作成する
• ベースラインのテスト検証を省略する
• 尋ねずに、テストが失敗した状態で続行する
• 曖昧な場合にディレクトリの場所を決めつける
• AGENTS.md の確認を省略する

必ず行うこと：

• ディレクトリの優先順位に従う：既存の場所 > AGENTS.md > 尋ねる
• プロジェクト内のディレクトリが .gitignore に含まれていることを確認する
• プロジェクトのセットアップを自動検出して実行する
• クリーンなテストベースラインを検証する

連携

呼び出し元：

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

併用するスキル：

• finishing-a-development-branch - 作業完了後のクリーンアップに必須
• executing-plans または subagent-driven-development - この worktree 内で作業を行います