Claude Codeで並列開発するには？worktreeで衝突を防ごう

「Claude Codeで並列開発するにはworktreeが要るの？」
「複数のエージェントを同時に走らせて一気に進めたい！」

Claude Codeを2つ同時に立ち上げて、片方に機能追加、もう片方にバグ修正をやらせる。
これを同じフォルダでやると、お互いのファイルを踏み合って一瞬で壊れます。

そこで使うのがgit worktree、つまり「履歴は共有したまま、作業フォルダだけ分ける」仕組みでした。
この記事では起動の手順から、破綻しないタスクの切り方までをまとめています。

Claude Codeの並列開発にworktreeが要る理由

Claude Codeの並列開発でworktreeが出てくるのは、ファイルの取り合いを避けるためです。

ここでは、なぜブランチだけでは足りないのかを3つの角度から見ていきます。

ブランチ切り替えでは並列にならない

gitのブランチは、同じフォルダの中身を切り替える仕組みです。

つまりある瞬間に机の上に出せるブランチは1つだけでした。

ここでClaude Codeを2つ立ち上げるとどうなるか、想像してみてください。

私も最初はターミナルを2枚開けば済むと思っていました。

結果は悲惨で、10分後には両方のセッションが別々の幻を見ながら作業していたんですよね。しかも壊れ方が静かなので、テストが落ちるまで気づけませんでした。

作業を分けたいなら、フォルダごと分けるしかありません。
その「フォルダごと分ける」を、リポジトリを丸ごとコピーせずにやるのがworktreeです。

履歴は共有・ファイルは分離という性質

git worktreeは、同じリポジトリに対して別の作業ディレクトリをもう1つ生やす機能です。

コミット履歴もリモートも共有したまま、チェックアウトされているファイルだけが独立します。

Git公式ドキュメントでも、独自のファイルとブランチを持つ別の作業ディレクトリとして説明されていました。

リポジトリを2回cloneするのと何が違うのか、と思いますよね。

cloneだと履歴が別物になるので、片方のコミットをもう片方から見るのにpushとfetchが要ります。

worktreeならコミットした瞬間から、隣のフォルダでもそのコミットが見えます。
マージもローカルで完結するので、行き来がとにかく軽いです。ディスクの使用量もリポジトリ1つぶんに収まるため、大きなプロジェクトほど差が出ました。

サブエージェントやエージェントチームとの違い

Claude Codeで並列といっても、実は3つの層があります。

混同しやすいので、公式ドキュメントの整理にそって並べてみますね。

ざっくり言うと、worktreeが分けるのは「置き場所」だけです。

作業の中身を分担させたいならサブエージェント、というふうに層が違います。どれか1つを選ぶ話ではなく、目的に応じて重ねて使うものだと考えてください。

この2つは組み合わせられるので、後半でその設定も紹介しますね。
サブエージェント側の基本はClaude Codeのサブエージェントの記事にまとめました。

Claude Codeでworktreeを立てて並列に動かす手順

ここからは実際にClaude Codeを2本同時に走らせる手順です。

gitのコマンドを覚えなくても、Claude Code側のオプションだけで完結します。

【ステップ1】worktreeオプションで1本目を起こす

まずリポジトリのフォルダで、--worktree を付けてClaude Codeを起動します。

claude --worktree feature-auth

これだけで新しい作業フォルダとブランチが用意され、その中でセッションが始まります。

置き場所は .claude/worktrees/feature-auth/、ブランチ名は worktree-feature-auth が既定でした。

ブランチの元になるのは、リポジトリの既定ブランチ（origin/HEAD）です。

つまり毎回きれいな状態から始まるので、手元の中途半端な変更を持ち込みません。

1つだけ先にやっておくことがあります。
そのフォルダで一度 claude を素で実行して、信頼のダイアログに答えておいてください。済ませていないと --worktree はエラーで止まります。

【ステップ2】別のターミナルで2本目を起こす

1本目を走らせたまま、新しいターミナルを開きます。

同じリポジトリのフォルダで、別の名前を付けて起動するだけです。

claude --worktree bugfix-123

これで2つのセッションが、それぞれ別のフォルダで動き始めます。片方に機能追加、もう片方にバグ修正を任せても、お互いのファイルには一切触れません。

ターミナルの扱いに慣れていない方は、タブを2枚並べるところから始めてみてください。

基本操作はClaude Codeでのターミナルの使い方で先に押さえておくと楽になります。

