AGENTS.mdが読まれない条件｜CLAUDE.mdと初回セッション

「AIに前提を伝えるファイルを置いたのに、指示どおりに動いてくれない」。そんなもやもやを抱えていませんか。

この記事では、AIエージェント共通の指示ファイル「AGENTS.md」が読まれる条件と、読まれていないときの見分け方を整理します。読み終わるころには、指示が効かないときに何から確認すればよいかが分かります。

結論を先に言うと、原因は書き方より先に「そもそも読まれていない」ことが多いです。文章を強くする前に、読まれたかどうかを確かめる手順を持ちましょう。

AGENTS.mdとは?AIエージェントに渡す共通の手順書

AGENTS.mdは、AIコーディングツールに「このプロジェクトでの仕事の進め方」を伝えるテキストファイルです。置き場所はリポジトリの中で、中身はふつうのマークダウンです。

なぜ共通の名前なのかというと、ツールごとに設定ファイルの名前がばらばらだと、乗りかえるたびに書き直しになるからです。Claude CodeもCodexも同じ名前を見にいく流れができつつあります。

身近なたとえで言えば、現場の手順書に近い存在です。新人が来るたびに口頭で説明する代わりに、机の上に手順書を置いておく。あの発想をAI向けにやったものだと考えると分かりやすいです。

書く中身としては、次のようなものが定番です。

• リポジトリの構成と、動かすための手順
• ビルド・テスト・lintの走らせ方
• 開発の決まりごとと、やってはいけないこと
• どうなったら完了なのか、その確かめ方

つまりAGENTS.mdは、毎回説明していた前提を1か所にまとめる置き場所です。ただし、置いたからといって必ず読まれるとはかぎりません。

AGENTS.mdが読まれない条件｜Claude Codeの場合

結論として、Claude CodeでAGENTS.mdが読まれる条件は公式ドキュメントで決まっています。条件から外れると、警告もなく静かに無視されます。

まず前提が1つあります。公式の変更履歴には、バージョン2.1.277で「AGENTS.mdのサポートを追加。CLAUDE.mdが無いプロジェクトでは、代わりにAGENTS.mdを読む」と書かれています。これより前のバージョンでは、置いても読まれません。

そのうえで、公式ドキュメントが挙げている「読まれなくなる条件」は次のとおりです。

• 作業ディレクトリか、その上のどこかにCLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.mdがある(このときはCLAUDE.md側だけが読まれる)
• 入れたて・上げたての1回目のセッション(公式に「次のセッションから読む」と明記されています)
• 機能フラグを取りにいかないセッション(Amazon Bedrockなど他社基盤を経由する場合や、テレメトリを切っている場合)
• フックを全部止めている場合や、/pluginで組み込みのagents-mdプラグインを無効にしている場合

見落としやすいのは1つ目です。自分用のメモをCLAUDE.local.mdに置くだけで、AGENTS.mdは読まれなくなります。いっぽう、ホームディレクトリの~/.claude/CLAUDE.mdや組織の管理用CLAUDE.md、.claude/rules/のファイルは「数えない」ので、AGENTS.mdと一緒に読まれます。

両方をまとめて読ませたい場合は、セッションで/configを開き、「Project instructions」の値をclaude-md-and-agents-mdに変えます。設定ファイルに書く方法もありますが、その場合は~/.claude/settings.jsonなどユーザー側に書く必要があります。プロジェクトの設定ファイルに書いても無視される点に注意してください。

読み込みの範囲も押さえておきましょう。セッションの開始時に読まれるのは、作業ディレクトリとその上にあるAGENTS.mdと.claude/AGENTS.mdです。下の階層のAGENTS.mdは、そこのファイルを実際に開いたときに読まれます。なお、AGENTS.local.mdやAGENTS.override.md、.agents/の下は読みません。この点は後述するCodexと逆なので、両方使う人は特に注意が必要です。

AGENTS.mdはCodexだと読み方が違う｜探索の範囲に注意

同じ名前のファイルでも、ツールが違えば読み方も違います。Codexでは「どこでツールを起動したか」が結果を左右します。

Codexの設定は、大きく2つに分かれています。config.tomlは実行環境の条件を決めるもので、使うモデルや権限、読み込みの上限などを書きます。いっぽうAGENTS.mdは仕事の進め方、つまり検証のしかたや制約、完了の条件を書く場所です。

公式ドキュメントによると、Codexは起動のたびに次の順で指示を組み立てます。

• まずCodexのホーム(既定は~/.codex)を見る。AGENTS.override.mdがあればそれを、無ければAGENTS.mdを、どちらか1つだけ読む
• 次にプロジェクトの一番上(ふつうはGitのルート)から、いま居るディレクトリまで降りてくる。各階層で読むのは1ファイルだけで、AGENTS.override.md→AGENTS.md→設定で足した別名、の順に探す
• 読んだものは上から順につなげる。いま居るディレクトリに近いファイルほど後ろに置かれ、前の指示を上書きする
• 読み込む量には上限(既定32KiB)があり、超えた分は届かない

