エージェントを2本同時に走らせて、片方の編集がもう片方のテストを壊した経験がある人は、たぶん同じ作業コピーで並列をやっている。
モデルを増やす話じゃない。ファイルシステムの話だ。同じ checkout を2つのエージェントが触ると、後から書いた方が勝つ。マージプロンプトが出ても、どっちが正か人間が決めることになる。仕事は増えるのに、レビュー対象は汚れる。
Cursor の worktree は、その衝突を Git の孤立 checkout で避ける仕組みだ。Agents Window、IDE の /worktree、Cursor CLI の --worktree は入口が違うだけで、作られるものは同じ系統の作業コピーだ。公式どおり、エージェント用の worktree は ~/.cursor/worktrees/<repo>/<name> に並ぶ。
同じリポジトリでも、同じディレクトリである必要はない
Git の worktree は、1つのリポジトリに複数の作業ディレクトリを生やす機能だ。ブランチもファイルも別。依存関係も別。メインのブランチで手元の実験を続けながら、エージェントには別のディレクトリでテストを直させる。
IDE なら、チャットにこう書く。
/worktree 落ちている auth のテストを直して、ログインのコピーも更新する
CLI ならこうだ。名前を省略すると Cursor が付ける。--workspace はリポジトリのルートを明示したいとき。--worktree が変えるのは、そのプロジェクトの中でエージェントがファイルを編集する場所だけだ。
# 今いるリポジトリから、名前は自動
agent --worktree "upgrade the test runner and fix any broken snapshots"
# 別リポジトリを明示して、名前付き
agent --workspace ~/src/my-app --worktree auth-fix "fix the flaky auth test and open a PR"
終わったら、worktree 側からコミットして PR を開いていい。公式も「多くの場合はそのまま push してよい」と書いている。手元のメインへ取り込みたいときだけ /apply-worktree。捨てるなら /delete-worktree。存在確認は Git の正攻法で足りる。
git worktree list
作った直後は、依存が入っていない
ここが詰まりやすい。Cursor は tracked なファイルをメインからコピーするが、依存も環境ファイルも、DB のマイグレーションも自動では入らない。エージェントがテストを叩いて落ちるのは、テストが壊れているからではなく、作業コピーがまだ空だから、ということが多い。
公式の入口は .cursor/worktrees.json。Agents Window、IDE、CLI のどれで作っても、このファイルを見る。探す順は「worktree 側、その次にプロジェクトルート」。
{
"setup-worktree-unix": [
"npm ci",
"cp $ROOT_WORKTREE_PATH/.env .env"
]
}
Windows なら setup-worktree-windows が優先される。キーの値はコマンドの配列でも、設定ファイルの隣に置いたスクリプトでもいい。公式は依存の共有にシンボリックリンクを使わないよう書いてある。速いパッケージマネージャで、worktree ごとに入れ直す。メイン側のパスは環境変数で渡るので、秘密情報のファイルはそこからコピーする。
環境ファイルはメイン側からコピーする。依存をシンボリックリンクで共有するのは公式が非推奨で、メイン側が壊れる。速いパッケージマネージャで入れ直した方が安全。
コマンドの配列で足りないなら、設定ディレクトリ配下のスクリプトを指す。Unix は setup-worktree-unix、Windows は setup-worktree-windows が setup-worktree より優先される。セットアップが効いているかは、エディタの Output パネルで Worktrees Setup を選ぶ。ここを見ずに「エージェントがテストを回せない」とモデルを責めるのは早い。
セットアップが失敗したままエージェントを走らせると、テスト失敗の原因がコードなのか環境なのか切り分けられなくなる。先に Worktrees Setup のログを見る。
Cloud Agent は worktree ではない
紛らわしいので先に分ける。
ローカルの worktree は、自分のマシン上の別ディレクトリだ。Cloud Agent は孤立したクラウド VM だ。リポジトリを clone して別ブランチで作業し、PR で戻す。手元の checkout は触らない。並列に何本でも投げられて、ノート PC がネットから切れても動き続ける。
CLI の会話をクラウドへ渡すなら、メッセージの先頭に & を付ける。例は & refactor the auth module。続きは cursor.com/agents で拾う。
ここで効くフックも違う。Cloud Agent が読むのはリポジトリの .cursor/hooks.json（コマンド型）。~/.cursor/hooks.json はクラウド VM にホームディレクトリが無いので乗らない。prompt 型フックもクラウドでは動かない。ローカルで git の push を止めているつもりが、Cloud Agent 側では素通り、というのはよくある穴だ。拒否したい操作はプロジェクトの hooks に落とす。
環境そのものは .cursor/environment.json か、ダッシュボードの Build。テストも起動もできない VM に仕事を投げても、ループは閉じない。公式が「エンジニアにパソコンを渡さないのと同じ」と書いているのは、そこだ。
ディスクは無限ではない
worktree は増える。Cursor 3.5 以降、クリーンアップはマシン全体の上限で動く。デフォルトは 25 本。間隔の例は 6 時間。リポジトリごとではなく、そのマシン上の全ワークスペースが同じ枠を使う。設定キーは cursor.worktreeCleanupIntervalHours と cursor.worktreeMaxCount。
/worktree スキルや、素の git worktree add で作ったものも、クリーンアップの対象になる。残したい実験コピーを Cursor 管理下に置きっぱなしにしない。手元で残すなら、Git の普通の worktree として自分で管理した方がいい。
同じプロンプトを複数モデルで走らせる /best-of-n も、候補ごとに worktree を切る。比較はできる。ただし公式どおり、勝者をメインへ自動マージはしない。選んだ worktree から push するか、/apply-worktree する。
明日からやること
- 並列を始める前に、ルートへ最小の
.cursor/worktrees.jsonを置く。依存のインストールと環境ファイルのコピーだけでいい。 - 実験やテスト修正は
/worktreeか CLI の worktree オプション。メインの dirty な作業コピーは触らせない。 - リモートへ出す操作を止めたいなら、ローカルの user hooks だけでなく
.cursor/hooks.jsonに置く。Cloud Agent はホームディレクトリを見ない。 - 終わった worktree は PR にするか
/delete-worktree。上限の 25 を無限の作業領域だと思わない。
モデルを並列にする前に、作業コピーを並列にする。ファイルがぶつからない方が、レビューは短い。