Codex ファイル操作で壊さず進める確認手順と実践ガイド

Codex ファイル操作とは何を任せることか

Codex ファイル操作とは、Codexにコードの断片を書かせるだけでなく、プロジェクト内のファイルを読み、関係を把握し、目的に沿って追加・修正・移動などを行わせる使い方です。OpenAIの公式ドキュメントでは、Codex CLIについてローカルのリポジトリを調べ、編集し、利用中の開発用ツールを動かす使い方が案内されています。詳しい位置付けはOpenAIのCodex CLI公式ドキュメントで確認できます。便利な一方で、ファイルの変更は会話の返答より影響範囲が広いため、依頼文に境界を含める必要があります。

任せる範囲は、読み取り、作成、既存内容の修正、名前の変更、削除に分けて考えると整理しやすくなります。読み取りは比較的安全ですが、編集では差分の確認が必要です。名前の変更や削除は参照先を壊す可能性があるため、対象を明記し、実行前に確認を求めるのが基本です。「不要なファイルを整理して」のような曖昧な依頼は避け、ファイル名、目的、変更しない場所、確認方法を一緒に指定します。

読む・変える・確かめるを分ける

最初から編集を頼むのではなく、まず「関係するファイルを調べ、現状と変更候補を説明してください」と依頼します。Codexがどのファイルを根拠に判断したかを見れば、対象の取り違えや古い実装の見落としに気付きやすくなります。その後に変更を頼み、最後に差分、テスト結果、未解決の点を別々に報告させます。三つの段階を分けると、途中で方針を直しても変更が広がりにくくなります。

対象ファイルを言葉で限定する

対象は「プロジェクト全体」ではなく、相対パスやディレクトリ名で指定します。たとえば画面の表示を直すなら、関連するコンポーネントとテストファイルを列挙し、設定ファイルや生成物は触らないと書きます。除外条件も重要で、「依存関係の更新はしない」「公開関数の名前は変えない」「新しいライブラリは追加しない」と明示すると、目的外の変更を減らせます。

なぜ今、ファイル操作を整理するのか

2026年8月25日、OpenAIの公式ブログでは、Codexに作業の目的を渡し、計画と実行内容、結果をノートに記録する活用例が紹介されました。ポイントは、作業を一度きりの会話に閉じ込めず、後から読める記録として残すことです。Codexがファイルを変更する場面でも、対象、理由、変更点、確認結果を同じ場所に置けば、修正の妥当性を人が追いやすくなります。事例の詳細はOpenAI公式ブログのCodex活用例に掲載されています。

また、公式ドキュメントのCodexの概要には、ローカルのリポジトリでファイルを調べて編集する使い方と、変更の前後にチェックポイントを作る考え方が示されています。現在のCodexは、単に一行のコードを提案する道具としてだけでなく、複数のファイルをまたぐ調査と修正を進める道具として説明されています。だからこそ、能力の大きさに合わせて依頼を細かくし、どこまで進めたかを記録することが実用上の差になります。

8月の公式事例から学べること

公式事例では、過去の作業記録を読み、今回の目的と計画を書き、途中の判断と結果を同じノートに追加する流れが紹介されています。ここから学べるのは、Codexに長い説明を一度だけ渡すことではありません。前回の結果、今回の変更理由、確認できなかった点を次の依頼に使える形で残すことです。担当者が変わっても、ファイルの状態と判断の根拠を追える記録があれば、同じ調査を最初からやり直さずに済みます。

結果を同じ場所に残す

ファイル操作では、変更そのものよりも変更後に何が起きたかが重要です。たとえば、変更したファイル名、実行した確認、成功したテスト、残った注意点をMarkdownの記録にまとめます。画面上の会話だけに頼ると、後日になって「なぜこの行を変えたのか」が分からなくなります。作業記録を対象プロジェクトの近くに置き、次の担当者が読める短い文章にしておくと、Codexへの追加依頼も具体的になります。

実践前の安全な準備

Codexにファイルを変更させる前に、作業場所の確認と現在の差分の確認を行います。プロジェクトのルートで作業しているか、別の変更が残っていないかを見ておくと、Codexが作った差分と自分の差分を区別できます。確認には、利用しているバージョン管理ツールの状態表示や差分表示を使います。変更前の状態を保存したコピーやチェックポイントを用意しておけば、期待と違う結果になったときにも落ち着いて戻せます。

