AIエージェント3並列で動かしたらgitブランチが混在した話

「速く終わらせたい」という欲が、余計な仕事を生み出した。Claude Code Agentを3つ同時に走らせた結果、PiloTube(パイロチューブ)のリポジトリがぐちゃぐちゃになった。今日はその失敗と、そこから学んだ並列実行の落とし穴を書いておく。

3並列なら3倍速いはず、という思い込み

先週、PiloTubeの開発タスクが3つ溜まっていた。

SAFEブランチ: LPのデザイン修正
NEW-034ブランチ: API周りの変更
もう一本: 細かいバグ修正

「どうせ別々のブランチで作業するんだから、同時に回せばいいじゃないか」そう思った。Claude Code Agentを3インスタンス立ち上げて、それぞれにタスクを投げた。コーヒーでも飲みながら待てば終わる、くらいの気持ちだった。

これが完全に甘かった。

何が起きたか

作業が終わったと思って各ブランチを確認したら、明らかにおかしい。

SAFEブランチにLPファイルが混入していない、どころか逆にAPIの変更コードが混ざっていた。NEW-034ブランチを見ると、今度はLPのHTMLファイルが入り込んでいる。ブランチの中身が、タスクと一致していない。

git log を追いかけてみると、原因がわかった。3つのエージェントが同じローカルリポジトリを触っていたせいで、ブランチの切り替えが干渉していた。エージェントAがSAFEブランチで作業中に、エージェントBがNEW-034にチェックアウトする。その瞬間、エージェントAのワーキングツリー(作業中のファイル群)がNEW-034の状態に引っ張られる。そこにエージェントAがファイルを書き込む。結果、NEW-034に本来SAFEブランチ向けのファイルが混入する。

gitは「今どのブランチにいるか」をリポジトリ全体で1つしか持てない。並列で複数エージェントがチェックアウトを繰り返せば、こうなるのは当然だった。後から考えれば「そりゃそうだ」なのだが、動かしてみるまで本当に気づかなかった。

気づいたのは差分確認のとき

混乱に気づいたきっかけは、SAFEブランチをステージング環境にデプロイしようとしたときだった。ビルドが通らない。ログを見るとAPIのエンドポイント定義が変わっていて、LP側のコードと噛み合っていない。「あれ、このブランチそんな変更入れたっけ?」と思って git diff main を叩いたら、全然関係ないファイルが山ほど出てきた。

そこで初めて「やばい、混在してる」と確信した。

解決するまでの地獄

まず現状把握から始めた。各ブランチで git log --oneline を出して、どのコミットが本来どのタスク向けだったかを手作業で仕分けた。これが想像以上にきつかった。エージェントのコミットメッセージが「Update files」「Fix implementation」みたいなふわっとしたものばかりで、何がどのタスクのコミットなのか判別しにくい。

次に git cherry-pick と git revert を組み合わせて、各ブランチから不要なコミットを取り除いていった。完全に分離できるまで2時間近くかかった。3並列で「速く終わらせよう」としたのに、後処理で倍以上の時間を食った。

対処法として実践したこと

この件以来、並列でエージェントを走らせるときのルールを自分の中で決めた。

1. リポジトリを物理的に分ける

同じリポジトリを複数エージェントで同時に触らせない。並列で動かしたいなら、リポジトリをクローンして別ディレクトリに展開する。エージェントAは /repos/PiloTube-safe/、エージェントBは /repos/PiloTube-new034/ という具合に、作業場所を完全に分離する。gitのブランチ管理はリポジトリ単位なので、ディレクトリが違えば干渉しない。

2. エージェントへの指示にブランチ名を明示する

「このディレクトリで、このブランチだけを触れ」という制約を指示文に入れる。エージェントは言われなければ自分でブランチを切り替えることがある。「SAFEブランチ以外にはチェックアウトするな」と明示的に書いておくだけで、かなりリスクが下がる。

3. コミットメッセージのフォーマットを指定する

「[SAFE] LP header修正」「[NEW-034] API endpoint変更」のようにブランチ名をプレフィックスとして入れるよう指示する。後から混在が起きたときに、どのコミットがどのタスク向けだったか追跡できる。これは保険として有効だった。

4. 作業完了後に即差分チェック

エージェントが「完了した」と言ってきても、すぐにマージしない。git diff main --name-only で変更ファイル一覧を出して、そのブランチのタスクと関係ないファイルが含まれていないかを確認する。面倒でも、これを挟むだけで混入を早期に発見できる。

並列実行は「場所を分ける」が大前提

今回の失敗をひと言でまとめると、「並列処理の単位とリソースの排他制御を混同していた」ということになる。

CPUコアが複数あれば並列計算できる。でもgitリポジトリは「今いるブランチ」を1つしか持てない共有リソースだ。複数のエージェントが同じリポジトリを触るのは、複数の人間が同じPCのデスクトップで同時に別々の作業をしようとするようなもので、そもそも無理がある。

AIエージェントを並列で使うこと自体は有効だし、これからも使い続ける。ただ、「並列に動かせる」と「同じ場所で同時に動かせる」は全然違う。この区別を頭に入れておかないと、自分みたいに後処理で時間を溶かすことになる。

読者への教訓

Claude CodeやCursorのAgentモードを複数並列で使っている人、あるいはこれから試そうとしている人へ。

同じリポジトリを複数エージェントで同時に触らせるな。クローンして物理的にディレクトリを分けろ。
エージェントへの指示には「どのブランチだけ触っていいか」を書け。書かないと勝手に動く。
完了報告を信用するな。差分確認を自分の目でやれ。
コミットメッセージにブランチ名を入れさせろ。混在したときの救命索になる。

速く終わらせようとした結果、遅くなった。AIエージェントは速いが、gitは正直だ。ごまかしが効かない分、人間側がちゃんと設計しておく必要がある。そこだけは、まだ自分でやらないといけない部分だと実感した。

PiloTube 開発日誌

並列処理の単位とリソースの排他制御を混同していた