AGENTS.override.md があると、同じ階層の AGENTS.md は読まれない

AGENTS.md と AGENTS.override.md を使っていて、しばらく勘違いしていたことがあったのでまとめます。

きっかけ#

Codex を使っていて、どうも AGENTS.md に書いている指示を見ていない気がすることがありました。

Codex に確認してみたところ、同じ階層に AGENTS.override.md がある場合は AGENTS.md を読み込んでいないと教えてくれました。公式ドキュメントでも同じ仕様を確認できます。

それまで AGENTS.md にルールを追加していたので、「今まで追加していたルール、適用されてなかったのか……」となりました。

結論#

同じディレクトリに AGENTS.override.md がある場合、Codex はその階層の AGENTS.md を自動では読み込みません。

Codex はディレクトリごとに、次の順で指示ファイルを探します。

1. AGENTS.override.md
2. AGENTS.md
3. 設定したフォールバックファイル

見つかった最初の空でない1ファイルだけが取り込まれるため、同じ階層にある AGENTS.override.md と AGENTS.md が自動でマージされることはありません。

自分は override という名前から、AGENTS.md を読み込んだうえで個人用の指示を追加・上書きしてくれるものだと思っていました。完全に「追加で上書きしてくれるもの」だと思っていました。

起こること#

たとえば、次のようにリポジトリ共通のルールを AGENTS.md に書き、個人用のルールを AGENTS.override.md に書いたとします。

AGENTS.md
AGENTS.override.md

この場合、Codex がその階層から読み込むのは AGENTS.override.md です。

そのため、AGENTS.md に書いた共通ルールは、そのままでは適用されません。

同じ階層に置きたい場合の回避策#

どうしても同じ階層に AGENTS.md と AGENTS.override.md を置きたい場合は、AGENTS.override.md から Codex 自身に AGENTS.md を読むよう指示する方法があります。

# 個人ルール

- 作業を始める前に、同じディレクトリの `AGENTS.md` を全文読む。
- 指示が矛盾する場合は、このファイルを優先する。

ただし、これは2つのファイルが自動でマージされるわけではありません。あくまで AGENTS.override.md から Codex に AGENTS.md を読ませるための運用上の回避策です。

自分はリポジトリ全体に共通ルールと個人ルールの両方を適用したかったので、この方法にしました。

ディレクトリ固有のルールとして使う場合#

個人用ではなく、特定のディレクトリだけに追加のルールを適用したい場合は、個別ルールが必要なサブディレクトリに AGENTS.override.md を配置できます。

AGENTS.md
services/
  payments/
    AGENTS.override.md

この場合、作業ディレクトリを services/payments/ にして開始すると、Codex はリポジトリ直下の AGENTS.md を読んだあと、services/payments/ の AGENTS.override.md も読み込みます。

Codex はプロジェクトルートから現在の作業ディレクトリまで各階層の指示を順番に取り込むので、ディレクトリ固有のルールを追加したい場合は、この仕組みを使えます。

補足#

AGENTS.override.md があると、親ディレクトリの AGENTS.md まで無視されるわけではありません。

今回のポイントは、あくまで同じ階層では AGENTS.override.md が優先されるということです。

余談#

今回の話とは直接関係ありませんが、Codex がプロジェクト指示として取り込めるサイズには上限があり、デフォルトでは 32 KiB です。

AGENTS.md にルールを追加し続けている場合は、この制限にも注意が必要です。

参考#

• Custom instructions with AGENTS.md（OpenAI Docs）
• Unrolling the Codex agent loop（OpenAI）