Codex CLIのAGENTS.md活用ガイド｜指示の優先順位と書き方

Codex CLIやIDE拡張を使っていて、「毎回同じ注意点を指示するのが面倒」「チームごとに作業ルールが違う」と感じたことがあれば、それを解決するのがAGENTS.mdというファイルだ。公式ドキュメントは「Codexはどんな作業を始める前にもAGENTS.mdファイルを読み込む。グローバルな方針とプロジェクト固有の上書きを重ねることで、どのリポジトリを開いても一貫した前提で各タスクを始められる」と説明している（OpenAI公式 Custom instructions with AGENTS.md、2026年9月25日取得）。結論から言えば、AGENTS.mdは「自分用のグローバル指示」と「リポジトリ用の共通ルール」と「特定ディレクトリだけの上書き」の3段階を、ファイルを置く場所だけで表現できる仕組みであり、テストコマンドやパッケージマネージャーの好みといった繰り返し伝えている指示を、この1ファイルへ集約するのが基本の使い方になる。

この記事では、公式ドキュメントの記述に沿って、Codexが指示ファイルを探す3段階の優先順位、グローバル指示とプロジェクト指示・ディレクトリ単位の上書きそれぞれの作り方、結合順序と読み込み上限、GitHubのコードレビューに使うルールの書き方、独自ファイル名を指示ファイルとして扱う設定、CODEX_HOME環境変数の使い方、設定が反映されているかの確認方法、よくあるトラブルと対処法まで整理する。Codex CLIの基本操作から確認したい場合はOpenAI Codex 使い方｜料金・始め方・Claude Codeとの違いを初心者向けに解説を先に読んでおくと理解しやすい。

AGENTS.mdとは何か｜Codexが起動時に読み込む指示ファイル

AGENTS.mdとは、Codexが作業を始める前に読み込む、プロジェクトやユーザーごとのカスタム指示を書くMarkdownファイルのことです。

公式ドキュメントの冒頭が示すとおり、AGENTS.mdの役割は「グローバルな方針」と「プロジェクト固有の上書き」を層状に重ねることにある。ユーザー単位のディレクトリに置けば全リポジトリ共通の作業前提になり、リポジトリのルートに置けばそのプロジェクトのメンバー全員が同じ前提でCodexを使える。さらにサブディレクトリごとに個別のAGENTS.mdを置けば、チームやサービス単位で異なるルールも表現できる。

似た仕組みとして、Codex CLI全体の挙動を細かく制御するconfig.tomlがあるが、役割は異なる。config.tomlはモデルや承認モード、MCPサーバーなど「Codexというツールの動かし方」を設定するファイルで、AGENTS.mdは「このリポジトリやこのディレクトリで何を守ってほしいか」という作業内容側の指示を書くファイルになる。config.toml自体の書き方はCodex CLIのconfig.toml完全ガイド｜設定の優先順位と書き方にまとめてある。両者の役割の違いは記事後半でも改めて整理する。

なぜAGENTS.mdを使うべきか｜作業前提をそろえる目的

AGENTS.mdを使う目的とは、テストコマンドや依存関係の好みといった繰り返し伝える指示を1ファイルに集約し、誰がCodexを使っても同じ前提でタスクを始められるようにすることです。

AGENTS.mdが無い状態でCodexにタスクを依頼すると、npmテストを実行してほしい、pnpmを使ってほしいといった要望をタスクのたびにプロンプトへ書き足すことになる。チームで使う場合はメンバーごとに伝える内容がぶれやすく、新しいメンバーが増えるたびに同じ説明を繰り返すことにもなる。AGENTS.mdへ書いておけば、Codexが起動するたびにこれらの指示を自動で読み込むため、プロンプト側で毎回繰り返す必要がなくなる。

個人の作業スタイルに関する指示はグローバルのAGENTS.mdへ、プロジェクト固有のルールはリポジトリのAGENTS.mdへ、サービス単位の細かい例外は各ディレクトリのAGENTS.mdやAGENTS.override.mdへと、指示の性質によって置き場所を使い分けるのが基本方針になる。次の章では、Codexがこれらのファイルをどの順番で探すのかを見ていく。

