Codex ワークツリーとは：並列タスク実行の基本と使い方

ワークツリーとは何か — Git の基本機能から理解する

Git のワークツリー機能は、ひとつのローカルリポジトリ（.git ディレクトリを持つフォルダ）から、複数の異なるブランチを別々のディレクトリに同時に展開できる仕組みだ。この機能は Git 2.5（2015年リリース）から搭載されており、大きなリポジトリで複数ブランチを並行して扱うエンジニアを中心に使われてきた背景がある。

通常の Git 操作では、あるブランチで作業しているときに別のブランチの内容を見たい場合、git checkout または git switch でブランチを切り替える必要がある。ブランチを切り替えると現在の作業ツリーの内容が変わるため、複数ブランチの内容を同時に参照・編集することは難しい。また未コミットの変更がある状態でのブランチ切り替えは、変更を一時保存（git stash）するか破棄するかの判断が必要になり、手間がかかる。

Git の worktree 機能を使うと、git worktree add ../my-feature feature-branch のようなコマンドで feature-branch というブランチを ../my-feature という別ディレクトリに展開できる。元のリポジトリディレクトリと .git を共有しているため両者は同じリポジトリの一部だが、ファイルシステム上は独立した場所に存在する（出典: https://git-scm.com/docs/git-worktree ）。

この機能の実用的な意義は「複数の作業を同時並行で進める」ことを Git のレベルで安全に実現できる点にある。たとえば本番バグの修正と新機能の開発を同時進行したいとき、ワークツリーを使えばどちらかの変更が他方に影響することなく、それぞれの作業を続けられる。

Git worktree の主要なコマンド

Git のワークツリー操作には以下のコマンドが主に使われる。

1. git worktree add <パス> <ブランチ名> — 指定パスに既存ブランチを展開する
2. git worktree add -b <新ブランチ名> <パス> — 新しいブランチを作成しながら展開する
3. git worktree list — 現在作られているワークツリーの一覧を表示する
4. git worktree remove <パス> — 不要になったワークツリーを削除する
5. git worktree prune — 参照先ディレクトリが存在しないワークツリーの記録を整理する

Codex は内部でこれらの操作を自動的に行うため、ユーザーが手動でコマンドを実行する必要は基本的にない。ただし仕組みを理解しておくことで、Codex が生成したブランチの管理や予期しない動作へのトラブルシュートがやりやすくなる。

Codex がワークツリーを採用している理由

Codex がワークツリーを並列実行の基盤として使う理由は、エージェントの安全性と独立性を確保しながら、開発者のリポジトリに誤った変更を直接書き込まないようにするためだ。

OpenAI の Codex CLI は、タスクを受け取ったときにリポジトリの現在の状態を元に新しいワークツリー（と専用ブランチ）を作成し、そのワークツリー内でコードの読み込み・編集・テスト実行を行う。タスクが完了してもメインブランチへの変更は自動で適用されることなく、開発者が確認・承認した段階でマージするかどうかを決める。この設計によって、Codex が生成したコードが人間のレビューを経ずに本番環境に反映されることを防いでいる（出典: https://github.com/openai/codex ）。

エージェント間の分離が必要な理由

並列で動くエージェントが同じファイルを同時に編集しようとすると、標準的な Git の仕組みだけでは衝突が発生する。たとえばエージェント A が src/utils.ts の 30 行目を書き換えている最中に、エージェント B が同じファイルの 28〜35 行目に変更を加えようとすると、どちらの変更が正しいのかを自動的に判断できない。

ワークツリーを使うと、エージェント A は自分専用の作業ディレクトリ内の src/utils.ts を編集し、エージェント B は別の作業ディレクトリ内の同ファイルを編集する。両者はファイルシステム上でまったく別の場所にあるため、リアルタイムでの干渉が起きない。最終的にどちらの変更を採用するかは、プルリクエストのレビューを通じて開発者が判断する流れになる。

セキュリティ面でのメリット

ワークツリーによる分離はセキュリティの観点からも重要な役割を果たす。Codex のサンドボックスモードでは、ネットワークへの書き込みやシステム設定の変更を制限できるが、ワークツリーを使うことで変更の及ぶ範囲をさらに限定できる。エージェントの操作が特定のワークツリー（ブランチ）の範囲内に収まるため、想定外のファイルが書き換えられるリスクを減らせる。加えて、ワークツリーは git objects を共有しているため、ある作業ツリーが壊れても元のリポジトリのコミット履歴には影響が及ばない安全性がある（出典: https://platform.openai.com/docs/codex ）。

