Codexクラウドタスクの使い方｜差分を安全にレビューする流れ

2026年9月15日に確認したOpenAI公式資料では、Codexの実行場所はLocal、Worktree、Cloudに分かれます。Localは現在のプロジェクトディレクトリを直接扱い、WorktreeはGit worktreeに変更を隔離し、Cloudは設定済みのクラウド環境でリモート実行します。LocalとWorktreeは手元のコンピューター上、Cloudはリモートという違いです。

この違いを見ると、時間のかかる処理はすべてCloudへ送ればよいように思えます。しかし、長さだけでは安全な分担を決められません。直接開始するクラウドチャットでは、ローカルにしかない未コミット変更、社内ネットワーク、端末固有のツール、外へ渡せないデータが前提なら、同じ状態を再現できないからです。反対に、選択したブランチやコミットだけで目的と完了条件を説明できる調査・修正・テストは、手元の対話作業から切り離しやすくなります。

境界を決める質問は「クラウドでできるか」ではなく、「入力となるGitの基点、変更してよい範囲、実行する検証、触れてはいけない対象を、ローカルの暗黙知なしで指定できるか」です。指定できなければローカルで前提を整理し、指定できる単位まで小さくしてから委任します。Codexを開発工程へ組み込む全体像は、Codexで進めるAI駆動開発の実践ガイドも参照してください。

安全な運用は、クラウドへ送ってから始まるのではありません。委任前に基点と責任範囲を固定し、返却後に人が判断できる形へ戻すまでを一続きに設計します。クラウドの完了はゴールではなく、ローカルレビューへの受け渡し点です。

ローカル①タスク分離（目的・対象・禁止事項） → ローカル②環境準備（基点・依存関係・検証コマンド） → クラウド③実行（編集・チェック・結果返却） → ローカル④差分確認（範囲・意図・不要変更） → ローカル⑤検証（手元の条件で再実行） → ローカル⑥採用判断（stage・commit・PR）の順に進めます。

入口では、ローカルでタスクを分離し、目的・対象・禁止事項を決めます。続いて基点、依存関係、クラウドで実行する検証コマンドをそろえてから委任します。クラウドは編集とチェックを行い、回答と変更差分を返します。

出口では、返却差分の範囲・意図・不要変更をローカルで確認します。差分を説明できなければ追加指示または不採用へ戻し、説明できた差分だけを手元の検証へ進めます。完了条件を満たした場合に限り、stage、commit、PRの採用判断へ移ります。

この流れの二つの分岐には別の役割があります。「差分は説明可能か」はレビュー可能性の判定であり、「完了条件を満たすか」は動作の判定です。テストが通っても意図を説明できない変更は採用せず、読みやすい差分でも必要な検証に失敗すれば戻します。片方だけを合格条件にしないことが、クラウド委任と採用責任を分ける要点です。

最初に、作業の目的を一つへ絞ります。「認証まわりを改善する」のように解釈が広い指示ではなく、対象となる現象、変更可能なファイルや層、維持すべき振る舞い、確認コマンド、成果物を区切ります。調査と実装を分けられるなら、まず調査結果だけを返すタスクにします。判断材料が不足したまま編集範囲を広げるより、調査結果を読んで次の委任を決めるほうが差分の由来を追えます。

次にGitの基点と委任経路を確定します。クラウドチャットを直接開始すると、Codexはコンテナを作成し、選択されたブランチまたはコミットSHAのリポジトリをチェックアウトします。一方、IDEの既存スレッドからCloudへ委任する経路では、計画やローカルのソース変更を含む会話コンテキストが新しいクラウドチャットへ引き継がれます。直接開始なら未コミット変更を当然に知っていると考えず、IDEからの委任なら何が引き継がれたかを確認します。どちらでも、実行の基点と依存する変更を送信前に明示することが必要です。

環境設定には依存関係、リンターやフォーマッターなどのツール、環境変数、セットアップスクリプトを用意できます。公式資料では一般的なパッケージマネージャーの自動セットアップにも対応し、複雑な構成では独自のセットアップスクリプトを使えます。通常の環境変数はチャットの実行中に設定されますが、Secretsはセットアップスクリプトだけで利用され、エージェント実行前に取り除かれます。秘密情報を使う本番操作まで任せる前提ではなく、秘密情報なしで成立する検証境界を作るべきです。

環境の再現が難しいからと、検証コマンドを書かずに委任してよいわけではありません。クラウドで実行できる確認と、ローカルでしか実行できない確認を最初から分記します。この区別が、返却時の「確認済み」と「未確認」を読み違えない基準になります。

プロンプトには、目的、基点、変更範囲、禁止事項、検証方法、返却してほしい説明を含めます。とくに「最小限の変更にする」「公開APIを変えない」「指定外の依存関係を更新しない」など、採用時に守る境界を明示します。禁止事項は慎重さを演出する文ではなく、差分レビューで機械的に照合できる条件として書きます。

公式資料では、セットアップ後のエージェントはターミナルコマンドを繰り返し実行し、コードを編集し、チェックを走らせて作業を検証します。リポジトリに`AGENTS.md`があれば、プロジェクト固有のlintやテストコマンドを見つけるために利用します。完了時には回答と変更ファイルのdiffが表示され、追加質問やPR作成へ進めます。

ここで表示される成功報告は、クラウド環境内で得た証拠です。セットアップが手元と一致しない、ネットワークや外部サービスを使えない、端末固有の設定を再現していない場合には、成功の意味も限定されます。実行ログから、何を実行し、何が成功し、何が実行できなかったかを分けて読みます。未実行の確認を成功扱いしないだけで、返却後のレビューはかなり明確になります。

クラウドタスクの結果画面では、まず返された回答と変更差分の外形を見ます。選択した基点は正しいか、変更ファイルは指定範囲内か、生成物・ロックファイル・設定変更が意図せず混ざっていないかを確認します。範囲外の変更があれば、その場で部分採用を考える前に理由を特定します。依存関係の連鎖で必要だったのか、指示が広すぎたのかで、戻すべき場所が変わるためです。

次に、各変更を目的へ結び付けます。入力境界、失敗時の挙動、既存インターフェース、権限やデータの扱い、テストが実装と同じ思い込みを共有していないかを読みます。「テスト追加済み」は安全の代名詞ではありません。変更前なら失敗し、変更後なら通ること、重要な回帰条件を含むことまで確かめて初めて証拠になります。

ChatGPTデスクトップアプリのreview paneは、クラウドタスクの結果画面とは別の確認面です。ここにはCodexが編集した箇所だけでなく、ユーザー自身の変更やリポジトリ内のほかの未コミット変更も含むGitの状態が反映されます。公式資料では、Unstaged、Staged、Commit、Branch、Last turnなどの範囲を選べます。対象を選ばずに開くと、返却差分と手元の既存差分を混同するため、レビュー範囲を先に固定します。

`/review`は、review paneに表示する範囲そのものではなく、Codexへコードレビューを依頼する操作です。ベースブランチとの差分または未コミット変更を選ぶと、Codexは作業ツリーを変更せずに優先順位付きの指摘を返します。クラウド結果のdiff、Git状態を操作するreview pane、指摘を得る`/review`を分けて使い、指摘の根拠は該当行と仕様へ戻して確かめます。必要なら行単位のコメントで修正範囲を限定します。ツールの役割比較から整理したい場合は、CodexとGitHub Copilotの違いを比較も判断材料になります。

差分を説明できたら、そこで初めてローカルへ受け渡します。クラウドが実行したのと同じlint、型チェック、単体テストを手元で再実行し、その後にローカル固有の統合テストや実機確認を加えます。同じコマンドの再実行は重複ではありません。チェックアウトされた基点、依存バージョン、OS、環境変数などの差が結果へ影響しないかを確かめる工程です。

一括で取り込む前に、差分の状態を保ったまま確認します。予想外のファイルが増えていないか、設定値やマイグレーションが実行環境へ及ぼす影響はないか、既存の未コミット作業と衝突していないかを見ます。失敗した場合は、クラウドの変更が誤っていると即断せず、環境差、基点差、実装不備のどれかを切り分けます。原因を特定できない状態は採用条件を満たしていません。

検証コマンドがすべて通っても、レビューで見つけた仕様上の懸念は消えません。反対に、クラウドだけで失敗した確認がローカルで通っても、なぜ差が出たかを記録しなければ次の委任で再発します。実行場所ごとの結果と理由を残し、同じタスクを誰が見ても採用根拠をたどれる状態にします。

採用できるのは、変更範囲が合意内に収まり、各変更を目的で説明でき、必要なローカル検証が完了し、未確認事項が明示されている場合です。条件を満たした差分だけをstageし、コミットまたはPRへ進めます。説明できない変更を「動いているから」で混ぜず、必要部分だけを残すか、追加指示で差分を作り直します。

冒頭の問いへの答えは、クラウドの完了直後にローカルへ戻すのではなく、返却差分が説明可能だと確認した時点で戻す、です。早すぎれば範囲外変更を手元へ混ぜ、遅すぎればクラウドの検証結果を採用判断と取り違えます。タスク分離と環境準備で入口を狭め、差分確認で受け渡し可能性を判定し、ローカル検証で環境差を埋める。この順序なら、クラウド委任の利点を使いながら、最終判断を開発チームの管理下に保てます。

運用へ定着させる際は、最初から大きな機能を任せず、差分の小さい独立タスクで基点・プロンプト・レビュー・検証の型を合わせます。AI駆動開発の研修や導入支援が必要な場合は、組織のリポジトリ規約と承認手順に合わせて受け渡し条件を設計することが重要です。ツールの出力が生産性や品質を自動的に保証するわけではなく、採用基準を運用として持つことが継続利用の前提になります。