Codex カスタム指示の書き方と使い分けを実例で解説する

Codex カスタム指示とは：毎回の依頼に共通する前提を置く方法

Codex カスタム指示とは、コードを変更する前に知っておいてほしいプロジェクトの前提を、ファイルなどにまとめて渡す考え方です。その場で「この関数を直して」と頼むだけでは、テストの実行方法、変更してはいけない場所、命名の基準、説明の粒度までは毎回伝わりません。AGENTS.mdに共通の約束を書けば、作業の入口がCLIでもアプリでも、同じリポジトリに対して同じ出発点を作れます。

ここで大切なのは、カスタム指示がCodexの能力を増やす魔法ではないことです。指示はプロジェクトの事実を補い、判断の優先順位を示し、確認の方法をそろえるために使います。存在しない仕様を断定する文や、すべての例外を一つのファイルに詰め込む文は、かえって読みにくくなります。対象、守る条件、完了の判断を一文ずつ分けると、Codexも人も読み返しやすくなります。

その場の依頼と永続的な指示を分ける

一度だけ必要な情報は会話で伝え、複数の作業で繰り返す情報はAGENTS.mdに置きます。たとえば「今回だけこの画面を赤くする」は会話向きですが、「公開画面では文言を日本語にする」「変更後は指定したテストを確認する」はリポジトリの約束として残す価値があります。この境界を決めずにすべてをファイルへ移すと、短い修正にも大量の前提が付き、重要な条件が埋もれます。

反対に、会話だけで済ませると、別のフォルダから始めたときや数日後に再開したとき、前提が抜ける可能性があります。共通方針をファイルに、今回の目的と例外を会話に分けると、指示の寿命が明確になります。Codex カスタム指示は「何でも保存する場所」ではなく、繰り返し使う判断基準を置く場所です。

指示の品質は短さではなく判定可能性で決まる

「丁寧に」「適切に」「よい感じに」といった抽象的な表現だけでは、結果を見た人が守られたか判断できません。「公開APIの変更時は関連するテストを追加し、変更理由を説明する」のように、対象と確認方法まで書くと、返答を評価しやすくなります。長い背景説明を足すより、どのファイルを見て、何を変え、何を確認するかを明示する方が実務では役立ちます。

2026年9月にCodexカスタム指示を見直す理由

カスタム指示そのものは以前から使える考え方ですが、2026年9月は見直しに向く時期です。9月9日に公開された Codex 0.154.0 のリリース情報には、GPT-6-Astraをモデル一覧へ追加する変更、作業用コピーを分ける試験的な機能、作業中に質問へ答える機能、Windowsセッションで同じ背景サーバーを共有する変更が並んでいます。これらはAGENTS.mdの読み込み規則を変更する発表ではありませんが、同じコードを別の入口や別の作業場所から扱う場面が増えたことを示します。

入口が変わると、利用者は「前に伝えた前提が今回も効いているか」を気にします。だから最新機能を試す前に、プロジェクトの指示がどの場所にあり、どの順で重なるかを確認しておくと、モデルや画面の違いとプロジェクト固有の条件を切り分けやすくなります。最新情報は OpenAIのCodex 0.154.0リリース で確認できます。

0.154.0をきっかけに見直す範囲

見直す対象は、指示の数ではなく、指示が届く範囲です。全リポジトリで共通にしたい内容、特定のリポジトリだけの内容、さらに一つのサービスだけの内容を分けてください。Codex 0.154.0の新しい利用場面を試すときも、まず同じフォルダから「読み込んだ指示の出典と要点」を確認すれば、モデルの応答差と指示の適用差を混同しにくくなります。なお、指示を整えた後は新しい実行で読み込み直す必要があります。

AGENTS.mdが指示を届ける仕組み

OpenAIの公式ガイドによると、Codexは作業前にAGENTS.mdを読み込み、共通の案内とプロジェクト固有の案内を一つの指示列にまとめます。ホームディレクトリにある共通ファイル、プロジェクトのルートから現在の作業フォルダまでの各階層にあるファイルが候補です。空のファイルは対象外になり、同じフォルダにAGENTS.override.mdがあれば、通常のAGENTS.mdよりそちらが優先されます。