なお、セッションの途中で「worktreeで作業して」と頼む方法もあります。
Claudeが自分でworktreeを作って移動してくれるので、あとから分けたくなったときに便利でした。

【ステップ3】worktreeincludeで環境ファイルを引き継ぐ

ここでたいていの人が最初につまずきます。

worktreeは新しいチェックアウトなので、gitで追跡していない .env のようなファイルは存在しません。

起動した瞬間にアプリが動かなくなって、原因がわからず固まるやつです。

解決策として、プロジェクトのルートに .worktreeinclude を置きます。

.env
.env.local
config/secrets.json

書き方は .gitignore と同じで、ここに書いたファイルが新しいworktreeへ自動でコピーされます。

コピーされるのはパターンに一致して、かつgitignoreされているファイルだけです。
追跡中のファイルが二重になる心配はありません。

【ステップ4】終わったセッションを片づける

作業が終わったら、worktreeを残すか消すかを決めます。

Claude Codeは終了時の状態を見て、扱いを変えてくれました。

公式ドキュメントの分岐を整理すると、次のようになります。

ここで「消す」を選ぶと、コミット済みの分まで含めて丸ごと消える点に注意してください。

マージ前のコミットが入っているときに勢いで消すと、普通に泣きます。

迷ったら残す、が安全です。
不要なworktreeは、あとから git worktree remove でいつでも片づけられますからね。

Claude Codeの並列開発をgitコマンドで手動管理する方法

置き場所やブランチを自分で決めたいときは、gitのコマンドで作ります。

既存のブランチをそのままチェックアウトしたい場合も、こちらのほうが素直です。

git worktree addで置き場所を自分で決める

基本のコマンドは git worktree add です。

第1引数がフォルダのパス、-b で新しいブランチ名を指定します。

git worktree add ../project-feature-a -b feature-a

作ったあとは、そのフォルダに移動してClaude Codeを起動します。

リポジトリの外に置けるので、エディタで並べて開きたいときはこちらが扱いやすいです。既存のブランチをそのまま開けるのも、レビュー中のPRを手元で動かしたいときに効きます。

親フォルダにきょうだいのように並ぶ形になるので、名前は project-機能名 のようにそろえておきましょう。
3つ4つと増えたとき、自分がどこにいるのかわからなくなるのを防げます。

依存関係のインストールは毎回必要

手動で作った場合、環境の初期化は自分でやります。

worktreeは新しいチェックアウトなので、インストール済みの依存はコピーされません。

公式ドキュメントにも、各worktreeで開発環境を初期化するよう書かれていました。

cd ../project-feature-a
npm install
cp ../project/.env .env

最後のやつが地味に厄介です。

原因は単なるインストール漏れなのに、Claudeが設定ファイルを書き換え始めることがあります。

worktreeを作ったら、まず自分でビルドかテストを1回通す。
この順番を守るだけで、無駄な修正を丸ごと防げますよ。

一覧の確認と削除

いま何本のworktreeがあるかは、1つのコマンドで確認できます。

git worktree list

フォルダのパス、コミット、ブランチ名が並んで表示されます。メインのチェックアウトも1行目に出てくるので、そこは消さないよう気をつけてください。

片づけるときは remove です。

git worktree remove ../project-feature-a

--force を付ける前に、必ず中身を確認してください。

「もう終わったはず」と思って消したフォルダに、コミットし忘れの実装が入っていたことがあります。

あとは .claude/worktrees/ を .gitignore に足しておきましょう。
これをやらないと、worktreeの中身が未追跡ファイルとして山ほど表示されます。

Claude Codeの並列開発が破綻しないタスク分割の粒度

並列開発でいちばん難しいのは、コマンドではなく分け方です。

ここでは、コンフリクトで足止めされないための判断基準を整理します。

判断の軸は「触るファイルが重なるか」

並列化の記事はどれも「独立した機能なら同時に進められる」と書いてあります。

ただ、その「独立している」をどう判定するのかが書かれていないんですよね。

私が使っている基準はひとつだけです。

2つのタスクが書き換えるファイルの一覧を出して、1つでも重なったら並列にしない。

機能として独立していても、同じ設定ファイルに1行ずつ足すなら衝突します。

逆に見た目が近い作業でも、触る場所が完全に別なら安全に並べられました。
「機能の独立性」ではなく「ファイルの重なり」で見る、これがコツです。

共有ファイルを先に洗い出す

実際のプロジェクトでは、みんなが触るファイルがだいたい決まっています。

並列を始める前に、この一覧を作っておくと判断が一瞬で済みます。

