Sun* DevelopersPublicationへの投稿
🤖

AIと開発するためのWorktree

泡沫京水
に公開
AI
Git
worktree
tech

はじめに

この記事は、

  • Claude Code
  • Codex

などの、Agent Codingを行うためのCLIを使用している方向けの記事です。

Cursorの場合

Cursorを使っている方におきましては、
CursorにWorktreeを活用した機能が搭載されているため、そちらを利用された方が、開発体験の向上が確実であるため、そちらを推奨します。

なぜAI×Worktreeなのか？

AIとWorktreeを組み合わせるという方法は、以前から注目を集めていたTipsの一つです。

まず、Worktreeの説明から始めます。

Worktreeとは

まず、Worktreeは、Git Worktreeの略称です。

Git Worktreeとは、Gitの機能の一つで、
この機能は、1つのリポジトリに対して複数の作業ディレクトリ（ワークツリー）を紐付け、それぞれで異なるブランチをチェックアウトすることにより、複数のブランチで同時に作業することを可能にする機能です。

では、どのようなメリットがあるのかについて説明します。

Worktreeのメリット

途中で発生した作業にすぐとりかかれる

例えば、特定の機能を開発している時に、

「〇〇という機能において、◼︎◼︎という挙動の不具合が見つかりました。原因を特定して、修正していただけますか？」という報告を受けたとします。

この時、別の機能を開発中で、その不具合を修正するためブランチを移動して対処することになります。

これまでは、

  1. Stashを使用して、開発中の作業を一時的に保存
  2. ブランチを移動して不具合を修正
  3. 不具合を修正した後、元のブランチに戻る
  4. Stashを復元して、開発を再開

という操作を行っていました。

しかし、Worktreeを使用することで、ブランチを移動する必要がなくなります。ディレクトリを移動するだけなので、非常に便利です。

独自のディレクトリ名でコピーできる

Worktreeとして作成したリポジトリのディレクトリ名は、自由に決めることができます。

そのため、設定するブランチの命名規則があり、その名前ではわかりにくい場合でも、ディレクトリ名をパッとみてわかりやすいものにすることで、
「この機能に関する実装または修正は、このディレクトリで開発している」ということが一目でわかるようにできます。

一例として、開発する機能に対して、特定の単位が存在して、その単位についているIDをブランチ名に含めないといけないと仮定して、そのブランチ名が
「feat/ticket-00121」のようになったとします。

この時、Worktreeとして作成したディレクトリ名を「[リポジトリ名]-feat-[機能の簡潔な略称]」のように設定することで、一目でわかりやすいものにできます。

複数のタスクを並行して進められる

レビュー待ちの間に別の機能を開発したり、長期的なリファクタリング作業を少しずつ進めたりする場合に便利です。

同じリポジトリ内でブランチを切り替える場合、node_modules などの依存関係の再インストールや、ビルド生成物の削除・再ビルドが必要になることがありますが、Worktreeであればそれぞれのディレクトリで環境が独立しているため、そうした手間を省くことができます。

Worktreeのデメリット

SSDの容量を圧迫する

別々のディレクトリにコピーを作成するため、SSDの容量を圧迫する可能性があります。

そのため、すでに大きくなったコードベースを持つリポジトリを扱う場合には、注意が必要です。

リポジトリ内のコード量によりますが、Worktreeの数が増えすぎると容量を圧迫するため、数はマシンのディスク容量を考慮して調整するのが良いでしょう。

それ以上になると、SSDの容量を圧迫し、仮想メモリを確保するスペースを圧迫してPCのパフォーマンスを落としてしまう可能性があります。

また、環境変数の設定やパッケージのインストール、開発環境の設定は、それぞれのディレクトリで行わなければなりません。

例えば、npm iを実行したり、.env.localを設定したりするなどの作業は、それぞれのディレクトリで行わなければなりません。

Worktree自体の管理が大変になる

そもそものWorktreeの管理が大変になってしまう可能性もあります。
これまでは同じディレクトリの中でブランチを変更して管理していたものを、Worktreeで別々のディレクトリを作成して管理することになるので、
「どのディレクトリがどのブランチを指しているのか」を覚えておかなければならなくなります。
一度実装を終えたら削除するなどの習慣を身につけておかないと、ディレクトリを削除するのを忘れてしまい、不要なディレクトリが溜まる可能性もあります。

Git操作の知識が必要

Worktreeを有効活用するには、Gitのブランチ操作にある程度慣れている必要があります。

複数のブランチで並列して開発を進め、最終的にそれらをマージしたり、良い部分を選別して取り込んだりする作業は、コンフリクトの解決などを含め、初心者にとってはハードルが高い場合があります。