読み込み順を理解するには、「広い場所から狭い場所へ」という一本の流れで考えると分かりやすくなります。ホームの案内が最初にあり、リポジトリの案内が続き、現在のフォルダに近い案内が最後に加わります。後から加わった内容が前の内容と矛盾する場合は、近い場所の指示が優先されます。したがって、深いフォルダに例外を書くときは、上位の約束を本当に変える必要があるかを確認します。

グローバル指示は全プロジェクトの共通部分にする

Codexのホームは通常 ~/.codex です。ここには、どのリポジトリでも変わらない好みや確認方針を置きます。公式ガイドの例にあるように、JavaScriptを変更したらテストを行う、依存関係を増やす前に確認する、といった広い約束が適しています。Windowsではホームの実際の場所を環境に応じて確認し、編集したファイルとCodexが参照する場所が同じかを確かめてください。

ホームの階層では、AGENTS.override.mdがあればそれが使われ、なければAGENTS.mdが使われます。両方を同じ場所に置いても、二つが単純に合体するわけではありません。一時的に全プロジェクトの共通方針を変えたい場合はoverrideを使い、元の案内を残したまま戻せる状態にしておくと管理しやすくなります。詳しい探索規則は AGENTS.mdの公式ガイド にまとまっています。

プロジェクト指示はリポジトリのルートから考える

プロジェクト側では、通常のGitルートが探索の起点になります。ルートのAGENTS.mdには、言語、主要な確認方法、変更の境界、成果物の説明方法など、プロジェクト全体に関係する内容を書きます。src/やservices/のような下位フォルダからCodexを始めた場合も、ルートから現在地までの階層にある案内が順に検討されます。ルートに置いたからすべての会話で無条件に同じ内容になる、と考えないことが重要です。

リポジトリの境界が見つからない場合は、現在のフォルダだけが確認対象になることがあります。そのため、想定したプロジェクトの中から始めているかを確認し、読み込まれたファイル名をCodexに説明させると、案内が効かない原因を早く見つけられます。ルートの指示は広い範囲に届くため、特定サービスの事情を詰め込みすぎず、下位フォルダへ分ける方が保守しやすくなります。

下位フォルダでは例外だけを上書きする

下位フォルダのAGENTS.mdは、上位ファイルの内容を最初から書き直すためのものではありません。サービス固有のテスト、扱うデータの境界、変更対象のディレクトリなど、上位には書けない例外だけを追加します。さらに短期間だけ方針を変える場合は、同じ場所にAGENTS.override.mdを置きます。公式ガイドの探索例でも、overrideがある場所では通常のAGENTS.mdが無視されるため、両方の内容が必要なら上位の通常ファイルに共通部分を残す設計が必要です。

ファイルを深くするほど、どの指示が最後に届くかを把握しにくくなります。階層を増やす前に、ルートの文をより具体的に書けないか、会話だけで済む例外ではないかを考えてください。下位ファイルは「その場所でしか成立しない約束」を置くものだと定義すると、指示同士の衝突を減らせます。

Codexカスタム指示を書く前の設計

ファイルを作る前に、Codexに任せたい作業の種類を一つか二つに絞ります。コードの読解、修正、テスト、文書更新をすべて同じ粒度で書くと、重要な条件と補助的な説明が混ざります。まず「何を守るべきか」を決め、その後で「どのように確認するか」を足すと、短くても意味のある指示になります。

指示の読み手はCodexだけではありません。新しく参加した人がリポジトリを理解する案内にもなり、レビューする人が変更の前提を確認する資料にもなります。専門用語だけで省略せず、対象フォルダ、代表的なコマンド、失敗したときの報告内容を具体的に書くと、誰が読んでも同じ判断に近づけます。

まず成果物と確認条件を書く

最初の段落では、変更するものと変更しないものを分けます。「画面の表示を変更する」とだけ書かず、「公開画面の文言と対応するテストを更新し、データベースの構造は変更しない」のように範囲を示します。完了条件には、テストの名前、手元で確認する画面、差分の説明などを入れます。結果を見た人が完了か未完了かを判定できる文が、カスタム指示の土台になります。

