AGENTS.mdをフォルダごとに置く：共通ルールと例外の分け方と、効いている指示の確かめ方

Codexに作業を頼むたびに「元のファイルは書き換えない」「出典を残す」と書き直しているなら、その決まりごとはAGENTS.mdに書いておけます。困るのは、フォルダごとに例外を置き始めてからです。部門のフォルダにAGENTS.override.mdを置いたら親のルールまで消えるのか、ルールを直したのに効かないとき、どのファイルが今効いているのか。ここが分からないと、例外を足すたびに共通ルールを落とす心配がつきまといます。

公式の説明と同じ3ファイル構成のフォルダでCodex CLIを起動し、「この作業に適用される指示」を2回尋ねました（2026年10月20日）。Codexに渡されていた指示は公式の説明どおり、親のAGENTS.mdと子のAGENTS.override.mdでした。ところがCodexの答えは、実際に効いていたoverrideのファイル名を一度も挙げず、読み込まれていない同じ階層のAGENTS.mdをシェルで開いて、その中身を答えに載せていました。

そこでこの記事では、共通ルールをルートに、例外を子フォルダに置く分け方と、効いているファイルをCodexの答えではなく、ファイルの一覧とセッションの記録で確かめる手順をまとめます。読み終えたら、自分のプロジェクトでAGENTS.mdの置き場所を決め、直したルールが本当に効いているかを確かめられます。

置き場所の決まり：同じ階層では1つ、階層をまたぐと重なる

公式の説明によると、Codexは指示ファイルを、グローバル設定のあとにプロジェクトのルートから起動した場所（作業ディレクトリ）へ向かって順に探します。各階層ではAGENTS.override.md、AGENTS.md、設定したフォールバック名の順に見て、最初に見つかった空でないファイルを1つだけ選びます。選ばれたファイルは親から子の順につなげられ、内容がぶつかる場合は起動した場所に近い子のファイルが優先されます。

この2つの決まりから、置き方は次のように決められます。

overrideが外すのは、同じ階層のAGENTS.mdだけです。親のAGENTS.mdはそのまま残り、上の表の共通ルールは子フォルダの作業でも効き続けます。その代わり、同じ階層のAGENTS.mdは丸ごと読まれなくなるので、overrideを置いたままAGENTS.mdを直しても、直した内容は効きません。

もう1つ、探すのは起動した場所までです。ルートでCodexを起動して子フォルダのファイルを直す場合、子のAGENTS.mdは探索の道筋に入りません。子の手順を確実に使わせたいなら、子フォルダで起動するか、ルートの指示から子のファイルを読むように書いておきます。

このサイトの制作フォルダでの置き方

このサイトの記事も、AIを使った制作フォルダで作っています。そこではAGENTS.mdを次のように置いています。

• ルートに、CodexとClaude Codeに共通の指示を1つ（40行ほど）。結論と根拠の伝え方、許可された作業を最後まで仕上げること、認証情報を読まないこと、WordPressへの接続や公開は依頼された範囲だけ行うこと、などです。

• 記事の制作、運用スクリプト、事業の検討の3つの子フォルダに、それぞれの作業の入口になるAGENTS.md（15〜19行）。

• AGENTS.override.mdは置いていません。

ルートの指示には「子の指示が自動で読まれる前提にせず、作業の前に該当する入口だけを読む」と書き、子フォルダのファイルへのリンクを作業の種類ごとに並べています。上で書いた「探すのは起動した場所まで」に左右されないようにするためです。Claude Code用のCLAUDE.mdには、ルートのAGENTS.mdを読み込む1行を書き、同じルールを2か所に持たないようにしています。

Codexに「適用される指示」を尋ねた結果

効き方を確かめるため、公式の説明どおりならoverrideが効く構成を、Gitで管理する空のフォルダに作りました。

repo/AGENTS.md
  共通ルール：出力はMarkdown。出典を必ず残す。
repo/dept/AGENTS.md
  部門ルール：出力はHTML。
repo/dept/AGENTS.override.md
  部門特例：出力はCSV。

repo/deptでCodex CLI（0.163.0）を非対話モードのcodex execで起動し、「この作業に適用される指示を全部挙げ、出力形式と出典の扱いを答えて」と1回依頼しました。続けてdept/AGENTS.mdだけを「部門ルール：出力はJSON。」に書き換え、新しいセッションで同じ依頼をもう1回送りました。

Codex CLIは、セッションごとの記録をホームフォルダの.codex/sessions/に保存します。そこに残っていた、Codexへ実際に渡された指示のうちプロジェクトの部分は、2回とも次のとおりでした（全体向けのグローバル設定の部分は省いています）。

--- project-doc ---

共通ルール：出力はMarkdown。出典を必ず残す。


部門特例：出力はCSV。

親の共通ルールと子のoverrideの2つで、dept/AGENTS.md（HTML、2回目はJSON）は入っていません。公式の説明どおりです。そして、指示はファイル名を付けずにつなげて渡されていました。

