はじめに
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ノートを追いながら使うのがおすすめです。