2026年9月19日公開約15分で読めます

Claude CodeがAGENTS.mdに対応でも.agentsはそのまま読まない

AIニュースClaude業務活用

監修: 寺師岳見(株式会社タレントクラウド代表取締役)フォロー

AGENTS.mdからClaude Codeへ矢印が伸び「設定不要」と示す図解。途中にCLAUDE.local.mdが置かれると「従来どおり」に戻ること、.agents/skillsフォルダは「未対応」で線が切れていることを並べ、「AGENTS.mdを、そのまま。」というコピーを添えたインフォグラフィック

Claude Codeが AGENTS.md を直接読むようになりました。日本時間の9月19日未明に公開された v2.1.277 からです。

同じリポジトリ(プロジェクトのファイル一式)をClaude CodeとCodexの両方で触ると、AI向けの指示書が CLAUDE.md と AGENTS.md の2つになります。回避策は、CLAUDE.md の中身を @AGENTS.md の1行だけにして取り込むこと。前にその話を書きました。

今回、その1行が要らなくなりました。ただし黙って全部が変わるわけではなく、条件を1つでも外すと従来どおりの動きに戻ります。

正直なところ、筆者としては歓迎したい変更です。ファイル名が違うというだけの理由で入口を2つ用意する。あの作業に意味があったとは、いまでも思えません。

新バージョンを入れて、テスト用のリポジトリで6パターン試しました。結果を先に出します。

試したこと	結果
`AGENTS.md` だけを置く	読まれた
サブディレクトリにも `AGENTS.md` を置き、その階層のファイルを読ませる	そちらも読まれた
`CLAUDE.local.md` を1つ足す	読まれなくなった
その状態で設定を「両方読む」に変える	読まれた
`.agents/skills` にスキルを置く	認識されない
`.claude/skills` からシンボリックリンクを張る	認識された

検証はmacOS、Claude Code v2.1.277、モデルはHaiku 4.5です。引っかかりそうなのは3行目でしょう。理由は後半で書きます。

設定は不要ただしCLAUDE.mdが1つでもあれば従来どおり

まず手順の話をすると、やることはありません。バージョンを上げれば追加設定なしで有効になります(使えない環境もあります。後述します)。

ファイルの置き方に関する条件は1つだけ。作業ディレクトリとその上のどこにも CLAUDE.md が無いことです。公式ドキュメントが、何を数えるかまで書いています。

ファイル	扱い
`CLAUDE.md` / `.claude/CLAUDE.md` / `CLAUDE.local.md`(作業ディレクトリとその上位)	数える。1つでもあるとAGENTS.mdは読まれない
`~/.claude/CLAUDE.md`(個人用)	数えない。AGENTS.mdと一緒に読まれる
組織が配布する管理下のCLAUDE.md	数えない
`.claude/rules/` の各ファイル	数えない

条件を満たすと、起動時にこういう行が出ます。実際の画面から採ったものです。

agents-md: no CLAUDE.md found; AGENTS.md loaded: /path/to/your-repo/AGENTS.md

テスト用のリポジトリで確かめました。ルートの AGENTS.md に合言葉を書いて聞くと、そのまま答えます。サブディレクトリに別の AGENTS.md を置いて、その階層のファイルを読ませてから聞くと、そちらの内容も反映されます。CLAUDE.md のときと同じ挙動です。

問題は、ここに CLAUDE.local.md が混ざったときでした。

CLAUDE.local.md は、コミットしない個人用のメモを置くためのファイルです。テスト用リポジトリに「特に重要なことは書いていません」という3行のダミーを置いて、同じ質問をしました。返ってきたのは「指示が見当たらない」という答えでした。中身が無関係でも、置いてあるだけで判定に入ります。

公式も注記でこの点に触れていて、個人メモを残したままAGENTS.mdも読ませたいなら設定を変えるように、と書いています。