Codexが指示を探す3段階の仕組み｜グローバル・プロジェクト・結合順序

Codexが指示を探す3段階の仕組みとは、グローバルスコープ・プロジェクトスコープ・結合順序という順番で指示ファイルを収集し、1つの指示チェーンにまとめる仕組みのことです。

公式ドキュメントは、Codexが起動時（実行ごと、TUIでは通常はセッションを開始するごと）に指示チェーンを構築すると説明したうえで、その探索順序を次の3段階に整理している（Custom instructions with AGENTS.md）。

段階	探す場所	採用されるファイル
1. グローバルスコープ	Codexホームディレクトリ（既定は~/.codex、CODEX_HOMEを設定していればそちら）	AGENTS.override.mdがあればそれを使い、無ければAGENTS.mdを使う。この階層で採用するのは最初に見つかった空でない1ファイルだけ
2. プロジェクトスコープ	プロジェクトルート（通常はGitのルート）から現在の作業ディレクトリまで、各ディレクトリを順にたどる	各ディレクトリでAGENTS.override.md→AGENTS.md→project_doc_fallback_filenamesに列挙したファイル名の順に確認し、1ディレクトリにつき最大1ファイルを採用する
3. 結合順序	ルート側のファイルから現在の作業ディレクトリ側のファイルへ向かって並べる	すべてのファイルを空行でつなげて1つの指示として連結する。現在のディレクトリに近いファイルほど後ろに来るため、あとから読まれる分だけ手前の指示を上書きする形になる

公式ドキュメントによれば、プロジェクトルートが見つからない場合、Codexは現在のディレクトリだけを確認する（Custom instructions with AGENTS.md）。つまりGit管理外のフォルダで作業している場合でも、そのフォルダに置いたAGENTS.mdは読み込まれる。次の2つの章では、実際にグローバル指示とプロジェクト指示をどう作るかを、公式ドキュメントの手順どおりに見ていく。

グローバル指示を作る｜~/.codex/AGENTS.mdの書き方

グローバル指示とは、Codexホームディレクトリに置くことで、開く場所を問わず全リポジトリへ引き継がれる持続的な既定ルールのことです。

公式ドキュメントが示す手順は次のとおりで、まずディレクトリを用意する。

mkdir -p ~/.codex

続けて~/.codex/AGENTS.mdを作成し、繰り返し使う作業合意を書く。ドキュメントに示された例は次のような内容だ。

# ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

作成後は、どこでCodexを起動しても読み込まれているかを次のコマンドで確認できる。

codex --ask-for-approval never "Summarize the current instructions."

公式ドキュメントによれば、このコマンドを実行すると、Codexは提案を出す前に~/.codex/AGENTS.mdに書いた項目を引用して答える。もし一時的にグローバル指示だけ変えたい場合は、ベースのAGENTS.mdを消さずに~/.codex/AGENTS.override.mdを作ればよい。上書きファイルを削除すれば、共有していたグローバル指示に戻る。

プロジェクトルートにAGENTS.mdを追加する｜リポジトリ共通のルール

プロジェクトルートのAGENTS.mdとは、リポジトリを開く全メンバーへ、そのプロジェクト固有の作業ルールを引き継ぐための指示ファイルのことです。

リポジトリレベルのファイルは、グローバルの既定を引き継ぎつつ、プロジェクト独自の規約をCodexへ伝える役割を持つ。公式ドキュメントの例は、リポジトリルートに基本的なセットアップを書く形になっている。

# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

チームによって異なるルールが必要なネストしたディレクトリには、個別の上書きを追加できる。たとえばservices/payments/で決済チーム独自のルールを適用したい場合、そのディレクトリにAGENTS.override.mdを置く。

# services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

この状態でpaymentsディレクトリからCodexを起動すると、指示の読み込み順を確認できる。

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