特に、後述するようなAIを活用した並行開発を行う場合、複雑なブランチ操作が発生しやすくなるため、Gitグラフをイメージできる程度の知識は求められます。

AI開発におけるWorktreeの活用

ここからが本題です。
Worktreeの「ディレクトリを分離できる」という特性は、ディレクトリとチャット履歴が紐づくClaude CodeのようなAIコーディングツールと非常に相性が良いです。

人間 vs AI の比較学習

片方のWorktreeでは自分で実装し、もう片方ではAIに実装させるという使い方も有効です。

自分の実装とAIによる実装を比較することで、
「自分では思いつかなかったアプローチ」や「AI特有の実装のクセ」を発見でき、自身のコーディングスキルの向上や、AI生成コードのレビュー能力を高めるトレーニングになります。

AIに複数パターンの生成を並列で依頼する

例えば、「機能Aについて実装して」という指示を、2つの異なるWorktreeでそれぞれ別のAI（または別のプロンプト）に与えることができます。

  • Worktree A: Claude に実装を依頼
  • Worktree B: Codex に実装を依頼

それぞれのディレクトリで独立してチャット履歴が保持されるため、互いの文脈が混ざることなく、純粋な出力結果の比較が可能になります。

活用フローのイメージ

feat/~~からfeat/~~-claude、feat/~~-codexといったブランチを作成して並行開発を行い、最終的に良い部分を取り込むフローは以下のようになります。

このように分岐して開発し、最後に統合する作業をスムーズに行うためには、Worktreeによるディレクトリの分離が非常に効果的です。

関連ツール

以前から注目されていることもあり、
AIとWorktreeを組み合わせて開発するために使えるツールや、そのために開発されたものもあります。

Worktreeと組み合わせて活用できるもの

Wikiやとほほのtmux入門などでも説明されていますが、細かい内容を省いて簡潔に説明するのであれば、1つのターミナルの画面を分割し、その上でそれぞれのディレクトリに移動してコマンドを打つことができるツールです。

そのため、先ほどの3つのWorktree上のコマンド操作を一つのウィンドウ上で実行することができるようになります。

Worktreeを使ったAgent Coding向けに開発されたもの

Worktreeの作成や削除、管理を効率化するためのCLIツールです。

個人的に使っていて、かなり出来が良かったツールの一つです。

これは、以下のような困りごとを解決してくれます。

  • Worktreeの作成時に名前を決めなくていい（ブランチ名がそのままディレクトリ名になる）
  • Worktreeの作成位置が元リポジトリの.git/phantom/worktrees以下になる
  • tmuxと組み合わせて使用することが想定されているので、作成時点ですぐ画面分割するためのオプションが存在している
  • 特定のWorktreeに対して、docker execのようにコマンドを実行することができる
  • 特定のWorktreeに対して、すぐさまClaude CodeやCodexなどのツールを起動することができる
  • このCLIから専用のMCPを起動できるため、AIにWorktreeの管理を任せられる
  • 専用の設定ファイル（phantom.config.json）を作成することで、作成時や削除時に自動でコマンドを実行してくれる

などのメリットもあり、現在も活発に開発が続けられているツールです。

注目すべきポイントとして、

  • 専用MCPによって、AIにWorktreeの管理を任せることができること
  • 設定ファイルによるコマンドの自動実行によるパッケージインストールや環境変数ファイルの作成といった作業を自動化できること

については、Worktreeを使っている時に感じていた不便さを解消する「かゆいところに手が届く」機能で便利でした。

終わりに

AIを開発に大きく利用するようになってきた現代において、AIをうまく使いこなすためのテクニックや関連ツールを押さえていく中で、Worktreeを活用する方法も押さえておくべきTipsの一つになっていくと感じています。

また、Worktreeを活用してAIによるコード生成を比較・検討することは、

  • モデルごとの特性を把握
  • 適切なコードを見極めたりするスキル

など、AIを使う開発のためのスキルだけでなく、コードリーディングの技術やコードの良し悪しの判断ができるようになるという、エンジニアとしての基礎的なスキルを磨くのに役立ちます。こうした能力は今後ますます重要になり、開発スピードの向上にもつながるはずです。

皆さんも、ぜひこのTipsを使ってより良いVibe Coding・Agentic Codingを体験してみてください。

GitHubで編集を提案
Sun* Developers
Sun* DevelopersPublication

Sun*は「誰もが価値創造に夢中になれる世界」をビジョンに掲げ、現在4ヶ国、6都市にて1500名以上のエンジニアやクリエイターが在籍するデジタル・クリエイティブスタジオです。

Discussion