次に、完了条件を先に決めます。「表示が変わる」だけでなく、対象の画面、入力例、期待する出力、通すべきテスト、触れてはいけない範囲を文章にします。完了条件がないまま依頼すると、Codexは見た目が整った時点で終了したと判断するかもしれません。人が確認する箇所を残し、外部サービスへの送信や公開操作など、影響の大きい行為は別の確認に分けておくことも大切です。

Step 1: 作業場所と対象範囲を決める

まずプロジェクトのルートを開き、現在の状態を自分で確認します。次のような情報を手元にそろえると、依頼文を短くても具体的にできます。

作業場所: プロジェクトのルート
対象: src/cart/ と tests/cart/
対象外: 設定ファイル、生成物、依存関係
目的: カート内の数量表示を修正する
完了条件: 既存テストが通り、数量が画面と明細で一致する

この時点では、まだ編集を頼みません。対象を決める前にCodexへ「いい感じに直して」と渡すと、関連しそうなファイルを広く変更する余地が生まれます。対象の根拠が分からない場合は、先に構成を説明させ、候補を自分が選んでから次へ進みます。

Step 2: 読み取り専用の依頼から始める

最初の依頼は、変更を禁止した調査にします。たとえば「src/cart/ と tests/cart/ を読み、数量が計算されて表示されるまでの流れを説明してください。ファイルは変更しないでください」と伝えます。返答には、入口となるファイル、値の変換箇所、表示箇所、既存テストの不足を含めてもらいます。説明が自分の理解と違うときは、その場で訂正し、正しい前提がそろってから編集へ進めます。

Step 3: 変更条件を一文にする

変更依頼は、目的と制約が一つの文章で読める形にします。「数量が0のときは空欄にする」のように期待結果を明確にし、「価格計算は変えない」「対象ファイル以外は変更しない」と境界を加えます。さらに、テストを追加するのか、既存テストだけで確認するのかを書きます。条件が複数あり互いに関係しないなら、依頼を分けた方が差分の原因を追いやすくなります。

Codexにファイル操作を依頼する書き方

良い依頼文は、長い説明文ではなく、Codexが判断に必要とする情報がそろった文章です。対象、目的、制約、確認方法の四つを最低限含めます。ファイルの内容をすべて貼り付ける必要はありません。どこを調べればよいかを示し、現状の理解が必要な部分はCodexに読み取らせます。依頼の冒頭で「まず変更案を説明し、確認を受けてから編集してください」と伝える方法も、変更範囲を管理するうえで有効です。

実際の依頼は、次のような形にできます。

src/price.ts の表示丸め処理だけを修正してください。
対象は src/price.ts と tests/price.test.ts です。
既存の公開関数名と価格計算の規則は変えないでください。
0.1 のような小数を含むケースのテストを追加し、テストを実行してください。
変更したファイル名、変更理由、確認結果、未確認の点を最後に示してください。

この形なら、Codexが何を読み、何を変え、何を確認するかを一つずつ照合できます。返答の中に対象外のファイルが出てきたら、変更前に理由を尋ねます。理由が妥当でも、対象を広げる判断は別の依頼として行うと、あとで差分を分けやすくなります。

対象・目的・制約・確認方法を入れる

対象はパスで示し、目的はユーザーから見える結果かテスト可能な条件で示します。制約には、変更しないAPI、増やしてよい依存関係、保ちたい書式、対象外のディレクトリなどを含めます。確認方法は、実行するテスト、確認する画面、見るべきログのどれかを指定します。最後に変更ファイルの一覧と未確認項目を報告させれば、成功したという短い返答だけで判断せずに済みます。

一度に触る範囲を小さくする

「バグを直して、画面を整えて、説明文も更新する」という依頼は、成功条件が三つあります。まず計算の不具合、次に表示、最後に文書というように分ければ、各段階の差分と確認結果を対応付けられます。複数の目的を同時に頼む必要があるときも、変更してよいファイルを目的ごとに区切り、完了した段階で一度止める指定を加えると安全です。

先に不明点を返してもらう

仕様に空白がある場合、Codexに推測で埋めさせないことが重要です。「不明な条件があれば編集前に質問してください」と明示し、質問への回答を待ちます。たとえば日付の扱い、空の値、既存データとの互換性は、見た目だけでは決められません。人が選択すべき点を質問として表に出させると、後から大きな修正をやり直す可能性を下げられます。