公式ドキュメントは、この結果としてCodexが「グローバルファイルを最初に、リポジトリルートのAGENTS.mdを2番目に、paymentsの上書きを最後に」報告すると説明している（Custom instructions with AGENTS.md）。Codexは現在のディレクトリに到達した時点で探索を止めるため、専用ルールを適用したいディレクトリのできるだけ近くに上書きファイルを置くのが基本の考え方になる。

ディレクトリ単位で上書きする｜AGENTS.override.mdの使い方

AGENTS.override.mdとは、同じディレクトリにある通常のAGENTS.mdを完全に置き換えて優先的に読み込まれる上書き専用の指示ファイルのことです。

先ほどのpaymentsの例が示すように、AGENTS.override.mdが存在するディレクトリでは、同じ場所にあるAGENTS.mdはまったく読み込まれない。1ディレクトリにつき採用されるのは最初に見つかった1ファイルだけという仕組みが、グローバルスコープにもプロジェクトスコープにも共通しているためだ。

用途としては、通常時はチーム全体で共有するAGENTS.mdを維持しつつ、期間限定のキャンペーン対応や大規模リファクタリング中だけ挙動を変えたいときに、そのディレクトリへAGENTS.override.mdを追加し、作業が終われば削除して元のルールに戻す、という使い方がしやすい。ベースのファイルを直接書き換えると差分管理が煩雑になるが、上書きファイルなら追加と削除だけで切り替えられる。

結合順序と読み込み上限｜project_doc_max_bytesとは

project_doc_max_bytesとは、Codexが指示チェーンへ組み込むAGENTS.md系ファイルの合計サイズに設ける、既定32 KiBの読み込み上限のことです。

公式ドキュメントは「Codexは空のファイルをスキップし、結合サイズがproject_doc_max_bytesで定義された上限（既定32 KiB）に達した時点でファイルの追加を止める」と説明している（OpenAI公式 Custom instructions with AGENTS.md、2026年9月25日取得）。あわせてAdvanced Configurationのドキュメントでも「CodexはAGENTS.md（および関連ファイル）を読み込み、セッションの最初のターンに一定量のプロジェクト指示を含める」としたうえで、これを制御する2つの設定項目（project_doc_max_bytesとproject_doc_fallback_filenames）を挙げている（OpenAI公式 Advanced Configuration、2026年9月25日取得）。探索そのものの範囲を変えるCODEX_HOME環境変数もあわせて整理すると、指示ファイルの探索に関わる主な項目は次のとおりになる。

設定項目	既定値	内容
project_doc_max_bytes（config.toml）	32 KiB	各AGENTS.mdファイルから読み込む上限バイト数。結合サイズがこの上限に達した時点で、それ以降のファイルは追加されない
project_doc_fallback_filenames（config.toml）	未設定	ディレクトリにAGENTS.mdが無いときに、代わりに指示ファイルとして試す追加のファイル名
CODEX_HOME（環境変数）	~/.codex	config.tomlの2項目とは別の仕組みで、グローバルスコープの探索対象そのものを既定のCodexホームディレクトリから切り替える

上限に達しやすいのは、多数のネストしたディレクトリにそれぞれ長いAGENTS.mdを置いているケースだ。この場合、公式ドキュメントが案内するとおり上限を引き上げるか、指示をよりネストしたディレクトリへ分割して、実際にCodexが作業する場所に近い指示から優先的に読み込まれるようにするのが対処法になる。上限値の変更方法は後述の「独自のファイル名を指示ファイルとして扱う」で具体例とあわせて扱う。

仮の例：グローバル指示とpaymentsディレクトリの上書きを組み合わせる

この節は、公式ドキュメントに示された設定例だけを使って、3段階の指示がどう積み重なるかを示す仮の例です。

ここからは仮の例であり、実在のチームやリポジトリを前提にしたものではない。ここまでの内容を1つの構成にまとめると、リポジトリは次のような構造になる。