ここはチームで使うなら気に留めておきたいところです。同じリポジトリを触っていても、人によってAIが読んでいるルールが違うという状態が起こり得ます。片方にはコードレビューの基準が渡っていて、片方には渡っていない。しかも画面上は普通に動くので、気づくきっかけがありません。バージョンの差でも同じことが起きます。確認するのは2点で十分です。手元に CLAUDE.local.md があるかどうかと、起動時に AGENTS.md loaded の行が出ているかどうか。

両方読ませたいなら4つの選択肢から選ぶ

読み方は4つから選べます。/config の「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/settings.json に置く形です。

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

ここで1つ注意があります。プロジェクト側の .claude/settings.json に書いても無視されます。 有効なのは個人設定、起動時に指定する設定ファイル、組織の管理設定の3つだけ。クローンしてきたリポジトリが、こちらの読み込み方を勝手に変えられないようにする作りです。

さきほどの CLAUDE.local.md を置いたままの状態で、この設定を claude-md-and-agents-md にして試したところ、合言葉が返ってきました。併読に切り替えれば解決します。

なお、AGENTS.md は /memory や /context のファイル一覧には出てきません。読まれているかどうかは、起動時のあの行で確認することになります。

.agentsフォルダは読まない共通化されたのはファイル1本だけ

ここが今回いちばん誤解されやすいところだと思います。共通化されたのは AGENTS.md というファイル1本で、.agents フォルダは未対応のままです。

公式ドキュメントは読まないものを名指ししています。AGENTS.local.md、AGENTS.override.md、そして .agents/ 配下のすべて。

Codexは、スキルを .agents/skills/ から探します(公式ドキュメント)。自分で置く場所としては、作業ディレクトリ、その上のディレクトリ、リポジトリのルート、ホーム直下。対してClaude Codeが探すのは .claude/skills/ と ~/.claude/skills/ のままです。

実際に .agents/skills/demo/SKILL.md を置いて、使えるスキルの一覧を出させました。一覧に demo は入っていませんでした。

回避策は以前と同じで、シンボリックリンク、つまり別の場所のファイルを指す目印を置いて、両方から見えるようにします。

ln -s ../../.agents/skills/demo .claude/skills/demo

これで同じ質問をすると、説明文つきで認識されました。Claude Codeはスキルのフォルダがリンクでも、リンク先の SKILL.md を読みます。

AGENTS.override.md が読まれない点も、Codexと併用しているなら知っておく価値があります。Codexは同じディレクトリに AGENTS.override.md があればそちらを優先しますが、Claude Codeはそれを無視して AGENTS.md のほうを読みます。同じフォルダで2つのAIが違うファイルを見ることになるので、併用するなら AGENTS.override.md は使わないほうが安全です。

動かない環境では、1行のCLAUDE.mdを残す

対応していない場面があります。主なものを挙げます。

v2.1.277より前。9月19日朝、筆者のmacOS環境で確認したところ、Claudeデスクトップアプリに同梱されているのは2.1.271でした。ターミナルの claude も、しばらく更新していなければ古いままです
Amazon Bedrock、Google Vertex、Microsoft Foundry 経由。変更履歴に「まだ対応していない」と明記されています
利用状況の送信(テレメトリ)を切っているセッション。DISABLE_TELEMETRY などを設定していると、機能の有効化に必要な情報をAnthropic側に取りに行かないため使えません
インストールや更新の直後の初回セッション。そのセッション中に設定を取りに行くので、次から有効になります
/plugin で agents-md を無効にした場合

このほかの条件は公式ドキュメントにまとまっています。

バージョンは claude --version で確認できます。2.1.277に届いていなければ更新です。標準のインストーラーやnpmで入れたなら claude update、HomebrewやWinGetで入れたなら brew upgrade claude-code や winget upgrade Anthropic.ClaudeCode のように、入れ方ごとのコマンドが違います。

そして、動かない環境が1つでも残っているなら、@AGENTS.md の1行だけのCLAUDE.mdは残しておくのが無難です。 公式も、残しても二重に読まれることはないと明記しています。どの設定値でも、インポート済みのファイルは読み飛ばされます。

