なぜCodexはあなたが書いた指示をスキップするのか
ディレクトリごとに1ファイル、そしてオーバーライドが常に優先される
Codexは起動時に、ドキュメントに記載された優先順位に従って指示チェーンを構築します。グローバルレベル（Codexのホームディレクトリ。CODEX_HOMEを設定していない場合はデフォルトで~/.codex）では、「AGENTS.override.mdが存在すればそれを読み込みます。存在しない場合はAGENTS.mdを読み込みます。Codexはこのレベルで最初に見つかった空でないファイルのみを使用します。」
次にプロジェクトスコープです。プロジェクトのルートから開始し、作業ディレクトリに向かって下っていきます。「パスに沿った各ディレクトリにおいて、AGENTS.override.md、次にAGENTS.md、そしてproject_doc_fallback_filenamesに指定されたフォールバック名をチェックします。Codexは各ディレクトリにつき最大1つのファイルのみを含めます。」
この最後の1文こそが、すべての問題の原因です。AGENTS.override.mdは、隣にあるAGENTS.mdとマージされるのではなく、それを置き換えます。ドキュメントでは、この想定される用途を一時的なものとして説明しています。「ベースファイルを削除することなく、一時的なグローバルオーバーライドが必要な場合は、~/.codex/AGENTS.override.mdを使用してください。共有ガイダンスを復元するには、オーバーライドを削除します。」しかし、一時的なファイルというのは往々にして恒久的なものになりがちです。半年後には、インシデント対応中に誰かがコミットしたオーバーライドファイルのせいで、レポジトリの実際のルールが抑制されていることなど誰も覚えていません。
検索は起動した場所で停止するため、それより深い階層は不可視になる
「プロジェクトのルート（通常はGitのルート）から開始し、Codexは現在の作業ディレクトリまで下っていきます。」そして「Codexは現在のディレクトリに到達すると検索を停止するため、オーバーライドは専門的な作業を行う場所にできるだけ近く配置してください。」
これはアドバイスではなく、制約として捉えてください。レポジトリのルートからCodexを実行した場合、services/payments/内に入念に書かれたAGENTS.mdはチェーンに含まれません。あなたはそれより上の階層にいるのであって、下の階層にいるわけではないからです。兄弟ディレクトリもチェーンに含まれることはありません。読み込まれるファイルのセットは単一の垂直なパスであり、どのパスになるかは起動したときにあなたがどのディレクトリにいたかに完全に依存します。
これに関連するギャップもあります。「Codexがプロジェクトのルートを見つけられない場合、現在のディレクトリのみをチェックします。」
チェーンには上限があり、2つの公式ページでその上限の説明が異なる
「Codexは空のファイルをスキップし、結合されたサイズがproject_doc_max_bytes（デフォルトは32 KiB）で定義された制限に達するとファイルの追加を停止します。」これに続くアドバイスは具体的です。「上限に達した場合は、制限を引き上げるか、ネストされたディレクトリに指示を分割してください。」
見て見ぬふりをするのではなく、この不整合を指摘しておく価値はあります。高度な設定ページでは、同じ設定を「各AGENTS.mdファイルから読み込む量」と説明しているのに対し、AGENTS.mdのページでは「結合されたサイズの停止ポイント」と説明しています。これらは同じルールではありません。32 KiBは実際に到達し得る天井として扱い、どちらの文章から推測するよりも、以下のダンプコマンドを使って結果を検証してください。そのために「Instructions truncated（指示が切り捨てられる）」というトラブルシューティング項目が存在するのです。
いずれにせよ、切り捨てはサイレントに行われ、チェーンの末尾（つまり、作業ディレクトリに最も近く、最も必要としている具体的なファイル）が切り捨てられます。
リストにないファイル名は存在しないものとされる
Codexは、AGENTS.override.md、AGENTS.md、およびproject_doc_fallback_filenamesにリストしたファイルを読み込みます。これは以下のように拡張できます。
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536これを設定すると、「Codexは各ディレクトリを次の順序でチェックします：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。」そして、重要な一文がこれです。「このリストにないファイル名は、指示の検出において無視されます。」
つまり、CONTRIBUTING.md、CLAUDE.md、.cursorrules、.github/copilot-instructions.mdなどはすべて、デフォルトでCodexからは見えません。複数のエージェントが使用されているレポジトリにおいて、これは最も一般的な問題のパターンです。指示は存在し、内容も優れているのに、Codexが最初から開くつもりのないファイルに書かれているのです。ツール間でファイル規格を移行する問題については、CLAUDE.mdからAGENTS.mdへの移行で解説しています。
チェーンは一度だけ構築されるため、セッション中の編集は反映されない
「Codexは起動時に指示チェーンを構築します（実行ごとに1回。TUIでは通常、起動されたセッションごとに1回を意味します）。」そして、検証ガイドにはこうあります。「指示が古く見える場合は、対象のディレクトリでCodexを再起動してください。Codexは実行ごと（および各TUIセッションの開始時）に指示チェーンを再構築するため、手動でクリアするキャッシュはありません。」
そのため、Codexがルールを無視していることに気づき、より強調してルールを追加し、再度質問するという自然なデバッグ手順は、同じセッション内では機能しません。すでに読み込まれたファイルを編集しているからです。再起動が解決策であり、それを知ってしまえば簡単なことです。
空のファイル、および設定したことを忘れているCODEX_HOME
トラブルシューティングリストから、手短に2つ紹介します。「Codexは空のファイルを無視します」— ツールによって作成され、中身が空のままのプレースホルダーAGENTS.mdであっても、そのディレクトリの唯一のスロットを占有してしまいます。そして、「プロファイルの混乱： Codexを起動する前にecho $CODEX_HOMEを実行してください。デフォルト以外の値が設定されている場合、Codexはあなたが編集したものとは異なるホームディレクトリを参照します。」ラッパースクリプトやプロジェクト固有の自動化プロファイルがこれを設定している場合、グローバルファイルはあなたが思っている場所にはありません。」
よく試される対策
より強い言葉でルールを書き直す。 気持ちは分かりますが、ファイルが読み込まれていなければ意味がありません。表現を気にする前に、まず読み込まれているかを確認しましょう。
すべてを1つの巨大なルートAGENTS.mdにまとめる。 これにより「ディレクトリごとに1ファイル」のルールは回避できますが、32 KiBの上限に直面することになります。ドキュメントでは逆のアプローチ、つまりネストされたディレクトリへの分割を推奨しています。
実行するたびにプロンプトで制約を繰り返す。 恒久的に機能はしますが、毎回同じコストがかかります。これはAIにコンテキストを何度も説明するのをやめる方法で説明されているループと同じです。
オーバーライドファイルを見つけ次第削除する。 正しい場合もありますが、意図的に設定されたルールを削除してしまうこともあります。まずは中身を確認してください。
指示を「強制力のあるルール」だと仮定する。 指示は最初のターンに含まれるガイダンスに過ぎません。常に遵守されるべきルールについては、CIチェックこそが保証となります。これはなぜエージェントはあなたが書いた指示ファイルを無視するのかで述べられている一般的な指摘です。
CLAUDE.mdからAGENTS.mdへのシンボリックリンクを作成して祈る。 project_doc_fallback_filenamesにファイル名を追加するのがドキュメントに記載された正しい方法であり、わずか1行で済みます。
解決策：Codexに読み込んだ内容を尋ね、フラット化する
2つのコマンドとクリーンアップ。まずは推測するのをやめましょう。
レポジトリのルートからチェーンをダンプする。 ドキュメントに記載されている確認方法です：
codex --ask-for-approval never "Summarize the current instructions."「Codexは、グローバルファイルとプロジェクトファイルからのガイダンスを優先順位に従ってエコーバックするはずです。」もしあなたが書いたルールが要約に含まれていない場合、問題はルールの遵守ではなく「検出」にあります。これで、プロンプトエンジニアリングに午後を丸々費やす手間が省けました。
実際に作業しているディレクトリから再度ダンプする。 チェーンは開始する場所によって異なるためです：
codex --cd services/payments --ask-for-approval never "Show which instruction files are active."ドキュメントによると、期待される出力は「最初にグローバルファイル、次にレポジトリルートのAGENTS.md、最後にpaymentsのオーバーライド」となります。これが、読み込まれるべきだとあなたが考えている内容と一致しているか比較してください。そのギャップこそがバグの原因です。
文章ではなく記録として残したい場合は、ログを取得します。 「Codexがどの指示ファイルを読み込んだかを監査するには、codex -c log_dir=./.codex-logを使用してプレーンテキストのTUIログを有効にし、./.codex-log/codex-tui.logを確認するか、セッションログを有効にしている場合は最新のsession-*.jsonlファイルを検査してください。」また、ワークスペースも確認してください。「意図したレポジトリにいること、およびcodex statusが期待するワークスペースルートを報告していることを確認してください。」
その後、次の順序でクリーンアップを行います。 レポジトリ内および~/.codex内のすべてのAGENTS.override.mdを見つけ、その抑制が意図的なものかどうかを判断し、意図的でないものはマージして削除します。他のエージェントの指示ファイル名をproject_doc_fallback_filenamesに追加して、不可視状態を解消します。32 KiBに近いものは、制限を引き上げて忘れてしまうのではなく、ネストされたディレクトリに分割します。空の指示ファイルを削除して、スロットを占有しないようにします。そして、echo $CODEX_HOMEを確認します。
これで指示が読み込まれるようになります。しかし、これでは解決できない問題があります。それは、チェーンに意図的に上限が設けられていることです。検出が正しく行われるようになると、作業するすべてのディレクトリで32 KiBの予算をやりくりすることになります。そして、最初に削られるのは常に同じカテゴリの情報です。なぜその制約が存在するのか、以前に何を試したのか、どの手法がどのような理由で却下されたのか、といった情報です。ルールは残りますが、その「背景にある推論（Reasoning）」は残りません。
それこそがMemoryLakeの役割です。プロジェクトの永続的な知識をツールが読み取るレイヤーに保持することで、指示ファイルを小さく保ちながら、推論を利用可能な状態に維持します。セットアップは3つのステップで完了します。
ステップ 1: APIキーの作成
MemoryLakeにサインインし、APIキーを作成します。接続するすべてのツールで共通の認証情報として使用できます。
ステップ 2: 最初の記憶（Memory）をアップロードする
1つの項目につき1つの主張を含む、短いエントリを作成します。指示チェーンの内部ではなく、外部に置くべき情報です：
理由が紐付けられた制約。 「npmスクリプトがサンドボックスのスタブを起動しないため、Paymentsはmake test-paymentsを使用する。」AGENTS.mdにはコマンドのみが記載されます。理由が添えられていなければ、誰かがそれを不要なものとして削除してしまうのを防ぐことはできません。
このコードベースで既に却下されたアプローチ。 指示ファイルのどこにも収まらず、新規実行のたびに提案されてしまうカテゴリの情報です。
どこにも明記されていない環境に関する事実。 ドキュメント化されていないレート制限、CIでのみ失敗するテスト、2つのマイグレーション間の順序要件などです。
インシデントからの決定事項。 そもそもなぜオーバーライドが存在していたのかという理由。これにより、次の担当者はそれが意図的な抑制なのか、単なる消し忘れなのかを判断できます。
ステップ 3: AIとエージェントを接続する
使用しているツールを接続します。MemoryLakeはMCPおよびAPI経由でアクセス可能です。そのため、Claude Code、Codex、OpenClawなどのMCPネイティブなエージェントはMCPサーバーを指定することで接続でき、その他のアシスタントはAPIを介して同じ記憶を読み取ることができます。実質的な効果として、取得された情報は最初のターンで送信されないため、指示の容量制限（バジェット）を消費しません。
ここで、3つの率直な制限事項を挙げます。MemoryLakeはあなたのAGENTS.mdファイルを書き換えることはありませんし、Codexがそれらを検出する方法を変更することもありません。 上記の6つのメカニズムはCodexのものであり、修正はすべてあなた自身で行う必要があります。また、MemoryLakeはあなたやエージェントが保存した内容のみを保持するため、ステップ2は手動で行う必要があります。さらに、指示は強制力のある設定ではなくあくまでガイダンスです。記憶レイヤーがコンプライアンスを強制するわけではないため、厳格な要件については引き続きCIが解決策となります。
実務における変化
「ルールが無視された」という問題が、1つのコマンドで解決する問いになります。 Codexに現在の指示を要約するよう求めてください。ルールがリストにあるかないかで、対処法は完全に異なります。
オーバーライドファイルが地雷ではなくなります。 一度フラット化してしまえば、後になって「隠されていたファイル」が見つかって混乱することはありません。
指示ファイルが小さくなります。 2つの役割を同時にこなそうとしていたために、チェーンは32 KiBの上限に近づいていました。これらを分離すれば、上限は制約ではなくなります。
他のエージェント用のファイルがデッドウェイト（無駄な荷物）にならなくなります。 config.tomlに1行追加するだけで、チームがすでに管理しているCLAUDE.mdやTEAM_GUIDE.mdが機能し始めます。
再起動が反射的な動作になります。 チェーンは実行ごとに1回構築されます。それを知っておくだけで、混乱を招くセッションがわずか5秒で解決するようになります。
Codexが実際に読み込むAGENTS.mdのベストプラクティス
編集する前に必ずチェーンをダンプする。 ルートおよび作業ディレクトリから、Codexに現在の指示を要約するよう求めてください。
恒久的なAGENTS.override.mdを放置しない。 これは隣にあるファイルを抑制してしまいます。ドキュメントでも一時的なものとして位置づけられています。
ルールを適用したいディレクトリから起動する。 チェーンは作業ディレクトリで停止します。それより深い階層のファイルは読み込まれません。
上限に近づいたら、単に引き上げるのではなく分割する。 ネストされたディレクトリへの分割は、project_doc_max_bytesに達した際のドキュメントに記載された解決策です。
他のすべてのエージェントの指示ファイル名をproject_doc_fallback_filenamesにリストする。 リストにないファイル名は、指示の検出において無視されます。
空の指示ファイルを削除する。 空のファイルはスキップされますが、それでもディレクトリの唯一のスロットを占有してしまいます。
編集後は再起動する。 指示チェーンは実行ごとに1回構築されるため、セッション中の編集は適用されません。
グローバルファイルの効果がないように見える場合は、echo $CODEX_HOMEを確認する。 デフォルト以外の値が設定されている場合、編集した場所とは異なるホームディレクトリを指しています。
推論（Reasoning）をチェーンに含めない。 指示には上限があり、常に有効です。ルールの背景にある議論こそが、明文化されていないケースにエージェントが対処できるようにするためのものです。これはなぜRAGは記憶ではないのかで述べられている一般的な問題です。
結論
Codexは指示の検出方法について非常に明示的であるため、これは謎のトラブルではなく、解決可能な問題です。Codexはディレクトリごとに最大1つのファイルを読み込み、AGENTS.override.mdがAGENTS.mdよりも優先されます。プロジェクトのルートから作業ディレクトリまで下り、そこで停止します。ルートから順に結合し、結合されたサイズがproject_doc_max_bytes（デフォルトは32 KiB）に達すると追加を停止します。検出リストにないファイル名や空のファイルは無視され、チェーン全体は実行ごとに1回だけ構築されます。
これら6つのメカニズムはすべてサイレントに動作しますが、Codexに読み込んだ指示を要約するよう求めることで、約10秒ですべて可視化できます。ルートおよび実際に作業しているディレクトリから要約を実行し、一時的であるべきオーバーライドをフラット化し、他のエージェントのファイル名をフォールバックリストに追加し、上限に近づいた場合はサイズを増やすのではなく分割してください。
そして、制約、インシデント、却下されたアプローチなどは、最初のターンで送信するレイヤーではなく、必要に応じてクエリできるレイヤーに配置してください。これにより、指示チェーンは完全に読み込めるほど小さく保たれ、重要な場面で推論を確実に利用できるようになります。