using-git-worktrees

using-git-worktreesスキルの概要

using-git-worktreesスキルでできること

using-git-worktrees は、新しい作業を始めるときに現在のチェックアウトを使い回さず、別の Git worktree を作るようエージェントに促すスキルです。単に git worktree add を実行するだけではなく、適切な配置先ディレクトリを選び、ローカルの worktree 用フォルダが安全に ignore されているか確認し、メインの作業領域を汚さないようにするのが本来の役割です。

どんな人に向いているか

このスキルは、次のような作業を日常的に行う人に特に向いています。

• いまの変更をそのまま残したまま、新しい機能開発を始めたい
• 複数のブランチを並行してレビュー・実装したい
• ブランチ切り替え事故を減らし、AI 主導のコーディングをより安全に進めたい
• プロジェクトをまたいでも、分離された作業環境を再現性高く作りたい

「これは別ブランチで始めて」「今の tree には触れずに進めて」とアシスタントに頼むことが多いなら、using-git-worktrees はかなり相性のよい選択です。

このスキルが解決する仕事

ユーザーが求めているのはひとつです。セットアップ時のミスを最小限にしつつ、分離されたワークスペースで実装を始められること。using-git-worktrees が便利なのは、作成前に判断フローを挟むからです。

• 既存の project 用 worktree ディレクトリがあればそれを優先する
• CLAUDE.md にリポジトリの方針が書かれていればそれに従う
• 安全なデフォルトがない場合はユーザーに確認する
• project 配下に worktree を作る前に ignore の挙動を確認する

そのため、いきなりシェルコマンドに飛ぶ汎用プロンプトより、実運用では信頼しやすくなっています。

通常のプロンプトとの違い

普通のプロンプトでも Git worktree の概念自体は理解しているかもしれませんが、リポジトリ固有のセットアップ条件までは見落としがちです。このスキルは、特にディレクトリ配置と .gitignore の扱いについて、明確な実行順序と安全確認をエージェントに与えます。using-git-worktrees for Git Workflows の差別化ポイントは、Git の理論を増やすことではなく、セットアップ時の当て推量を減らせることです。

向いていないケース

次のような場合は using-git-worktrees を使わないほうが早いことがあります。

• いつも単一ブランチ・単一ディレクトリでしか作業しない
• 環境上、追加の作業ディレクトリを作れない
• 分離実行ではなく、単に素早くブランチを切り替えたいだけ
• チームに、この判断ロジックを完全に置き換える固定の wrapper script がすでにある

こうしたケースでは、単純なシェルコマンドや既存の社内フローのほうが効率的です。

using-git-worktreesスキルの使い方

using-git-worktreesのインストール前提

obra/superpowers のスキルコレクションからインストールします。

npx skills add https://github.com/obra/superpowers --skill using-git-worktrees

インストール後は、現在のチェックアウトを使い回さずに始めたい作業に入る直前で使うのが基本です。

実際にどう呼び出すか

このリポジトリでは、スキル使用時にエージェントが冒頭でその利用を宣言することが明示されています。実際の依頼では、「分離して作業したい」ことがはっきり伝わる書き方にするのが有効です。たとえば次のような形です。

• “Use using-git-worktrees and set up an isolated workspace for this feature.”
• “Before implementing, create a worktree for branch feature/auth-refresh.”
• “Use the using-git-worktrees skill so my current changes stay untouched.”

こうしておくと、エージェントが自己流で進めず、スキルに沿って動く可能性が上がります。

スキルに渡すべき入力

using-git-worktrees をうまく機能させるには、次の情報があると精度が上がります。

• 対象ブランチ名
• 新規ブランチか既存ブランチか
• project ローカルに置きたいか、グローバルに置きたいか
• 「project root 配下に必ず置くこと」など、リポジトリ固有の制約

最低限あると役立つ入力:

• ブランチ名またはタスク名
• worktree を作成してよいという許可

よりよい入力:

• ブランチ名
• 希望するディレクトリ方針
• 現在のチェックアウトに未コミット変更があるか
• セットアップ後に何をするか（例: 「そのまま実装を始めて」）

組み込みのディレクトリ選択ロジック

using-git-worktrees skill の価値が最も出るのは、ディレクトリ選択のワークフローです。優先順位は次のとおりです。

1. .worktrees がすでに存在すればそれを使う
2. なければ worktrees が存在するか確認して使う
3. それもなければ CLAUDE.md を確認し、明記された方針に従う
4. それでも決まらなければ、ユーザーに次のどちらかを選んでもらう
   • .worktrees/
   • ~/.config/superpowers/worktrees/<project-name>/

これは実務上かなり重要です。セッションごとに毎回別の場所へ worktree を作る運用になると、管理負荷がすぐに大きくなります。

project ローカル作成前の安全確認

導入時に見落としやすい重要ポイントとして、リポジトリ内に worktree を置く場合、このスキルは作成前にそのディレクトリが ignore されていることの確認を求めます。これにより、worktree 用フォルダが誤って追跡対象になったり、git status が不要なノイズで汚れたりするのを防げます。

これは場当たり的な使い方に対する明確な優位性です。チームとして project ローカルの worktrees を前提にするなら、.worktrees/ または worktrees/ が Git で ignore される状態を、事前に整えておくべきです。

using-git-worktreesで失敗しにくいプロンプト例

弱いプロンプト:

• “Start working on OAuth cleanup.”

より強いプロンプト:

• “Use using-git-worktrees to create an isolated workspace for new branch feature/oauth-cleanup. Prefer .worktrees/ if safe and ignored. After setup, begin implementation without touching my current checkout.”

この書き方が優れている理由:

• スキル名を明示している
• 対象ブランチが明確
• ディレクトリ方針を指定している
• セットアップ後に何をするかまで伝えている

