Codexワークツリーの使い方と注意点

こんにちは。Osukeラーニング、運営者の「osuke」です。

Codexで新しい作業を始めるとき、LocalとWorktreeのどちらを選ぶか迷いますよね。ワークツリーは便利そうでも、detached HEAD、開始ブランチ、引き継ぎといった言葉が続くと、現在のコードを壊さないか、変更を見失わないかが不安になります。

結論からいうと、Codexワークツリーは作業を無条件に速くする機能ではなく、変更を別の場所に分ける機能です。独立したタスクを2つから試し、短い単独修正はLocalを選ぶと運用しやすくなります。この記事では、2026年9月19日に確認したOpenAIとGitの公式資料を仕様の根拠にし、Xの複数の公開投稿は実際の用途やつまずきを知る材料として分けて整理します。私自身の利用実績をもとにした体験談ではありません。

記事のポイント

• CodexワークツリーとLocalの違い
• 開始ブランチとセットアップの確認方法
• detached HEADや同じブランチの制限
• 並列化が向く仕事と向かない仕事

Codexワークツリーの使い方

最初に決めるのは、何個のチャットを動かすかではなく、どの変更を別の作業場所へ分けるかです。Localとの違い、Gitの状態、開始地点、環境の再現、完了確認の順に整理すると、初回でも迷いにくくなります。

Localとの違いを先に知る

Localは普段使っているチェックアウトで直接作業する方法です。Worktreeは同じGitリポジトリから別のチェックアウトを作り、独立したディレクトリでCodexを動かします。ファイルの置き場所が分かれるため、Localで自分が作業を続けながら、Worktreeで別の修正や調査を進められます。ただし、リポジトリの履歴やブランチ情報まで完全に別物になるわけではありません。

短い単独修正、今開いているIDEで直ちに確認したい作業、既存の開発サーバーをそのまま使いたい作業はLocalの方が簡単です。反対に、長いテストの追加と別機能の調査、緊急修正と進行中の改修のように、待ち時間や変更範囲を分けられる仕事はWorktreeに向きます。選ぶ基準は「複雑そうだから」ではなく「別の作業場所に置く意味があるか」です。

Cloudは、OpenAI側などのリモート環境で作業を進める選択肢であり、Worktreeと同じ意味ではありません。Worktreeはプロジェクトがあるコンピューターまたは接続先の開発環境上でGitの作業場所を分けます。作業をどこで実行するかと、同じリポジトリの作業場所をどう分けるかを別々に考えると、Local・Worktree・Cloudを混同しにくくなります。作業環境の全体像はCodexアプリ・CLI・IDEの違いと選び方でも整理しています。

迷ったときは、今のチェックアウトを空ける必要があるかを問い直します。必要がなければLocalのまま進め、別の成果を待つ時間があるならWorktreeを選ぶ。この一問を置くだけで、機能名の比較ではなく作業の流れに合った選択になります。

最初の使い分け

• 単独の小さな修正と即時確認はLocal
• 変更範囲を分けられる並行作業はWorktree
• リモート側で完結させたい仕事はCloudも比較

Gitリポジトリを確認する

CodexのWorktreeは内部でGit Worktreeを利用するため、対象プロジェクトがGitリポジトリに入っていることが前提です。単にフォルダーを開いただけで、Gitによる履歴管理がないプロジェクトでは同じ仕組みを使えません。CodexでWorktreeを選べないときは、設定画面を探し回る前に、対象のプロジェクトがGit管理されているかを確認するのが最初です。

次に、現在のブランチ、未コミット変更、リモートとの同期状況を確認します。OpenAIの公式文書では、mainやmasterだけでなく、機能ブランチ、ステージングされていないローカル変更を含む現在のブランチも開始地点に選べます。便利な一方、意図しない変更を含めて始めると、後で「今回のタスクが作った差分」と「開始前からあった差分」を見分けにくくなります。

さらに、2つのタスクが変更するファイルを想像します。たとえば、片方がログイン画面の表示、もう片方が同じ画面の入力検証を変える場合、ディレクトリが別でも統合時に同じ行を触る可能性があります。Worktreeは作業中の上書きを防ぎやすくしますが、統合時の論理競合まで消すものではありません。開始前の5分で、対象ファイルと完了条件を1行ずつ書いておくと境界が見えます。

未コミット変更を含めるか判断できない場合は、変更の目的を一覧にし、今回のタスクへ必要なものと無関係なものへ分けます。必要性を説明できない変更は持ち込まず、別の作業として残す方が、後の差分確認を短くできます。

開始前の5分チェック

