Codexファイル指定の使い方と読めないときの原因と確認手順

Codexのファイル指定で伝える三つの情報

ファイルを指定するときは、作業場所、参照対象、編集対象を一緒に考えます。作業場所は相対パスの起点です。参照対象は判断材料として読んでほしいファイルで、編集対象は変更してよいファイルを意味します。この三つが曖昧なままだと、同じ名前の別ファイルを調べたり、参考に渡した設定まで修正候補に含めたりする可能性があります。依頼を短くする場合も、この区別は省略しない方が確認しやすくなります。

たとえば、表示の不具合を調べるために画面のコードとテストを渡す場面を考えます。画面は修正対象でも、テストは現状を理解するための参照対象かもしれません。反対に、テストの修正だけを頼みたいこともあります。「この二つを見て直して」では、どちらも変更してよいと受け取られる余地があります。「両方を読み、変更は画面のファイルだけ」と書けば、作業結果と依頼を照合する基準ができます。

OpenAIのCodex CLI公式資料は、ローカルのコードを調べ、編集し、手元の開発用ツールを利用する機能を説明しています。一方、Codex IDE拡張の公式資料は、開いたファイルや選択したコードを依頼に含める使い方を紹介しています。以下の依頼文は、これらの機能を使う際に対象を明確にするための編集部による例です。

CLIでは作業フォルダと相対パスを揃える

CLIでの指定は、現在の作業フォルダを基準に考えると整理できます。プロジェクトのルートが起点なら、src/cart/total.tsのような相対パスで対象を示せます。別の場所が起点になっている場合、同じ記述でも見つからないことがあります。まずどのフォルダを開いているかを揃え、その後にファイルを指示します。パスの長さよりも、Codexと利用者が同じ起点を共有していることが大切です。

公式のCLIコマンドリファレンスでは、--cdまたは-Cは作業フォルダを指定する引数として説明されています。これはファイルを添付する機能ではありません。また、起点を指定しただけで、依頼中のすべてのファイルが必ず読まれるという意味でもありません。作業場所の指定と、実際に何を読むかという依頼を組み合わせて使います。

フォルダ名に空白がある場合は引用符で囲む

以下は利用者が新しい作業を始める際の記述例です。Windowsのフォルダ名に空白がある場合、パス全体を引用符で囲みます。依頼文も一まとまりとして囲むと、どの部分が作業場所で、どの部分が指示なのかを見分けやすくなります。例のパスとファイル名は説明用なので、実際のプロジェクトに置き換えてください。

codex --cd "C:\Projects\Sample App" "src/cart/total.tsを読み、合計の計算条件を説明してください。ファイルは変更しないでください。"

同名ファイルは親フォルダまで指定する

index.tsやREADME.mdは、複数の場所に存在しやすい名前です。ファイル名だけを渡すと、どれが対象かを判断するための追加調査が必要になります。packages/store/src/index.tsのように、起点からの位置が分かるパスで示しましょう。似た名前のファイルがある場合は、その違いも短く添えます。「管理画面側ではなく購入画面側」のような条件があると、候補の取り違えを確認できます。

IDEでは開いたファイルと選択範囲を確認する

IDE拡張では、エディタで開いたファイルや選択したコードを依頼の文脈として使えます。コードの一部について質問したいときは、該当部分を選んでから目的を伝えると、説明対象を共有しやすくなります。ファイル全体を調べてほしい場合は、部分的な選択だけで必要な情報が揃うとは限りません。関数の定義、呼び出し側、関連するテストなど、判断に必要な場所を依頼文に補います。

公式のIDE拡張資料は、開いたファイル、選択範囲、最近の会話を入力欄から参照する使い方を案内しています。画面の表示や操作項目は利用するエディタや版によって変わるため、特定の操作がすべての環境で同じだとは限りません。送信前に、入力欄へ対象が追加されたか、別のファイルを指していないかを目で確かめる習慣が役立ちます。

保存前のコードとディスク上のコードを区別する

エディタの表示内容と、保存されたファイルの内容が異なる場合があります。選択したコードを説明させたいのか、保存済みのファイルを読ませたいのかを決めましょう。どの画面でも未保存の編集が同じように扱われるとは断定できません。保存済みの状態を基準に調査したいなら、必要な編集を保存してから依頼し、読んだファイルと確認した内容を返答に含めてもらいます。

選択範囲の外にある条件も補足する

数行だけを選ぶと、処理の前提が抜けることがあります。たとえば数量の計算では、引数の型、丸め方、呼び出し側での変換が結果を左右します。選択範囲は問題の入口として使い、「呼び出し側も確認し、追加で読んだパスを報告してください」と補足すると、必要な調査を追いやすくなります。範囲を狭く指定する目的は、判断材料を欠かすことではなく、調査の出発点を明確にすることです。

読むファイルと変更するファイルを書き分ける

