↓ メインコンテンツへスキップ

Claude Code AI Agents Git

Claude Codeのworktreeの使い方:並列エージェントを衝突させずに動かす

Claude Codeのworktreeの使い方。claude -w の動き、.worktreeincludeで.envを持ち込む方法、node_modulesの扱い、base ref、後片付け、tmuxで複数のエージェントを並列に動かすコツまで。

Claude Codeのworktreeの使い方:並列エージェントを衝突させずに動かす

Claude Codeをgitのworktreeで動かすには、claude -w <名前>(長い形は--worktree)で起動します。Claude Codeはリポジトリのルートに.claude/worktrees/<名前>/を作り、リモートのデフォルトブランチから切ったworktree-<名前>という新しいブランチをそこにチェックアウトします。以後、そのセッションが編集できるのはこのフォルダの中だけです。別のターミナルで名前を変えて同じコマンドを打てば、お互いのファイルに手を出せないエージェントが2つ並びます。ただし落とし穴があって、worktreeは真っさらなチェックアウトです。.envもnode_modulesも、gitが無視しているものは、自分でコピーかインストールをするまで存在しません。私がworktreeでつまずいたのは、ほぼ全部これが原因でした。

私はふだんから多くのエージェントを並列で動かしていて、worktreeには痛い目を見てからたどり着きました。この記事では、claude -wの動き(バージョン2.1.328で確認)、.worktreeincludeの役割、node_modulesをどうするか、tmuxでのセッションの並べ方、そして今でも素のgit worktree addを使う場面をまとめます。

この記事を8分の映像にしました。ナレーションは英語で、日本語字幕が付きます。映像素材の一部はCoverrのものです。

なぜ1つのチェックアウトでは並列エージェントがうまくいかないのか
#

9月のある日、私が作っているマーケットプレイスアプリの同じチェックアウトで、Claude Codeのセッションが5つ同時に動いていました。その日、2つのことが起きました。テスト設定ファイルへの1行の修正が、4回のビルド失敗を生き延びたのに、いざコミットしようとしたら消えていたのです。git commitは「working tree clean」と言い、ファイルには別のセッションの内容が入っていました。こういう更新の消失は、gitのどこにも記録が残りません。reflogにもstashにも何もなく、更新日時もごく普通です。同じ日には、作業ツリーからビルドするデプロイスクリプトが、別のセッションの書きかけの変更を本番に出しかけました。

10月には3つ目が起きました。あるセッションが、別のセッションのステージされていない変更の横で自分のファイルをコミットしたところ、pre-commitフックがフックの実行中、ステージされていない変更をすべてstashしました。もう一方のセッションの編集はその間ディスクから消え、型チェッカーはそのセッションの新しいファイルでエラーになり、コミットは中止されました。しかも、どのセッションも私の名前でコミットするので、git logを見ても誰が何をしたのか分かりません。

worktreeを使う理由は一言で言えます。書き手が複数いる作業ツリーは競合状態で、負けた側はそれに気づけません。エージェントごとに作業ツリーを分ければ、競合そのものがなくなります。

1つのリポジトリに3つの作業ディレクトリ。履歴は1か所に保存され、ファイルとHEADとindexはworktreeごとに持ちます。

claude -w の使い方と動き
#

使い捨てのリポジトリで実際に動かしたところ。セッションが終わった後もロックが残っている点に注目してください。