• Gitリポジトリとして認識されているか
• 開始ブランチと未コミット変更は何か
• 並行タスクが同じファイルや同じ仕様を変えないか
• 各タスクの完了条件とテスト方法を書けるか

開始ブランチを正しく選ぶ

新しいチャット画面でWorktreeを選び、その下でベースとなるブランチを選択してから依頼を送ります。Codexは選択した地点を基に新しいWorktreeを作成します。ここで重要なのは、名前が分かりやすいブランチではなく、タスクに必要な前提コードが入っている地点を選ぶことです。作業の成否は、プロンプトより前の開始地点で決まることがあります。

たとえば、認証機能の修正がfeature/authの変更に依存しているのに、古いmainからWorktreeを作ると、Codexは必要なコードがない状態で原因を探すことになります。反対に、関係のない未コミット変更を多く含む現在ブランチから始めると、レビュー対象が広がります。「このタスクはどの変更を前提にするか」を一文で書き、その前提が入った最小の開始地点を選ぶのが安全です。

開始後には、Codexへ実装を急がせる前に、現在のブランチ相当の開始コミット、対象ファイル、実行予定のテストを確認させる方法もあります。これは作業を遅らせるためではなく、誤った土台で長く進む手戻りを防ぐためです。初回タスクの頼み方に迷う場合は、Codexの始め方と初回タスク6手順の完了条件の決め方も使えます。

開始地点が正しいか確信できないときは、実装前の成果を「関係ファイルと前提の一覧」に限定する方法があります。その一覧を人が確認してから変更へ進めれば、誤ったブランチで大きな差分を作るリスクを抑えられます。

開始地点を選ぶ順番

• タスクに必要な前提コードを言葉にする
• その前提を含む最小のブランチを選ぶ
• 未コミット変更を持ち込む理由があるか確認する
• 開始地点とテスト方法をタスク冒頭に残す

セットアップを再現する

Worktreeにはリポジトリで追跡されているファイルが用意されますが、依存関係、ビルド成果物、キャッシュ、ローカルだけにある設定まで同じ状態になるとは限りません。別ディレクトリであるため、パッケージの導入、コード生成、データベース準備などをやり直す場合があります。「コードはあるのにテストが動かない」というときは、不具合より先に環境差を疑います。

Codexのローカル環境にセットアップスクリプトを用意し、依存関係の導入や必要な準備を再現できるようにすると、Worktreeごとの状態差を減らせます。手順は「いつも手でやっていること」を全部書くのではなく、新しいチェックアウトが動作確認へ到達するために必要な最小単位にします。10分かかる準備を毎回人が直すより、成功・失敗が分かる1本の手順にした方が原因を追いやすくなります。

Xの公開投稿では、Claude CodeとCodexのセッションを5〜10個並行する利用者が、Worktreeごとのnode_modulesによる容量の重複を課題に挙げていました。これは個人の高並列な運用例であり、推奨数ではありません。ただし、依存関係やビルドキャッシュがWorktreeごとに増えるという注意はOpenAI公式文書とも整合します。まず2つでセットアップ時間と容量を測り、共有キャッシュなどを検討するのはその後で十分です。

再現手順の良し悪しは、新しいWorktreeで同じコマンドを実行し、同じテスト開始地点へ到達できるかで確認します。途中で個人の記憶にしかない操作が必要なら、その1手だけを手順へ追加し、環境全体を複雑な自動化へ作り替えないのが現実的です。

環境差で詰まらないための確認

• 依存関係が自動で揃うと決めつけない
• セットアップを再実行可能な手順にする
• コードの不具合と環境不足を切り分ける
• Worktreeごとの容量と準備時間を測る

独立タスクを2つから試す

SNSでは、多数のAIコーディングセッションを同時に動かす使い方が目立ちます。陈成氏の公開投稿には5〜10個のClaude Code/Codexセッションを独立ディレクトリで動かす例があり、Michael Schade氏の投稿では独立Worktreeと差分レビューの価値が紹介されていました。ただし、これらは使い方の実例であり、Codexが保証する最適な並列数ではありません。

初回は、変更範囲が重なりにくい2タスクで十分です。たとえば「APIの入力検証を直す」と「別モジュールのテストを追加する」、「長いテストを調査する」と「READMEを更新する」のように分けます。それぞれに対象外の範囲、完了条件、実行するテストを書きます。同じ設定ファイルや共通型を両方が変更しそうなら、並行ではなく順番に処理した方が早いかもしれません。

完了後は、差分、テスト結果、未解決事項、統合順の4点を人が確認します。2件の結果を当日中に確認でき、待ち時間が減ったなら3件目を検討します。結果が積み上がって確認待ちになったら、起動数を増やす段階ではありません。Worktreeの価値は「同時に何個動かしたか」ではなく、「分離された変更を安全に確認して完了へ持っていけたか」で測ります。