洗い出し自体はClaude Codeにやらせるのが早いです。「この機能を実装すると、どのファイルを書き換えることになりそうか一覧にして」と頼めば、着手前に見積もりが出てきますよ。

この5つに触るタスクが2つ以上あるなら、片方は順番待ちにします。

どうしても同時に進めたいときは、先に共有ファイルだけを1本のブランチで片づけてしまう手もありますね。

ルーティングの登録だけ先にmainへ入れて、実装は各worktreeで並列に進める。
この順番にすると、マージのときにぶつかる箇所がほぼゼロになります。

並列に向かない仕事の見分け方

そもそも並列に載せないほうがいい種類の仕事もあります。

無理に分けると、片づけのコストのほうが大きくなりました。

判断に迷ったときは、次の表を見てみてください。

下3つは、作業範囲が始める前に確定しないという共通点があります。

調べているうちに触る場所が広がるので、どう分けても後から重なるんですよね。リファクタリングにいたっては、範囲が広がること自体が目的だったりします。

こういう仕事は素直に1本で進めましょう。
並列にする前に、範囲が読めるところまで分解できているかを確かめるのが先です。

同時に回せる本数はレビューできる量で決まる

「何本まで同時に走らせられますか」とよく聞かれます。

マシンの性能で言えば、4本でも5本でも動きます。

ただし、詰まるのはいつも人間側でした。

並列で作らせるほど、あとで読む差分が同時に積み上がります。

3本を1時間で走らせて、レビューに3時間かかったら意味がありません。しかも読む側は3つの文脈を頭の中で切り替えることになるので、見落としも増えました。

速くなるのは実装の待ち時間だけで、確認の時間は減らない。
ここを見誤ると、並列にしたのに前より遅くなるという状態になります。

Claude Codeのサブエージェントをworktreeに分離する設定

worktreeは、サブエージェントと組み合わせるとさらに効きます。

ここでは、サブエージェントごとに作業フォルダを分ける設定を紹介しますね。

フロントマターにisolationを書く

サブエージェントは既定だと、メインと同じフォルダで作業します。

調査だけなら問題ないのですが、複数のサブエージェントに同時に編集させると踏み合います。

そこでカスタムサブエージェントの定義に1行足しておきましょう。

---
name: api-builder
description: APIエンドポイントの実装を担当する
isolation: worktree
---

毎回設定するのが面倒なら、その場で「エージェント用にworktreeを使って」と頼む形でも動きます。

定義ファイルの作り方そのものはClaude Codeのカスタムエージェントの作り方にまとめました。

ここまで来ると、1つのターミナルの中で複数の作業が並行する形になります。
手元のターミナルは1枚のまま、裏で3本走っているという感覚ですね。

ベースブランチをheadに変える設定

worktreeは既定で、リポジトリの既定ブランチから枝分かれします。

これはきれいな状態から始められる反面、困る場面もありました。

まだpushしていない自分の作業の続きを、サブエージェントにやらせたいときです。

{
  "worktree": {
    "baseRef": "head"
  }
}

設定ファイルは .claude/settings.json に置きます。

プロジェクト単位で切り替えたいときは、リポジトリ側の設定に書いておくとチームでも共有できますね。

使い分けとしては、独立した新機能なら既定のまま。
作りかけの土台の上に積む作業だけ "head"、という切り替えがちょうどよかったです。

自動で消えるものと残るもの

worktreeを増やしていくと、気づけばフォルダが散らかります。

ここは仕組みを知っておくと、掃除の手間がかなり減りました。

Claudeが自動で作ったworktreeには、自動削除のルールが用意されています。

自動削除の対象になるのは、未コミットの変更も未追跡ファイルも未pushのコミットもない場合だけです。

何か残っていれば、勝手に消えることはありません。

エージェントが動いている間はロックがかかるので、実行中に消される心配もない仕組みでした。
それでも自分で作った分は残るので、週に一度 git worktree list を眺める習慣をつけると平和です。

Claude Codeの並列開発でハマりやすい落とし穴

最後に、並列を始めてから実際にぶつかったところをまとめます。

どれも一度やると忘れませんが、初回は必ず時間を取られる種類のものです。

同じブランチは2つのworktreeで開けない

gitの仕様として、同じブランチを複数のworktreeで同時にチェックアウトできません。

やろうとすると「already checked out」と怒られます。

これは制限というより、事故を防ぐための安全装置ですね。

同じブランチを2か所で編集できたら、それこそ何が正なのかわからなくなります。