作成後におすすめの進め方

using-git-worktrees usage を安定させる実践的な流れは次のとおりです。

1. まずエージェントにスキルを使うよう依頼する
2. worktree の配置先とブランチ名を確認する
3. 新しいワークスペースへ作業を移してもらう
4. その後で初めて編集・テスト・実装計画に入る

現在のチェックアウトに未コミット変更が残っている場合、この順序は特に有効です。

先に読むべきリポジトリ内ファイル

このスキルで実質的に見るべきソースは SKILL.md だけです。

ここで確認したいポイント:

• ディレクトリ優先順位の正確な定義
• 優先方針がない場合に、ユーザーへどう確認する想定か
• ignore 確認が必須であること
• スキル利用を宣言させる activation phrasing

非常に軽量なスキルなので、導入判断の本質は「このロジックが自分たちの Git ワークフローに合うか」です。

依存前に知っておきたい実務上の制約

このスキルは意図的に範囲を絞っています。次の機能は用意されていないようです。

• wrapper scripts
• automation helpers
• branch naming enforcement
• stale な worktrees の cleanup routines
• platform-specific fallbacks

つまり using-git-worktrees install で手に入るのは、運用判断のガイドであって、worktree 管理全体を面倒見てくれるシステムではありません。ライフサイクル全体を自動化したいなら、自前のシェルツールと組み合わせる前提で考えるのがよいです。

using-git-worktreesスキル FAQ

using-git-worktreesは初心者にも向いている？

はい。基本的なブランチの概念を理解していて、「今のワークスペースには触れずに進めたい」という安全な流れを求める初心者には向いています。ただし、これは Git のチュートリアルではなく、セットアップを構造化するためのスキルです。Git worktree が何か、clone とどう違うかまで完全に初学者向けに説明してくれるわけではありません。

普通のプロンプトより何をうまく解決できる？

普通のプロンプトは、面倒な部分を飛ばしがちです。つまり「worktree をどこに置くか」「project ローカルのディレクトリが安全に ignore されているか」といった点です。スキル内に組み込まれた using-git-worktrees guide によって、その種のセットアップミスを減らし、エージェントの挙動を安定させやすくなります。

project ローカルの worktree が必須？

いいえ。ローカル用ディレクトリが存在せず、リポジトリ側にも方針が書かれていない場合、このスキルはグローバル配置へ誘導できます。つまり、リポジトリ内に余計なフォルダを増やしたくない場合でも使えます。

using-git-worktreesは既存ブランチにも使える？

はい。既存ブランチを別ワークスペースとしてチェックアウトしたいときにも有効です。価値の中心はブランチ作成そのものではなく、作業の分離にあります。

using-git-worktreesを使わないほうがいいのはいつ？

次のようなときは使わないほうがよいです。

• 現在のブランチで小さな修正をひとつ入れるだけ
• チームが未管理の worktree 配置先を禁止している
• 配置場所や ignore ルールを扱う社内ツールがすでに確立している
• リポジトリに、このスキルが想定していない特殊な Git 制約がある

これで Git の知識は不要になる？

いいえ。using-git-worktrees skill は起動時の指示やセットアップの規律を改善してくれますが、ブランチ名の付け方、rebase、cleanup、merge 戦略といった判断には、引き続き基本的な Git の理解が必要です。

using-git-worktreesスキルを改善するには

ブランチとディレクトリ方針を明示する

最も効果の大きい改善は、対象ブランチと希望ディレクトリ方針を両方ともエージェントに伝えることです。例:

“Use using-git-worktrees for branch fix/cache-invalidation. If .worktrees/ exists and is ignored, use it; otherwise ask before using a global location.”

この一文だけで、よくある曖昧さの大半を潰せます。

CLAUDE.md に方針を明文化する

このスキルは CLAUDE.md を確認するため、将来の結果を安定させたいなら、次の点を文書化しておくと効果的です。

• 推奨する worktree ディレクトリ
• project ローカルの worktrees を許可するかどうか
• ブランチ名やフォルダ名の命名規則

これにより、毎回ユーザーが補足していた内容を、リポジトリ共通のポリシーに変えられます。

ローカル用ディレクトリの ignore ルールを先に整える

チームとして .worktrees/ または worktrees/ を project 内に置きたいなら、事前に ignore ルールを追加しておきましょう。そうしておくと、using-git-worktrees for Git Workflows の運用がスムーズになります。途中で確認が必要になって作業が止まるのではなく、安全確認をそのまま通過できるからです。

よくある失敗パターンを把握する

主な失敗パターンは比較的わかりやすいものです。

• エージェントが未承認の場所に worktree を作る
• ローカルの worktree フォルダが ignore されていない
• あいまいな機能依頼からブランチ名を不適切に推測してしまう
• 分離が完了する前に、元のチェックアウトで実装を始めてしまう

多くはスキル自体の問題ではなく、プロンプト情報が足りないことから起こります。

コーディング前の確認を必須にする

シンプルですが有効な改善プロンプト:

• “Use using-git-worktrees, then report the final path and branch before making edits.”

これで初動ミスを早い段階で拾えます。特に、ネストしたフォルダが多いリポジトリや、配置ルールが特殊な環境では有効です。

初回実行後に運用を微調整する

最初の結果が概ね問題なくても、すべて書き換えるのではなく、運用パターンを少しずつ整えるのが得策です。

• 望ましいディレクトリ配置を固定する
• CLAUDE.md に注意書きを追加する
• プロンプト内のブランチ命名を標準化する
• 編集前の確認を明示的に必須にする

そうすることで、using-git-worktrees usage は時間とともに予測しやすくなり、毎回のセットアップ摩擦も減っていきます。