Codex フォルダ構成の決め方と指示・資料・テストの配置

Codexのフォルダ構成は作業の起点から決める

Codexのために特別なフォルダ名へ揃える必要はありません。最初に決めたいのは、今回の作業でどのプロジェクトを開き、どの場所を基準にファイルを指定するかです。画面とサーバー側が同じプロジェクトにある場合も、別々に分かれている場合も、依頼文で示すパスの基準が曖昧だと、同名のファイルを取り違えやすくなります。

OpenAIのCodex CLI公式案内では、ローカルのプロジェクト内でファイルを調べ、編集し、手元の開発用ツールを使う形が紹介されています。フォルダ構成を考える際は、この「手元で開いている場所」を入口として扱います。作業したいアプリが下の階層にあるなら、上位に何があるかだけでなく、実装の入口がどこかも伝えます。

例えば、product/の中にweb/とapi/があり、問い合わせ画面を直すなら、「基準はproduct、画面はweb、送信先の仕様はapi/docs」という説明が役立ちます。一方、web/を開いて作業しているなら、同じパス表記をそのまま使うと意味が変わります。依頼文には基準の場所と対象の場所をセットで書き、実際に認識された場所を編集前に確かめてください。

指示・仕様・実装・テストを役割で分ける

構成を整理するときは、最初にファイルを四つの役割で見ます。継続的な指示、製品の仕様、動作するコード、動作を確認するテストです。役割が分かれば、どの変更にどの資料が必要かを説明できます。以下は小さなWebアプリを想定した編集部の配置例であり、OpenAIが定める標準構成ではありません。

project/
  README.md
  AGENTS.md
  docs/
    requirements.md
    screen-spec.md
    decisions.md
  src/
    screens/
    services/
  tests/
    screens/
    services/

README.mdは人もCodexも入口として使える案内にし、アプリの目的、主要な場所、動作確認の方法を記載します。AGENTS.mdには日々の作業で守る判断基準を書き、長い仕様本文はdocs/など既存の資料置き場へ置きます。src/とtests/は例の名前です。Laravelのapp/やresources/、別の構成にあるpackages/などを、図に合わせるためだけに改名する必要はありません。

この分け方なら、「ボタンの文言を直す依頼では画面仕様を見る」「送信項目を変える依頼では要件と通信部分のテストを見る」と説明できます。毎回すべてを読む指定にするより、変更と根拠を結び付けやすくなります。既存の開発者が使っている置き場を尊重し、案内を足すだけで解決できるなら、ファイルの移動を増やさない方が確認も簡単です。

AGENTS.mdの配置は読まれる範囲と一緒に考える

継続的な指示を配置するときは、ファイル名だけでなく、どの範囲で読まれるかを確認します。公式のAGENTS.mdガイドでは、起動時に指示を組み立てる際、プロジェクトのルートから現在の作業ディレクトリへ至る経路上のファイルを探す仕組みが説明されています。より深い場所の指示は、先に読み込まれた広い範囲の指示より優先されます。

同ガイドでは、一つのディレクトリについて、AGENTS.override.md、AGENTS.md、設定された代替名の順で候補を探し、最大一つを取り込むとされています。したがって、同じ場所に両方を置けば、二つとも同じ重みで足されると考えるのは適切ではありません。不要になった上書き用ファイルが残ると、通常の指示を更新しても期待した内容が使われない原因になります。

ここで説明しているのは、公式ガイドにある起動時の探索です。ルートから始めた会話で、別の深いフォルダを編集する際のすべての挙動まで、配置図だけで保証するものではありません。専門領域に指示を置いたら、その場所を起点にした新しい会話で、認識された指示を尋ねて確かめます。資料置き場に普通のMarkdownを置いた場合も、指示として扱わせたいのか、必要時に参照する根拠なのかを明確にしてください。

小さなプロジェクトは、まずルートの短いAGENTS.mdから始められます。画面と決済などで守る条件が異なるなら、共通部分をルートに、個別部分を必要な範囲に配置する案を検討します。階層を深くする目的は、文書を細かく分けること自体ではなく、関係する作業にだけ必要な指示を届けることです。

2026年9月の公式記事から参照条件を見直す

今回、フォルダ構成を見直すきっかけは、2026年9月11日公開のOpenAI公式記事「Rethinking skills and prompts for GPT-6 Astra」です。この記事は、新しいモデルに合わせて、積み重ねてきた指示を点検する考え方を紹介しています。すべての編集前に大量の資料を読む指定より、作業に必要な資料を参照する形を例示しています。

これをフォルダ構成に当てはめるなら、資料を減らすことと、資料へ到達する案内を減らすことを混同しないようにします。要件や設計上の判断は残したまま、「画面項目を変える場合はscreen-specを参照」「サービスの境界を変える場合は設計資料を参照」と条件を書きます。この配置への応用は本記事の提案であり、公式記事が特定のフォルダ名を必須にしたわけではありません。