作業の順番まで固定したい場合は、その理由も添えます。たとえば仕様を読んでからコードを変更するのは、読み取りと修正を分けたいからです。順番に意味がない箇所を細かく指定すると、状況に合わせた判断を妨げます。必須条件と推奨条件を文章上でも分け、どちらを優先するかを明示してください。

失敗時の扱いまで決める

テストが失敗したときに、成功したことだけを報告する指示では役に立ちません。失敗したテスト名、エラーの要点、変更との関係、次に確認すべき点を分けて示すように書きます。外部サービスが使えない場合や、仕様が不明な場合も、推測で進めず「未確認」と示す条件を置いておくと、結果の信頼性を保ちやすくなります。

また、Codexに変更を求める文と、変更を許可する文は別の役割です。カスタム指示に「ファイルを変更してよい」とだけ書いても、実際の許可設定や作業環境の境界が変わるわけではありません。指示には判断基準を書き、実行の可否は利用しているCodexの設定と確認画面で別に確かめる、と整理しておくと誤解が減ります。

32KiBを意識して分割する

公式ガイドでは、読み込むプロジェクト指示の合計サイズは project_doc_max_bytes で制限され、初期値は32KiBと案内されています。ファイルが長すぎると、後半の重要な文が読み込み対象から外れる可能性があります。背景の説明、日々の作業手順、サービス固有の条件を一つの巨大なファイルに集めず、共通部分をルート、固有部分を下位フォルダへ分けるのが基本です。

設定を広げる場合は、公式の Codex Configuration Reference で現在の項目名と既定値を確認します。値を増やせば安全になるとは限らず、読ませる内容が増えるほど重要な条件が見えにくくなります。文字数ではなくバイト数で管理されるため、日本語の説明を多く入れると見た目以上に上限へ近づく点にも注意してください。

Codexカスタム指示を設定する手順

ここからは、既存のリポジトリへ最小限の指示を追加し、読み込まれたことを確認する流れを示します。最初から複数階層を作らず、ルートのAGENTS.mdだけで始めてください。効いていることを確認できてから、必要な範囲にだけ下位ファイルを足すと、どの変更が結果へ影響したかを追いやすくなります。

Step 1: 適用範囲を決める

最初に、全リポジトリで守る方針か、一つのリポジトリだけの方針か、特定フォルダだけの方針かを決めます。全体の作法ならホーム、リポジトリ全体ならルート、サービス固有なら対象フォルダが候補です。現在の作業場所からルートまでの経路を書き出し、同じ名前の指示ファイルやoverrideがすでにないかを調べます。

Step 2: 最小のAGENTS.mdを作る

ルートにAGENTS.mdを作り、目的、変更範囲、確認方法、報告形式を短く書きます。次の例のように、一文が一つの判断を担当する形にすると、曖昧さが減ります。これはそのまま使うテンプレートではなく、プロジェクトの実際のテスト名やフォルダ名へ置き換えるための骨組みです。

# AGENTS.md

## 作業の約束

対象の変更範囲を最初に説明する。
既存のテストと設定を確認してから変更する。
変更後は関連するテストを実行し、結果と未確認点を分けて報告する。
仕様が不明なときは推測で範囲を広げず、確認したい点を質問する。

Step 3: 必要な場所だけoverrideを置く

ルートの指示と異なる扱いが必要なフォルダだけにAGENTS.override.mdを置きます。同じ階層にAGENTS.mdとoverrideを両方置くとoverride側が選ばれるため、共通条件を消してしまわないよう注意してください。短期の調査が終わった後にoverrideを残すか、通常のAGENTS.mdへ反映するかも決めておくと、後から見た人が現在の方針を読み違えません。

Step 4: 読み込み結果を新しい実行で確かめる

ファイルを保存しただけでは、すでに開いているセッションの表示が変わらないことがあります。新しい実行を対象フォルダから始め、「現在読み込んでいる指示ファイルの名前と、それぞれの役割を説明してください」と頼みます。公式ガイドにも、ルートと下位フォルダの指示源を説明させて確認する方法が示されています。期待したファイルが出なければ、作業場所、名前、空ファイル、overrideの有無を順に調べます。

実例：小さなWebプロジェクトで指示を分ける