AGENTS.md                      # リポジトリ共通ルール（npm run lintなど）
services/
  payments/
    AGENTS.md                  # 上書きが存在するため無視される
    AGENTS.override.md         # 決済サービス固有のルール（make test-paymentsなど）
    README.md
  search/
    AGENTS.md                  # search用の個別ルール

この構成にグローバル指示（~/.codex/AGENTS.mdのnpm test・pnpm優先などの作業合意）を加えると、Codexがpaymentsディレクトリで起動したときの指示チェーンは、グローバル指示→リポジトリルートのAGENTS.md→paymentsのAGENTS.override.mdの順に連結される。後ろに来るpaymentsの指示ほど優先されるため、「npm testを使う」という一般ルールがあっても、paymentsディレクトリでは「make test-paymentsを使う」という上書きが実際の指示として採用される。searchディレクトリで起動した場合は上書きが無いため、リポジトリルートのAGENTS.mdまでがそのまま適用される。

この仮の例からわかるのは、AGENTS.mdの設計では「全体に共通させたいルールほど浅い階層に、例外ほど深い階層に」置くという方針が、結合順序の仕組みとそのまま対応しているという点だ。

コードレビュー専用のルールを書く｜Code Review Rulesセクション

Code Review Rulesセクションとは、GitHub上のCodexコードレビューに向けて、AGENTS.mdの中に専用の見出しで書く追加ルールのことです。

公式ドキュメントは、GitHubでのCodexコードレビュー向けに、ルールを適用したいコードに最も近いAGENTS.mdへ## Code Review Rulesという見出しのセクションを追加する方法を案内している。リポジトリ全体に適用したいチェックはルートのAGENTS.mdへ、サービス固有のチェックはネストしたファイルへ書き分ける。示されている例は次のような内容だ。

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

公式ドキュメントは「ルールは簡潔にし、フラグを立てたい挙動と、あれば安全な代替策や例外を説明し、フォーマットやlintのチェックはCIに任せる」ことを勧めている（OpenAI公式 Custom instructions with AGENTS.md）。GitHub連携でのCodexコードレビュー自体は「プルリクエストの差分を確認し、リポジトリのガイダンスに従って、重大な問題に絞った標準的なGitHubコードレビューを投稿する」機能で、コメントで@codex reviewと書くと開始できる（OpenAI公式 Review GitHub pull requests with Codex）。Codex CloudやGitHub連携の導入手順そのものはCodex Cloudの使い方｜導入手順・環境設定・料金プランを解説で扱っているので、レビュー機能自体を使い始めたい場合はそちらを先に確認してほしい。

独自のファイル名を指示ファイルとして扱う｜project_doc_fallback_filenames

project_doc_fallback_filenamesとは、リポジトリが既に使っている別名のファイルを、AGENTS.mdの代わりに指示ファイルとして扱えるようにする設定項目のことです。

すでにTEAM_GUIDE.mdのような別名のファイルで作業ルールを管理している場合、AGENTS.mdへ書き直さなくても、config.tomlにフォールバック名を追加するだけで指示ファイルとして扱える。設定例は次のとおり。

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

設定を保存したら、Codexを再起動するか新しいコマンドを実行して、更新した設定を読み込ませる。この設定を追加すると、Codexは各ディレクトリを次の順序で確認するようになる。

確認順	ファイル名	備考
1	AGENTS.override.md	既定の上書きファイル名。設定に関わらず常に最優先
2	AGENTS.md	既定の指示ファイル名
3	TEAM_GUIDE.md	project_doc_fallback_filenamesに追加した1つ目のフォールバック名
4	.agents.md	同じく2つ目のフォールバック名。リストに無いファイル名は指示として扱われない

公式ドキュメントは、この一覧にない名前のファイルは指示の探索対象として無視されるとしたうえで、project_doc_max_bytesを大きくした分だけ、切り詰められる前に読み込める指示の総量が増えると説明している。フォールバック名を設定していても、あるディレクトリにAGENTS.override.mdがあれば、そちらがTEAM_GUIDE.mdや.agents.mdより優先される点は変わらない。