移行時にやることは、元の形によって違います。

いまの形	やること
`@AGENTS.md` の1行だけのCLAUDE.md	そのままでよい。消してもよい
「AGENTS.mdに従うこと」と文章で書いたCLAUDE.md	消すか、`@AGENTS.md` に置き換える
CLAUDE.mdをAGENTS.mdへのシンボリックリンクにしている	そのままでよい
起動フックでAGENTS.mdを流し込んでいる	直接読まれる環境だけで使っているなら消す。放置すると同じ内容が2回載る

2番目が地味に重要です。文章での指示は、AIが読みに行くと判断して初めて中身が載ります。つまり載るかどうかが確率の問題になる。ここは前の記事で書いた3つの層の話と同じで、@ による取り込みとは1段違います。

このサイトのリポジトリは、CLAUDE.mdが @AGENTS.md の1行です。今回の対応で消せるようになりましたが、当面は残します。手元のデスクトップアプリがまだ2.1.271で、Codexとも併用しているためです。二重読み込みは起きないので、残しておく実害は小さいという判断になります。

13か月かかった対応と、その3週間前に起きたこと

経緯を追うと、今回の形が「妥協案」であることが見えてきます。

時期	出来事
2025年8月	OpenAIが `AGENTS.md` を公開。直後に Issue #6235 が立つ
2025年12月	Linux FoundationのAgentic AI Foundationが発足。AGENTS.mdが管理下に入り、Anthropicも創設メンバーとして参加
2026年2月19日	Anthropic側が「すべてのモデルでプロンプトを共有すると性能が少し落ちる」と説明
2026年8月17日	Issue #6235が「`@AGENTS.md` かシンボリックリンクで」という回答とともにクローズ
2026年8月25日	ShopifyのCEOが公開の場で不満を表明
2026年9月19日	v2.1.277で対応

Issue #6235には、9月19日朝の時点で賛成の👍が5,168件、コメントが399件ついていました。1年以上動かなかったものが、8月末から3週間ほどで実装されています。

その3週間前にあったのが、Shopifyのトビ・リュトケ氏の投稿です。「AGENTS.mdと .agents/skills を読むように方針を変えるまで、社内でClaude Codeを禁止することを考えている」「チームメンバーが違うツールを使うと、記憶が分裂した状態になる。不必要なことだ」。9月19日朝の時点で、1万9千件を超えるいいねがついています。Anthropicがこの投稿を受けて動いたという発表はないので、分かるのは時系列だけです。

これに対する、Claude Code開発チームのThariq氏の返答が、当時の考え方をよく表しています。「Claude Codeをもっと改造しやすくする作業を進めていて、その中にAGENTS.mdを簡単に使えるようにすることも含まれます」「理由は、モデルファミリーに互換性がないと考えているからです。システムプロンプトは性能に大きく影響します」。

そして今回の発表後、リュトケ氏本人が「素晴らしい決定です」と引用しています。OpenAIでCodexを担当するティボ・ソティオー氏も「こちらへおいで」と反応していました。

対応の投稿そのものは、公開から半日ほどで表示161万・いいね1.8万(9月19日朝の時点)。Hacker Newsのスレッドを上から読むと、「ようやく」「最低限のことをしただけ」「なぜこんなに時間がかかったのか」が並びます。少なくとも反応の上位は、素直な歓迎というより長かった、という空気でした。

考察 9日前に静かに置かれた「mod」という仕組み

ここまでが、公式ドキュメントと公開ソース、当事者の投稿で確認できる事実です。ここから先は筆者の読みになります。

今回の実装には、見逃せない特徴があります。CLAUDE.md を読む処理を書き換えたのではなく、agents-md という名前のプラグインを同梱する形で足されていることです。

Claude Codeの起動情報を出力させると、読み込まれたプラグインの一覧に agents-md が並びます。起動時のあの通知行に agents-md: という接頭辞が付くのも、そのためです。