公式ドキュメントのworktreesのページに書いてあることと、実際に試して確認したことです。

  • 場所とブランチ。 claude -w add-searchは、.claude/worktrees/add-search/をworktree-add-searchという新しいブランチで作ります。名前を省略すると、bright-running-foxのような名前が自動で付きます。.claude/worktrees/は.gitignoreに入れておきましょう。入れないと、メインのチェックアウトで全部が未追跡ファイルとして表示されます。
  • どこから切るか(base ref)。 worktree.baseRefの既定値は"fresh"で、リモートのデフォルトブランチ(たいていはorigin/main)から切ります。直近24時間fetchしていなければ、最大5秒でfetchしてくれます。"head"にすると、手元の今のHEADから切るので、まだpushしていないコミットも引き継がれます。ブランチ名は指定できないので、特定のブランチから作りたいときは自分でgit worktree addを使います。
  • プルリクエスト。 claude --worktree "#1234"は、そのPRのheadをfetchして.claude/worktrees/pr-1234を作ります。引用符を忘れると、シェルが#以降をコメントとして扱ってしまいます。
  • 信頼の確認。 一度もClaudeを開いたことのないフォルダで、対話モードのclaude -wを最初に打つと「Workspace trust not yet accepted」で失敗します。そこで一度だけ普通にclaudeを起動して、信頼のダイアログを承認してください。claude -p -wはこの確認を飛ばします。
  • 囲い。 worktreeの中にいる間、Claude Codeはメインのチェックアウトにあるファイルの編集、メインのチェックアウトを作業ディレクトリにしたコマンド、git -Cや--git-dir、GIT_DIRでメイン側を指したgitを拒否します。逆に何を防がないかも、ドキュメントにはっきり書いてあります。メインのチェックアウトに書き込むcpやシェルのリダイレクトは、このチェックでは止まりません。

worktreeがメインのチェックアウトと何を共有するかも、何を共有しないかと同じくらい大事です。すべてのworktreeが同じ.gitに書き込むので、どれかで作ったコミットやブランチは全部から見えます。プロジェクトスコープのプラグインはどこでも読み込まれます。そして、worktreeの中で「Yes, and don’t ask again」と答えた承認は、メインのチェックアウトの.claude/settings.local.jsonに保存されます。つまりその承認はすべてのworktreeに効き、承認したworktreeを消した後も残ります。便利ですが、承認するコマンドに秘密情報を入れない理由がまた1つ増えたとも言えます。

後片付けと、残るロック
#

対話モードのworktreeセッションを終了するとき、Claude Codeは削除で失われるものがないかを確認します。名前のないセッションでworktreeに変更がなければ、ブランチごと自動で削除されます。名前付きのセッションは先に確認してきます。作業が残っていれば、残すかどうかを聞かれ、表示されるclaude --worktree <名前> --resumeで後から戻れます。

非対話モードは事情が違い、試していて引っかかったのはここだけでした。claude -pには終了時の確認がないので、後片付けをしません。さらにClaude Codeはセッション中、worktreeにgit worktree lockをかけていて、-pの実行が終わった後も、もう存在しないプロセスIDのままロックが残ります。上の録画でも、git worktree removeが「cannot remove a locked working tree, lock reason: claude session add-search」と拒否しています。ドキュメントにもまさにこう書いてあり、後のセッションの古いロックの掃除で外れるか、先にgit worktree unlockを実行すれば消せます。分かってしまえば無害ですが、最初は少しぎょっとします。

.worktreeinclude:真っさらなチェックアウトにないファイル
#

worktreeに入っているのは、追跡されているファイルだけです。gitが無視しているファイルも持ち込みたいときは、リポジトリのルートに.worktreeincludeを置きます。書き方は.gitignoreと同じで、Claude Codeがコピーするのは、パターンに一致し、かつgitに無視されているファイルだけです。追跡済みのファイルが二重になることはありません。

# .worktreeinclude
.env
.env.local
config/secrets.json

これはClaude Codeがgitで作るworktreeすべてに効きます。claude -w、サブエージェントのworktree、デスクトップアプリの並列セッションです。git worktree addで自分で作ったworktreeには効かず、WorktreeCreateフックで作成処理を置き換えた場合も丸ごと無視されます。