2タスクの試し方

• 変更ファイルが重なりにくい2件を選ぶ
• 各タスクに対象外・完了条件・テストを書く
• 差分とテストを確認してから統合する
• 確認待ちが残るなら並列数を増やさない

Codexワークツリーの注意点

作業ディレクトリが分かれても、Gitのブランチ制限、成果を残す手順、設定ファイルの扱い、統合レビューは残ります。よくある誤解を先に解いておくと、Worktreeを増やしたのに作業が遅くなる失敗を避けやすくなります。

detached HEADを理解する

Codexが管理するWorktreeは、デフォルトでdetached HEADの状態から始まります。これは、特定のブランチ名を直接チェックアウトせず、選んだブランチの開始コミットを参照している状態です。「ブランチが壊れた」という警告ではありません。一時的に試し、不要なら捨てる作業場所を増やすとき、ブランチ名をむやみに増やさないための自然な開始方法です。

変更を残してリモートへpushしたい、Pull Requestとして共有したい場合は、Worktree側の「ここにブランチを作成」からブランチ化できます。普段使っているIDEや既存の開発サーバーで続けたい場合は、チャットをLocalへ引き継ぐ選択肢があります。つまり、開始時点では一時作業、確認後に残し方を選ぶという2段階で考えればよいわけです。

反対に、detached HEADという表示だけを見て、慌ててLocalと同じブランチをWorktreeへ割り当てようとすると、次の同一ブランチ制限に当たります。開始直後にブランチ名を付けること自体が目的ではありません。成果が採用候補になった時点で、Worktreeでブランチ化するのか、Localへ移すのか、破棄するのかを選ぶと、試行と正式な変更を分けられます。

たとえば調査だけで原因が分かり、コード変更が不要だったなら、ブランチを作らず結果だけを記録して終えられます。実装まで進み、レビュー対象として残したいときだけブランチ化する方が、用途不明のブランチを増やさずに済みます。

detached HEADでの判断

• 一時的な調査や試作ならそのまま進める
• pushやPRへ進めるならWorktree側でブランチ化する
• 普段のIDEで続けるならLocalへの引き継ぎを使う
• 採用しない変更は無理にブランチへ残さない

同じブランチの競合を避ける

Gitは原則として、同じブランチを複数のWorktreeで同時にチェックアウトさせません。ブランチはコミット、リセット、リベース、マージなどで更新される1本の参照なので、複数の作業場所が同時に正本として動かすと更新順が曖昧になるからです。これはCodexだけの制限ではなく、Git Worktreeの安全策です。

Worktreeで作ったfeature/aをLocalでもチェックアウトしようとして、すでに別Worktreeで使われているというエラーが出た場合は、強制操作で押し通すより、チャットをLocalへ引き継ぎます。あるいはWorktree側を別ブランチへ移し、元のブランチを解放します。どちらを選ぶかは、これから主に作業する場所を基準にします。LocalとWorktreeの両方を同じブランチの正本にしないことが重要です。

別ブランチを使えばすべての競合が消える、という反論にも注意が必要です。たとえば2つのWorktreeが同じ関数の引数を別々に変えれば、作業中は干渉しなくても統合時に判断が必要になります。ファイル競合が発生しなくても、片方が古い前提に依存する論理競合は残ります。ブランチを分けるだけでなく、タスクの責任範囲と統合順も分けてください。

統合順を決めるときは、他方のタスクが前提にしている変更を先にします。独立しているつもりでも共通の型や設定を変えた場合は、1件目の統合後に2件目のテストをもう一度実行し、開始時点との差を確認する必要があります。

ブランチ競合を避けるルール

• 同じブランチをLocalとWorktreeの両方で使わない
• エラー時は引き継ぎか別ブランチへの移動を選ぶ
• 別ブランチでも同じ仕様や同じ行を同時に変えない
• 統合順とテスト担当をタスク開始時に決める

引き継ぎと無視ファイルに注意

引き継ぎは、チャットとコードをLocalとWorktreeの間で移動する仕組みです。Worktreeでバックグラウンド作業を進め、内容を確認する段階でLocalへ移すことも、Localで始めた仕事をWorktreeへ移してフォアグラウンドを空けることもできます。1つしか起動できないアプリや、普段のIDE設定を使った確認が必要なときに役立ちます。

