#cursor#worktree#parallel-agent#apply#git

Cursor 組み込み Worktree：上級活用

8 min read

06-cursor-cli-with-worktree は 手動 worktree + CLI の並列利用を扱いました。本稿は Cursor が自動作成する worktree（並列 Agent / Apply）の上級活用に焦点を当てます：複数タスクの投入、Apply で Merge と Full Overwrite の選択、コンフリクト解消、git worktree list による日常管理。導入は省略し、実践に直行します。

上級シナリオ 1：複数タスク並列 → レビューしてから Apply

一つの機能を複数の「サブタスク」に分け、それぞれを Agent が自分の worktree で実行。Apply するのは欲しいものだけで、一括で全部ではない。

例：「utils のリファクタ」「ユニットテスト追加」「API ドキュメント生成」を同時にやりたい場合：

  • 異なるプロンプトで 3 つの並列 Agent を開始（または 1 つずつ、それぞれ worktree で）
  • 終了時に 3 つの結果：例えば「リファクタ」は良し、「テスト」は手直し、「ドキュメント」は捨てる
  • 「リファクタ」のカードだけ Apply；他は Apply しないので、main にマージされるのはリファクタのみ — 残り二つはメインディレクトリに触れない

上級のポイント：一度に全部コミットする必要はない。「タスクごと・カードごとに Apply」でき、main に入るのは承認したものだけ。

上級シナリオ 2：Apply で Merge か Full Overwrite か

Apply 時、Cursor はクリーンにマージしようとします。同じ Best-of-N や複数回の Apply でコンフリクトが出ると、選択を求められます：

オプション いつ使うか
Merge（コンフリクト解消 UI） main の内容を一部残し、worktree の変更の一部だけ取り込みたいとき、または複数 worktree の変更を「段落ごと」にマージしたいとき
Full Overwrite worktree のファイルを採用し、main のファイルを丸ごと置き換えてよいとき、またはコンフリクトが多すぎて「このカード」を唯一の正としたいとき

実務では：単一タスク・単一 Agent・少数ファイル → Merge で十分なことが多い。同じリクエストを複数モデル（Best-of-N）で実行し、カード A の一部とカード B の一部を Apply → コンフリクトしやすい；その場合は 1 枚のカードだけ Apply するか、Merge でファイル単位に解消。複数カードから同じファイル群に Full Overwrite を繰り返すのは避ける — 上書きし合ってしまう。

上級シナリオ 3：main に未コミット変更があるときの挙動

worktree 作成時、Cursor はメインディレクトリの追跡済み変更と新規ファイルを worktree に持っていく（Git で無視されているファイルは持っていかない）。したがって：

  • main で何か変更してコミットしない状態で worktree の Agent を開始 → Agent は「現在の状態」の上で作業する；Apply すると「未コミット変更 + Agent の変更」をマージすることになる
  • 並列タスクをクリーンな main から始めたいなら、先に git stash または commit してから worktree を作成し、「WIP + Agent の変更」が混ざって Apply でコンフリクトだらけになるのを防ぐ

逆に利用することもできる：意図的に main に WIP を残し、実験用の worktree を作り、Apply では Merge で気に入った部分だけ取り込む；残りは worktree に残して Apply しない。

上級シナリオ 4：git worktree list で確認・整理

Cursor が作った worktree は git worktree list に表示される。パスはだいたい .cursor/worktrees/<repo>/<id> の下：

git worktree list

習慣にするとよいこと：

  • Apply して main が問題なさそうになったら Cursor が数は自動管理；リストに worktree が多くてディスクがきつい場合は、Cursor の設定（例：cursor.worktreeMaxCount、クリーンアップ間隔）を確認するか、使っていない Cursor のプロジェクトウィンドウを閉じて古い worktree を片付けさせる
  • デバッグ時：リストで「サンドボックス」がいくつあるか、各 worktree がどのブランチかが分かるので、main と Agent の worktree を混同しない

Cursor が作ったパスに対して、その Agent が終わったと分かっていない限り、手動で git worktree remove は避ける。そうでないと Cursor の内部状態がずれることがある。

上級シナリオ 5：並列 Agent が同じファイルを触る場合

2 つの Agent を、一方は src/auth/、もう一方は src/api/ を変更するように動かすと、通常はコンフリクトしない — 片方 Apply してからもう片方（順序はあまり関係ない；Merge で自動解決することが多い）。

両方の Agent が同じファイルを変更した場合（例：両方とも package.json や同じ config.ts を触る）：

  • 1 つ目を Apply → main にその変更が入る
  • 2 つ目を Apply → マージフローに入り、コンフリクトが出ることがある
  • Cursor のコンフリクト UI で「main のこの部分、worktree のこの部分」を選ぶか、2 つ目の worktree の版を丸ごと使うなら Full Overwrite

戦略：並列タスクを組むときは、Agent ごとにファイル集合を重ならないようにする（例：1 つは frontend 用ディレクトリ、1 つは backend 用）；そうすると手でコンフリクトを解くことはほとんどなくなる。

まとめ

  • 複数タスク並列：worktree でサブタスクに分け、レビューしてから欲しいカードだけ Apply；main に入るのは承認した分だけ
  • Apply の選択：main の一部を残すなら Merge；worktree のファイルを採用するなら Full Overwrite；複数カードから同じファイルへの Full Overwrite の重複は避ける
  • メインディレクトリの状態：未コミット変更は worktree に持ち込まれる；クリーンなベースにしたいなら先に stash/commit；または意図的に WIP を残して「実験用 worktree + 選択的 Merge」に使う
  • 管理：git worktree list で確認し、Cursor のクリーンアップと整合；タスクごとにファイル集合を重ならせないとコンフリクトが減る

次: 09-worktree-advanced — Best-of-N 複数モデル比較、worktrees.json、クリーンアップ設定。