CODEX_HOME環境変数でプロファイルを切り替える

CODEX_HOME環境変数とは、Codexがグローバル指示や設定ファイルを探しに行くホームディレクトリを、既定の~/.codexから変更するための環境変数のことです。

プロジェクト専用の自動化ユーザーなど、通常の個人設定とは別のプロファイルを使いたい場合に、CODEX_HOMEを指定して実行できる。公式ドキュメントの例は次のとおり。

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

このコマンドを実行すると、Codexは現在のディレクトリ配下の.codexを基準にしたファイルパスで、有効な指示ファイルの一覧を出力する。既定の~/.codexとは別のディレクトリをグローバルスコープとして扱わせたい場合に使う設定であり、CI環境やリポジトリに同梱した専用設定を使い分けたいときに向いている。

設定が読み込まれているか確認する3つの方法

設定が読み込まれているかの確認方法とは、公式ドキュメントが案内する、指示チェーンの内容とその優先順位を実際にCodexへ聞いて確かめる手順のことです。

公式ドキュメントは、確認方法として次の3つを挙げている（Custom instructions with AGENTS.md）。

• リポジトリのルートからcodex --ask-for-approval never "Summarize the current instructions."を実行し、グローバルとプロジェクト両方のファイルからの指示が、優先順位どおりに引用されるか確認する
• codex --cd subdir --ask-for-approval never "Show which instruction files are active."を使い、ネストしたディレクトリの上書きが、より広い範囲のルールを実際に置き換えているか確認する
• Codexが読み込んだ指示ファイルを監査したい場合は、codex -c log_dir=./.codex-logでプレーンテキストのTUIログを有効にして./.codex-log/codex-tui.logを確認するか、セッションログを有効にしていれば直近のsession-*.jsonlファイルを調べる

公式ドキュメントはあわせて、「指示が古いままに見える場合は、対象ディレクトリでCodexを再起動する。Codexは実行のたびに（TUIなら各セッションの開始時に）指示チェーンを再構築するため、手動でクリアするキャッシュは存在しない」としている。つまり、AGENTS.mdを編集した直後にすでに起動済みのセッションへ反映したい場合は、そのセッションを終了して同じディレクトリでCodexを再起動する必要がある。

よくあるトラブルと対処法｜指示が反映されない・上書きされる・切り詰められる

よくあるトラブルとは、AGENTS.mdの指示が読み込まれない・意図しない内容が優先される・途中で切り詰められるといった、公式ドキュメントが挙げる代表的な症状のことです。

公式ドキュメントの「Troubleshoot discovery issues」には、次の5つの症状と対処法がまとめられている（Custom instructions with AGENTS.md）。

症状	対処法
何も読み込まれない	意図したリポジトリにいるか、codex statusで想定どおりのワークスペースルートが報告されるかを確認する。指示ファイルに内容があるかも確認する（Codexは空のファイルを無視する）
意図しない指示が出てくる	ディレクトリツリーの上位やCodexホームにAGENTS.override.mdが無いか探す。通常のファイルへ戻したい場合は上書きファイルをリネームまたは削除する
フォールバック名が無視される	project_doc_fallback_filenamesに指定した名前にタイプミスが無いか確認し、Codexを再起動して更新済みの設定を反映させる
指示が途中で切り詰められる	project_doc_max_bytesを引き上げるか、大きなファイルをネストしたディレクトリへ分割して、重要な指示が上限内に収まるようにする
プロファイルの混同	Codexを起動する前にecho $CODEX_HOMEを実行する。既定と異なる値になっていれば、編集したディレクトリとは別のホームディレクトリをCodexが見ている

この5つのうち、実務でまず疑うべきは「意図しない指示が出てくる」と「プロファイルの混同」の2つだ。想定どおりの内容にならないときは、まずAGENTS.override.mdの有無とCODEX_HOMEの値を確認すると、原因の切り分けが早い。

