エージェントを並べて走らせる時、ファイルとDBをどう分けるか　道具ごとに比べる

Claude CodeやCodexを2体、3体と並べて走らせると、ぶつかる場所は2つある。同じファイルを書き換え合うことと、同じデータベースを取り合うことだ。ファイルの側はgit worktreeという答えがほぼ定まり、主な道具はどれもこれを土台にしている。難しいのはデータベースの側で、分け方は道具によってかなり違う。今週はSupabase CLIがworktreeごとの環境に対応し、DBを分けるやり方が道具ごとにそろってきた。両方を公式文書で確かめ、並べて比べた。

ファイルはworktreeで分ける

gitの公式文書によると、worktreeは1つのリポジトリに複数の作業用の写しをつなぐ仕組みだ。コミットやブランチの記録は共有し、HEADやindexのように写しごとの部分だけを分ける。同じブランチを2か所で同時に開くことはできない。

3つの道具はどれもこの上に乗っている。

• Claude Code：claude --worktreeに名前を付けて起動すると、分かれた並列のセッションになる。既定の置き場所はリポジトリの .claude/worktrees/ の下だ。
• Codexアプリ：チャットごとにworktreeを作り、既定ではブランチを持たないdetached HEADで作業する。管理するworktreeは既定で最新の15個まで残す。
• Cursor：Agents Windowでworktreeを作り、IDEでは /worktreeや /best-of-nで使う。上限は既定で1台あたり25個だ。

注意したいのは、gitが無視する .envのようなファイルはworktreeに入らないことだ。Claude CodeとCodexは .worktreeincludeに書いたものを写し、Cursorは .cursor/worktrees.jsonに準備の手順を書く。Cursorの文書は、依存のフォルダーをシンボリックリンクで共有しないよう勧めている。

片付けにも違いがある。Codexは自分で管理するworktreeを消す前に作業のスナップショットを残す。Cursorの自動の掃除は、git worktree addで手作りしたものも消す対象に含める。上限を超えると古い順に消えるので、長く残したいなら設定のcursor.worktreeMaxCountを大きくしておく。手で作ったworktreeはgit worktree removeで消すのが基本で、変更が残っていると断られる。

データベースは1体に1つ

ファイルを分けても、全員が同じlocalhostのPostgresに向いていれば意味は半分になる。片方がリセットやマイグレーションをすれば、もう片方のテストが落ちる。道具ごとの分け方は次のとおりだ。

Supabase CLIはv2.119.0の実験的な機能で、worktreeごとにsupabase startすると別々の環境が立ち、ポートもCLIが選ぶ。詳しくは今朝の記事（Supabase CLI、worktreeごとのローカル環境とDockerなしの起動に対応）にまとめた。

NeonはクラウドのPostgresを書き込み時コピーの「ブランチ」で分ける。作った時点のデータをそのまま持ち、書き込みは差分として保存されるので、親には負荷がかからない。並列のテストでは、ブランチごとに専用の計算資源が付く。データを持たない構造だけのブランチや、期限を過ぎると自動で消えるブランチも作れる。

Docker Composeでは、プロジェクト名が環境を分ける単位になる。名前は既定でフォルダー名から決まり、-p、環境変数COMPOSE_PROJECT_NAME、ファイルのname: の順で上書きできる。公式文書は使いどころとして、機能ブランチごとに環境を複製する例を挙げている。ただし、外に出すポート番号は、プロジェクト名とは別に分ける必要がある（編集部の推測）。

SQLiteは1ファイルが1つのデータベースだ。公式文書によると、書き込めるのは同時に1つの処理だけで、ほかはSQLITE_BUSYで断られることがある。エージェントごとにファイルを分ければ、取り合いそのものが起きない。ただし同じ文書は、ネットワーク上のファイルシステムにSQLiteのファイルを置かないよう勧めている。

ポートと準備の手順を決め打ちしない

並べた時に地味に効くのがポートだ。番号を人が決めて設定に書くと、2体目を立てたところでぶつかる。番号は道具に選ばせ、エージェントには決め打ちの既定値を使わせず、道具が出す接続先を読ませる。自分で組む場合も、接続先はworktreeごとに環境変数で渡す形にしておけば、何体並べても同じ手順で済む。

データの準備もworktreeを作る時に済ませたい。Cursorの文書には、worktreeを作るたびにnpm ci、.envの写し、npm run db:migrateを流す例が載っている。シードもここに足せば、どのエージェントも同じ出発点から始められる。

マイグレーションの衝突は残る

DBを分けても、最後に1つのmainに戻る点は変わらない。2体が別々にマイグレーションを足せば、合流した時に順番や中身がぶつかりうる。ここは道具が解いてくれない。片方を先に合流させ、もう片方はそれを取り込んでから自分のDBを作り直す、という順番を人が決めるしかない。Supabaseのブログは、宣言的なスキーマのファイルを書き換え、マイグレーションはCLIに書かせる使い方を紹介している。

編集部の見方

並べ方の型は「ファイルはworktree、DBは1体に1つ、ポートと準備は自動で」にまとまる。手元で軽く済ませるならSQLiteのファイル分けかComposeのプロジェクト名、本番に近いデータで試すならNeonのブランチ、Supabaseを使っているならCLIの新機能が近道だ。どの道を選んでも、マイグレーションを合流させる順番だけは人が決める。まずは2体から始めて、どこでぶつかるかを確かめたい。