変更後の確認手順

ファイルが書き換わったら、まず何が変わったかを差分で確認し、次にテストや画面で結果を確かめます。順序を逆にすると、テストが通ったことだけを理由に不要な変更を見逃すことがあります。変更ファイルの一覧、追加・削除された行、想定外の書式変更、テスト結果を分けて見てください。Codexの説明も参考になりますが、実際のファイルと実行結果を基準に判断します。

確認が終わったら、変更理由と結果を作業記録へ追記します。うまくいかなかった場合も、試した方法と失敗した条件を残します。失敗の記録は次の調査で同じ道をたどらないための情報になります。変更が大きくなった場合は、いったん戻して依頼を小さくし直す方が、修正を重ねて原因が分からなくなるより早く解決できます。

Step 4: 差分を確認する

変更後は、ファイル名だけでなく内容を読みます。差分表示では、目的の行の前後、関数の引数、条件分岐、インポート、コメントを確認します。対象外のファイルが増えていないか、改行やインデントだけの変更が混ざっていないかも見ます。たとえば次のような確認を自分の環境で行い、Codexの報告と照合します。

git status --short
git diff --stat
git diff -- src/price.ts tests/price.test.ts

Step 5: テストと表示を確かめる

テストが通っても、依頼した条件をすべて検証できたとは限りません。正常値、境界値、空の値、既存データの四つの観点を使い、必要なケースを選びます。画面の変更なら、対象の画面を実際に開き、入力から表示までを確認します。Codexには実行したコマンドと結果を報告させ、失敗したテストを成功扱いにしないようにします。

Step 6: 不要な変更を戻す

目的外の差分があるときは、全体を残したまま次の依頼へ進みません。対象外のファイルを一つずつ確認し、必要がなければ作業前の状態へ戻します。戻す前に自分の変更が混ざっていないかを見て、保存したい差分だけを分けます。Codexに「全部元に戻して」と頼むより、パスと戻してよい範囲を明示する方が、必要な修正まで失う危険を減らせます。

ファイル操作で起こりやすい失敗

Codexのファイル操作で問題になるのは、コードが書けないことよりも、依頼の境界が曖昧なことです。プロジェクト全体を読ませてから目的を説明すると、関連の薄い設定や文書まで変更候補に入ることがあります。また、見た目の整形とロジック変更を同時に頼むと、差分が大きくなり、どの変更が不具合の原因か分からなくなります。

失敗したときは、Codexを責めるのではなく、対象、目的、制約、確認方法のどこが足りなかったかを記録します。次の依頼では対象をさらに狭め、変更案を先に説明させ、差分を確認してから次のファイルへ進みます。ファイル操作は、一回の依頼で完璧な結果を得るより、観測と修正を短く繰り返す方が安定します。

対象を広く指定しすぎる

「アプリ全体を最新の書き方に直す」のような依頼は、対象も完了条件も広すぎます。まず一つの画面、一つの処理、一つのテストに絞り、変更前後の動作を確認します。複数のディレクトリが必要なら、なぜ必要なのかを説明させ、関係するパスを依頼文に追加します。広い範囲を一度に変更するのは、各部分の境界が分かってからにします。

書式だけの変更が混ざる

インデント、改行、並び順の変更は、ロジックを直した差分を見えにくくします。「書式変更は行わない」「必要な整形は別の作業にする」と指定し、差分のノイズを減らします。もし書式変更が必要なら、ロジックの修正と分けて実施し、どちらの差分かを記録します。読みやすさの改善であっても、レビューする側の負担が増える点を考慮します。

削除・移動を曖昧に頼む

削除や移動は、ファイルの参照、読み込み設定、文書リンクに影響します。「使われていないものを削除」ではなく、対象のパス、根拠、代替先、確認方法を指定します。削除前に参照箇所を調べ、影響がないという説明を受けても、自分で差分とテストを確認します。迷う場合は削除せず、候補を一覧にして人が決める段階を置きます。

ローカル・クラウド・IDEでの使い分け

Codexは同じ名前でも、どこで動かすかによって確認しやすい範囲が変わります。ローカルのプロジェクトでは、現在のファイルとテストを見ながら小さな差分を作りやすい一方、作業者の環境に依存します。クラウド側で扱う場合は、対象のリポジトリ、参照できるデータ、結果を戻す場所を先に確認します。IDEの拡張機能では編集中のファイルをすぐ参照できますが、開いているファイルだけが全体の前提とは限りません。

