using-git-worktrees

概要

using-git-worktrees とは？

using-git-worktrees は、obra/superpowers リポジトリで提供されているワークフロースキルで、機能開発用の分離された Git worktree を作成する手順をガイドしてくれます。worktree をどこにどう作るかを標準化することで、1 つの作業ディレクトリでブランチを頻繁に切り替えることなく、複数のブランチを安全に並行作業できます。

手作業で worktree の置き場所を勘で決めたり、Git によって追跡されていない／無視されていないディレクトリを作ってしまうリスクを避けるために、このスキルは明確なディレクトリ選択と検証プロセスを組み込んでいます。目的は、本体のプロジェクトツリーをクリーンに保ちつつ、実装作業用の環境を確実に分離することです。

このスキルは誰向け？

このスキルは、次のような開発者向けに設計されています。

• 複数の機能やバグ修正を並行して進めている
• プロジェクトをまたいで、再現性のある Git worktree の運用ルールを持ちたい
• worktree 用ディレクトリの配置が正しく、コミットを汚さないことを確実にしたい
• コマンドラインの Git を使っており、簡単なシェルコマンドの実行に慣れている

特に、チームとしてドキュメント化された一貫性のある Git ワークフローを整備したい場合や、一時的な環境・長期の機能ブランチ用環境を安全に立ち上げたい場合にフィットします。

using-git-worktrees が解決する課題

using-git-worktrees は、複数ブランチで作業するときに起こりがちな問題を避けるのに役立ちます。

• ブランチ切り替えの負荷: 1 つの作業ディレクトリで stash と checkout を繰り返すことなく、複数ブランチを同時に進められます。
• プロジェクトルートの散らかり: 思いつきで作ったディレクトリや worktree フォルダがバラバラに散らばる状況を防ぎます。
• worktree フォルダの誤コミット: worktree 用ローカルディレクトリが無視されていることを作成前に確認するフローを重視しています。
• マシンごとにバラバラな流儀: CLAUDE.md にある既存のディレクトリやオプション設定を確認することで、プロジェクトごとに標準的なレイアウトへ誘導します。

Git worktree を日常的に使っている、あるいはこれから安全に使い始めたいのであれば、このスキルは軽量かつ意見のはっきりした手順を提供してくれます。

using-git-worktrees が向いている場面

using-git-worktrees を使うとよい場面は次の通りです。

• 現在の作業ツリーからきちんと分離した状態で新しい機能開発を始めたいとき
• 既存の設計や計画に基づいて実装を行うにあたり、その実装専用のクリーンな worktree を用意したいとき
• リポジトリで既に .worktrees や worktrees ディレクトリを使っており、その慣例を今後も守りたいとき

逆に、あまり向かないケースは次のような場合です。

• 常に 1 つのブランチだけで作業しており、複数の作業コピーが不要な場合
• すでに社内ツールなど、別の厳格な自動ツールで worktree 管理を行っている場合

それ以外の多くのケースでは、using-git-worktrees のフローを取り入れることで、Git ワークフローがより予測可能で安全になります。

使い方

インストールとセットアップ

using-git-worktrees スキルを環境に追加するには、obra/superpowers リポジトリからインストールします。

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

インストール後は次の手順を行います。

1. リポジトリの checkout で、skills/using-git-worktrees/SKILL.md ファイルを開きます。
2. ディレクトリ選択と安全確認のステップを理解するため、一度最初から最後まで読み通します。
3. 追加の worktree 用ディレクトリを作成してもよいと判断できる Git リポジトリ内で作業していることを確認します。

Git と、このスキルの説明に記載されたコマンドを実行できるシェル以外に、特別な依存関係は必要ありません。

基本フロー: 分離された機能開発の開始

新しい機能開発を始めるときに、現在の作業ツリーから分離されたワークスペースを用意したい場合は、using-git-worktrees に組み込まれている高レベルのフローに従います。

1. ワークフローを宣言する（自分自身や支援ツール向けのメモ）：

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

2. ディレクトリ選択プロセス（次のセクション）に従って、worktree 用ディレクトリを決定します。これにより、任意のパスに worktree が散らばるのを防ぎます。

