git-worktree

並列エージェントのための Git ワークツリー

Cloudroom 内（$ROOM_THREAD_ID が設定されている場合）

自分で git worktree add を実行しないでください。Cloudroom が削除するのは、自身が作成したワークツリーだけです。手動で作成したワークツリーは ~/code にいつまでも残ります。

• 新しいタスク： 代わりに New worktree を使ってスレッドを開始します。

• このスレッドを専用のワークツリーに移動する： Cloudroom が管理するワークツリーにフォークします。Cloudroom がブランチを作成し、最後のスレッドがアーカイブされた後（ワークツリーの保持期間の設定に従います。デフォルトは 30 日です）にフォルダーを削除します。

  room-cli thread fork "$ROOM_THREAD_ID" --new-environment worktree --title "<task>" \
    --prompt "You now run in a new worktree. Copy the gitignored .env files from <primary checkout> into it, then stop and wait for the user."
  

  main から分岐するため、未コミットの編集は引き継がれません。先にコミットするか、--base-branch <ref> を渡してください。その後、新しいスレッドで続けて、このスレッドをアーカイブするようユーザーに伝えます。このスキルの残りの手順はスキップしてください。

まず確認すること

編集を始める前に、現在の作業場所を確認します。

[ "$(git rev-parse --path-format=absolute --git-dir)" = "$(git rev-parse --path-format=absolute --git-common-dir)" ] \
  && echo "primary checkout" || echo "worktree"

• プライマリーチェックアウト → タスク名のワークツリーを作成し、以下のセットアップを完了してから、そのワークツリーに cd して編集を始めます。
• ワークツリー（Cursor が作成したものを含む）→ タスクに進みます。

作業モデル

ワークツリーは作業ファイルとブランチを個別に持ちますが、Git の履歴、stash、設定、参照は共有します。

• 1 タスク = 1 ワークツリー = 1 エージェントセッション。 エージェント間で作業ディレクトリを共有しないでください。
• プライマリーチェックアウトは main のままにし、レビュー、マージ、プッシュにのみ使用します。
• 自動マージは行われません。人間が各差分を確認してから、マージするか、ワークツリーを破棄します。
• タスクブランチはローカルで短期間だけ使用します。ユーザーから明示的に依頼された場合を除き、プッシュするのは main のみです。
• 一度にマージするワークツリーは 1 つにしてください。main が進んでいる場合は、マージ前にタスクブランチをリベースします。

作成と削除

git worktree add ../myrepo-task-x          # new worktree + branch "myrepo-task-x"
git worktree add ../fix-y -b fix-y main    # explicit branch off main
git worktree list                          # see all worktrees
git worktree remove ../myrepo-task-x       # delete when merged/abandoned
git worktree prune                         # clean up stale registrations

ブランチは main を含め、1 つのワークツリーでのみチェックアウトできます。

Cursor では、Agents Window または /worktree <task> を使います。/apply-worktree は結果をメインのチェックアウトに適用し、/delete-worktree は結果を破棄します。/best-of-n model1,model2 <task> は、モデルごとに 1 つずつ、並列のワークツリーで同じタスクを実行します。Cursor は古いワークツリーを自動削除するため、結果は速やかに保存してください。タスクブランチのプッシュには、引き続き明示的な承認が必要です。

セットアップを完了する

新しいワークツリーに含まれるのは、追跡対象のファイルのみです。タスクに取りかかる前に、必要なセットアップを行います。

1. 環境変数／シークレットのファイル — .env、.env.local などのファイルをプライマリーチェックアウトからコピーします。編集内容が元ファイルに反映されるため、シンボリックリンクは使わないでください。
2. 依存関係 — ローカルにインストールします（npm ci、pnpm install、uv sync、bundle install）。プライマリーチェックアウトの node_modules へのシンボリックリンクは使わないでください。Next.js/Turbopack などのバンドラーは、ワークツリー外のパスを拒否します。シンボリックリンクになっている場合は rm -f node_modules で削除し、通常の方法でインストールします。
3. データベースとサービス — 状態を共有するか、ワークツリーごとに分けるかを選びます。サービスを共有する場合は、重複したインスタンスやポートの競合を避けるため、識別情報を固定します。Docker Compose のサービスを共有する場合は、トップレベルの name: などでプロジェクト名を固定します。そうしないと、ワークツリーごとにフォルダー名が異なるため、別々のプロジェクトが作成されます。SQLite ファイルなどの状態をワークツリーごとに分ける場合は、コピーするか、シードを再実行します。
4. ポート — 開発／テストサーバーとデバッガーは 1 つずつ実行するか、ワークツリーごとに別のポートを設定します。
5. 生成ファイルとキャッシュ — Git の追跡対象外である出力ファイルをワークツリー内で再生成します（npm run build、コード生成）。
6. Git フック — core.hooksPath と .git/config は共有されます。フックスクリプトがプライマリーチェックアウトのパスを前提としていないことを確認してください。

セットアップを自動化する

Cursor では、.cursor/worktrees.json を使って作成時にセットアップを実行できます（$ROOT_WORKTREE_PATH はプライマリーチェックアウトです）。

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

それ以外の場合は、チェックリストを scripts/setup-worktree.sh に記載し、新しいワークツリーごとに最初に実行します。ワークツリーからプライマリーチェックアウトを特定するには、次のコマンドを使います。

dirname "$(git rev-parse --path-format=absolute --git-common-dir)"

マージとクリーンアップ

# from the primary checkout, after reviewing the worktree's diff:
git merge --no-ff task-branch     # or: git merge --squash task-branch
git worktree remove ../myrepo-task-x
git branch -d task-branch

Cursor では、/apply-worktree を使ってから、レビューしてコミットします。

• ブランチを main にマージまたはプッシュしたら、各ワークツリーをすぐに削除します。ワークツリーをクリーンアップするものは、ほかにありません。
• 数日間停滞しているワークツリーは、リベースするか、作り直します。
• 早めに、こまめにコミットします。ワークツリーを削除すると未コミットの作業は失われますが、コミットは共有リポジトリに残ります。