.envだけでなく、もっと入れておくことをおすすめします。忘れがちなgitignore対象のファイルほど、派手には壊れてくれないからです。私のアプリでは、ほかのセッションのコミット前の編集が絶対に本番に出ないよう、デプロイスクリプトをクリーンなworktreeからビルドする形に変えました。ところがそのクリーンな作業ツリーには、ある機能が使うgitignore対象の署名用証明書がありませんでした。イメージはそのままビルドされ、その機能は本番で13日間失敗し続け、スクリプトを証明書をコピーし、足りなければ警告する形に直すまで止まりませんでした。worktreeからの別のデプロイでは、gitignore対象のテーマフォルダがなく、2分かかるエクスポートで作業ツリーを汚した後でビルドが失敗しました。出荷に関わる作業をworktreeに任せる前に、メインのチェックアウトでgit status --short --ignoredを実行し、そのうちどれをビルドが読むのか確かめておきましょう。

node_modules:いちばん重いところ
#

.worktreeincludeは小さなファイル向けです。node_modulesには役立ちませんし、Claude Codeにもworktree間で共有する仕組みはありません。コードを動かす必要があるworktreeは、それぞれ自分のnode_modulesが要ります。

デモ用リポジトリでの素のgit worktree。インストールするまでは84 KB、した後はまた45 MBまるごと。

実際のプロジェクトでは数字が深刻になります。私のモバイルアプリのリポジトリには、メインのチェックアウトの横に19個のworktreeがあります。そのうち12個を測ると194 MBから12 GBまであり、大きい4つは、どれも自分のnode_modulesを持っていた4つでした。今週はノートPCのディスクが96%埋まっているので、掃除するならまずここからです。

選択肢を、単純なものから順に並べます。

  1. worktreeごとにインストールする。 最初にエージェントにnpm installを実行させるか、自分でやります。遅くてディスクも食いますが、驚かされることはありません。
  2. ロックファイルが同じチェックアウトからクローンする。 macOSなら、cp -c -R ../myapp/node_modules .でAPFSのクローンが使えます。クローンは、どちらかが変更されるまでデータブロックを共有します。デモの45 MBは0.8秒でした。私は実際のworktreeからのデプロイでもこれを使っています。クローンしていいのはロックファイルが一致するときだけで、ネイティブのビルドフォルダには注意してください。私の場合、メインのチェックアウトのiOSのPodsはworktreeのブランチより古いSDK向けにビルドされていたので、そこだけは入れ直す必要がありました。
  3. pnpmを使う。 パッケージは1つのストアに置かれ、macOSのpnpmはハードリンクより先にクローンを試します(LinuxとWindowsではハードリンクが先)。デモでは、2つ目のworktreeのインストールが約5秒で終わりました。
  4. WorktreeCreateフックでインストールする。 フックはClaude Code標準のgit処理を置き換えるので、git worktree addの後にインストールまで走らせることもできます。これはまだ試していません。やるなら、.worktreeincludeが処理されなくなるので、.envのコピーもフックの中でやる必要があります。

tmuxで並列エージェントを動かす
#

私はもともとtmuxの中で暮らしているので(レイアウトは日々の使い方の記事に書きました)、worktreeはそのまま収まります。worktreeごとにウィンドウかペインを1つずつ。下は、同じファイルを変更するよう指示した3つのエージェントを同時に起動したところです。

エージェント3つ、ファイル1つ、衝突なし。メインのチェックアウトはクリーンなままで、それぞれの変更は自分のブランチで待っています。

2つのエージェントが同時にsrc/index.jsを編集し、どちらも相手に気づきませんでした。それぞれのsrc/index.jsは、ディスク上では別のファイルだからです。メインのチェックアウトもクリーンなままでした。最後に残るのは、レビューしてマージする3つのブランチで、ここはworktreeが代わりにやってくれない仕事です。2つのエージェントが同じ行を変えれば、やはりマージコンフリクトになります。ただし、黙って上書きされるのではなく、目に見えるマージの場面で出てきます。

VS Codeでは、worktreeはただのフォルダです。code .claude/worktrees/add-searchで、そのブランチの別ウィンドウとして開けます。

worktreeはスナップショット
#