config.toml・MCPサーバー設定との役割の違い

config.toml・MCPサーバー設定との役割の違いとは、Codexを動かす仕組みを設定するファイルと、作業内容そのものを指示するファイルという、目的が異なる3つの設定の関係のことです。

ここまで見てきたAGENTS.mdは、config.tomlやMCPサーバー設定と混同しやすいが、扱う対象が異なる。3つを役割で整理すると次のようになる。

項目	AGENTS.md	config.toml	MCPサーバー設定
主な役割	このリポジトリ・このディレクトリで守ってほしい作業内容の指示	モデル・承認モード・サンドボックスなどCodexというツール自体の挙動設定	Codexが呼び出せる外部ツール（ドキュメント検索やブラウザ操作など）の接続設定
保存場所	AGENTS.md/AGENTS.override.md（グローバル・プロジェクト・ディレクトリ単位）	~/.codex/config.tomlまたはプロジェクト単位の.codex/config.toml	config.toml内の[mcp_servers.<name>]テーブル
読み込みタイミング	Codexの起動ごと（TUIはセッション開始ごと）に指示チェーンとして再構築	Codexコマンド実行時に設定として読み込み	Codex起動時にサーバー定義として読み込み、ツール一覧に反映

project_doc_max_bytesやproject_doc_fallback_filenamesのようにAGENTS.mdの挙動を調整するキー自体はconfig.tomlに書く点も紛らわしいポイントだ。「何を守ってほしいか」はAGENTS.mdに、「AGENTS.mdをどう探すか・Codex全体をどう動かすか」はconfig.tomlに書く、という切り分けで考えると整理しやすい。MCPサーバーの接続方式やオプションの詳細はCodex CLIのMCP連携ガイド｜サーバー追加とconfig.toml設定に、CLI・IDE拡張・クラウド・アプリという提供形態そのものの違いはOpenAI Codexの提供形態の違い｜CLI・IDE・クラウド・アプリ比較にまとめてある。

なおAGENTS.mdが扱うのは、あくまでCodexとの対話やエージェントへの作業指示であり、API経由で呼び出すモデルの応答そのものをJSON Schemaで固定したい場合は、別の仕組みであるOpenAI APIの構造化出力の使い方｜JSON Schemaで固定する手順を使う。目的が「Codexにどう作業してほしいか」なのか「APIの出力形式をどう固定するか」なのかで、参照すべき設定が変わる点は覚えておきたい。

組織でAGENTS.mdの運用ルールを統一したい場合は、チーム展開の前提となる導入計画も合わせて確認しておきたい。Codexの企業導入全体の流れはOpenAI Codex企業導入ガイド｜モデル・コスト・移行計画・2026年の最新情報で扱っている。ChatGPT側でプロジェクトごとに指示やファイルを整理する仕組みと役割分担を比較したい場合はChatGPTのプロジェクト機能の使い方｜ファイル・指示・チャットの整理手順も参考になる。

よくある質問（FAQ）

Q1. AGENTS.mdはどこに置けばいいですか。

置き場所によって適用範囲が変わります。全リポジトリに共通させたい指示はCodexホームディレクトリ（既定~/.codex）に、特定のプロジェクトだけに適用したい指示はそのリポジトリのルートに、さらに細かい例外はサブディレクトリに置きます。公式ドキュメントが示すとおり、Codexはグローバルスコープを確認したあと、プロジェクトルートから現在の作業ディレクトリまでを順にたどって指示ファイルを収集します。

Q2. AGENTS.mdとAGENTS.override.mdの違いは何ですか。

同じディレクトリに両方あった場合、CodexはAGENTS.override.mdだけを使い、AGENTS.mdは無視します。ベースの指示を残したまま一時的に挙動を変えたいときにAGENTS.override.mdを追加し、不要になれば削除して通常のAGENTS.mdに戻す、という使い分けができます。

