Cursor Worktree 上級: Best-of-N と worktrees.json

前回 08-worktree-merge では Cursor の自動作成 worktree と Apply を扱った。今回は Best-of-N（同じプロンプトを複数モデルで並列実行し、1 つを選んで Apply）と worktrees.json（worktree 作成時に deps インストール・マイグレーション実行・.env コピー）の二本立て。

Best-of-N: 1 プロンプト、複数モデルを一括

Best-of-N とは：1 つのタスクを送ると、Cursor が 複数モデル を別々の worktree で実行し、各モデルの変更が「カード」として複数出る — 1 枚選んで Apply する。

いつ使うか

要するに：複数モデルが同じタスクをやり、その中から 1 つを選ぶ — 難易度が高いタスクや品質を重視するときに有効。

使い方

Cursor で Agent を開始する際、「複数モデル」または Best-of-N オプション（現行 UIに応じて）を選ぶ。プロンプト送信後、複数カードが表示される；切り替えて比較し、main に Apply したい 1 枚を選ぶ。

同一 Best-of-N 実行から 2 枚以上 Apply する（例：A を Apply してから B）と、Cursor が マージ（コンフリクト解消） か Full Overwrite（ファイル全体を置換）を聞くことがある。

worktrees.json: worktree 作成時に環境を整える

Cursor が worktree を作成するとき、デフォルトでは 追跡済みファイル をメインディレクトリからコピーするが、deps のインストール・.env のコピー・DB マイグレーションは行わない。
.cursor/worktrees.json で、新規 worktree 作成後に実行するコマンド を指定できる（例：npm ci、cp .env、npm run db:migrate）。

設定の置き場所

Cursor は次の順で参照する：

1. プロジェクトルート: .cursor/worktrees.json
2. worktree のパス

通常は プロジェクトルート に置く：.cursor/worktrees.json。

設定の 3 キー

各キーは次のいずれか：

• 文字列: スクリプトへのパス（.cursor/worktrees.json を含むディレクトリからの相対）
• 配列: シェルコマンドのリスト。順に実行

例: Node プロジェクト

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

$ROOT_WORKTREE_PATH は Cursor が渡す変数で、メインの作業ディレクトリ を指す（例：.env のコピー元）。
Windows では copy や PowerShell が必要な場合がある；OS で分けてもよい：

{
  "setup-worktree-unix": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ],
  "setup-worktree-windows": [
    "npm ci",
    "copy %ROOT_WORKTREE_PATH%\\.env .env"
  ]
}

例: DB マイグレーション実行

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env",
    "npm run db:migrate"
  ]
}

複雑な場合: スクリプトファイルを参照

コマンドやロジックが多い場合はスクリプトを書き、worktrees.json から参照する：

{
  "setup-worktree-unix": "setup-worktree-unix.sh",
  "setup-worktree-windows": "setup-worktree-windows.ps1",
  "setup-worktree": ["echo 'Using generic fallback'"]
}

スクリプトは .cursor/ 以下に置く（例：.cursor/setup-worktree-unix.sh）。中身は npm ci、.env コピー、chmod、マイグレーションなど。
Windows では .ps1 を使い、スクリプト内でメインディレクトリのパスは $env:ROOT_WORKTREE_PATH を使う。

ヒント: worktree に deps を symlink するのは避ける — メイン worktree とぶつかることがある。npm ci、pnpm、bun、uv などで新規インストールする。

worktree のクリーンアップと上限

Cursor は worktree の数を管理してディスクを圧迫しないようにする：

• 各ワークスペースに 最大 worktree 数（例: 20）がある
• 上限を超えると 最も最近使っていない ものから削除される
• クリーンアップは ワークスペース単位；別リポジトリ同士は影響しない

調整するには（Cursor のバージョンが対応していれば）、次のような設定を探す：

• cursor.worktreeMaxCount: 保持する worktree の最大数
• cursor.worktreeCleanupIntervalHours: クリーンアップの実行間隔

キー名は Cursor の現行設定に依存する。

worktree セットアップのデバッグ

worktree 作成後に deps が入っていない・マイグレーションが走っていない場合は、Cursor の Output パネルを開き、ドロップダウンで 「Worktrees Setup」 を選ぶ。作成時に実行されたコマンドとエラーが確認でき、worktrees.json やスクリプトの問題のデバッグに使える。

まとめ

• Best-of-N: 同じプロンプトを複数モデルで並列実行し、1 枚のカードを選んで Apply。ベンチマーク・難題・品質重視に有効
• worktrees.json: .cursor/worktrees.json で setup-worktree / setup-worktree-windows / setup-worktree-unix により作成後にコマンドやスクリプトを実行
• .env などを main からコピーするには $ROOT_WORKTREE_PATH（Unix）または %ROOT_WORKTREE_PATH% / $env:ROOT_WORKTREE_PATH（Windows）を使用
• worktree には上限と自動クリーンアップあり；デバッグは Output → Worktrees Setup で

次: 10-headless-scripts — --print・--force によるヘッドレスモードと、実際にファイルを書き換えるスクリプト。