一方、Codexの答えはCSVの表でした。出力形式と出典に関わる行だけを抜き出します（表現は変えていません。ほかの行は、私が普段使っているグローバル設定の内容でした）。1回目の答えです。

出力形式,実ファイルの部門ルールではHTML
出力形式,今回提示された部門特例ではCSV,ユーザー提示のAGENTS.md instructions,最終出力はCSV

2回目の答えです。どちらも、部門ファイルについて述べた行は先頭から内容の部分までを抜粋しています。

部門ファイルの実測,出力はJSONという指定がある。
直接指定,今回ユーザーが提示した部門特例は出力をCSVとしている。,ユーザー提示のproject-doc

結論の「出力はCSV、出典は残す」は2回とも合っていました。ずれていたのは、その根拠に挙げたファイルです。Codexは答える前にシェルで親フォルダからAGENTS.mdという名前のファイルだけを探して開き、読み込まれていないdept/AGENTS.mdの中身を答えに載せました。効いていたAGENTS.override.mdは探しておらず、CSVの出所は「ユーザー提示」と書いています。指示がファイル名なしで渡されているので、Codexにはどのファイルから来た指示かが見えていなかったと考えられます。

読者の場面に置き換えると、ここが落とし穴になります。overrideの置き忘れに気づかないままAGENTS.mdを直し、Codexに「どのルールが効いている？」と尋ねると、2回目のように直した内容が「実測」として答えに出ます。直したルールが読み込まれたように見えますが、実際にCodexが従うのはoverrideのほうです。

効いているファイルを確かめる手順

Codexの答えとは別に、次の2つで確かめます。今回の観測はCodex CLI 0.163.0での1構成・各1回で、セッションの記録の形式は版によって変わる可能性があります。

1. 起動する場所から上へ、各階層のファイルを一覧する。 Codexを起動するフォルダで次を実行すると、ルートまでの各階層で選ばれるはずのファイルが、起動する場所から順に表示されます。同じ階層に両方あれば、表示されるのはoverrideです。Gitリポジトリ外では、現在のフォルダだけを確認して終了します。

d=$(pwd -P)
root=$(git rev-parse --show-toplevel 2>/dev/null) || root="$d"
while :; do
  for name in AGENTS.override.md AGENTS.md; do
    if [ -s "$d/$name" ]; then echo "$d/$name"; break; fi
  done
  [ "$d" = "$root" ] || [ "$d" = / ] && break
  d=$(dirname "$d")
done

記事と同じ構成のrepo/deptの下で動かすと、repo/dept/AGENTS.override.mdとrepo/AGENTS.mdが表示されます。フォールバック名を設定している場合は、forの行にその名前を足します。

2. Codexを動かしたあと、セッションの記録で渡された指示を見る。 次のPythonは、いちばん新しいセッションの記録から、プロジェクトの指示として渡された部分だけを表示します。

import glob
import json
import os
import sys

files = sys.argv[1:] or sorted(
    glob.glob(os.path.expanduser("~/.codex/sessions/**/*.jsonl"), recursive=True),
    key=os.path.getmtime,
)[-1:]
for path in files:
    for line in open(path, encoding="utf-8"):
        payload = json.loads(line).get("payload") or {}
        for part in payload.get("content") or []:
            text = part.get("text", "") if isinstance(part, dict) else ""
            if "--- project-doc ---" in text:
                start = text.find("--- project-doc ---")
                end = text.find("</INSTRUCTIONS>", start)
                print(path)
                print(text[start:end if end >= 0 else None].strip())
                sys.exit(0)
print("プロジェクトの指示が見つかりませんでした")

表示された指示の各段落が、1で一覧したファイルのどれの中身かを照らし合わせます。直したはずのルールがここになければ、同じ階層にoverrideが残っていないかを1の一覧で見ます。overrideを置くときは、置いた理由と外す予定を中に1行書いておくと、置き忘れたときに気づけます。

AGENTS.mdに書いておきたいルールの例

# プロジェクト作業ルール
- 元資料は改変せず、成果物は output/ ディレクトリへ出力する。
- 入力データにない数値、期限、担当者を推測で補わない。
- 抽出した事実やデータには、出典や元ファイルの位置を書く。
- データ変換時は入力件数、出力件数、除外件数を報告する。
- ファイルの外部送信や本番公開は、今回の指示に明示されている場合のみ行う。

こうした「このプロジェクトではいつもこうする」という決まりごとをAGENTS.mdに書き、対象のファイル名や今回の作業、締め切りといった個別の指示は、その都度の依頼文で渡します。AGENTS.mdに古い個別の指示が残り続けることも防げます。

AGENTS.mdはCodexへの指示で、書き込みを技術的に止める仕組みではありません。大事なファイルへの書き込みを防ぎたい場合は、サンドボックスや承認の設定と組み合わせます。

参考にした公式情報

• Custom instructions with AGENTS.md：探索順と上限（2026年10月9日確認）

• Agent approvals & security：技術的な制限（2026年10月9日確認）