たとえば、ルートにWebアプリ全体の約束を書き、frontend/だけに画面確認の条件を追加するとします。ルートでは、データを直接書き換えないこと、関連テストを確認すること、変更範囲を説明することを定めます。frontendでは、表示文言、画面幅、既存コンポーネントの再利用など、画面に固有の条件だけを追加します。バックエンドの実装条件をfrontendのファイルへ複製しないのがポイントです。

ディレクトリ構成を文章で表すと、次のような考え方になります。

project/
  AGENTS.md
  frontend/
    AGENTS.md
  backend/
    AGENTS.md

frontendで作業を始めると、ルートの案内の後にfrontendの案内が加わります。backendから始めると、backendの案内が加わります。各ファイルに同じ説明をコピーするのではなく、上位に共通条件、下位に専門条件を置くことで、修正箇所を減らせます。もしfrontendだけ一時的に確認方法を変えるなら、frontend/AGENTS.override.mdを置き、通常のAGENTS.mdを直接書き換えない方法も選べます。

この構成で重要なのは、Codexへ「全部のルールを守って」と頼むことではありません。ルートの方針、現在のフォルダの方針、今回だけの依頼を分け、読み込まれた結果を確認することです。指示ファイルの役割が重ならなければ、モデルを変えたときにも、どの条件が共通でどれが専門的かを説明しやすくなります。

AGENTS.md・設定ファイル・rulesの使い分け

Codexの設定には、作業内容を案内するファイル、クライアントの振る舞いを調整する設定ファイル、コマンドの許可範囲を扱うrulesがあります。これらを一つのファイルへ集めると、指示を読んでほしいのか、設定値を変えたいのか、実行の可否を決めたいのかが分からなくなります。役割ごとに置き場所を分けることが、Codex カスタム指示を安定させる近道です。

AGENTS.mdはプロジェクトの判断基準を書く

AGENTS.mdには、コードの構造、変更の境界、テストの考え方、返答に含める情報を書きます。人がレビューできる約束として残したい内容に向いています。グローバルとプロジェクトの層を分ければ、個人の好みとチームの方針を混ぜずに済みます。ファイル名を独自にしたい場合は、公式ガイドにある project_doc_fallback_filenames の設定を確認し、Codexがその名前を探索するようにします。

config.tomlはCodexの動作設定を置く

config.tomlは、モデル、承認方式、文脈の上限、指示ファイルの探索に関係する項目など、Codexクライアントの動作を調整する場所です。プロジェクトの文章をここへ長く書くのではなく、設定値は設定値として管理し、意味や採用理由はAGENTS.mdに説明する方が読みやすくなります。設定の項目名は版によって増減するため、現在の Configuration Reference を見てから変更してください。

rulesはコマンドの扱いを分けて考える

rulesは、特定のコマンドを許可、確認、拒否のどれとして扱うかを決める仕組みです。AGENTS.mdに「安全に作業する」と書いても、具体的なコマンドの扱いが変わるわけではありません。逆にrulesへプロジェクトの背景を長く書いても、Codexが作業の目的を理解するための案内にはなりません。判断基準はAGENTS.md、クライアントの値はconfig.toml、コマンドの扱いはrulesという分担にすると、確認箇所が明確になります。

カスタムプロンプトは一時的な定型文と区別する

カスタムプロンプトは、呼び出したときに使う定型文をまとめる仕組みです。一方、AGENTS.mdは作業の開始時に読み込ませるプロジェクトの前提です。毎回同じ依頼文を呼び出したいのか、どの依頼にも共通する約束を伝えたいのかで、選ぶ場所が異なります。両方を使う場合も、同じ説明を二重に書かず、定型文は依頼の形、AGENTS.mdは判断基準という関係にしてください。

Codexカスタム指示が効かないときの確認

指示が効かないと感じたとき、すぐに文章を増やすのは得策ではありません。Codexが別の場所から始まっている、ファイル名が探索対象ではない、overrideが通常ファイルを置き換えている、合計サイズが上限に達している、といった原因が先に考えられます。公式ガイドの探索順に沿って、場所、名前、順番、サイズを一つずつ確認してください。

Step 5: 作業場所とリポジトリの境界を確認する