どの環境でも、ファイルを読めることと、変更を確定してよいことは別に扱います。ローカルだから無条件に広く編集してよいわけではなく、クラウドだから人が確認できないわけでもありません。作業場所、権限、利用できるツール、変更結果の受け取り方を最初に言葉にすれば、環境が変わっても同じ確認手順を使えます。

ローカル作業に向く場面

ローカルは、手元のテスト、画面、ログ、未コミットの差分を一緒に確認したい場面に向いています。特に、既存の開発環境でしか再現しない不具合や、複数のファイルを読みながら小さく直す作業では、現在の状態を見ながら依頼を調整できます。開始前にルートと差分を確認し、終了後に同じ確認をもう一度行うことが大切です。

クラウドで確認を受ける場面

クラウド側で作業を進める場合は、どのリポジトリのどの時点を対象にしたか、結果をどこで確認するかを明記します。手元のファイルと離れた場所で変更が進むほど、開始時点と終了時点の差を記録する価値が高まります。結果を取り込む前に、変更ファイル、テスト結果、残った注意点を確認し、必要な部分だけを自分の環境へ反映します。

チームで再現できる形に整える

個人の使い方として便利でも、チームで共有するときは、依頼文と結果の形式をそろえると品質が安定します。レビュー担当が見るべき情報を毎回同じ順序で出させ、対象外の変更や未確認の項目を隠さないようにします。担当者の経験や記憶に頼るのではなく、ファイル名、目的、確認方法、結果を文章で残すことが重要です。

OpenAIの公式リポジトリであるopenai/codexは、Codexがターミナルで動く軽量なコーディングエージェントであることと、公式ドキュメントへの入口を示しています。製品の更新で表示や利用できる機能が変わることはあるため、細かな操作を固定するよりも、対象範囲と確認の考え方を共有する方が長く使えます。

誰が見ても分かる依頼文にする

依頼文には、作業者しか知らない略称を使わず、パス、目的、期待する結果、変更しない条件を書きます。レビュー担当が文章だけを読んでも、変更の妥当性を判断できることが目標です。結果の報告では、成功した点だけでなく、試せなかった環境や残った疑問も示します。これにより、次の担当者が同じ前提を確認し直す時間を減らせます。

作業記録に残す項目

最低限、開始時点、対象ファイル、依頼の目的、変更したファイル、実行した確認、結果、未解決の点を記録します。判断が分かれた場合は、採用した案と見送った案、その理由も短く残します。記録は長文の議事録にする必要はなく、次に同じファイルを触る人が状況を再現できる粒度にします。公式事例のように、実行内容と結果を同じ記録へ追加すると、会話を探し直さずに済みます。

Codex ファイル操作の確認チェック

作業を始める前と終えた後に、次の項目を確認します。すべてを機械的に埋めるのではなく、今回の変更に関係する項目を選び、確認できないものは未確認として残してください。チェック項目があると、変更そのものに目を奪われて、対象外の差分や境界値の見落としを防ぎやすくなります。

1. 作業場所は意図したプロジェクトのルートになっているか。
2. 開始前の差分と、自分が持っている未保存の変更を把握しているか。
3. Codexに読むファイル、変えてよいファイル、変えないファイルを伝えたか。
4. 目的と完了条件を、画面やテストで確認できる言葉にしたか。
5. 削除、移動、依存関係の変更など影響が大きい操作を明記したか。
6. 変更後の差分に、目的外のファイルや書式変更が混ざっていないか。
7. 正常値、境界値、空の値、既存データを必要に応じて確認したか。
8. 実行した確認、結果、未確認の点を作業記録に残したか。

まとめ

Codex ファイル操作を安全に使う要点は、Codexの能力を小さく見積もることではなく、変更の境界を先に決めることです。読み取りで現状を把握し、対象と目的を狭く指定し、変更案と差分を確認してからテストへ進みます。削除や移動のような影響の大きい操作は、通常の編集と分けて人の判断を入れます。

2026年8月のOpenAI公式情報が示すように、Codexを長く役立てるには、目的、判断、実行内容、結果をファイルやノートに残すことが大切です。最初は一つのファイルと一つの確認から始め、変更前後を比べる習慣を作ってください。そうすれば、Codexはコードを生成するだけでなく、プロジェクトの状態を確かめながら修正を進める相棒として使いやすくなります。