気になるAIツールを、分かりやすく
2026年9月18日のClaude Code 2.1.277で、CLAUDE.mdが無いプロジェクトではAGENTS.mdがそのまま読まれるようになりました[1]。AGENTS.mdは、AIコーディングツール各社が共通で読む「このリポジトリの作法を書いたファイル」です。これまでClaude CodeだけはCLAUDE.mdという自分専用の名前を要求していたので、2つ置くか、片方からもう片方を読み込ませる必要がありました。
結論から言うと、多くのリポジトリでは今日から何も変わりません。読まれるのは「CLAUDE.mdが1つも無いとき」だけで、しかも切り替えると失うものがあります。
- どのファイルがあると、どれが読まれるか（実機で測った表）
- 自分用のメモを1枚置くだけで、チームの指示が落ちる条件
- 読まれたことを確認する手段が変わる
- 切り替えていい人・やめておく人のチェックリスト
Claude CodeのCLIを2.1.278に上げ、使い捨てのリポジトリ5つと設定3種類で挙動を測りました[3]。公式ドキュメントの記述と、実際に返ってきた結果の両方を並べます。
01 何が変わったか
changelogの記述は1行です。「CLAUDE.mdが無いプロジェクトでは、Claude CodeはかわりにAGENTS.mdを読む。/configのProject instructionsで変更できる（Bedrock・Vertex・Foundryはまだ非対応）」[1]。
この1行だけ読むと「2つ置く必要がなくなった」と読めます。公式ドキュメントの該当ページには、もっと細かい条件が書かれていました[2]。要点は3つです。
- 既定の動きは「CLAUDE.mdがあればそれだけ、無ければAGENTS.md」。両方読むわけではない
- 数えるファイルは
CLAUDE.md／.claude/CLAUDE.md／CLAUDE.local.mdの3つ。しかも作業ディレクトリだけでなく、その上のどの階層にあっても数える - 個人設定の
~/.claude/CLAUDE.md、組織が配るCLAUDE.md、.claude/rules/は数えない（AGENTS.mdと一緒に読まれ続ける）
「上の階層も数える」は効いてきます。会社のリポジトリを1つのフォルダにまとめて置いている人は、その親フォルダにCLAUDE.mdを1枚置いた時点で、配下すべてのリポジトリでAGENTS.mdが読まれなくなります。
02 実測：どのファイルがあると、どれが読まれるか
使い捨てのリポジトリを5つ作り、それぞれの指示ファイルに別々の合言葉を書きました。セッションを起こして「このプロジェクトの合言葉は？ 指示が無ければUNKNOWNと答えて」と聞き、返ってきた合言葉で「どれが読まれたか」を判定します。各2回ずつ実行し、結果は2回とも同じでした[3]。
| 置いたファイル | 返ってきた合言葉 | 読まれたのは |
|---|---|---|
| AGENTS.md だけ | CAG-AGENTS-7Q41 | AGENTS.md |
| AGENTS.md ＋ CLAUDE.md | CAG-CLAUDE-3M88 | CLAUDE.md だけ |
| AGENTS.md ＋ CLAUDE.local.md（合言葉なし） | UNKNOWN | どちらも読まれない |
| AGENTS.local.md ＋ .agents/AGENTS.md | UNKNOWN | どちらも読まれない |
AGENTS.md ＋ CLAUDE.md（中身は@AGENTS.mdの1行） | CAG-AGENTS-7Q41 | 読み込み経由でAGENTS.md |
4行目は、名前が似ていても対象外だという確認です。読まれるのはAGENTS.mdと.claude/AGENTS.mdだけで、AGENTS.local.md・AGENTS.override.md・.agents/の下にあるものは読まれません[2]。
5行目は、これまで広く使われてきた「CLAUDE.mdからAGENTS.mdを読み込ませる」書き方です。新機能が入った後もそのまま通ります。この書き方が広まった経緯は、以前の記事で扱いました。
関連記事 ｜ そもそもAGENTS.mdに何を書くかAIエージェント時代、強いリポジトリは「AGENTS.md」を持っている ──CopilotがレビューにAGENTS.mdを読み始めた日
→
03 いちばん危ないのは CLAUDE.local.md
3行目をもう一度見てください。CLAUDE.local.mdに書いたのは「簡潔に答えて」という自分用のメモだけです。合言葉は書いていません。それなのに、チームで共有しているAGENTS.mdまで読まれなくなりました。
CLAUDE.local.mdは、リポジトリに入れずに自分の手元だけで持つ個人メモとして使われるファイルです。つまり、こういうことが起きます。
- チームはAGENTS.mdに作法を書いて共有している
- ある人が自分用の好みを
CLAUDE.local.mdに1枚足す - その人のセッションだけ、チームの作法が読まれなくなる
- 手元のファイルは増えただけなので、本人には減ったものが見えない
直し方は公式に書かれています。/configを開いてProject instructionsをclaude-md-and-agents-md（両方読む）に変えることです[2]。実際に同じリポジトリで設定だけ変えて測ると、合言葉が返るようになりました（2回とも）[3]。
| Project instructions の値 | 読まれるもの |
|---|---|
| claude-md-or-agents-md | CLAUDE.md、無ければAGENTS.md（既定） |
| claude-md-and-agents-md | 両方。各階層でCLAUDE.mdが先、AGENTS.mdが後 |
| claude-md | CLAUDE.md だけ |
| managed-only | 組織が配るCLAUDE.mdと自動メモリだけ |
設定ファイルに書くこともできますが、プロジェクトやローカルの設定ファイルに書いても無視されます（個人設定か、組織が配る設定にだけ効く）[2]。チーム全員に同じ設定を配りたい場合は、ここが分かれ目になります。
04 読まれたことが、見えなくなる
CLAUDE.mdには「読み込んだ記録が残る」という性質がありました。AGENTS.mdを直接読ませると、この記録の一部が消えます。
公式ドキュメントは2点を挙げています。/memoryと/contextのMemory filesの一覧に出ないこと。そしてInstructionsLoadedという「指示ファイルを読んだときに動く自動処理」が動かないこと[2]。
後者を実機で測りました。指示ファイルを読むたびに通知の中身を記録する自動処理を仕込み、AGENTS.mdだけのリポジトリとCLAUDE.mdのあるリポジトリで比べます[3]。
発火した回数だけ見ると、どちらも動いています。差が出るのは、通知された中身でした。
| リポジトリ | 通知された指示ファイル |
|---|---|
| AGENTS.md だけ | 個人設定のCLAUDE.md ／ そこから読み込まれたAGENTS.md ／ 個人のrulesファイル 3件すべて個人設定。プロジェクトの行が1件も無い |
| CLAUDE.md あり | 上の3件 ＋ プロジェクトのCLAUDE.md（計4件） |
自動処理そのものは止まりません。止まるのは「プロジェクトの指示を読んだ」という通知だけです。指示ファイルの読み込みを記録して監査に使っている場合、AGENTS.mdに切り替えた日から、その記録だけが静かに欠けます。回数を見ている限り気づけません。
読まれたかどうかを確かめたいときは、対話セッションの冒頭に出るno CLAUDE.md found; AGENTS.md loaded: ...の行を見るか、Claude自身に「いまのプロジェクト指示には何が書いてある？」と聞くことになります[2]。
05 読まれない4つの条件
「更新したのに読まれない」が起きる条件が4つあります[2]。うち2つは実機で再現しました。
4番目は少し意外です。AGENTS.mdの読み込みはClaude Codeに内蔵されたプラグインとして実装されており、安全のために自動処理（フック）を一括停止すると、指示ファイルの読み込みまで一緒に止まります[2]。締めたつもりが、AIに渡すはずの作法が落ちる。
どの条件に当たっていても、CLAUDE.mdから@AGENTS.mdを読み込ませる書き方なら通ります[2]。
06 手元の60リポジトリを数えた
CAGでは2026年9月8日から、AGENTS.mdを正とし、CLAUDE.mdは@AGENTS.mdの1行だけを書いた「殻」として置く運用にしています。Claude CodeとCodexの両方に同じ作法を渡すためです。
今回の発表を見て最初に思ったのは「では、その殻を消せるのか」でした。手元の開発フォルダを機械的に数えた結果がこれです[4]。
60件中58件は、今日から何も変わりません。CLAUDE.mdがあるので、AGENTS.mdは読み込み経由で入るという従来どおりの動きになります。
公式ドキュメントも、この殻についてそのままにしてよい、読み込みを残してもAGENTS.mdが二度読まれることはないと明記しています。消すべきなのは別のパターンです[2]。
| これまでのやり方 | どうするか |
|---|---|
CLAUDE.mdに@AGENTS.mdと書いている | そのままでよい。消すのは、ほかに何も書いていない場合だけ |
| CLAUDE.mdに「AGENTS.mdを読んで」と文章で書いている | 消すか、@AGENTS.mdの読み込みに書き換える（文章だと、AIが開く気になったときしか読まれない） |
| CLAUDE.mdをAGENTS.mdへのシンボリックリンクにしている | そのままでも、消してもよい |
| セッション開始時にAGENTS.mdを流し込む自動処理を入れている | 消す。直接読まれるようになると、同じ内容が2回入る |
07 切り替えていい人、残すべき人
切り替えていいかどうかは、3つの質問で決まります。
- CLAUDE.mdを1枚も置かずに済むか（上の階層も含めて。1枚でもあればAGENTS.mdは読まれない）
- チーム全員が2.1.277以降で、Bedrockなどを経由していないか（1人でも外れていると、その人だけ指示が無い状態で動く）
- 指示ファイルの読み込みを記録・監査していないか（していれば、プロジェクトの行が消える）
3つとも問題なければ、CLAUDE.mdを消してAGENTS.md 1本にできます。1つでも引っかかるなら、@AGENTS.mdの1行を書いた殻を残すのが安全です。公式もそれを許しています。
| AGENTS.md 1本にする | @AGENTS.md の殻を残す | |
|---|---|---|
| ファイル数 | 1つ | 2つ（うち1つは1行） |
| 他社ツールとの共通化 | できる | できる |
| 版・提供経路の影響 | 受ける（4条件） | 受けない |
| CLAUDE.local.md を足したとき | 指示が落ちる | 落ちない |
| /memory・/context への表示 | 出ない | 出る |
| 読み込みの自動処理・記録 | プロジェクトの行が出ない | 出る |
読むファイルが1つ減ったのではなく、どのファイルを読んだかが見えにくくなった。それがこの変更の中身です。
AIに渡す「社内の作法」を設計したい方へ
電脳技巧集団（AI職人ギルド）は、AI駆動で業務システムをつくっています。どの作法をAIに渡し、どこを人が判断するかの設計から相談できます。お問い合わせはこちら
出典・注記
- Claude Code changelog 2.1.277（2026年9月18日）。https://code.claude.com/docs/en/changelog
- Claude Code ドキュメント「How Claude remembers your project」AGENTS.md の節（2026年9月21日閲覧）。https://code.claude.com/docs/en/memory
- 実機検証はCAGが2026年9月21日に実施（Claude Code CLI 2.1.278・macOS）。使い捨てのリポジトリに指示ファイルごとの合言葉を書き分け、返答で判定した（各2回、更新直後の挙動のみ3回）。試していない経路＝Bedrock・Vertex・Foundry 経由、Windows、組織が配る managed 設定。
- リポジトリの件数は2026年9月21日時点で、手元の開発フォルダ直下のAGENTS.md・CLAUDE.mdの有無を機械的に数えたもの（非公開の案件を含む）。
本記事の公式仕様は上記ドキュメントの2026年9月21日時点の記述に基づきます。実機検証の範囲は脚注3のとおりです。