例えば、誤字修正のたびに全資料を読む条件は、依頼の大きさに対して重すぎる場合があります。一方、料金表示の計算方法を変えるなら、表示例と計算仕様の両方が必要です。同じdocs/でも、必要な文書は作業ごとに変わります。入口の案内には「必ず全部読む」と書く代わりに、文書の役割と参照する場面を短く残すと、情報の取り違えを減らせます。

古い資料を削除できない場合は、現行の資料と過去の検討案を分け、更新日や対象バージョンを明示します。フォルダ名だけで新旧を区別しようとすると、移動後のリンクが切れたり、昔の指示が残ったりします。現行の仕様がどれかを本文で説明し、判断が変わった理由も記録する方が、次の担当者へ引き継ぎやすくなります。

既存プロジェクトの構成を確認する四つの手順

構成の改善は、読み取りで現状を把握し、短い案内を足し、指示の範囲を確かめ、小さな修正で試す順に進めます。先に大規模な移動を行うと、構成が悪かったのか、移動で参照先を壊したのかを切り分けにくくなります。まず一つの画面や関数を対象に、迷った場所だけを直す進め方が実用的です。

四つの手順では、どこを変えたかだけでなく、なぜその案内を追加したかも残します。途中で仕様の矛盾が見つかった場合は、フォルダ整理の判断だけで内容を確定させず、製品として期待する動作を担当者が決めてから、現行の資料へ反映します。

Step 1: 今の配置と変更対象を読み取る

Codexには、いきなり整理や移動を依頼せず、「ファイルを変更せず、今回の修正対象、関連する仕様、対応するテストの場所を説明してください」と伝えます。説明には実際のパスを含めてもらい、人が開いて内容を確認します。対象の画面が一つでも、通信や入力の検証が別の場所にある場合があります。見つからない資料は推測で補わせず、どの情報が不足しているかを残します。

Step 2: 入口の案内と参照条件を短く書く

見つけた場所を、既存のREADMEや指示ファイルへ短く記録します。例えば「画面仕様はdocs/screen-spec.md」「入力検証の変更ではtests/servicesを確認」のように、場所と使う場面を結び付けます。まだ存在しない確認方法を、利用できるものとして書かないことも大切です。実際に使える方法、今後整備したい方法、担当者の判断が必要な事項を区別し、案内と現状を一致させます。

Step 3: 指示の適用範囲を新しい会話で確認する

継続的な指示の配置を変えたら、意図した場所を起点に新しい会話を始め、適用される指示と対象フォルダを説明してもらいます。現在の作業場所、認識された指示ファイル、今回参照する資料をそれぞれ確認します。期待と違う場合は、上位の上書き用ファイルや、別の場所を開いている可能性を調べます。会話の説明だけで終わらせず、示されたパスが手元に存在するかも確認してください。

Step 4: 小さな修正で参照先と差分を比べる

最後に、一つの表示文言や狭い範囲の処理を直す依頼で構成を試します。完了報告には、読んだ仕様、変更したファイル、確認した結果を含めてもらいます。差分を見て、依頼と無関係な移動や書き換えが増えていないかを確認します。対応するテストがある場合は、その変更に必要な確認を行います。期待した場所に到達できなかったときは、フォルダ全体を作り直す前に案内の不足を修正します。

構成を変える前に避けたい三つの失敗

よくある失敗は、整理のためにコードと資料を一度に移すことです。見た目は揃っても、読み込み先、テストの対象、資料内のリンクが一緒に変わり、影響が広がります。配置の説明だけで迷いが解消するなら、移動は不要です。移動が必要な場合は、対象を絞り、参照している箇所と動作確認を一緒に扱います。

二つ目は、同じ仕様を複数の指示ファイルへ丸ごとコピーすることです。片方だけが更新されると、どれを根拠にしたかで結果が変わります。共通の仕様本文は一か所に置き、指示側には参照先と適用条件を残します。個別領域の例外は、その例外が必要な理由と範囲を短く書くと、共通仕様との関係を判断しやすくなります。

三つ目は、フォルダ構成を整えれば変更範囲も制限できると思い込むことです。資料の置き場や指示は、作業を理解する助けですが、アクセス範囲を決める設定そのものではありません。編集してよい場所は依頼に明記し、最終的な差分で守られたかを確認します。顧客情報や個人用の資料など、今回の作業に不要なデータは、そもそもプロジェクトへ混ぜないようにしてください。

良い構成の目安は、新しく参加した人とCodexの両方が、対象のコード、仕様の根拠、確認方法へ短い案内で到達できることです。変更時に毎回同じ場所で迷うなら、その場所への説明を一つ足します。作業のたびに全体を読み直す前提を増やすより、迷った理由を具体的に解消する方が、構成を維持しやすくなります。