Codex Worktreeで二つの作業を並行し個別に検証する

Codex Worktreeで二つの作業を並行し個別に検証する

決済ページを編集中に、連絡ページの不具合をCodexに直してもらいたいとします。約30分から45分で、二つの作業用コピーを開き、それぞれを検証してから、変更を適切な場所へ移せます。Gitのプロジェクト、Codexを使えるChatGPTデスクトップアプリ、プロジェクトのテストを実行する権限が必要です。

OpenAIのWorktreesガイドによると、CodexはGit worktreeを使い、同じリポジトリの二つ目の作業用コピーを作ります。各コピーは別々のファイルを持ちながらGitの履歴を共有します。並行できる二つの作業を分ける方法ですが、diffの確認、テスト、変更のレビューは引き続き必要です。Codexをリポジトリで初めて使うなら、先にCodex CLIで最初の変更を行うガイドを参照してください。

🧰 準備

ChatGPTデスクトップでプロジェクトを開き、Codexを選びます。プロジェクトのディレクトリがGitリポジトリ内にあることを確認します。決済ページと連絡ページなど、小さく独立した二つの作業を選びます。同じファイルを変更する、または未完了の同じ変更に依存するなら、並行で始める前に範囲を整理します。

開始時のブランチ、ファイルの状態、テストコマンドを記録します。パスワードや顧客データを依頼文に入れないでください。コマンド実行の権限についてはCodexの作業範囲と権限を守るガイドを参照してください。

OpenAIの文書では、Localは現在開いている作業用コピー、WorktreeはCodexが作る別のGitコピー、Hand offはその二つの間で会話とコードを移す操作です。WorktreeにはGitが必要で、Gitを使わないプロジェクトには同じ手順を適用できません。スマートフォンからworktreeを見る場合も、処理が端末上で実行されるわけではありません。Remoteは接続済みのコンピューターや遠隔環境を操作します。

🪜 手順

1. 並行できる独立した作業を選ぶ

二つの作業メモを作り、それぞれに入力、範囲、完了の確認方法を書きます。たとえば「連絡フォームのメール欄が空のときのエラー表示を直す」と「決済確認ボタンの文言を分かりやすくする」です。二つの会話に共通して「UXを改善して」とだけ頼まないでください。どちらのコピーがどの変更を担当したか分からなくなります。

一つ目のCodex会話はLocalで始めます。二つ目の作業では、会話を作る画面で入力欄の下にあるWorktreeを選びます。開始するブランチを選んでから依頼を送ります。Codexがそのブランチからworktreeを作ります。OpenAIによると、新しいコピーは既定でdetached HEADです。まだ新しい独立ブランチには載っていません。

次の依頼文をコピーし、角括弧の部分を置き換えてください。

[プロジェクト名]で、[ページまたはコンポーネント]だけを変更してください。
目標：[変更後の具体的な動作]。
[範囲外の場所]は変更しないでください。
終了前に[プロジェクトのテストコマンド]を実行してください。
変更ファイル、テスト結果、まだ確認できていない点を報告してください。

範囲と報告の指定があると、結果を確かめやすくなります。リポジトリのAGENTS.mdにチームのルールがあれば、Codexは作業ディレクトリに適用される指示も読みます。AGENTS.mdでチームのルールをそろえる方法も参考になります。

2. 新しいworktreeでテストできるようにする

Worktreeは別のディレクトリです。開始時のGit commitにあるファイルはありますが、インストール済みのライブラリ、Gitで無視される設定ファイル、Localで起動中のサービスがない場合があります。「packageがない」というエラーだけでCodexのコードが間違いだと判断せず、先に環境を確認してください。

OpenAIのLocal environmentsガイドでは、Codexがworktreeを作るときに走るsetup scriptと、よく使うコマンドのactionを設定できます。この機能はChatGPTデスクトップのCodexで利用します。Nodeプロジェクトなら、依存関係のインストールとbuildをsetup scriptにする例が考えられます。別のパッケージ管理ツールを使うリポジトリでは、例をそのままコピーしないでください。

適したプロジェクトでのsetup scriptの例：
npm install
npm run build

テスト用actionの例：
npm test

アプリのSettingsでlocal environmentを設定します。OpenAIによると、設定はプロジェクトのルートにある.codexディレクトリに保存され、Gitに入れてチームで共有することもできます。チーム全体に展開する前に、一つのworktreeで試してください。setup scriptがネットワーク権限を必要とする、または時間のかかるコマンドを実行するなら、承認する担当者を決めます。

3. Gitで無視するファイルを意図的に扱う

新しいworktreeには、通常.gitignoreで除外されたファイルがありません。アプリを動かすためにローカルのファイルが本当に必要なら、OpenAIはリポジトリのルートに置く.worktreeincludeを説明しています。ここに列挙した無視対象のファイルを、Codexが管理するローカルworktreeへコピーします。文書の例には.env、.env.local、独自の設定パスがあります。これはファイルをコピーする仕組みであり、Gitに追加する指示ではありません。

最初はダミーの設定ファイルかテスト用の環境変数を使います。機密ファイルを指定するのは、コピー先、アクセスできる人、アクセスを取り消す方法を理解してからにしてください。OpenAIは、遠隔worktreeやコマンドラインから自分で作ったGit worktreeには、このコピーが適用されないと明記しています。Codexは元のsymlinkをコピーせず、すでに存在するコピー先ファイルも上書きしません。

