CodexのWorktreeは、同じGitリポジトリの作業場所を分け、手元の変更と混ぜずに開発を進める機能です。大切なのは、別フォルダーを作ることだけではありません。どこでテストし、どの変更を引き継ぐかまで決めると、並行作業の結果を使いやすくなります。
この記事は2026年10月28日に確認したOpenAIの公式資料に基づく解説です。デスクトップアプリでの操作、Handoff、削除後の復元は編集部では実演していません。以下の依頼文と点検表は編集部が作った教材で、特定の案件の成功実績ではありません。 本記事では製品操作の実測は行っていません。
CodexのWorktreeで分けられるもの
Gitのブランチは変更の流れを分ける仕組みで、Worktreeはファイルを開いて作業する場所を増やす仕組みです。例えば、手元で検索画面を作っている間に、別のWorktreeで集計処理の修正を依頼できます。ファイルの置き場所が分かれるため、別々の変更を同じフォルダーへ同時に書き込むことを避けられます。
OpenAIのWorktreesの公式資料では、Gitで管理しているプロジェクトが必要とされています。各Worktreeはファイルの作業コピーを持ち、コミットやブランチの情報は共有します。LocalとWorktreeの両方は自分のコンピューター側で動き、Cloudとは実行場所が異なります（公式の実行環境の説明）。
ここで「フォルダーが別だから、すべてが独立した」とは考えないでください。例えば、両方の開発サーバーが同じポートを使ったり、同じ外部データベースへ接続したりすれば、ファイルの外で競合する可能性があります。これは編集部の運用上の注意です。ファイル、実行中のサービス、接続先を分けて点検すると、Worktreeで解決する範囲が明確になります。
Worktreeを使う仕事を、小さく分ける
最初は「別の担当へ丸ごと任せられ、変更範囲を説明できる仕事」を選ぶと管理しやすくなります。バグを一つ再現して修正する、決まった画面の表示を直す、といった単位です。二つの依頼が同じファイルの同じ箇所を直すなら、フォルダーを分けても最後の取り込み時に判断が必要です。
| 仕事の組合せ | 分け方の例 | 合流時の確認 |
|---|---|---|
| 検索画面と集計処理 | 対象フォルダーとテストを分ける | 画面が使うデータ形式が変わっていないか |
| 同じ画面の案Aと案B | 比較用として別Worktreeで作る | どちらを採用するか決めてから取り込む |
| 調査と実装 | 調査側は書き換えを依頼しない | 調査時点と実装時点のコードの違い |
この表は公式の制限一覧ではなく、編集部が提案する仕事の分け方です。「同時に動かす数」を先に増やすより、各仕事の終了条件を決めます。終了条件が違えば、結果を混ぜずに評価できます。
CodexでWorktreeの作業を始める
公式手順は、新しい会話でWorktreeを選び、開始元のブランチを指定して依頼を送る流れです。必要ならローカル環境も指定します。作成直後は通常、特定のブランチに付いていないdetached HEADという状態です。これはそれだけで作成失敗を意味しません。開始操作の名称や配置はアプリの版で異なる可能性があるため、公式資料と実際の表示を併せて確認してください。
開始前に残す情報は三つです。どのブランチを出発点にしたか、手元に未コミットの変更があるか、今回どこを変更するか。開始元に手元の変更を含める場合は、その変更が新しい作業にも入ることを意識します。別の仕事の未完了差分を持ち込むと、後で「今回の変更」を判別しにくくなります。
このWorktreeでは、検索結果が0件のときの表示だけを修正してください。
最初に作業ディレクトリ、開始元、変更済みファイルを確認してください。
検索APIとデータ形式は変更しません。
修正前の再現条件、変更ファイル、実行したテスト、未確認の点を返してください。
別の目的の変更が必要なら、その理由を先に説明してください。依頼後は、返答だけでなく作業対象のパスと差分を見ます。想定外のファイルが含まれていたら、追加実装へ進める前に由来を確かめます。書き換え済みファイルを全部削除してやり直すと、別の作業を失うおそれがあります。
Worktreeで実行できる環境を用意する
ファイルを取り出せても、テストや起動に必要な準備が済んでいるとは限りません。OpenAIのLocal environmentsは、新しいWorktreeで必要なセットアップを実行するための機能です。依存関係のインストールや初回ビルドを、プロジェクトに合わせて用意します。
編集部が勧める確認順は、必要な道具の版、依存関係、設定、テスト、起動です。例えば「画面が出ない」という一つの症状でも、ライブラリーが未導入なのか、起動した場所が違うのか、同じポートを別のサーバーが使っているのかで対処が変わります。コードの修正を重ねる前に、準備のどの段階で止まったかを分けてください。
Gitで無視している設定ファイルにも注意します。公式資料には、ローカルのCodex管理Worktreeへ必要な無視ファイルをコピーする.worktreeincludeの説明があります。ただし、自分でコマンドから作ったWorktreeなどへ同じ動作を一般化できません。秘密を含むファイルを無差別に指定せず、必要な項目と共有範囲を確認します。
Worktreeのまま続けるか、Localへ引き継ぐか
公式には、Worktree側でブランチを作って続ける方法と、Hand offでLocalへ移す方法が案内されています。前者はWorktreeで検証まで行える場合、後者は普段のIDEや手元の実行環境で確認したい場合に向きます。Handoffは会話とコードを移す操作なので、単に会話の名前を変える操作とは区別してください。
Gitでは通常、同じブランチを複数のWorktreeで同時にチェックアウトできません。「そのブランチは別の場所で使われている」というエラーが出た場合、強制的な操作を試す前に、どの作業場所がそのブランチを使っているか確認します。公式資料も、Localで続けるならHandoffを利用する流れを説明しています。
編集部の確認表では、引き継ぎ前に「変更の保存場所」「必要な設定」「未完了テスト」を記録し、引き継ぎ後に同じ項目を照合します。元の場所で合格したテストでも、移動先の設定や実行環境が変われば、必要な確認をもう一度行います。移動先に差分が見えることと、アプリが正しく動くことは別の完了条件です。
Worktreeの成果を取り込む前の点検
例えば、検索画面の修正担当と集計処理の修正担当が両方「完了」と報告したとします。各Worktreeでテストが通っていても、画面が期待する項目名と集計処理の出力が食い違う可能性があります。結果を合わせた状態で、利用者が行う一連の操作を確かめる工程を設けます。
- 各変更が依頼した目的に収まっているか、ファイルごとの差分を読む。
- テスト結果に実行した場所・対象・失敗の有無があるか確認する。
- 共通して触ったファイルやデータ形式を照合する。
- 取り込んだ状態で必要なテストと画面操作を確かめる。
- 未確認があれば、その対象と次の確認方法を残す。
「変更なし」と報告された箇所も、依頼の対象だったなら理由を確認します。既存動作で要件を満たしていたのか、調査できなかったのかでは判断が変わります。レビューの依頼方法はCodexのコードレビュー記事で詳しく説明しています。
Worktreeの整理は、必要な成果を保存してから
公式資料は、Codex管理Worktreeの自動整理と、削除前のスナップショット、再度会話を開いた際の復元について説明しています。ただし、会話履歴が残っていることだけを、必要なファイルの保存確認の代わりにはしないでください。大事な変更はコミットや成果物として確認し、どこに残したかを明確にします。
整理の前に、まだ実行中の処理がないか、未コミットの変更が必要か、生成物や設定の保存先はどこかを点検します。整理後に必要なファイルが見つからない場合は、同名のWorktreeを新規作成して埋め合わせる前に、元の会話と復元の選択肢を調べます。新規作成は、失われた作業が復元された証拠にはなりません。
最初の一件では、変更箇所を絞った仕事をWorktreeへ任せ、差分・テスト・引き継ぎまで一周させるのがおすすめです。会社の開発へ組み込む場合も、作業の分離方法と受入条件を先に決めると、任せる範囲を広げやすくなります。業務全体の選び方はCodexの業務活用を参照してください。