worktreeは古くなります。11月19日、2〜3日前から用意されていたworktreeからOTAアップデートが出たところ、その間に別の場所から出ていた2つの修正を黙って巻き戻してしまいました。その日のうちに気づいて差し替えましたが、worktreeは完璧に隔離されていて、それが問題でした。その修正を一度も見ていなかったのです。gitのコマンド1行で、リリース前に気づけたはずでした。

作りたてではないworktreeから出荷する前に実行したいチェックです。

baseRef: "fresh"は新しいworktreeを最新に保ってくれます。古いworktreeを最新に保ってくれるものはないので、そこからリリースする前に確かめましょう。

サブエージェントとフック
#

この隔離を得るのに、エージェントごとにターミナルを開く必要はありません。フロントマターにisolation: worktreeと書いたカスタムサブエージェントは、毎回専用の一時worktreeで動きます。

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

これはドキュメントの例です。サブエージェントが変更なしで終われば、そのworktreeは削除されます。変更があるものは、作業を失わずに消せるようになるまで、定期的な掃除で消されずに残ります。細かい点を1つ。.claude/worktrees/の下のworktreeで動くサブエージェントは、指示をメインの会話から引き継ぎ、worktreeのルートにあるCLAUDE.mdは読み込みません。

WorktreeCreateとWorktreeRemoveのフックは、git処理を丸ごと置き換えます。git以外のバージョン管理システムや、worktreeを.claude/worktrees/以外に置きたいとき向けですが、上のインストールのような準備処理を入れる場所にもなります。

素のgit worktree addのほうが向いている場面
#

白状すると、私のアプリのリポジトリの.claude/worktreesフォルダは空です。19個のworktreeはすべて素のgit worktree addで、すべてこの1か月の間に作られたもので、半分はdetached HEADです。ノートPCのほかのリポジトリにも、40、40、18、10、3、2、2個あります。しかも作っているのはたいてい私ではありません。このノートPCにあるClaude Codeの会話記録638件のうち85件で、エージェントがgit worktree addを実行していて、その回数は合わせて336回です。

素のgitのほうが向いているのは、次のようなときです。

  • 既存の特定のブランチが必要なとき。 たとえば、ホットフィックス用に残しているリリースブランチです。baseRefではできません。
  • 修正を1つだけ出したいとき。 ほかのセッションがまだデプロイしていない変更をmainにコミットしていたので、本番で動いているコミットにdetachedのworktreeを作り、自分の修正だけをcherry-pickしてそこからデプロイしました。こうすれば、出ていくのはその修正だけです。
  • 自分でエージェントに指示を書くとき。 1つのリポジトリで複数のエージェントを動かすとき、私はそれぞれへの指示に、git worktree add --detach "$TMPDIR/<task>-wt" refs/remotes/origin/mainで自分専用のworktreeを作り、git push origin HEAD:mainでpushし、コンフリクトしたらrebaseするように書いています。
  • 消されたくないとき。 Claude Codeの掃除は、git worktree addで自分で作ったworktreeを決して削除しません。

claude -wが向いているのは、手でセッションを始めるときに、ブランチ作成、.envのコピー、メインのチェックアウトへの囲い、後片付けを任せたい場合です。両者は問題なく混ぜて使えます。どちらで作っても、Claude Codeは同じようにworktreeとして扱い、上で書いたメインのチェックアウトとの共有も同じです。

まとめ
#

並列で動かすセッションごとにclaude -w <名前>を使い、.claude/worktrees/を.gitignoreに入れましょう。.worktreeincludeには.envだけでなく、ビルドが必要とするgitignore対象のファイルをすべて書いておきます。node_modulesは、worktreeごとのインストール、クローン、pnpmのどれでいくか決めておきます。-pで動かした後は、git worktree unlockが必要なロックが残っているかもしれません。作りたてではないworktreeから出荷する前には、すでに本番に出ているものが入っているか確かめます。worktreeは、エージェント同士がファイルを上書きし合うのは防いでくれますが、意見が食い違うのまでは防いでくれません。最後に3つのブランチをレビューするのは、やはりあなたです。

参考リンク
#

このサイト内:

外部: