リポジトリCodexの開き方・安全確認手順Windows対応入門

リポジトリとCodexの関係を先に押さえる

Codexは、ファイル単体に返答するだけの補完機能ではなく、作業場所にある複数のファイルを読み、依頼に必要な範囲を調べ、変更や確認の結果を返すAIコーディングエージェントだ。公式リポジトリもCodex CLIを「ローカルのコンピューター上で動くコーディングエージェント」と説明している（出典: https://github.com/openai/codex ）。そのため、最初に指定する場所が一つのファイルなのか、アプリケーション全体のリポジトリなのかで、読み取る前提も結果の影響も変わる。

リポジトリとは、ソースコードだけを置く箱ではない。Gitの履歴、ブランチ、設定ファイル、テスト、ドキュメント、無視対象の定義が一つの作業単位を形づくっている。Codexに「このアプリを直して」と頼む前に、どのルートで、どのブランチを基準にし、どの範囲を変更してよいかを示すことが、依頼の精度を上げる。対象を狭く言い過ぎると必要な参照を読み落とし、広く言い過ぎると関係のない場所まで調べ始めるため、境界を言葉にすることが大切だ。

リポジトリのルートを見誤ると何が起きるか

モノレポの下位フォルダー、フロントエンドとサーバーを分けた構成、サブモジュールを含む構成では、画面上のフォルダー名だけでルートを判断しにくい。上位ディレクトリからCodexを起動すると、想定していない設定や別のテストを参照することがある。反対に下位ディレクトリだけを開くと、共有ライブラリやルートの説明書が見えず、原因を一部だけで判断する可能性がある。

そこで、見た目のパスではなくGitにルートを返させる。次の結果が、これから扱うリポジトリの基準になる。

git rev-parse --show-toplevel
git status --short --branch

返ってきたパスが依頼した場所と一致しないなら、その場でCodexへ作業を依頼しない。まず端末を目的のルートへ移し、もう一度同じ確認を行う。ルートが確定して初めて、ファイルの読み取り範囲と変更範囲を正しく指定できる。

フォルダーを開くことと信頼して編集を許すことは別

Codexでリポジトリを開けても、編集や端末操作をどこまで認めるかは別の判断になる。初めて扱う場所では、表示されたパス、リポジトリの出所、現在の差分を確認してから、必要な範囲だけを許可する。見慣れた名前のフォルダーでも、同名の別プロジェクトや一時コピーである可能性があるため、場所の確認を省かない。

2026年8月7日公開の0.147.0リリースノートでも、見慣れないローカルプロジェクトについて明示的な信頼確認を求める方向が示されている。これは操作を遅くするためだけの表示ではなく、リポジトリの中身を読ませる前に「この場所でよいか」を確認する境界だ（出典: https://github.com/openai/codex/releases/tag/rust-v0.147.0 ）。

0.147.0公開後に確認したい変更点

Codex CLI 0.147.0は2026年8月7日に公開された安定版として、公式リリース一覧の先頭に掲載されている。リリースノートには、ローカルやワークスペースなど複数のカタログからエージェント向け拡張を探す機能、会話を区切って整理する機能、Cursorで管理していたスキルや会話を取り込む機能、MCPの新しい仕様への対応などが並ぶ。リポジトリを開く記事で重要なのは機能を全部試すことではなく、作業場所の認識と確認が更新されたタイミングを押さえることだ（出典: https://github.com/openai/codex/releases/tag/rust-v0.147.0 ）。

同じリリースには、日本語文字や絵文字の表示、Windowsのバックグラウンド処理、Windowsのファイルパスの扱いを整える修正も記載されている。Windowsでは大文字と小文字、ドライブ文字、WSL側のLinuxパス、ネットワーク経由のパスが見た目の似た別表記になりやすい。更新後に表示や移動が安定したとしても、作業対象の確認を省略してよいという意味ではない。むしろ、版を更新した日は同じ確認コマンドをもう一度実行し、以前の状態と比べるよい機会になる。

リリースノートを作業手順へ置き換える

リリースノートの「Windowsのパスを扱う修正」は、利用者にとっては「Codexが現在のリポジトリをどの表記で認識しているかを見る」という行動に置き換えられる。「日本語表示の修正」は、ファイル名や差分の表示が欠けていないかを確認する行動になる。「見慣れないローカルプロジェクトへの信頼確認」は、表示された場所と編集範囲を承認前に読む行動になる。

このように、機能名だけを覚えるのではなく、変更が自分の確認項目にどう影響するかを決めておく。更新のたびに全機能を試す必要はない。自分のリポジトリで起き得る問題に関係する項目だけを、短い検証で確かめればよい。

版番号とモデル名を混同しない

codex --version が返すのはCodex CLIという利用環境の版番号であり、画面で選ぶモデルの名前とは別だ。0.147.0へ更新したからといって、モデルの名称や応答の性質が同じ比率で変わるとは限らない。リポジトリの扱いを確認するときは、CLIの版、モデル、OS、端末の種類を分けて記録する。

たとえば「Codex CLI 0.147.0、Windows 11のPowerShell、リポジトリのルートはDドライブ」のように残すと、後で同じ問題を再現しやすい。モデルの変更を調べる場合はモデルの公式情報を、CLIの挙動を調べる場合はCLIのリリースページを参照する。入口を取り違えないことが、更新の効果を正しく判断する近道だ。

開く前にリポジトリの状態を整える

Codexを起動する前に、作業場所の状態を人が把握しておく。これはCodexに任せる作業を制限するためだけではない。開始時点の状態が分かっていれば、Codexが加えた変更と、もともと存在した変更を分けて読めるからだ。特に複数人で触る共有リポジトリや、前回の作業を残したまま再開するリポジトリでは、開始時点の確認が結果の信頼性を左右する。

Step 1: ルートと現在地を確認する

まず、端末がどこにいるかと、Gitがどこをルートと認識しているかを確認する。macOSやLinux、WSLでは次のコマンドを使える。WindowsのPowerShellでもGitが利用できれば同じGitコマンドを実行できる。

pwd
git rev-parse --show-toplevel
git status --short --branch

PowerShellでは現在地を目で確認するために、先に次を実行してもよい。

Get-Location
git rev-parse --show-toplevel
git status --short --branch

git status --short --branch の先頭行に表示されるブランチ名と、変更を示す行数を控える。ルートの出力が空になる、Gitリポジトリではないと表示される、想定外のドライブが出る場合は、Codexの起動を止めてパスを直す。Codexへ「現在地を確認して」と頼むこともできるが、初期状態の確認は自分の端末でも行ったほうが比較しやすい。

Step 2: ブランチと既存の差分を記録する

ルートが合っていたら、現在のブランチと変更の一覧をもう少し詳しく見る。未追跡ファイル、編集済みファイル、ステージ済みの差分が混ざっていると、Codexの変更を後から見分けにくくなる。作業開始前に全部を消したり、勝手に保存したりするのではなく、残すべき状態を確認してから次へ進む。

git branch --show-current
git status --short
git diff --stat
git diff --cached --stat

ブランチ名が空なら、デタッチ状態や特殊な確認用の状態かもしれない。通常の修正を始める前に、どの履歴を基準にするかを決める。既存の差分がある場合は、依頼文に「既存の変更を保持し、今回の対象ファイルだけを触る」と書き、Codexの返答後に同じコマンドを実行して比較する。既存の編集を「不要なもの」と決めつけて戻す依頼は、明示的な判断なしに行わない。

Step 3: 参照先と作業範囲を言葉にする

リモートのURLや現在のブランチが正しいか、必要なときだけ確認する。公開リポジトリを扱う場合でも、似た名前の別プロジェクトを開いていないかを見ておく。プライベートなリポジトリや社内リポジトリでは、表示されたURLや接続先の扱いを組織のルールに合わせ、不要な情報を依頼文へ貼り付けない。

依頼文には、対象、目的、変更してよい範囲、触れてはいけない範囲、確認してほしいテストを含める。「このリポジトリを直して」だけでは、Codexが問題の原因を広く探すため、意図しないファイルまで候補になる。対象を src/ と tests/ に限定し、設定や依存関係は変更しない、といった境界を先に置くと結果を確認しやすい。

Codexをリポジトリのルートから開く

ルートの確認が終わったら、同じ端末でCodexを起動する。Codex CLIの公式リポジトリは、インストール後に codex を起動する流れと、WindowsではWSL2を利用する構成を案内している（出典: https://github.com/openai/codex/blob/main/docs/install.md ）。大切なのはコマンドそのものより、確認したルートと、Codexが最初に開く場所を一致させることだ。

Step 4: CLIの起動場所を固定する

端末でGitのルートへ移動してからCodexを起動する。次の例では、/path/to/repository を自分のリポジトリの実際のパスへ置き換える。

cd /path/to/repository
git rev-parse --show-toplevel
codex

起動直後の依頼は、変更を求めない確認にする。「現在の作業ディレクトリ、Gitのルート、ブランチ、変更ファイル、使用できるテストコマンドを読み取り専用で報告し、ファイルは変更しない」と伝えると、Codexの認識を人が確認できる。返答のパスが端末で確認したルートと違うなら、続けて編集を依頼せず、端末環境や起動場所を見直す。

Codexがリポジトリ内の説明書を見つけても、その内容を無条件に正しいとみなさない。更新されたばかりのブランチ、途中の移行、古いドキュメントが混在している可能性があるため、現在の設定やテストの実態と照合する。リポジトリの説明は手がかりとして使い、Gitの状態と実際のファイルを基準に判断する。

デスクトップアプリやエディタから開く場合

デスクトップアプリやエディタの入口を使う場合も、プロジェクト選択画面で表示されたパスを確認する。Windowsでは同じ場所が C:\work\app、D:\work\app、WSLの /mnt/c/work/app、Linux側の /home/user/app など別の表記になることがある。見た目が似ていても同じファイルシステムとは限らないため、開いた後にCodexへ現在地を報告させ、端末の git rev-parse --show-toplevel と比べる。

エディタ内蔵のターミナルから起動したCodexと、別のPowerShellから起動したCodexでは、環境変数、Gitの設定、Node.jsなどの版が異なる場合がある。同じリポジトリでも再現結果が違うときは、モデルを疑う前に起動元の端末、現在地、git --version、codex --version をそろえる。環境をそろえてから比較すれば、リポジトリの問題と起動経路の問題を分けられる。

最初の依頼は読み取り中心にする

リポジトリを開いた直後に大きな変更を頼むと、Codexが前提を取り違えたままファイルを書き換える可能性がある。最初の一往復は、作業場所を理解しているかを見るための棚卸しにする。公式ドキュメントやリポジトリの説明に沿って、構成、テスト、実行方法、注意点を整理させると、次の依頼に必要な情報がそろう（出典: https://developers.openai.com/codex/cli/ ）。

Step 5: 最初の確認文を具体化する

最初の依頼には、変更しない条件を明示する。たとえば次のように書く。

このリポジトリを読み取り専用で確認してください。
1. 現在の作業ディレクトリとGitのルートを示す
2. ブランチ名と未コミットの変更を示す
3. アプリの主要な入口と、関連するテストを示す
4. 実行してよい確認コマンドと、まだ実行しない操作を分ける
ファイルの作成・編集・削除は行わないでください。

この文では、必要な情報を順序付きで求めながら、変更を禁止している。返答にルート、ブランチ、既存差分が含まれているかを確認し、端末の結果と一致するか比べる。テストコマンドの候補が書かれていても、すぐに全部を走らせず、時間や外部接続への影響を考えて一つずつ選ぶ。

確認結果を人が読み直す

Codexが「問題ありません」と返しても、リポジトリが正常だと確定したわけではない。確認したファイル、実行したコマンド、観察した差分を分けて読む。ルートの勘違い、古いブランチ、未追跡の設定、テストの不足が残っていないかを見て、必要なら依頼文を狭くして再確認する。

読み取りの段階で、Codexが編集や削除を提案した場合は、目的と対象ファイルを先に確認する。調査のために変更が必要だと説明されても、別ブランチやコピーで試せるか、元の状態を保存できるかを考える。小さな確認で前提を固めるほど、後の差分を短く保ちやすい。

編集を頼むときの範囲を決める

読み取りでルートと状態が合っていると確認できたら、初めて変更を依頼する。依頼には「何を変えるか」だけでなく、「何を変えないか」と「完了をどう判定するか」を入れる。リポジトリでの作業は複数ファイルに影響するため、ファイル名、関数、画面、APIの入口、テストなど、確認できる単位まで落とし込むのがよい。

変更対象と対象外を分ける

たとえば「ログイン画面のエラーメッセージを修正し、対応するテストを更新する。依存関係、データベース定義、ビルド設定には触れない」と指定する。このように対象外まで明示すれば、Codexが便利そうだからという理由で設定全体を変更する余地を減らせる。対象外のファイルに変更が必要なら、理由と影響を説明させ、了承してから依頼を広げる。

既存の未コミット差分がある場合は、「開始時点の変更を保持し、今回の差分と混ぜない」と書く。Codexが既存差分に起因するエラーを見つけても、勝手に整理せず、どの差分が関係するかを示させる。作業を一度止めて人が判断する境界を用意しておくと、別の問題まで同時に直してしまう状況を避けられる。

完了条件をテストと差分で表す

完了条件は「直ったこと」ではなく、観察できる結果で書く。たとえば「空の入力ではエラーが表示される」「既存の正常系テストが通る」「変更は指定した二つのファイルだけ」「差分に認証情報や一時ファイルが含まれない」といった形だ。最後の確認項目は、環境やチームのルールに合わせて設定する。

Codexがテストを通したと報告しても、実行したコマンドと対象を確認する。テストが一部だけだったのか、失敗を無視して進んだのか、実行環境が端末と違うのかで、意味が変わる。テスト結果、差分、画面やコマンドの確認を三つに分けて読み、どれか一つだけを根拠に完了としない。

WindowsとWSLでパスをそろえる

Windows 11でCodexを使う場合、公式のインストール文書はWSL2を対応環境として案内している（出典: https://github.com/openai/codex/blob/main/docs/install.md ）。Windows側のCodexとWSL側のCodexは、同じ名前で起動しても別の実行ファイルや別の設定を参照することがある。リポジトリを開くときは、どちらの環境を使うかを先に決め、最初から最後まで同じ環境で確認する。

0.147.0のリリースノートにはWindowsのファイルシステムパスを一貫して扱う修正が含まれるが、パスの表記差がすべて消えるとは限らない。C:</code> と /mnt/c/、WSL内の /home/、ネットワーク経由のUNCパスを混ぜると、Codexが見ているルートとGitが返すルートの比較が難しくなる。表示されたパスをそのまま信用せず、同じ端末でGitのルートを確認することが重要だ（出典: https://github.com/openai/codex/releases/tag/rust-v0.147.0 ）。

git rev-parse --show-toplevel
git status --short --branch
git --version
codex --version

git status --short --branch
git diff --stat
git diff --name-only
git diff --check