Codex CLI でのワークツリーの動き方

Codex CLI を使ってタスクを実行するとき、バックグラウンドでどのようにワークツリーが使われているかを理解しておくと、ブランチ管理や成果物の確認がスムーズになる。

Codex CLI でタスクを起動すると、以下の流れでワークツリーが作成・利用される。

1. タスク受信 — Codex はプロンプト内容を受け取り、対象リポジトリを確認する
2. ワークツリー作成 — git worktree add に相当する操作でタスク専用のブランチと作業ディレクトリを作る
3. 作業実行 — 専用ワークツリー内でコードの読み込み・編集・テスト実行を行う
4. 結果の提示 — 変更内容をまとめてユーザーに提示し、プルリクエストの作成またはブランチ保持を提案する
5. クリーンアップ — タスクが不要と判断されたワークツリーを削除する

ワークツリーのライフサイクル

各ワークツリーは基本的に「1タスク＝1ワークツリー」の対応関係になる。タスクが正常に完了してプルリクエストが作成されると、ワークツリーは削除されブランチだけが残る。タスクが失敗したりユーザーが手動で停止した場合は、ワークツリーとブランチの両方が不完全な状態で残ることがある。

git worktree list コマンドを実行すると、現時点で存在するワークツリーの一覧を確認できる。意図せず残ったワークツリーがあれば git worktree remove <パス> で削除し、対応するブランチも git branch -d <ブランチ名> で整理するのが基本的なメンテナンス手順になる。ブランチに未マージのコミットがある場合は -d ではなく -D オプションが必要になる点に注意する。

タスク数とワークツリー数の関係

Codex で複数タスクを並列で動かすと、同時に複数のワークツリーが存在することになる。リポジトリの容量が大きい場合、各ワークツリーは git objects を共有しつつ個別のファイルツリーを持つため、ディスク容量の消費が通常より増える。node_modules のような重い依存ディレクトリはワークツリーごとに個別にインストールされる場合があり、容量がさらに増加することもある。タスクを多数並列実行する際は、完了後に不要なワークツリーをこまめに削除するとディスク管理がしやすくなる（出典: https://github.com/openai/codex ）。

ワークツリーを意識した効果的な Codex の使い方

ワークツリーの仕組みを理解したうえで Codex を使うと、タスクの設計から成果物のレビューまでをより意図した形で進められる。

タスクの粒度を「ブランチ 1 つ分」に合わせる

ワークツリーは 1 タスクにつき 1 ブランチを作る前提で動くため、タスクの粒度を「1 つのプルリクエストにまとめられる作業量」に合わせると管理しやすい。「ログイン機能を実装して、テストも書いて、ドキュメントも更新して」という大きな指示を 1 タスクに詰め込むと、プルリクエストの変更範囲が広くなりすぎてレビューに手間がかかる。「ログイン機能の実装」「ログインのテスト追加」「ログインのドキュメント更新」と分けて 3 タスクを並列で走らせる方が、それぞれのプルリクエストが単一の目的を持ち、確認が格段に楽になる。

作業ごとに担当ファイルやディレクトリが重ならないように指示を設計することもポイントだ。「src/components/ 以下のみ修正する」「README.md は変更しない」といった制約を指示の中に含めておくと、ワークツリー間のコンフリクトリスクをさらに低減できる。

AGENTS.md でワークツリー環境を整える

プロジェクトのルートに置く AGENTS.md ファイルは、Codex がタスクを開始するときに読み込む設定ファイルだ。テストの実行コマンド、依存パッケージのインストール手順、コードスタイルのルールを記載しておくと、各ワークツリー内でエージェントが統一された環境でコードを書ける。複数のワークツリーが存在していても、各エージェントは同じ AGENTS.md を参照するため、設定の一貫性が保たれる（出典: https://platform.openai.com/docs/codex/guides/agents-md ）。

AGENTS.md に記載する内容の例:

• 使用するパッケージマネージャー（npm / yarn / pnpm）と依存インストールコマンド
• テスト実行コマンド（例: npm test / pytest tests/）
• コード整形ツールの実行コマンド（例: npm run lint）
• 変更してはいけないファイル・ディレクトリのリスト

完了後のブランチ整理を習慣にする

Codex タスクを繰り返し使うと、未マージのブランチが蓄積することがある。git branch --no-merged コマンドで未マージブランチを一覧表示し、不要なものを定期的に削除するのが長期的な管理コストを下げるポイントになる。ブランチ名にタスクの目的や日付を含めるルールを設けておくと、後から見返したときにどのブランチが何のためのものかがすぐわかり、削除判断がしやすくなる。

