はじめに

OpenAI が公開している Codex CLI は、ローカルリポジトリを「ワークスペース」として AI エージェント的に動かせるツールです。
その挙動を制御する仕組みが AGENTS.md。リポジトリ直下やサブディレクトリに置くことで、開発方針や禁止事項を「エージェントの行動ガイドライン」として読み込ませることができます。

しかし実際には「どこまで自動で読まれるのか？」「階層が複数あるときの優先順位は？」といった疑問がありました。そこで Codex CLI 0.31.0 を使って検証した結果をまとめます。

検証環境

Ubuntu（WSL2上）
Codex CLI: 0.31.0

~/.codex/config.toml にプロファイルを設定

[profiles.build]
sandbox_mode = "workspace-write"

[projects."/home/devuser/work/CodeX/TEST/A"]
trust_level = "trusted"

ディレクトリ構成と AGENTS.md の内容

TEST/
└─ A/               ← リポジトリルート
   ├─ AGENTS.md     (POLICY_TOKEN=ROOT, FORBID=全域禁止)
   ├─ B/
   │   ├─ AGENTS.md (POLICY_TOKEN=B-OVERRIDE, 禁止解除)
   │   └─ C/
   │       ├─ AGENTS.md (POLICY_TOKEN=C-OVERRIDE, C直下のみ禁止)
   │       └─ D/   (AGENTS.mdなし)
   └─ Makefile

各ファイルの差分ルールは以下のように設定しました。

A (root): 全域で FORBIDDEN.txt 作成禁止
B: Rootの禁止を上書きして許可
C: C直下のみ再び禁止
D: Cの配下。Cのルールを継承するか確認

実行ログ（抜粋）

Bディレクトリで `report-scope` 実行

$ codex --profile build "report-scope"
> Effective POLICY_TOKEN: B-OVERRIDE
> Wrote .codex_scope.txt with B-OVERRIDE

Bディレクトリで `try-forbidden` 実行

$ codex --profile build "try-forbidden"
> Created FORBIDDEN.txt in B because B/AGENTS.md overrides the root forbid

→ 禁止が解除され、FORBIDDEN.txt が作成された。

Cディレクトリで `report-scope`

$ codex --profile build "report-scope"
> Effective POLICY_TOKEN: C-OVERRIDE
> Wrote .codex_scope.txt with C-OVERRIDE

Cディレクトリで `try-forbidden`

$ codex --profile build "try-forbidden"
> I must refuse: creating FORBIDDEN.txt in this C folder is prohibited

→ C直下では禁止が再適用され、ファイルは作られなかった。

Dディレクトリで `report-scope`

$ codex --profile build "report-scope"
> Effective POLICY_TOKEN: C-OVERRIDE

Dディレクトリで `try-forbidden`

初回は「/etc への書き込み」など別の禁止アクションを代替しようとする挙動が見られたが、これは AGENTS.md のタスク定義が曖昧だったため。
修正すれば期待通り「Dでは許可（FORBIDDEN.txt 作成される）」挙動になる見込み。

得られた知見

AGENTS.md は自動的に検出・読み込まれる
report-scope の実行で、repo root → 親ディレクトリ → 現在ディレクトリ の順に走査され、最も近いものが優先される。
禁止ルールも階層で上書き可能
Rootで全域禁止 → Bで解除 → Cで再禁止、という流れが期待通りに動作した。
ただし完全に暗黙適用はされない
実際の行動に反映させるには「report-scope」「try-forbidden」などのタスクを明示的に指示する必要がある。
曖昧なタスク定義は別動作に置き換えられる
今回 try-forbidden を曖昧に書いていたら Codex が「ネットワーク操作」や「/etc 書き込み」を代替として選んだ。→ AGENTS.md の指示は具体的に書く必要がある。
初回承認ダイアログ
サブディレクトリ（B/C/D）は「非バージョン管理ディレクトリ」と判定され、初回のみ承認を求められた。
- git init でルートをGit管理にすると軽減
- ~/.codex/config.toml に [projects."..."] trust_level="trusted" を追加すると抑制可能

まとめ

Codex CLI 0.31 は AGENTS.md を階層的に解釈し、近いディレクトリのルールが優先されることが確認できた。
ただし「暗黙に従う」わけではなく、起動時にタスクを明示的に指示するのが実用的。
タスクの定義は 曖昧にせず具体的に書くことで、予期しない代替動作を防げる。
承認ダイアログを抑えたい場合は、Git管理＋trust_level設定が有効。

PoC では「動くかどうか」が重要でしたが、商用で使う場合はガードレールをより厳密に記述する必要があります。
今後のリリースで暗黙適用が安定すれば、さらに自走度が高まりそうです。

補足

この記事は検証の記録です。挙動は今後のバージョンで変わる可能性があります。
Codex CLI 自体はまだ開発途上なので、Issue/Releaseノートを追いながら使うのがおすすめです。