Claude CodeはAGENTS.mdを読む?CLAUDE.mdとの共存の書き方8通りを102回実測
AGENTS.mdとCLAUDE.mdを両方置くと、Claude Codeは既定でCLAUDE.mdしか読みません。置き方8通りを102回実測すると、読み込まれない置き方ではルールが18回中5回しか守られませんでした。書き方を解説します。

この記事の結論
- Claude Code(v2.1.277以降)はAGENTS.mdを読めますが、作業フォルダかその上にCLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.mdが1つでもあると、既定ではCLAUDE.mdだけを読みます。
- 当研究所がv2.1.325で置き方8通りを試すと、起動時にAGENTS.mdが読み込まれたのは「CLAUDE.mdなし」「@AGENTS.mdで取り込み」「シンボリックリンク」「--settingsで両方読む設定」の4通りでした。
- 1ファイルを直す作業では、AGENTS.mdが読み込まれる置き方と「読んで」と書いた置き方でルールが6回中6回守られました。CLAUDE.mdがAGENTS.mdを指さない3通りでは18回中5回で、守られたのはClaudeが自分でAGENTS.mdを開いた回だけでした(Sonnet 5.5は9回中0回)。
- 自分用のCLAUDE.local.mdを1つ足すだけで、チームのAGENTS.mdは読まれなくなりました(CLAUDE.mdで@AGENTS.mdを取り込んでいれば読まれます)。「両方読む」設定も、リポジトリの.claude/settings.jsonに書くと無視されます。
- チームで共有するなら、CLAUDE.mdの先頭に@AGENTS.mdの1行を書く方法がおすすめです。公式ドキュメントが勧める書き方で、リポジトリにコミットでき、当研究所の実測ではCLAUDE.local.mdを足しても読み込まれ続けました。
Claude Code研究所 技術ブログ担当です。CodexやCursorと一緒に使うチームでは、ルールをAGENTS.mdにまとめておくことが増えました。では、Claude Codeはそのルールを本当に守るのか。Harbor社の調査では、AGENTS.mdとCLAUDE.mdを両方置いたリポジトリの約6分の1で、AGENTS.mdが読まれない置き方になっていました。そこで、AnthropicのClaude Code(v2.1.325)で、CLAUDE.mdの置き方を8通り変えて計102回試しました。結果は、AGENTS.mdが読み込まれる置き方ではルールが毎回守られ、CLAUDE.mdがAGENTS.mdを指さない置き方では18回中5回だけでした。確実な書き方と、意外な落とし穴をまとめます。
目次
Claude CodeはAGENTS.mdを読む?
読みます。ただしClaude Codeは、作業フォルダかその上にCLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.mdが1つでもあると、既定ではCLAUDE.mdの側だけを読み、AGENTS.mdは読み込みません。
AGENTS.mdは、CodexやCursorなど複数のAIコーディングツールが共通で読む「エージェント向けの説明書」です。Claude Codeはもともと自前のCLAUDE.mdを読む仕組みで、公式ドキュメントによると、v2.1.277からAGENTS.mdも直接読めるようになりました。ただし、読むのは「CLAUDE.mdが無いとき」の代わりとしてです。
Harbor社が10月にGitHubの公開リポジトリを調べた調査(11月14日更新)では、AGENTS.mdの横にCLAUDE.mdがある745組のうち、置き方は次のように分かれていました(同社の加重推定)。
- CLAUDE.mdで「@AGENTS.md」と取り込む:25%
- CLAUDE.mdをAGENTS.mdへのシンボリックリンクにする:23%
- CLAUDE.mdがAGENTS.mdに一切触れない:16%
- CLAUDE.mdに「AGENTS.mdを読んで」と文章で書く:15%
- 中身をコピーしている(うち半分は内容がずれている):14%
「触れない」と「文章で書く」を合わせると、約3割です。この3割で何が起きるのかが、私の一番の関心でした。なお、Harbor社はルールファイルの診断ツールを提供している会社です。
置き方8通りで、起動時に読み込まれるのはどれ?
起動時にAGENTS.mdが読み込まれたのは、「CLAUDE.mdなし」「@AGENTS.mdで取り込み」「シンボリックリンク」「--settingsで両方読む設定」の4通りでした。残りの4通りでは、AGENTS.mdは読み込まれませんでした。
同じ小さなPythonのリポジトリに、AGENTS.mdだけにチームのルールを2つ書き、CLAUDE.mdの置き方だけを変えました。起動直後に /context all を実行し、「Memory files」に何が並ぶかを確かめています。
| 置き方 | 起動時に読み込まれたファイル | AGENTS.md |
|---|---|---|
| ① AGENTS.mdだけ(CLAUDE.mdなし) | AGENTS.md | 読まれる |
| ② CLAUDE.mdの先頭に @AGENTS.md | CLAUDE.md+AGENTS.md | 読まれる |
| ③ CLAUDE.mdをAGENTS.mdへのシンボリックリンクに | CLAUDE.md(中身はAGENTS.md) | 読まれる |
| ④ CLAUDE.mdに「作業の前にAGENTS.mdを読んで」と1文 | CLAUDE.md | 読まれない |
| ⑤ CLAUDE.mdがAGENTS.mdに触れない | CLAUDE.md | 読まれない |
| ⑥ ⑤+「両方読む」設定をリポジトリの .claude/settings.json に | CLAUDE.md | 読まれない |
| ⑦ AGENTS.md+自分用のCLAUDE.local.mdだけ | CLAUDE.local.md | 読まれない |
| ⑧ ⑤+「両方読む」設定を --settings で渡す | CLAUDE.md+AGENTS.md | 読まれる |
⑦には驚きました…! 自分用のメモとしてCLAUDE.local.mdを1つ置いただけで、チームのAGENTS.mdが読まれなくなっています。ただし、CLAUDE.mdに@AGENTS.mdを書いた状態でCLAUDE.local.mdを足した場合は、3つとも読み込まれました(追加で確認)。ドキュメントにも、CLAUDE.local.mdはCLAUDE.mdと同じく数えられると注記がありました。チームのリポジトリでは、気づかないうちに起きやすい形だと思います。
⑥も落とし穴です。「両方読む」設定(claude-md-and-agents-md)は、リポジトリの .claude/settings.json に書いても効きませんでした。ドキュメントによると、この設定はユーザーの設定(~/.claude/settings.json)、--settings で渡すファイル、管理設定からだけ読まれ、プロジェクトとローカルの設定ファイルでは無視されます。チーム全員に配るつもりでコミットしても、効かないわけです、、、
AGENTS.mdのルールは実際に守られた?
1ファイルを直す作業では、AGENTS.mdが読み込まれる置き方と「読んで」と書いた置き方で、ルールが6回中6回守られました。CLAUDE.mdがAGENTS.mdを指さない3通りでは18回中5回で、守られたのはClaudeが自分でAGENTS.mdを開いた回だけでした。
AGENTS.mdに書いたルールは次の2つです。どちらも、書かれていなければClaudeがふだんしない動きです。
- 作業報告の最後に「【変更ファイル】」という見出しを付けて、変更したファイルを箇条書きにする
- テストは ./run_tests.sh で実行する(pytest を直接呼ばない)
まず、リポジトリを見て回らなくても済む「billing/discount.py の volume_discount で、qty が負の数のときは ValueError を出すようにして」という作業で、報告に【変更ファイル】の見出しが付いた回数を数えました(Sonnet 5.5・Opus 5.5、各3回)。編集そのものは、48回すべてで正しくできていました。
| 置き方 | 見出しが付いた回数 | AGENTS.mdを自分で開いた回数 |
|---|---|---|
| ①②③⑧ 読み込まれる置き方 | 24/24 | 0/24(最初から読み込み済み) |
| ④ 「AGENTS.mdを読んで」と1文 | 6/6 | 6/6(毎回1手目に開いた) |
| ⑤ CLAUDE.mdが触れない | 3/6(Opus 3・Sonnet 0) | 3/6 |
| ⑥ 設定をリポジトリに書いた | 2/6(Opus 2・Sonnet 0) | 2/6 |
| ⑦ CLAUDE.local.mdだけ | 0/6 | 0/6 |
⑤⑥⑦では、ルールが守られた回とAGENTS.mdを開いた回がぴったり一致していました。つまり、読み込まれない置き方では「Claudeがたまたま見つけるかどうか」で結果が決まります。中でもSonnet 5.5は9回中0回で、一度もAGENTS.mdに気づきませんでした…! 記録を見ると、Sonnet 5.5は対象のファイルを開いてすぐ編集に入り、Opus 5.5は先にファイル一覧を確認していました。この作業の進め方の違いが、そのまま差になっています。
使う側から見ると、編集はきちんとできているのに、チームのルールだけが抜け落ちる形です。Harbor社の言う「6分の1」で起きているのは、まさにこの状態だと思います。
④の「読んで」と書く方法は、この作業では毎回1手目にAGENTS.mdを開いて守りました。ただ、次の作業では結果が割れています。
読み込まれなくても、Claudeが自分で見つけることはある?
あります。リポジトリを見て回る作業では、AGENTS.mdが読み込まれていなくても、Claudeは2〜3手目に自分でAGENTS.mdを開き、そのあとはルールに従いました。ただし、最初のテスト実行はルールを読む前に済ませてしまっていました。
2つ目の作業は「テストが1つ失敗しています。原因を調べて直して」です。こちらでは、報告の見出しはAGENTS.mdのある全パターンで付きました。ファイル一覧を見た時点でAGENTS.mdに気づき、読みに行っていたからです。正直、ここは想像以上に賢いと感じました!
差が出たのは、もう1つのルール「テストは ./run_tests.sh で」です。最初のテストをどう走らせたかを、全54回のコマンドを1つずつ見て数えました。
| 置き方 | 最初のテストを ./run_tests.sh で実行 |
|---|---|
| 指示ファイルなし(比較用) | 1/6 |
| ①②③⑧ 読み込まれる置き方 | 24/24 |
| ④ 「AGENTS.mdを読んで」と1文 | 3/6(Opus 3/3・Sonnet 0/3) |
| ⑤⑥⑦ 読み込まれない置き方 | 2/18 |
読み込まれない置き方では、Claudeは1手目にいきなり pytest を走らせ、そのあとファイル一覧からAGENTS.mdを見つけて、以降は ./run_tests.sh に切り替えていました。今回の環境では、この1手目の pytest は24回とも「pytest が入っていない」というエラーで失敗しただけでしたが、本番のリポジトリなら、チームが避けたいコマンドをルールを読む前に実行してしまう形です。なお、⑦の2回はOpus 5.5が最初にAGENTS.mdを開いた回でした。
④の「読んで」と1文の方法では、Opus 5.5は3回とも先にAGENTS.mdを読んでから動きました。一方、Sonnet 5.5は3回とも、AGENTS.mdを読む呼び出しと pytest を走らせる呼び出しを、同じ応答の中で同時に出していました。読みに行くのとテストを走らせるのが同時なので、ルールが間に合わなかったわけです…。「読んで」と書くだけでは、いつ読まれるかがClaude任せになる、ということがよく分かる結果でした。
見落としやすい落とし穴は?
実測とドキュメントから見えた落とし穴は、次の4つです。どれも、AGENTS.mdを置いた本人は「読ませているつもり」になりやすい点が共通しています。
- 自分用のCLAUDE.local.mdで止まる:AGENTS.mdだけのリポジトリでも、誰かがCLAUDE.local.mdを置くと、その人のClaude CodeはAGENTS.mdを読まなくなります。CLAUDE.local.mdは通常コミットしないため、人によって挙動が違うことになります。CLAUDE.mdで@AGENTS.mdを取り込んでおけば防げます
- 「両方読む」設定はリポジトリで配れない:/config の Project instructions や ~/.claude/settings.json での設定は、各自のパソコンでしか効きません。リポジトリの .claude/settings.json に書くと無視されます
- 上の階層のCLAUDE.mdでも止まる:ドキュメントによると、判定は作業フォルダ「かその上」です。モノレポの親フォルダや、ホームの下の作業用フォルダにCLAUDE.mdがあると、AGENTS.mdは読まれません(ホームの ~/.claude/CLAUDE.md は数えません)
- 読めないセッションがある:v2.1.277より前のバージョン、AGENTS.mdを読む組み込みプラグインを /plugin で無効にした場合、v2.1.276以前からのアップグレード直後の最初のセッションなどでは、CLAUDE.mdだけが読まれます。v2.1.281より前は、Amazon Bedrock経由やテレメトリを無効にしたセッションも読めませんでした
読み込まれているかを確かめるには、セッションの中で /memory か /context を実行し、AGENTS.mdのパスが並んでいるかを見ます。今回の表も、この方法で確かめました。
CLAUDE.mdとAGENTS.mdの確実な書き方は?
チームで確実に共有するなら、CLAUDE.mdの先頭に「@AGENTS.md」と1行書き、その下にClaude Code専用の指示を足す方法がおすすめです。公式ドキュメントもこの書き方を勧めていて、今回の実測でもルールが毎回守られ、誰かがCLAUDE.local.mdを足しても読み込まれ続けました。
@AGENTS.md
## Claude Code
- 請求金額を計算する Python パッケージです(billing/)。
ポイントは次のとおりです。
- @AGENTS.md はバッククォートで囲まない:囲むとただの文字列になり、取り込まれません
- 共通のルールはAGENTS.mdに1本化:CLAUDE.mdにコピーすると、Harbor社の調査のように、いずれ内容がずれます
- シンボリックリンクも効くがWindowsに注意:ドキュメントによると、Gitの core.symlinks が無効だと、Windowsではリンクが普通のテキストファイルとして取り出されます
- 「読んで」の1文は取り込みに置き換える:途中で読まれることはあっても、最初の一手には間に合わないことがありました
1行足すだけで済むので、AGENTS.mdを置いているチームは今日にでも見直す価値があります!
CLAUDE.mdそのものの書き方は、CLAUDE.mdの書き方(「IMPORTANT」は逆効果?)で、チームで共有する仕組みはClaude Codeのメモリをチームで共有する方法で詳しく紹介しています。
検証の方法と限界
検証はClaude Code v2.1.325、macOS、Ultraプランのログインで、claude -p(非対話モード)を使って行いました。
- 素材:テストが1つ失敗する小さなPythonのリポジトリ。AGENTS.mdにだけルールを2つ書き、CLAUDE.mdの置き方を8通り(+指示ファイルなしの比較用)用意しました
- 読み込みの確認:各置き方で起動直後に /context all を実行(10回)
- ルールの遵守:バグ修正の作業54回(9通り×2モデル×3回)と、1ファイルの編集作業48回(8通り×2モデル×3回)、計102回。モデルはSonnet 5.5とOpus 5.5、effortは既定、権限は acceptEdits+ツールの許可リスト。このほか、編集の要らない作業(すでに英語のdocstringの書き換え)で48回の予備試行も行いました。費用は全160回で合計約11.9ドル(API定価換算)でした
- 採点:報告の見出しは最終回答の文字列で、テストの実行方法は各回の最初のテストコマンドを目で見て判定しました
限界もあります。
- リポジトリは1つ、ルールは2つ、各条件3回です。大きなリポジトリでは、Claudeが自分でAGENTS.mdに気づくかどうかが変わる可能性があります
- Opus 5.5は、指示ファイルが無くても ./run_tests.sh を使うことがありました(1/6)。テストの実行方法のルールは、Sonnet 5.5の差のほうがはっきりしています
- 「両方読む」設定は --settings で渡す方法だけを試しました。~/.claude/settings.json と /config での設定は、ドキュメントの記載にもとづいています
- Harbor社の割合は、同社がGitHubの検索結果から推計した値です
Claude Codeを初めて使う方は、Claude Codeとは?(入門ガイド)から読むと全体像がつかみやすくなります。
まとめ
Claude CodeはAGENTS.mdを読めますが、CLAUDE.mdやCLAUDE.local.mdが1つでもあると、既定ではAGENTS.mdを読み込みません。CLAUDE.mdがAGENTS.mdを指さない置き方では、ルールが守られるかはClaudeが自分で見つけるかどうか次第でした。チームで共有するなら、CLAUDE.mdの先頭に @AGENTS.md を書くのが確実です。
この記事のまとめ
- 起動時にAGENTS.mdが読まれたのは、CLAUDE.mdなし・@AGENTS.md・シンボリックリンク・--settingsで両方読む設定、の4通り(v2.1.325)
- 1ファイルを直す作業では、読み込まれる置き方で24/24、CLAUDE.mdがAGENTS.mdを指さない置き方で5/18(Sonnet 5.5は0/9)
- 見て回る作業ではClaudeが自分でAGENTS.mdを見つけるが、最初のテスト実行はルールを読む前だった
- CLAUDE.local.mdを足すだけでAGENTS.mdは読まれなくなる(@AGENTS.mdの取り込みなら防げる)。「両方読む」設定はリポジトリでは配れない
- チームの正解は、CLAUDE.mdの先頭に @AGENTS.md の1行
記事で紹介した設定を、自社の業務に合わせて組み上げる。
CLAUDE.mdによるプロジェクト規約の設定から、業務に合わせたオリジナルskillsの作成まで、一社ごとにヒアリングした業務を題材に対面で進めます。受講者限定のオリジナルskillsとプロンプトテンプレート集もお渡しします。
- 一社ごとに業務をヒアリングして設計
- 実際の業務データでハンズオン
- スパルタ以上は全額返金保証
- 受講法人数100社超
オンライン30分・無料。フォームは入力1分で、2営業日以内にご連絡します。
よくある質問
Claude CodeはAGENTS.mdを読みますか?
読みます。Claude Code v2.1.277以降は、作業フォルダかその上にCLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.mdが無ければ、AGENTS.mdをプロジェクトの指示として読み込みます。ただし、これらが1つでもあると、既定ではCLAUDE.mdの側だけを読み、AGENTS.mdは読み込みません。読み込まれたかどうかは /memory か /context で確認できます。
CLAUDE.mdとAGENTS.mdを両方置くにはどう書けばいいですか?
CLAUDE.mdの先頭に「@AGENTS.md」と1行書き、その下にClaude Code専用の指示を足す方法が確実です。Anthropicの公式ドキュメントもこの書き方を勧めています。当研究所の実測(v2.1.325)でも、この書き方ではAGENTS.mdのルールが毎回守られました。CLAUDE.mdをAGENTS.mdへのシンボリックリンクにする方法も効きますが、WindowsではGitの設定によって普通のテキストファイルになります。
CLAUDE.mdに「AGENTS.mdを読んで」と書くだけではだめですか?
起動時には読み込まれません。Claudeが作業の途中でAGENTS.mdを開いたときにだけ効きます。当研究所の実測では、1ファイルを直す作業では毎回最初に開いて守りましたが、テストの実行方法のルールは、Sonnet 5.5が読むのと同時にテストを走らせたため3回とも守られませんでした。確実にしたい場合は「@AGENTS.md」の取り込みに書き換えます。
CLAUDE.local.mdを置くとAGENTS.mdが読まれなくなるのはなぜですか?
Claude CodeはCLAUDE.local.mdもCLAUDE.mdと同じ扱いで数えるため、AGENTS.mdだけのリポジトリに自分用のCLAUDE.local.mdを足すと、既定ではAGENTS.mdを読まなくなります。当研究所の実測でも、1ファイルを直す作業でAGENTS.mdのルールは6回とも守られませんでした。CLAUDE.mdで@AGENTS.mdを取り込んでおけば、CLAUDE.local.mdがあってもAGENTS.mdは読み込まれます。/configのProject instructionsを「claude-md-and-agents-md」にすれば、両方を読みます。
AGENTS.mdとCLAUDE.mdを両方読ませる設定はありますか?
あります。/configのProject instructionsを「claude-md-and-agents-md」にするか、~/.claude/settings.jsonのpluginConfigsで「cc-plugin-agents-md@builtin」に同じ値を設定します。ただし、この設定はプロジェクトやローカルの設定ファイルに書いても無視されるため、リポジトリにコミットしてチーム全員に配ることはできません。
参考資料・出典
- 公式ドキュメントHow Claude remembers your project(AGENTS.md の節)
AGENTS.mdを読む条件(v2.1.277以降・CLAUDE.mdが無いとき)、CLAUDE.local.mdも数える注意、Project instructionsの4つの値と設定ファイルでの扱い、@AGENTS.mdの推奨例、読めないセッション
- 公式ブログ・記事In 1 in 6 repos with both files, Claude Code never loads the AGENTS.md
GitHubの公開リポジトリ3,905ファイルの調査(2026年10月18日時点)。AGENTS.mdとCLAUDE.mdの組745のうち、CLAUDE.mdがAGENTS.mdに触れないのは16%(同社の加重推定)
- スレッドIn 1 in 6 repos with both files, Claude Code never loads the AGENTS.md
上記調査の投稿
- 公式ドキュメントAGENTS.md
複数のAIコーディングツールが共通で読むエージェント向けの説明書AGENTS.mdの仕様と対応ツール
- GitHubClaude Code v2.1.325
検証に使ったバージョン
Claude Codeを実務で活用したい方へ
一社ごとにカスタマイズする対面のClaude Code研修は「スパルタClaude Code塾」。経営者・士業・エンジニア・マーケター・営業職まで、業務をヒアリングしてカリキュラムを設計します。まずは30分の無料相談で、自動化プランと費用対効果をご確認ください。