ワークツリーに関するトラブルと対処法

Codex を使っていてワークツリーに起因するトラブルが発生することがある。よくあるパターンと対処法を押さえておくと、問題が起きたときに素早く対応できる。

ワークツリーが残ってディスクを占有する

Codex のタスクが途中でキャンセルされたり、ネットワーク切断などで異常終了したりすると、不要なワークツリーがリポジトリ内に残ることがある。この場合、git worktree list でワークツリーの一覧を確認し、不要なものを git worktree remove <パス> で削除する。対応するブランチが残っている場合は git branch -D <ブランチ名> で削除する（出典: https://git-scm.com/docs/git-worktree ）。

削除できない場合は、ワークツリーのディレクトリ自体が別プロセスに使われている可能性がある。Codex CLI プロセスが動き続けているなら、先にプロセスを終了してから削除を試みる。それでも削除できなければ git worktree prune を実行すると、参照先ディレクトリが存在しないワークツリーの記録を Git の管理データから除去できる。

「ロックされたワークツリー」エラーが出る

git worktree remove を実行したとき error: 'path' is locked というエラーが出ることがある。これはワークツリーが別の操作によってロックされているためだ。git worktree unlock <パス> でロックを解除してから再度削除を試みる。それでも解決しない場合は .git/worktrees/<ワークツリー名>/locked ファイルを手動で削除するという方法もある。削除後に git worktree prune を実行して記録を整理すると、以後のトラブルを防ぎやすくなる（出典: https://git-scm.com/docs/git-worktree ）。

同じブランチを複数のワークツリーで使おうとするとエラーになる

Git のワークツリーは「1 ブランチを複数のワークツリーで同時にチェックアウトすること」を許可していない。Codex がタスク用ブランチを作成しようとしたとき、同名のブランチが既に別のワークツリーでチェックアウトされていると作成に失敗する。この場合は既存のワークツリーを削除するか、タスクのブランチ名を変えるかで対処できる。タスクごとにユニークなブランチ名を自動生成する Codex の設計がこのエラーを防ぐためにあるが、手動でブランチ名を指定する際は重複に注意が必要だ。

ワークツリーと並列エージェントを組み合わせた実践例

ワークツリーの仕組みを活かした実際の開発パターンをいくつか紹介する。

独立したバグ修正を並列で処理する

複数の Issue が積み上がっていて、それぞれが互いに無関係の場合、並列で修正を走らせると全体の処理時間を大幅に短縮できる。「ログイン画面の表示崩れを直す」「API のタイムアウト処理を追加する」「旧バージョンの依存パッケージを更新する」の 3 つは互いの変更が干渉しないため、並列で進めやすいケースだ。各エージェントが別々のワークツリー（ブランチ）で作業し、それぞれのプルリクエストをまとめてレビューする流れが自然に組める。

テストとドキュメントの更新を並行させる

新機能を実装した後、テストコードの追加とドキュメントの更新を同時に走らせるパターンも実用的だ。テストとドキュメントは同じコードベースを参照しながらも互いに書き換えるファイルが重なりにくいため、並列に進めてもコンフリクトが起きにくい。Codex にそれぞれのタスクを同時に投げると、2 つのワークツリーが作られてそれぞれの作業が並行して進む。

複数言語対応の実装を同時進行する

同じロジックを JavaScript と Python の両方で実装する、あるいはデスクトップとモバイル向けに別々の UI を同時に実装するといった作業は、エージェントごとに明確な担当範囲を与えやすい。作業範囲がファイル単位・ディレクトリ単位で分けられるほど、ワークツリーによる分離が効果を発揮する。各エージェントは自分のワークツリー内のみを変更するため、片方の実装が完了しても他方には影響が及ばない（出典: https://platform.openai.com/docs/codex ）。

まとめ

Codex のワークツリーは Git の worktree 機能を活用した、エージェントが安全に独立して動くための基盤となる仕組みだ。「1タスク＝1ワークツリー（1ブランチ）」という対応関係を把握しておくと、並列タスクの設計・管理・後片付けをより意図した形で行える。タスクの粒度を「1プルリクエスト分」に合わせる、AGENTS.md で環境を整える、完了後に不要なワークツリーを削除するという 3 点を意識するだけで、Codex を使った開発フローが整理しやすくなる。ワークツリーという概念をひとつ理解するだけで、Codex の並列実行機能を使いこなすための見通しが大きく広がる（出典: https://github.com/openai/codex ）。