まず、Codexを始めたフォルダが想定したリポジトリの中かを確かめます。ルートのAGENTS.mdを作ったのに、別の親フォルダやリポジトリのない場所から始めていれば、そのファイルは探索経路に入りません。現在のフォルダ、プロジェクトのルート、対象ファイルの場所を一緒に説明させると、最初の切り分けができます。

Step 6: ファイル名とoverrideの有無を確認する

AGENTS.mdのつづり、拡張子、空白、保存場所を確認します。独自名のファイルは project_doc_fallback_filenames に登録しない限り、通常の候補になりません。同じ階層のAGENTS.override.mdが見つかった場合は、通常のAGENTS.mdが選ばれないため、overrideに必要な共通条件が入っているかを見直します。

Step 7: 新しい実行で読み込み直す

指示を保存した後も、すでに開いている会話が以前の指示列を使っていることがあります。いったん新しい実行を対象フォルダから始め、読み込まれたファイル名を質問します。期待するファイルが読み込まれた後で、同じ依頼を試してください。指示の変更と依頼内容の変更を同時に行わなければ、改善の原因を追跡しやすくなります。

Step 8: サイズ上限と設定の参照先を確認する

複数階層の指示を足した後だけ内容が欠けるなら、project_doc_max_bytes の値と合計サイズを調べます。重要な条件をファイルの後半へ寄せるのではなく、共通条件と専門条件を分け、不要な背景説明を削ります。さらに CODEX_HOME を変更している環境では、編集した設定と実際に参照されるホームが異なることがあります。公式の設定リファレンスと実際の読み込み結果を照合してください。

指示を更新するときに守る運用上のコツ

カスタム指示は、一度書いたら終わりではありません。プロジェクトのテスト名が変わった、フォルダ構成が変わった、以前の例外が不要になった、といった変化に合わせて見直します。ただし、毎回文章を追加するだけではファイルが膨らみます。新しい条件を足す前に、古い条件と重複していないか、下位ファイルへ移すべきではないか、会話だけで済む一回限りの事情ではないかを確認してください。

追加前に重複と矛盾を減らす

同じ内容がグローバル、ルート、下位フォルダの三か所にあると、どれを直すべきか迷います。まず最も広い場所に置く必要があるかを考え、必要な範囲で最も狭い場所へ置きます。矛盾しそうな文を見つけたら、近い場所で上書きするより、上位の表現を広く保ち、下位では例外だけを書く方が読み込み順を説明しやすくなります。

完了条件を実際の作業に合わせて保つ

「テストを実行する」という指示があっても、テストの名前や対象が変われば意味が薄れます。リポジトリのREADME、設定、テストの入口を見直し、現在の作業で本当に確認できる条件へ更新します。実行できない確認を必須条件に残すと、毎回未完了の報告になり、重要な失敗が埋もれます。必要なら代替の読み取り確認を明記してください。

変更後は指示の読み込み自体を確認する

指示ファイルを変更したときは、コードの結果だけでなく、Codexがどのファイルを読み込んだかも一度確認します。ルートから始めた場合と下位フォルダから始めた場合で、説明される指示源がどう変わるかを比べると、意図した層構造を検証できます。指示が効いたように見えるだけで判断せず、ファイル名と適用範囲を記録しておくと、後日の再現にも役立ちます。

まとめ：Codexカスタム指示は範囲と確認方法から整える

Codex カスタム指示を始めるなら、最初にルートのAGENTS.mdへ、変更範囲、守る条件、完了の確認方法を書きます。全プロジェクト共通の内容はホーム、リポジトリ全体の内容はルート、特定の場所だけの例外は下位フォルダへ分けます。AGENTS.override.mdは通常の案内を置き換えるため、短期の変更に使うときも共通条件を失わないようにしてください。

指示の読み込みでは、プロジェクトのルートから現在の場所へ重なる順番、空ファイルの扱い、独自ファイル名の登録、32KiBの既定上限を確認します。Codex 0.154.0のような更新で利用する入口が増えても、指示の出典を新しい実行で確かめれば、モデルや画面の違いとプロジェクトの前提を分けて考えられます。詳しい探索規則は OpenAI公式のAGENTS.mdガイド と Codex設定リファレンス を参照してください。