ここから分かるのは、いま居るディレクトリより下にあるAGENTS.mdは、そこで起動しないかぎり最初の組み立てに入らないということです。サブディレクトリに細かい決まりを置いている場合は、起動場所を変えるだけで結果が変わります。

もう1つ起きがちな事故が、上書き用ファイルの使い方です。AGENTS.override.mdは追記ではなく置きかえなので、一時的な注意だけを書くと元の手順がまるごと消えます。公式のトラブルシュートにも「おかしな指示が出てきたら、上の階層やCodexのホームにAGENTS.override.mdが無いか探す」とあります。ある解説記事でも、これで検証手順が出てこなくなった例が紹介されています。

確かめる手段も用意されています。/statusはセッションの設定(使っているモデル、権限、書き込みできる範囲)を表示します。/debug-configは設定の層と優先順位を出すもので、AGENTS.mdの読み込み先そのものを追う機能ではない点に注意してください。指示が古いままに見えるときは、目的のディレクトリで起動しなおせば組み立て直されます。キャッシュは残りません。

AGENTS.mdに書かないほうがよいこと

AGENTS.mdは、何でも書けばよいわけではありません。すぐ古くなる情報を入れると、かえって足を引っぱります。

理由は単純で、古い記述はうその手順書と同じだからです。人が読んでも迷いますし、AIはそれを前提として素直に信じます。

避けたほうがよいものを挙げます。

• 関数の一覧など、実装の細かい話(コードを変えるたびにずれる)
• 特定の操作の手順(スキルなど、別のしくみに切り出す)
• 他のプロジェクトでは動かないコマンド
• 権限まわりの設定(config.tomlなど、設定側で管理する)

逆に相性がよいのは、めったに変わらない判断のよりどころです。「変更したら検証結果と、やらなかった範囲を報告する」のような書き方は、コードが変わっても生き残ります。

筆者の考察｜AGENTS.mdは「合言葉」で読まれたか確かめる

私がおすすめしたいのは、指示の文面を練り直す前に、読まれたかどうかを確かめることです。手間は1分もかかりません。

Claude Codeなら、まず画面に出る行を探します。公式ドキュメントによれば、読み込まれたときは「no CLAUDE.md found; AGENTS.md loaded: …」のような行が対話の中に表示されます。やっかいなのは、この形で読まれたAGENTS.mdが/memoryや/contextの一覧には出てこないことです。一覧に無いから読まれていない、とはかぎりません。

一覧で確かめられないときに効くのが、有志の検証記事で使われていた合言葉のやり方です。AGENTS.mdのどこかに、ふだん出てこない単語を1つ書いておきます。そして次のセッションの最初に「いま渡されている指示の中に合言葉はありますか」と聞くだけです。返ってこなければ、そのファイルは読まれていません。ファイルを読む機能を止めたうえで聞けば、最初から渡されていた内容だけを切り分けられます。

この考え方は、運用や監視の現場とまったく同じです。監視の設定を入れたあと、わざとしきい値を超えさせてアラートが飛ぶか試しますよね。設定を入れた状態と、効いている状態は別物だからです。AIへの指示も同じで、置いた事実は効いた証拠になりません。

指示の中身そのものを見直したいときは、ルールとして書くより手順に埋めるという考え方が役に立ちます。読まれてはいるのに守られない、という段階の話です。

また、出てきたコードが追えないときは、依頼する前の準備を見直すほうが近道です。読まれる条件、指示の書き方、依頼のしかた。この3つは似ているようで、詰まる場所がそれぞれ違います。

まとめ｜AGENTS.mdで押さえたい3点

• AGENTS.mdはAIに前提を渡す共通の手順書。構成・動かし方・完了の条件を書く場所として使う
• 読まれる条件はツールごとに違う。Claude CodeではCLAUDE.mdとCLAUDE.local.mdの有無、そして1回目のセッションかどうか。Codexでは起動した場所と上書き用ファイルが効いてくる
• 置いた事実は効いた証拠にならない。合言葉を1語入れて、読まれたかを毎回たしかめる

次の一歩は、手元のAGENTS.mdに合言葉を1語だけ足すことです。次のセッションで聞いてみれば、いま自分の指示が届いているのかが1分で分かります。

参考リンク

• How Claude remembers your project(Claude Code公式ドキュメント) ― AGENTS.mdが読まれる条件、Project instructionsの設定値、読み込み確認の行
• CHANGELOG(Claude Code公式) ― v2.1.277「Added AGENTS.md support」の記載
• Custom instructions with AGENTS.md(OpenAI Codex公式) ― 探索の順序、上書きの挙動、読み込み量の上限
• Developer commands(OpenAI Codex公式・旧「Slash commands in Codex CLI」) ― /statusと/debug-configがそれぞれ何を出すか
• Claude Code が AGENTS.md を読むようになった。ただし1回目のセッションでは読まれない(Qiita) ― 合言葉で読み込みを確かめる方法(有志の検証)
• Codexを使うなら、config.tomlとAGENTS.mdを押さえておきたい(じゃあ、おうちで学べる) ― config.tomlとAGENTS.mdの使い分けの解説