並列にするなら、ブランチも人数分だけ用意する。

当たり前に聞こえますが、慌てているときほど同じブランチを開こうとしがちです。
エラーが出たら「分け忘れているな」と思い出してください。

node_modulesと環境ファイルは共有されない

これはさきほども触れましたが、実害がいちばん大きいので繰り返します。

新しいworktreeには、依存パッケージも .env も入っていません。ソースコードだけがそろった、まっさらな状態だと思ってください。

とくに.worktreeinclude を使わずgitコマンドで作ったときに起きます。

この3つをスクリプトにして、worktreeを作るたびに叩くのがおすすめです。

私は setup-worktree.sh という名前で置いています。

ちなみに依存のインストールは、フォルダの数だけディスクを食います。
4本並列すると node_modules も4つできるので、容量には気をつけてください。

フォルダを手で消すと参照だけが残る

不要になったworktreeを、Finderやコマンドでフォルダごと消したくなりますよね。

これをやると、gitの側には「あるはず」という登録だけが残ります。

その状態で同じ名前のworktreeを作ろうとすると、エラーで止まります。

git worktree prune

このコマンドで、実体のない登録がまとめて片づきます。消えたフォルダを探しにいって失敗する、という無駄なエラーもなくなりますよ。

gitの基本操作をClaude Codeに任せる方法はClaude CodeとGitの連携方法にまとめました。

ブランチだけ残っているのも地味に邪魔です。
片づけのときは、フォルダとブランチをセットで消す癖をつけておきましょう。

マージのコンフリクトで足止めされる

並列開発で最後に待っているのが合流です。

ここで詰まると、並列で稼いだ時間を全部返すことになります。

効くのは、順番を決めておくことでした。

全部できてからまとめて合流させると、コンフリクトが同時に襲ってきます。

1本終わるたびにマージして、残りに取り込ませる。この順番なら、直したところがすぐ他のworktreeにも行き渡りました。

この形にすると、ぶつかる量が毎回小さいままで済みます。
並列開発の成否は、走らせ方より合流のさせ方で決まります。

Claude Codeの並列開発とworktreeに関するよくある質問

ここでは、並列開発を始めるときによく出てくる疑問に答えていきます。

Q：worktreeを使わずにフォルダを2つcloneするのではだめですか？

A：動きますが、行き来が重くなります。cloneすると履歴が別物になるので、片方のコミットをもう片方で見るのにpushとfetchが必要です。

worktreeなら履歴を共有しているので、コミットした瞬間から隣のフォルダで見えます。ディスク容量もリポジトリ1つぶんで済みますよ。

Q：Claude Codeを何本まで同時に走らせられますか？

A：仕組み上の上限というより、レビューできる量で決まります。最初は2本から始めて、その日のうちにマージまで終わる量に収めるのが安全です。

本数を増やすほど、あとで読む差分が同時に積み上がります。実装が速くなっても確認の時間は減らないので、そこが詰まると全体では遅くなりました。

Q：worktreeで作った変更はどうやってmainに入れますか？

A：普通のブランチと同じです。worktree内でコミットしてpushすれば、そのままプルリクエストを作れます。

ローカルでマージしても問題ありません。履歴が共有されているので、メインのフォルダに戻って git merge ブランチ名 を実行すれば取り込めます。

Q：worktreeを消したらコミットも消えますか？

A：ブランチごと削除した場合は消えます。終了時に「削除」を選ぶと、未コミットの変更だけでなくコミット済みの分も破棄されるので注意してください。

すでにpush済みか、mainにマージ済みなら残ります。迷ったときは残す方を選んで、あとから git worktree remove で片づけるのが安全です。

まとめ

Claude Codeの並列開発は、worktreeでフォルダを分けるところから始まります。

起動は claude --worktree 名前 だけ、環境ファイルは .worktreeinclude で引き継ぐ。ここまでは仕組みの話です。

難しいのはむしろ、何を並べるかを決めるほうでした。触るファイルが1つでも重なるなら、その2つは並列に載せない。

まずは2本から試してみて、自分がその日のうちに読める差分の量を測ってみてください。
そこがわかると、何本走らせるべきかは自然と決まってきますよ。

ここまでの内容を一人で回せるようになったら、次は同じやり方をチームや社内に広げる段階に入ります。体系立てて学び直したい方や、研修という形で社内に展開したい方は、社会人におすすめの生成AI研修スクール｜スクール6校を比較を参考にしてみてください。