注意したいのが、.gitignoreで除外されたローカルファイルです。Git操作を使う引き継ぎでは、無視対象のファイルは通常一緒に移りません。OpenAI公式文書では、ローカルのCodex管理Worktreeに必要な無視対象ファイルを、リポジトリ直下の.worktreeincludeで限定指定できます。ただし、これは「見つからないファイルを全部コピーする」仕組みとして使うものではありません。

設定ファイルに認証情報や顧客データが含まれる場合、利便性より先に保管ルールとアクセス範囲を確認します。必要なファイルだけを限定し、サンプル設定で代替できるものは実値を使わない方が安全です。セットアップ不足によるエラーとコードの不具合を混同しないため、ファイル名、入手方法、保管場所、実値を扱える環境を別々に記録してください。

引き継ぎ後に動かない場合は、直前の差分を疑う前に、無視ファイル、依存関係、実行ポート、外部サービスへの接続の順で環境差を確認します。確認順を固定すると、コードを戻しても直らない問題へ不要な修正を重ねるのを防げます。

無視ファイルの扱い

• .gitignore対象は通常の引き継ぎで移らない
• .worktreeincludeは必要なパスだけに限定する
• 秘密情報を無差別に複製しない
• サンプル設定と実値の設定を分けて管理する

並列化しすぎない基準を持つ

Worktreeはファイルの作業場所を分けますが、要件の確認、レビュー、テスト、統合判断まで不要にする機能ではありません。完了物が増えるほど、人が読む差分と失敗時の切り分けも増えます。SNSで多数セッションの運用例を見ても、その数だけを再現すると、作業中の待ち時間は減っても、確認待ちの山を作ることがあります。

Worktree一般については、並列開発には有効でも、日常の小さなバグ修正ではセットアップと調整の負担が上回り、マージ競合の責任は残るという反対意見も公開されています。これはCodex固有の仕様ではありませんが、判断材料として重要です。5分で直せる1ファイルの修正に、環境準備と引き継ぎで15分かかるなら、Localで終える方が合理的です。

並列数の上限は、起動できる最大数ではなく、当日中に差分、テスト結果、権限変更、未解決事項を確認できる数で決めます。目安として、2件の結果を確認して両方を安全に完了できたら3件目を試し、未確認の成果が1件でも翌日に残るなら増やしません。速度の指標を「開始した件数」ではなく「検証して統合できた件数」に変えると、Worktreeが目的化しにくくなります。

また、Worktreeごとのディスク使用量が増え、セットアップが長くなったら、古いチャットや不要なWorktreeの整理も必要です。Codex管理Worktreeはデフォルトで直近15個を保持するため、数だけでなく依存関係とビルドキャッシュの大きさも見ます。

増やす・止める判断

• 独立タスクがあり、待ち時間を別作業に使えるなら増やす
• レビュー待ちや環境エラーが積み上がったら止める
• 小さな単独修正はLocalへ戻す
• 完了と検証の件数を並列化の成果にする

Codexワークツリーのまとめ

Codexワークツリーは、現在の作業を守りながら、独立したタスクを別のGitチェックアウトで進めるための仕組みです。OpenAIのCodex Worktree公式ガイドでは、Gitリポジトリでの開始方法、detached HEAD、Localとの引き継ぎ、同一ブランチの制限、管理Worktreeと永続Worktreeの違いまで確認できます。仕様は公式文書で確認し、SNSの投稿は運用のヒントとして分けて読むことが大切です。

開始前は、Gitリポジトリ、ベースブランチ、未コミット変更、セットアップ、変更範囲、完了条件を確認します。作業後は、差分、テスト、未解決事項を見て、Worktree側でブランチを作るか、Localへ引き継ぐか、採用せず閉じるかを決めます。同じブランチを2か所で使わず、無視ファイルや秘密情報は必要最小限にするのが基本です。

今日試すなら、現在の作業と変更範囲が重ならない1件を選び、LocalとWorktreeの2作業だけで一巡させてください。Codexでできる仕事の全体像から選びたい場合は、Codexでできること・使い方・注意点を先に確認すると候補を絞れます。短い単独修正ならLocalを選ぶ判断も正解です。Worktreeを使った数ではなく、分離した変更を安全に確認し、完了へ進められたかを基準にしましょう。

初回の記録には、準備にかかった時間、Codexの作業時間、レビューと手直しの時間を分けて残します。合計時間が短くなったかだけでなく、Localの作業を中断せずに済んだかも見れば、自分の仕事にWorktreeが合うか判断できます。

最初の1回で行うこと

• 今の作業と重ならない独立タスクを1件選ぶ
• 開始ブランチ・対象外・完了条件・テストを書く
• Worktreeで実行し、差分とテスト結果を確認する
• ブランチ化・引き継ぎ・破棄のどれかを選ぶ