一つのテストを動かすためだけに、秘密情報のディレクトリ全体を指定しないでください。実際の連携が不要ならダミーデータを使います。本物の権限が必要なら、agentに渡す前にアクセス権と作業範囲を別々に確認します。

4. Localへ移す前に各作業の結果を確認する

Codexの作業が終わったら、各会話のdiffを開きます。変更ファイルを読み、その変更が入ったworktreeでテストコマンドを実行します。画面の不具合なら、実際の画面でも動作を試します。Local environmentsには、アプリ内でdiffの確認、行へのコメント、変更の一部をstageする操作、commit、push、pull requestの作成に使うGitの操作があります。

結果は作業ごとに分けて記録します。二つのworktreeが同じファイルを変更したら、両方のdiffを読み、どちらから取り込むか決めます。Gitは業務上の矛盾を自動で解決しません。

5. Worktreeを残すかHand offするか決める

Worktreeで作業を続けるなら、Create branch hereでそこにブランチを作ります。確認後にcommit、push、pull requestの作成を進めます。Gitでは同じブランチを二つのworktreeで同時にcheckoutできません。worktreeがそのブランチを使っている間、Localでも開こうとしないでください。

LocalにあるIDE、開発サーバー、既存の環境で確認したいなら、会話の見出しにあるHand offを使ってLocalへ移します。OpenAIによると、アプリは移動に必要なGit操作を処理します。その後もう一度移せば、会話は関連付けられたworktreeに戻ります。特にLocalに未コミットの変更がある場合は、移動の前後でGitの状態を確認します。

Hand offを「すべてをmergeするボタン」と考えないでください。移動後もdiff、テスト、ブランチを確認し、リポジトリのpull requestレビューを守ります。大きな作業にはCodex Subagentsで分担する方法もあります。ただし、subagentによる分担と二つのGit checkoutは別の仕組みです。

✅ 結果の例

試験では、連絡ページの作業はフォームだけを変更し、そのworktreeでnpm testが成功しました。決済ページの作業はボタン文言だけを変更し、あなたが画面と確認の流れを試しました。連絡ページはブランチを作ってpull requestに進め、決済ページは模擬決済環境で試すためLocalへHand offします。チームの記録では、二つの作業ID、二つのdiff、二つのテスト結果を分けて残します。

Worktreeに依存関係がなくテストできないなら、「未検証」と記録します。setupを済ませてテストを再実行してから状態を更新してください。

💡 結果を良くするコツ

会話には作業の名前を付けます。diffをすぐ読める大きさに仕事を保ちます。Gitにないファイルが必要なら、worktreeを開く前にチェックリストへ書きます。テストが失敗してから探すより確実です。繰り返すテストコマンドには共通のactionを使うと、新しいメンバーも同じ手順を実行できます。

OpenAIによると、Codexが管理するworktreeは自動で整理される場合があります。既定ではアプリが最近の15件を残し、この件数はSettingsで変更できます。実行中の会話、ピン留めした会話、permanent worktreeは自動整理の対象外です。長期間使う環境が必要なら、仮のコピーに頼らずpermanent worktreeを作ります。

⚠️ 知っておきたい制約

Worktreeはすべてを隔離するわけではありません。コピー同士はGitのmetadataを共有し、一台のマシンにある同じサービス、データベース、ポートを使うこともあります。二つの作業が同じ本番データを扱えば、影響し合う可能性があります。書き込みがあるならテストデータとテストアカウントを使ってください。

Gitで無視されるファイルは、Codexが.worktreeincludeでローカルworktreeへコピーする場合を除き、Hand offだけで自動的には移りません。コピーされた秘密情報は、アクセス権を別途管理すべきもう一つのコピーです。遠隔worktreeでは、ローカルのコピー手順に頼らず、その環境固有の仕組みを確認します。

機能や画面は変わる場合があります。WorktreeやLocal environmentsが見つからないなら、ChatGPTデスクトップを使っているか、Codexを開いているか、プロジェクトにGitがあるか確認してください。デスクトップの手順をCodex CLIやブラウザのセッションにそのまま当てはめないでください。

❓ よくある質問

Gitを使っていないプロジェクトでもCodex Worktreeを作れますか？ この手順ではできません。WorktreeはGitに依存します。プロジェクトのディレクトリで作業はできますが、Worktree機能による別のcheckoutは得られません。

開始前にブランチを作る必要がありますか？ いいえ。Worktreeと元のブランチを選ぶと、Codexは既定でdetached HEADのcheckoutを作ります。変更を保持してremoteへ送るときに、worktree内でブランチを作ります。

Localではテストが成功するのにWorktreeで失敗するのはなぜですか？ 依存関係、setup script、Gitで無視されたファイル、環境変数、依存サービスを確認してください。Worktreeは別ディレクトリなので環境が異なる場合があります。

LocalとWorktreeで同じブランチをcheckoutできますか？ Gitは同じブランチを二つのworktreeで同時にcheckoutできません。Hand offを使うか、チームの手順に合う別のブランチを作ります。

Worktreeを削除すると会話も消えますか？ OpenAIによると、会話は履歴に残る場合があります。Codex管理のworktreeは整理前にsnapshotが保存され、会話を開き直したとき復元を提案されることがあります。それでも重要な成果はリポジトリの手順に従ってcommitするなど、別途保存してください。

公式資料：Worktrees、Local environments。OpenAI Learn、2026年10月5日確認。

#Codex #GitWorktree #ChatGPT #VibeCoding

他の記事