Anthropicはこれを「mod」と呼んでいて、ソースも公開しています。ハーネス、つまりAIモデルを包んで動かしている本体側の振る舞いを、差し替え可能な部品にしたものです。

興味深いのは日付です。このフォルダが公開リポジトリに現れたのは9月9日で、そのときの中身は差分表示・テレメトリ・組織向けの保護という3本でした。agents-md が加わったのは9日後の9月18日。同梱4本のうちの4本目です。

発表者はこれを「Claude Codeのハーネスをカスタマイズするための、近日公開の方法」だと説明し、「独自版のプロジェクト指示も自分で作れるようになる」と続けています。仕組み自体はまだ一般公開されておらず、公式ドキュメントにも項目がありません。

つまり、2月に語られた「モデルごとに最適化したい」という考えは、撤回されたのではなく、差し替え可能な部品の側に移されたのだと思います。本体は CLAUDE.md を読むままで、AGENTS.md を読む挙動はプラグインが足している。この作りなら、標準に合わせつつ、Claude向けの最適化という主張も手放さずに済みます。

もっとも、これは意図というより手順の問題だった可能性もあります。9月9日にmodの土台ができていたのだから、そこに載せるのがいちばん早かっただけ、という見方です。どちらなのかは、今のところ外からは分かりません。

初期設定が「両方」ではなく「CLAUDE.mdがあればそちら」になっているのも、その名残ではないでしょうか。CLAUDE.mdを置いている環境の挙動は、この更新でまったく変わりません。慎重と言えば慎重ですし、「意地でもCLAUDE.mdを優先したい気持ちが出ている」と受け取られても仕方がない気もします。

では、この先どうなるか。当たり外れを後から確かめられる形で、3つ挙げておきます。

agents.md の対応エージェント一覧にClaude Codeが載るか。 9月19日時点では、CodexやCursor、Gemini CLIなど十数種が並ぶ中にClaude Codeの名前はありません
.agents/skills が読まれるようになるか。 リュトケ氏の要求はファイルとフォルダの2つで、今回はファイルだけでした
modが一般に公開され、第三者が作ったmodが出てくるか。 ここが開くと、指示の読み方だけでなく、ハーネスの振る舞いを外から差し替える話になります

個人的には、3つ目がいちばん大きい変化になると見ています。指示書のファイル名がどちらでもよくなること自体は、率直に言えば小さな話です。それよりも、ユーザーが最初に目にしたmodが「プロジェクト指示の読み方」だったことのほうが気になっています。自分で書けるようになったとき、まず差し替えたくなるのはそこだろうと思うからです。

まとめ触る場所は変わらない

v2.1.277から、CLAUDE.mdが無いリポジトリではAGENTS.mdが読まれる。 設定は不要
CLAUDE.local.md を1つ置くだけで読まれなくなる。 個人メモを残すなら、設定を claude-md-and-agents-md に
設定値は4つ。/config の「Project instructions」か、~/.claude/settings.json の pluginConfigs。プロジェクト側の設定ファイルでは変えられない
.agents フォルダは読まれない。 Codexとスキルを共有するなら、シンボリックリンクは今も必要
Bedrock・Vertex・Foundry経由、古いバージョン、テレメトリを切った環境では使えない。動かない環境が残るなら @AGENTS.md の1行は残す
実装は本体の書き換えではなく、同梱プラグイン(mod)の追加。ソースは公開されている

指示書の運用そのものは、今回の対応で変わりません。ルールを足したくなったらAGENTS.md、CLAUDE.mdは触らない。触る場所を1つに決めておけば、どちらのファイル名が主役になっても困らないからです。

お使いの環境でどう読まれているかは、Claude Codeを起動したときの最初の数行で分かります。次に立ち上げたとき、AGENTS.md loaded の行が出ているかどうか、一度見てみてください。

設定は不要 ただしCLAUDE.mdが1つでもあれば従来どおり