3. 選んだディレクトリの種類に応じた安全確認（プロジェクトローカルかグローバルか）を実行します。このステップは、worktree フォルダを誤ってコミットしてしまうことを防ぐうえで不可欠です。

4. 必要なブランチ用に Git worktree を作成 します。例えば次のように実行します。

   git worktree add <path-to-worktree> <branch-name>
   

5. 新しい worktree に移動 し、その中で実装作業を行います。元の作業コピーはクリーンな状態のまま保ち、コードレビューや軽微な修正、その他のタスクに利用できます。

新しい機能やスパイク、実験など、現在の作業ディレクトリと干渉させたくない作業を始めるたびに、このフローを繰り返してください。

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

using-git-worktrees は、毎回迷わずに済むよう、worktree を配置するディレクトリを決めるための優先順位付きルールを定義しています。

1. 既存の worktree ディレクトリを優先

リポジトリのルートから、次の優先順位で worktree 用ディレクトリを確認します。

ls -d .worktrees 2>/dev/null     # 優先（隠しディレクトリ）
ls -d worktrees 2>/dev/null      # 代替案

• .worktrees が存在する場合は、それを使用します。
• .worktrees がなく worktrees が存在する場合は、worktrees を使用します。
• どちらも存在しない場合は、次のステップに進みます。

このルールにより、同じプロジェクト内での過去の選択と一貫したワークフローを維持できます。

2. CLAUDE.md でプロジェクトの方針を確認

標準的な worktree ディレクトリがない場合は、プロジェクトルートの CLAUDE.md にディレクトリの方針が記載されていないか確認します。

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

CLAUDE.md に worktree ディレクトリの慣例が明記されている場合は、追加の検討なしにその方針に従います。これにより、プロジェクト全体で好ましい worktree レイアウトを中央集約的に文書化できます。

3. 方針がない場合は場所を決めて選択

既存のディレクトリも CLAUDE.md による指針もない場合は、新しい worktree をどこに置くかを明示的に決めます。スキルでは、自分（やチーム）に対して次のような分かりやすい選択肢を提示することを推奨しています。

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?

• Option 1: .worktrees/ は、worktree をプロジェクトと並べて配置します。隠しディレクトリなので普段は目立ちませんが、リポジトリ内で見つけやすい配置です。
• Option 2: ~/.config/superpowers/worktrees/<project-name>/ は、リポジトリルートの外側にプロジェクト単位で worktree を集約します。Git の作業ディレクトリを見た目上ミニマルに保ちたい場合に便利です。

一度どちらかを選んだら、同じプロジェクトではその場所に統一して配置し、フラグメンテーションを避けましょう。

worktree 作成前の安全確認

using-git-worktrees は、とくに Git リポジトリ内に作るプロジェクトローカルなディレクトリに対して、安全確認を重要視しています。

プロジェクトローカルディレクトリが無視されているかの確認

.worktrees や worktrees のようなプロジェクトローカルディレクトリを使う場合は、その中に worktree を作る前に、Git によって無視されていることを確認します。このスキルでは、これを MUST 条件 として扱っています。

最低限、次を行うべきです。

• .worktrees または worktrees が、関連する ignore ファイル（.gitignore、.git/info/exclude、またはグローバル ignore ファイル）に記載されていることを確認する
• git check-ignore を使って、現在の設定で Git がそのディレクトリを実際に無視しているか検証する

典型的には、該当ディレクトリのパスを指定して git check-ignore を実行し、ローカル・グローバル・システムの ignore 設定を踏まえて Git が無視対象と認識していることを確かめます。

ディレクトリが 無視されていない 場合は次を行います。

• 適切な ignore ファイルに追記し、リポジトリに含めるべきルールであればコミットする
• その場所に worktree を作成する前に、再度チェックを実行する

これにより、worktree 用のインフラが誤ってステージングされたりコミットされたりするリスクを抑えられます。

グローバルな場所を安全に使う

~/.config/superpowers/worktrees/ のようなグローバルディレクトリを選んだ場合、ディレクトリはリポジトリの外にあり、Git によって追跡されません。この場合、ignore の必須要件は緩くなりますが、次の点は確認しておくとよいでしょう。

