Cursor Worktreeとは？git worktreeで並列エージェントを動かす完全ガイド【2026年最新】

Cursor Worktreeとは？git worktreeで並列エージェントを動かす完全ガイド【2026年最新】

git worktreeの基本コマンド：Cursor使用前に押さえておくこと

# 既存のブランチからworktreeを作成
git worktree add ../feature-auth feature/auth

# 新しいブランチを作りながらworktreeを作成
git worktree add -b feature/notifications ../feature-notifications

# 全worktreeの一覧を表示
git worktree list

# 使い終わったworktreeを削除
git worktree remove ../feature-auth

Cursor 3のWorktree機能：/worktreeと/best-of-nコマンド

/worktree 認証テストの失敗を修正して、ログイン画面のコピーも更新して

と打つと、エージェントがworktreeで作業して、完了後に/apply-worktreeでメインブランチに変更を取り込む流れになります。

/best-of-n sonnet, gpt, composer フラキーなログアウトテストを修正して

と打つと、各モデルが別々のworktreeで同じ問題に取り組んで、親エージェントが結果を比較してくれる。

Cursor AgentsウィンドウのエージェントLocation設定：Local・Worktree・Cloud

テキトー教師: Cursor 3で新たに追加されたAgentsウィンドウの話もしておきましょう。Cmd+Shift+P → Agents Windowで開けるやつですね。

.cursor/worktrees.jsonの設定：マルチエージェントの自動タスク分配

{
  "setup-worktree-unix": "npm install && cp .env.example .env.local",
  "setup-worktree-windows": "npm install; Copy-Item .env.example .env.local"
}

{
  "setup-worktree-unix": "SESSION=$(date +%s%N); AGENT_ID=1; while [ -f .task-claim-$AGENT_ID ]; do AGENT_ID=$((AGENT_ID+1)); done; echo $AGENT_ID > .agent-id; touch .task-claim-$AGENT_ID; echo 'Agent ID: '$AGENT_ID",
  "setup-worktree-windows": "..."
}

worktrees.jsonで設定できる内容の一覧

Cursor worktreeの実践的なセットアップ手順

ステップ1：worktreeを作成する

# メインプロジェクトのディレクトリで実行
cd ~/dev/my-app

# 2つのworktreeを並列で作成
git worktree add -b feat/auth ../my-app-auth
git worktree add -b feat/notification ../my-app-notification

# 作成されたか確認
git worktree list

ステップ2：各worktreeに依存パッケージをインストール

# worktree1のセットアップ
cd ~/dev/my-app-auth
npm install
cp .env.example .env.local

# worktree2のセットアップ
cd ~/dev/my-app-notification
npm install
cp .env.example .env.local

ステップ3：各worktreeをCursorで開いて並列実行

# ターミナルから2つのCursorウィンドウを開く
cursor ~/dev/my-app-auth
cursor ~/dev/my-app-notification

cursor worktreeの削除とクリーンアップ

# 1. worktreeのブランチの変更をメインにマージ
cd ~/dev/my-app
git merge feat/auth

# 2. worktreeディレクトリを削除
git worktree remove ../my-app-auth

# 3. ブランチも削除（任意）
git branch -d feat/auth

# 4. 古いworktreeの参照を整理
git worktree prune

worktreeのステータス確認コマンド早見表

cursor devcontainerとworktreeの組み合わせ

{
  "name": "My App Dev Container",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:18",
  "customizations": {
    "vscode": {
      "extensions": [
        "esbenp.prettier-vscode",
        "dbaeumer.vscode-eslint"
      ]
    }
  },
  "postCreateCommand": "npm install"
}

cursor worktree agentの実践例：複数機能を同時開発するワークフロー

1. git worktree add -b feat/search ../my-app-search
2. git worktree add -b feat/cart ../my-app-cart
3. Cursorで両方のworktreeを開いて、それぞれにエージェントを起動
4. エージェント1には「検索機能をsrc/features/searchに実装して」
5. エージェント2には「カート機能をsrc/features/cartに実装して」
6. 両方が完了したらdiffを確認してマージ

cursor worktree vs cursor local：どっちを使うべきか

cursor worktreeのよくあるエラーと対処法

cursor worktreeエラー早見表

まとめ

• git worktreeはcloneと違い、同じリポジトリを共有しながら作業ディレクトリだけを分離する仕組み
• Cursor 3では/worktreeコマンドと/best-of-nコマンドでworktreeを簡単に使えるようになった
• AgentsウィンドウでLocationを「Worktree」に設定すると、複数のエージェントを安全に並列実行できる
• .cursor/worktrees.jsonでworktree作成時のセットアップを自動化できる
• worktreeは「タスクが独立している」場合に最大限の効果を発揮する
• WSL2+devcontainerとの組み合わせには既知の制限がある

FAQ

Q. worktreeを使うとCursorの課金が増えますか？

Q. Cursor worktreeはWindows（PowerShell環境）でも使えますか？

Q. cursor worktrees（複数形）と worktree（単数形）は同じものですか？

Q. cursor worktree mergeのタイミングはいつがいいですか？

出典

• Cursor公式ドキュメント - Worktrees
• Cursor 3.0 リリースノート