Codexへ作業を頼むたびに、「このコマンドでテストする」「このディレクトリは変更しない」「最後に変更点を報告する」と書き直していないでしょうか。毎回同じルールを依頼文へ足すと、本当に今回だけ必要な作業内容が埋もれやすくなります。一方、すべてを1つの長い設定へ詰め込むと、どのディレクトリに何が適用されるのか分かりにくくなります。
AGENTS.md には、何度も使う短い作業ルールを置けます。ルートにはプロジェクト共通のルール、下位ディレクトリにはその範囲だけの差分を置き、実際にCodexへ渡った内容を確認するのが基本です。この記事では、記事専用の架空リポジトリを使い、ルート、下位、AGENTS.override.md、fallback名、サイズ上限の読込結果を確認します。
検証条件：2026年9月29日、Linux 4.18.0 x86_64、codex-cli 0.157.1。記事専用fixtureと隔離した一時 CODEX_HOME を使い、codex debug prompt-input の完全なJSON出力で確認しました。モデル応答は検証対象ではないため、API認証や入れ子の codex exec は使っていません。掲載した確認スクリプトはfixture内で直接実行しています。
AGENTS.mdと通常の依頼文を分ける
AGENTS.md に向くのは、作業のたびに変わりにくいルールです。その回だけの目的や対象ファイル、受入条件は通常の依頼文へ残します。
| 置き場所 | 向いている内容 |
|---|---|
AGENTS.md |
セットアップ、対象範囲、禁止事項、確認コマンド、完了報告 |
| 通常の依頼文 | 今回の目的、変更する機能、対象ファイル、今回だけの受入条件 |
| Codexの権限設定 | ファイルシステム、ネットワーク、承認などの実行境界 |
特に3行目は重要です。AGENTS.md の「ネットワークへ接続しない」はモデルへの指示であり、OSやサンドボックスによる強制的な遮断ではありません。実行を制限したい場合は、別途、権限や承認の設定を使います。
探索順はグローバルから現在地まで
OpenAI公式資料では、Codexは起動時に次の順序で指示を探します。
CODEX_HOME（未指定なら通常は~/.codex）のグローバル指示- プロジェクトルートの指示
- ルートから現在の作業ディレクトリまでにある下位の指示
各ディレクトリでは、AGENTS.override.md、AGENTS.md、設定したfallback名の順に探し、最初に見つかった空でない1ファイルを使います。複数階層の内容はルート側から下位側へ連結されるため、競合するルールは現在地に近い側が後に置かれます。探索は現在の作業ディレクトリで止まるので、別の下位ディレクトリにある指示までは読みません。
|
1 2 3 4 5 6 7 |
グローバルの指示 ↓ example-project/AGENTS.md ↓ example-project/app/AGENTS.md ↓ 今回の依頼文 |
公式資料が示す既定の合計上限は32 KiBです。設定キーは project_doc_max_bytes で、fallback名は project_doc_fallback_filenames に並べます。値はCodex CLIの更新で変わる可能性があるため、利用中の版と公式資料を一緒に確認してください。
最小テンプレートは5区分に絞る
記事用fixtureのルートでは、次のように短いテンプレートを使いました。コマンドは外部接続や本番変更を行わず、固定文字列を出すだけです。
|
1 2 3 4 5 6 7 8 |
# Root project rules - Scope: all files in this example project. - Setup: no installation is required. - Do not: access the network or files outside this fixture. - Test: run `sh scripts/check-root.sh`. - Completion: report the command and its exit status. - Output marker: `ROOT_RULE_ACTIVE`. |
「必ず安全にする」のような抽象的な表現ではなく、対象範囲と確認コマンドを具体的にします。ただし、この禁止事項も強制的な権限境界ではありません。
同じ入力で4つの読込ケースを比べる
架空リポジトリは次の構成です。.git/ はプロジェクトルートを示す空のマーカーとして用意し、業務用リポジトリは使っていません。
|
1 2 3 4 5 6 7 8 9 10 11 |
example-project/ ├── AGENTS.md ├── scripts/check-root.sh ├── app/ │ ├── AGENTS.md │ ├── AGENTS.override.md │ ├── check-app.sh │ └── check-override.sh └── fallback/ ├── PROJECT_RULES.md └── check-fallback.sh |
各ケースで現在地だけを変え、同じ確認文を渡しました。
|
1 2 3 |
CODEX_HOME=/path/to/isolated-codex \ codex debug prompt-input \ "List the instruction markers that apply here. Do not perform any task." |
| 現在地・条件 | 完全出力内の指示 | 終了状態 |
|---|---|---|
| リポジトリルート | ROOT_RULE_ACTIVE |
0 |
app/、overrideを一時的に外す |
ROOT_RULE_ACTIVE → APP_RULE_ACTIVE |
0 |
app/、overrideあり |
ROOT_RULE_ACTIVE → OVERRIDE_RULE_ACTIVE。同じ階層の通常版は入らない |
0 |
fallback/ |
ROOT_RULE_ACTIVE → FALLBACK_RULE_ACTIVE |
0 |
この版の prompt-input では、採用されたプロジェクト指示がルート側から下位側の順で、1つの <INSTRUCTIONS> ブロックへ連結されていました。期待したマーカーだけを見るのではなく、ファイル全文と順序、現在地、終了状態まで対応づけています。
fallbackケースでは、隔離した設定を次のようにしました。fallback名は標準で決め打ちされているのではなく、自分で追加する名前です。
|
1 2 |
project_doc_fallback_filenames = ["PROJECT_RULES.md"] project_doc_max_bytes = 1024 |
グローバル指示も隔離した CODEX_HOME で追加確認し、GLOBAL_RULE_ACTIVE の後にルートの ROOT_RULE_ACTIVE が入ることを確認しました。実際のホームディレクトリや認証ファイルは読み取っていません。
サイズ上限では後ろ側が途中で切れる
上限の挙動を見やすくするため、project_doc_max_bytes=350 をコマンドラインで指定しました。ルートの指示に続く下位ファイルは、SIZE_RULE_BEGIN と途中の文字列までは入りましたが、末尾の SIZE_RULE_END は入りませんでした。コマンド自体の終了状態は0です。
さらに設定を置かない隔離 CODEX_HOME で、合計40,332バイトのルート・下位指示を用意しました。CLIが取り込んだ指示本文は32,768バイトで切れ、末尾マーカーは入りませんでした。これは公式資料の「既定32 KiB」と一致します。長いファイルはエラーで止まるとは限らないため、重要な停止条件を末尾へ詰め込まず、内容を短くするか対象別の下位ファイルへ分けます。
WordPressとPythonでは差分だけを足す
ここからは展開前のチェックリストです。記事専用のWordPress／Pythonプロジェクトでの読込実行は行っていないため、「確認できた」とはしていません。
WordPress向けに足す項目
- 変更対象を架空の子テーマなど、明示した範囲へ限定する
- 本番へ直接変更しないことと、復元条件を明記する
- 保存後の表示・機能確認を完了条件へ入れる
- バックアップや表示確認が用意できなければ停止する
WordPress改修前のバックアップや復元手順は、別記事のCodexでWordPressを改修する前の安全確認チェックリストで扱っています。本記事では手順を重ねず、AGENTS.md に何を差分として書くかだけに絞ります。
Python向けに足す項目
- 使用する仮想環境と依存関係ファイルを指定する
- 変更した範囲に対応するテストコマンドを指定する
- 秘密情報をコード、fixture、テスト出力へ含めない
- 依存関係の追加や外部接続が必要なら、実行前に停止条件を確認する
共通テンプレートを複製して長くするのではなく、対象ディレクトリの下位ファイルへ差分だけを追加します。
読み込まれないときの確認順
- Codex CLIの正確な版と、現在の作業ディレクトリを記録する
- 想定したプロジェクトルートから現在地まで、ファイル名と空ファイルを確認する
- 同じ階層や上位に
AGENTS.override.mdが残っていないか確認する - fallback名の綴りと
project_doc_fallback_filenamesを確認する project_doc_max_bytesに達し、後半が切れていないか確認する- 新しいセッションで
codex debug prompt-inputの完全な出力を確認する
期待と違う場合は、成功例へ整形せず、現在地、採用ファイル、順序、切り詰め位置をそのまま記録します。CLI更新時にも同じfixtureを使って再確認すると、古い指示や不要になった回避策を整理しやすくなります。
まとめ
AGENTS.md は、全作業に共通する短いルールをルートへ、対象限定の差分を下位へ置くと整理しやすくなります。通常の依頼文には今回だけの目的と受入条件を残し、権限制御は別の設定で行います。配置しただけで反映を決めつけず、隔離した小さなfixtureで、現在地、入力、採用ファイル、完全な prompt-input、終了状態を対応づけて確認してください。
公式資料・CLI確認日：2026年9月29日。参照：OpenAI「Custom instructions with AGENTS.md」、OpenAI「Configuration Reference」、OpenAI「Model guidance」、OpenAI「Rethinking skills and prompts for GPT-6 Astra」。探索仕様や設定値は変更される可能性があるため、利用時と公開直前に公式資料と採用CLI版を再確認してください。