• パスがマシン間で安定している、またはチームメンバー向けに文書化されていること
• 複数のフル worktree を配置するのに十分なディスク容量があること

これらの確認を一貫して行うことで、Git の履歴をツールの産物ではなくソースコードの変更に集中させることができます。

自分のワークフローへの取り込み方

using-git-worktrees は意図的に軽量で、リポジトリ単位の運用に焦点を当てています。より広いワークフローへ統合する際には、次の点を検討してください。

• 最終的に選んだ worktree ディレクトリの場所を、プロジェクトのコントリビュートガイドやオンボーディングドキュメントに明記する
• チームが Git worktree をどう使うかについて、CLAUDE.md に短いセクションを追加する
• ワンコマンドでセットアップしたい場合は、ディレクトリ選択と安全確認のステップを自作のシェルスクリプトにラップし、元のルールを「仕様のソース」として保つ

このスキルは、ある種の「リファレンス実装」として設計されており、そのままなぞってもよいですし、自分の環境に合わせて慎重に拡張・調整しても構いません。

FAQ

普通の Git checkout と比べて、using-git-worktrees を使う主なメリットは何ですか？

using-git-worktrees を使うと、同じ Git 履歴を共有する追加の作業ディレクトリ（worktree）を作成することで、複数ブランチを並行して簡単に扱えるようになります。1 つのディレクトリで何度も checkout と stash を繰り返す代わりに、各機能や修正をそれぞれ専用の分離されたワークスペースに置けるうえ、一貫したディレクトリ選択と安全確認のプロセスがガイドしてくれます。

using-git-worktrees スキルはどうやってインストールしますか？

obra/superpowers リポジトリから、次のコマンドでインストールします。

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

インストール後は、ローカルの checkout で skills/using-git-worktrees/SKILL.md を開き、詳細なワークフローに従ってください。

このスキルを使うために Git のワークフローを大きく変える必要はありますか？

ワークフロー全体を作り直す必要はありません。using-git-worktrees が扱うのは、主に分離されたワークスペースの始め方と管理方法です。コミットやリベース、push などはこれまで通り続けられます。このスキルは主に、worktree をどこにどう作るかを標準化し、安全な配置を保証する役割を担います。

どんな Git リポジトリでも using-git-worktrees を使えますか？

はい。Git worktree 機能と互換性のあるリポジトリであれば利用できます。このスキルは標準的な Git コマンドとシェルユーティリティに依存しています。最良の結果を得るには、リポジトリルートからディレクトリチェックを実行し、プロジェクトローカルな worktree ディレクトリについては ignore の推奨事項に従ってください。

既に別の worktree 運用ルールがある場合はどうなりますか？

プロジェクトで .worktrees や worktrees、あるいは CLAUDE.md に記載された慣例をすでに使っている場合、using-git-worktrees はディレクトリ選択ルールを通じて自然にその方針を拾います。まったく異なる慣例がある場合でも、「ディレクトリを明確に決める」「安全確認を行う」といった原則だけを取り入れ、既存のディレクトリレイアウトに合わせて適用することができます。

using-git-worktrees は大規模・長期プロジェクトにも向いていますか？

はい。長期にわたって複数の長命ブランチが走り続けるような大規模プロジェクトに特に有効です。体系だったディレクトリ選択と ignore ルールの徹底によって、多数の worktree を抱えるようになってもリポジトリの整理された状態を保ちやすくなります。

using-git-worktrees の利用を避けるべきなのはどんなときですか？

同時に複数のブランチで作業することがほとんどなく、常に 1 つの作業コピーで足りている場合や、既に別の専用ツールで worktree 管理とディレクトリ方針の強制を行っている場合は、このスキルの追加構造がそこまで大きな価値をもたらさないかもしれません。そのような環境では、無理に切り替える必要はありません。

このスキルの正式な定義はどこで確認できますか？

using-git-worktrees の公式な定義は、GitHub 上の obra/superpowers リポジトリ内、skills/using-git-worktrees ディレクトリにある SKILL.md ファイルに記載されています。もっとも正確で最新の挙動を知りたい場合は、そのファイルを参照してください。