参照対象を示すことと、変更の許可を与えることは別の判断です。仕様書やテストを読ませても、それらを修正する必要があるとは限りません。依頼文には、参考に読む場所と変更してよい場所を明記しましょう。指定外のファイルが関係しそうなら、まず理由と候補を説明してもらう形にすると、対象が広がった理由を確認できます。依頼文による限定は意図を伝えるものであり、アクセス制限そのものとは区別します。

また、「このファイルだけ見て」と指示すると、問題の原因が別の場所にある場合に調査が止まることがあります。読み取りをどこまで広げてよいかと、編集をどこまで許すかを別々に決めると、この問題を避けやすくなります。たとえば関連する呼び出し元の読み取りは認めつつ、変更は一つのファイルに限る依頼ができます。追加調査で読んだ場所を報告してもらえば、対象を広げた経緯も残せます。

作業場所はsample-appのルートです。
src/cart/total.tsとtests/cart/total.test.tsを読んでください。
数量が0のときに合計がどう決まるかを説明してください。
まず調査だけ行い、読んだパスと根拠となる関数名を報告してください。
修正が必要なら案を示してください。今回はファイルを変更しないでください。

この例は読み取りの依頼です。調査結果が妥当なら、次の依頼で編集するファイルと期待結果を追加します。「合計を直す」よりも「数量が0なら合計を0とし、数量が正の場合の計算は維持する」のように書く方が、変更の成否を確かめやすくなります。対象を指定するだけでなく、何を満たせば完了なのかまで共有することが、結果の確認につながります。

ファイルを読めないときの確認手順

読めない原因は、存在しないパス、作業場所の違い、保存されていない内容、アクセス可能な範囲の違いなどに分かれます。エラーの文章だけで一つに決めつけず、同じ対象を小さな依頼で確かめましょう。プロジェクト全体の説明を求めるより、一つのファイルについて冒頭の見出しや関数名を確認する方が、読み取りに成功したかを判断しやすくなります。内容を見ずに推測した返答も区別できます。

次の手順は編集部による確認方法です。必要な情報が得られるまでは、編集の依頼を保留します。読み取りに失敗した状態で修正を頼むと、対象を推測したまま別のファイルへ変更が広がる可能性があるためです。特に作業場所の外にあるファイルは、名前を伝えることと実際にアクセスできることを分けて考え、現在の利用画面で扱える範囲を確認します。

1. 利用者が対象ファイルの存在と保存状態を確認します。綴り、大文字と小文字、拡張子、親フォルダが一致しているかを確かめます。
2. Codexに現在の作業場所を報告してもらいます。相対パスの起点が想定と違う場合は、正しい場所から依頼をやり直します。
3. 対象を一つに絞り、「変更せず、関数名と役割を説明してください」と依頼します。返答に実際に読んだパスを含めてもらいます。
4. 失敗した場合は、試したパスとエラーの要点を記録します。対象が作業場所の外にあるのか、別の場所や環境にあるのかを確認します。
5. 読み取りが確認できたら、参照対象、編集対象、期待結果を指定して次の作業へ進みます。調査中に増えた候補は、その理由を見て判断します。

追加の場所を許す前に用途を確かめる

CLIリファレンスにある--add-dirは、主な作業場所に加えて別のフォルダへの書き込みを許すための引数です。ファイルの場所を教えるだけの機能ではありません。読めないという理由だけで追加する前に、何をする必要があるのかを確認しましょう。単に資料の内容を参照したい場合と、別のフォルダへ編集結果を保存したい場合では必要な範囲が異なります。

画像の添付とテキストの参照を混同しない

公式リファレンスの--imageまたは-iは、最初の依頼に画像ファイルを添付するための引数です。コードや仕様書を何でも渡す汎用の添付指定としては説明されていません。テキストのコードを調べたいならパスと読み取り依頼を使い、画面の見た目を伝えたいなら画像の添付を検討します。何を伝えるためのファイルなのかに合わせて、指定方法を選びます。

指定したファイルが判断に使われたかを確かめる

対象を送信しただけで確認を終えず、返答がそのファイルに基づいているかを見ます。読んだパス、関連する関数名、判断の根拠となった条件があれば、手元のコードと比べられます。「確認しました」という返答だけでは、同名の別ファイルを読んだのか、内容を見ずに一般論を述べたのかが分かりません。短い報告でも、根拠を含めてもらうことで誤解を見つけやすくなります。

編集を依頼した場合は、指定したファイルの変更だけで目的が満たされたかを確認します。差分の要約と実際の変更箇所を比べ、対象外の編集があるならその理由を確かめます。テストを行ったという報告では、対象のテスト名、結果、確認できなかった点を見ます。依頼時の指定と作業後の根拠を対にして残すと、追加修正や担当者への引き継ぎにも利用できます。

Codexのファイル指定を安定させるには、起点となる作業場所を揃え、参照と編集の範囲を文章で分け、実際に読んだ場所を返答で確認します。CLIとIDEでは文脈を渡す方法が異なるため、同じ依頼を別の画面で使う際にも対象を見直しましょう。一つのファイルの読み取りから始め、必要な関係だけを広げると、具体的な根拠を持って次の編集へ進めます。