Q3. project_doc_max_bytesの上限を超えるとどうなりますか。

結合した指示の合計サイズが上限（既定32 KiB）に達した時点で、Codexはそれ以降のファイルを指示チェーンへ追加しなくなります。重要な指示が切り詰められている場合は、project_doc_max_bytesを引き上げるか、指示を複数のネストしたディレクトリへ分割して、作業する場所に近い指示から優先的に読み込まれるようにします。

Q4. 既存のTEAM_GUIDE.mdのような別名ファイルを、そのままAGENTS.mdの代わりに使えますか。

使えます。config.tomlのproject_doc_fallback_filenamesにそのファイル名を追加すると、AGENTS.override.mdとAGENTS.mdのどちらも無いディレクトリで、指定した順番のフォールバック名を指示ファイルとして扱います。一覧に含めていないファイル名は、指示の探索対象にはなりません。

Q5. AGENTS.mdを編集したら、起動中のセッションにもすぐ反映されますか。

起動中のセッションには自動反映されません。公式ドキュメントは、Codexが実行のたびに（TUIでは各セッションの開始時に）指示チェーンを再構築するため手動でクリアするキャッシュは無いとしたうえで、指示が古いままに見える場合は対象ディレクトリでCodexを再起動するよう案内しています。

Q6. AGENTS.mdはGitHubのコードレビューにも使われますか。

使われます。ルールを適用したいコードに最も近いAGENTS.mdへ## Code Review Rulesという見出しのセクションを追加すると、GitHub上のCodexコードレビューがそのルールに沿ってチェックします。リポジトリ全体のルールはルートに、サービス固有のルールはネストしたファイルに書き分けます。

Q7. AGENTS.override.mdを削除するとどうなりますか。

そのディレクトリでは通常のAGENTS.mdにフォールバックします。公式ドキュメントのトラブルシューティングでも、意図しない指示が出ている場合はディレクトリツリーの上位やCodexホームにAGENTS.override.mdが残っていないか確認し、不要ならリネームまたは削除して通常のファイルへ戻すことを案内しています。

Q8. project_doc_fallback_filenamesに複数のファイル名を設定した場合、探す順番はどうなりますか。

各ディレクトリでAGENTS.override.md、次にAGENTS.md、そのあとはproject_doc_fallback_filenamesに書いた順番でファイル名を確認します。たとえば["TEAM_GUIDE.md", ".agents.md"]と設定した場合、TEAM_GUIDE.mdが.agents.mdより先に確認され、最初に見つかったファイルだけがそのディレクトリの指示として採用されます。

まとめ

AGENTS.mdは、Codexが起動するたびに読み込む指示ファイルを、グローバルスコープ・プロジェクトスコープ・結合順序という3段階の仕組みで積み重ねる機能だ。全リポジトリ共通の作業合意は~/.codex/AGENTS.mdに、プロジェクト固有のルールはリポジトリルートのAGENTS.mdに、サービスやチーム単位の例外はネストしたディレクトリのAGENTS.override.mdに書くという整理をしておくと、指示の優先順位も自然と設計しやすくなる。

運用面では、project_doc_max_bytesによる読み込み上限とproject_doc_fallback_filenamesによる代替ファイル名の扱いを理解しておくと、指示が切り詰められる・既存ファイルをAGENTS.mdへ書き直さずに済ませたいといった場面で対処しやすい。GitHub連携でのコードレビューにルールを反映させたい場合は、対象コードに最も近いAGENTS.mdへ## Code Review Rulesセクションを追加する。

設定した指示が想定どおり反映されているかどうかは、codex --ask-for-approval never "Summarize the current instructions."のようなコマンドで実際に確認できる。反映されない場合は、意図しないAGENTS.override.mdが上位にないか、CODEX_HOMEが想定と違うディレクトリを指していないかから疑うとよい。設定項目や既定値は更新される可能性があるため、本番運用の前に公式のCustom instructions with AGENTS.mdとAdvanced Configurationで最新の内容を確認してほしい。