結論：CLAUDE.md が無いプロジェクトだけ AGENTS.md を読む（2026年9月19日時点）
Claude Code は v2.1.277（GitHub Releases 2026年9月18日公開）から、AGENTS.md をプロジェクト指示として直接読めるようになりました。ただし既定で読むのは「作業ディレクトリとその上位に CLAUDE.md が 1 つも無いプロジェクト」だけで、両方ある時は CLAUDE.md が優先されます。リリースノートの原文は「in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under “Project instructions” in /config (not yet on Bedrock, Vertex or Foundry)」です（GitHub Releases v2.1.277）。
- 優先順位：AGENTS.md と CLAUDE.md の両方がある時、既定では CLAUDE.md だけが読まれます。両方読ませたい時は
/configの Project instructions をclaude-md-and-agents-mdに変えます。 - 未対応の環境：Amazon Bedrock などの第三者プロバイダ経由、テレメトリを無効にしたセッション、更新後の最初のセッションでは AGENTS.md を直接読めません。こうした環境では従来どおり CLAUDE.md に
@AGENTS.mdと書いて import します。 - 共通化の型：Codex・Cursor・Claude Code を併用するチームは、規約を AGENTS.md の 1 本に寄せ、CLAUDE.md には import 行と Claude Code 固有の 3 項目だけを残す構成にすると、3 つのツールが同じ指示を読みます。
対象読者：Codex や Cursor と Claude Code を同じリポジトリで併用していて、CLAUDE.md と AGENTS.md の二重管理に手間を取られている開発者・テックリード。読み終えたらできること：自分のリポジトリで Claude Code がどのファイルを読むかを判定し、指示ファイルを 1 本に寄せる移行を始められます。
この記事は、GitHub のリリースノートと公式ドキュメント「How Claude remembers your project」の AGENTS.md 節の記述を根拠に書いています。執筆時点で筆者の手元の Claude Code は v2.1.277 より前のバージョンで、/config の画面は実機で確認できていません。そのためスクリーンショットは載せず、挙動の説明はすべて「公式ドキュメントによれば」「リリースノートによれば」の形で書き分けます。後半の移行例は想定シナリオで、実在の企業の事例や測定値ではありません。
v2.1.277 で何が変わったか：AGENTS.md を直接読む条件
これまで Claude Code がプロジェクト指示として読むのは CLAUDE.md だけでした。AGENTS.md を運用しているリポジトリでは、CLAUDE.md に @AGENTS.md と書いて import するか、シンボリックリンクを張るのが定番の回避策でした。当サイトのCLAUDE.md 設計・運用ガイドでも「Claude Code は AGENTS.md を直接読まない」と説明していましたが、v2.1.277 でこの前提が変わりました。
公式ドキュメントによれば、Claude Code は AGENTS.md をプロジェクト指示として読めるため、他のコーディングエージェント向けに整えたリポジトリが「CLAUDE.md の追加も、import も、設定も無しで」動きます。既定で何が読まれるかは、リポジトリにあるファイルの組み合わせで決まります。
| リポジトリにあるファイル | Claude Code が読むもの |
|---|---|
| AGENTS.md だけ | AGENTS.md |
| AGENTS.md と CLAUDE.md の両方 | CLAUDE.md だけ |
| @AGENTS.md を import した CLAUDE.md | CLAUDE.md と import 先の AGENTS.md |
変更点を項目別に整理すると次のとおりです。
| 項目 | 内容（出典） |
|---|---|
| 対応バージョン | v2.1.277 以降（リリースノート・公式ドキュメント） |
| 公開日 | 2026年9月18日（GitHub Releases の公開日時は UTC 18:06） |
| 既定の挙動 | CLAUDE.md が無いプロジェクトでは AGENTS.md を読む |
| 切替方法 | /config の Project instructions（4 つの値） |
| 未対応 | Bedrock・Vertex・Foundry（リリースノート）。公式ドキュメントでは「機能フラグを取得しないセッション」全般 |
| 読み込みの確認 | 対話セッションの会話に no CLAUDE.md found; AGENTS.md loaded: （パス） の行が出る |
判定で「CLAUDE.md がある」と数えられるのは、作業ディレクトリとその上位にある CLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md の 3 種類です。一方、ユーザー全体の ~/.claude/CLAUDE.md、組織の管理 CLAUDE.md、.claude/rules/ のファイルは判定に数えられず、AGENTS.md と一緒に読み込まれ続けます。
読み込む範囲も公式ドキュメントに書かれています。セッション開始時は、作業ディレクトリとその上位にあるすべての AGENTS.md と .claude/AGENTS.md を読みます。サブディレクトリの AGENTS.md は、Claude がそのディレクトリのファイルを Read ツールで開いた時に、そこに 3 種類の CLAUDE.md が無ければ追加で読まれます。AGENTS.md の中の @path import は展開され、claudeMdExcludes の除外パターンも効きます。逆に AGENTS.local.md・AGENTS.override.md・.agents/ ディレクトリ配下は読まれません。
この変更は開発者コミュニティの要望が長く続いていたもので、gihyo.jp の報道（2026年9月19日）によれば、Anthropic で Claude Code の開発に携わる Thariq Shihipar 氏が 9月18日に X で案内しました。Hacker News でも「Claude Code now reads AGENTS.md if there is no Claude.md」のスレッドが 600 ポイント・コメント 200 件を超えています（Hacker News、2026年9月19日参照時点）。
優先順位と切替：/config の Project instructions で選ぶ 4 つの値
既定の優先順位を変えたい時は、Claude Code のセッションで /config と入力して設定パネルを開き、Project instructions を次の 4 つの値のいずれかにします（公式ドキュメント「Choose which instruction files load」）。
| 値 | Claude Code が読むもの | 向いている場面 |
|---|---|---|
claude-md-or-agents-md（既定） |
CLAUDE.md が無い時だけ AGENTS.md を読む | AGENTS.md だけで運用しているリポジトリ |
claude-md-and-agents-md |
CLAUDE.md と AGENTS.md の両方を読む | 共通の AGENTS.md と Claude Code 固有の CLAUDE.md を並べて置くチーム |
claude-md |
CLAUDE.md だけを読む | v2.1.277 より前と同じ挙動に固定したい時 |
managed-only |
組織の管理 CLAUDE.md と自動メモリだけ | 起動時の指示を組織の管理ファイルに限定したい時 |
押さえておきたい点が 3 つあります。1 つ目は、claude-md-and-agents-md では各ディレクトリで CLAUDE.md が先、AGENTS.md が後の順に読まれ、すでに読み込んだ AGENTS.md は飛ばされることです。CLAUDE.md が import やシンボリックリンクで AGENTS.md を参照していても、同じ内容が二重に読まれることはありません。2 つ目は、managed-only でも、サブディレクトリの CLAUDE.md や .claude/rules/ は Claude がそこのファイルを読んだ時に読み込まれることです。3 つ目は、gihyo.jp の記事も指摘しているとおり、CLAUDE.md を読まずに AGENTS.md だけを読む専用の値は用意されていないことです。
設定ファイルで指定する方法もあります。公式ドキュメントによれば、組み込みプラグイン agents-md の ID の下に pluginConfigs で書きます。置き場所は ~/.claude/settings.json、--settings で渡すファイル、管理設定のいずれかで、プロジェクト設定とローカル設定のファイルに書いても無視されます。リポジトリにコミットした設定でチーム全員の挙動をそろえることはできない、という意味なので注意してください。
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}変更は、次に送るメッセージと、それ以降の新しいセッションから反映されます。
設定経由で読む AGENTS.md と CLAUDE.md の違い
Project instructions の設定を通じて読まれた AGENTS.md は、CLAUDE.md とまったく同じ扱いにはなりません。公式ドキュメント「Where AGENTS.md differs from CLAUDE.md」には次の 4 点が挙げられています。
| 場面 | CLAUDE.md | 設定経由で読む AGENTS.md |
|---|---|---|
/memory と /context の Memory files 一覧 |
表示される | 表示されない（読み込み行を見るか、Claude にプロジェクト指示の内容を聞いて確認する） |
InstructionsLoaded フック |
発火する | 発火しない（CLAUDE.md から import した AGENTS.md では通常どおり発火） |
--add-dir で追加したディレクトリ（CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 設定時） |
CLAUDE.md が読まれる | AGENTS.md は読まれない |
作業ディレクトリの外を指す @path import |
外部 import の承認を求められる | そのプロジェクトで承認済みの時だけ、確認なしで読まれる |
フックで指示ファイルの読み込みを監査しているチームや、--add-dir で複数リポジトリをまたいで作業しているチームは、import 方式のほうが従来の仕組みと噛み合います。
AGENTS.md と CLAUDE.md の役割分担：共通に書くもの、Claude Code に残すもの
AGENTS.md は、公式サイト（agents.md）の説明では「エージェントのための README」にあたる、オープンな Markdown 形式です。必須の項目は無く、よく書かれる内容として、プロジェクトの概要、ビルドとテストのコマンド、コードスタイル、テストの手順、セキュリティ上の注意が挙げられています。同サイトによれば 6 万以上のオープンソースプロジェクトで使われ、現在は Linux Foundation 傘下の Agentic AI Foundation が管理しています。
併用するツール側の読み方も、それぞれの公式ドキュメントで確認しておきます。
| ツール | AGENTS.md の読み方（各公式ドキュメント） |
|---|---|
| Codex | グローバル（~/.codex）とプロジェクトの 2 層。プロジェクトルートから作業ディレクトリまでを下りながら、各ディレクトリで AGENTS.override.md、AGENTS.md の順に探して 1 ファイルずつ連結する。合計サイズは既定で 32 KiB（project_doc_max_bytes）まで |
| Cursor | プロジェクトルートとサブディレクトリの AGENTS.md に対応。入れ子の AGENTS.md は、そのディレクトリ配下のファイルを扱う時に親の内容と合わせて適用され、より具体的な指示が優先される。.cursor/rules の簡易な代替という位置づけ |
| Claude Code | v2.1.277 以降。既定では CLAUDE.md が無い時だけ、作業ディレクトリとその上位の AGENTS.md と .claude/AGENTS.md を読む |
出典は Codex が「Custom instructions with AGENTS.md」、Cursor が「Rules」の AGENTS.md 節です。3 つのツールに共通するのは「リポジトリのルートに置いた AGENTS.md は読まれる」という 1 点で、override ファイルやサイズ上限のような細部はツールごとに違います。共通化の土台にするのは、この共通部分だけにしておくのが安全です。
そのうえで、2 つのファイルの役割を次のように分けます。
| AGENTS.md（全ツール共通） | CLAUDE.md（Claude Code 固有） |
|---|---|
| ビルドとテストのコマンド | プランモードを使う範囲 |
| コード規約 | サブエージェントとスキルの呼び分け |
| ディレクトリ構成 | .claude/rules/ とフックの前提 |
| PR とコミットの決まり | （先頭に @AGENTS.md の import 行） |
判断基準は「その指示は、どのツールが読んでも意味が通じるか」です。pnpm test を実行する、コミットメッセージは Conventional Commits にする、といった規約はどのエージェントにも通じるので AGENTS.md に置きます。プランモード、サブエージェント、スキル、フックは Claude Code の機能名なので、Codex や Cursor が読んでも意味を持ちません。こうした指示を AGENTS.md に混ぜると、他のツールにとってはノイズになります。
CLAUDE.md に何を書くと効くのか、逆に何を消すべきかは、Claude 5 世代のコンテキスト新ルールと CLAUDE.md の書き換えで整理しています。AGENTS.md に寄せる前に、そもそも不要になった指示を落としておくと移行が軽くなります。
Codex・Cursor・Claude Code で指示ファイルを 1 本にする 5 ステップ
ここからは、CLAUDE.md と AGENTS.md を別々に育ててきたリポジトリを、AGENTS.md の 1 本に寄せる手順です。コマンドは一般的なシェルと、各公式ドキュメントに載っているものだけを使います。
ステップ 1：2 つのファイルを棚卸しする
まず Claude Code のバージョンと、リポジトリ内の指示ファイルの場所を確認します。CLAUDE.local.md は判定に数えられるので、個人で置いている人がいないかも見ておきます。
claude --version
find . -path ./node_modules -prune -o \
\( -name 'AGENTS.md' -o -name 'CLAUDE.md' -o -name 'CLAUDE.local.md' \) -print
wc -l AGENTS.md CLAUDE.md次に、2 つのファイルの中身を分類します。目視でもできますが、Claude Code に表を作らせると食い違いを拾いやすくなります。
CLAUDE.md と AGENTS.md を読み比べて、各指示を次の 3 つに分類した表を作ってください。
(a) 両方に同じ内容がある
(b) 両方にあるが内容が食い違っている（どちらが新しいかは git log で確認）
(c) Claude Code の機能（プランモード・サブエージェント・スキル・フック・.claude/rules/）を前提にしている
ファイルはまだ変更しないでください。
不足している情報があれば、最初に質問してから作業を開始してください。ステップ 2：共通部分を AGENTS.md へ寄せる
分類 (a) と (b) を AGENTS.md に統合します。(b) の食い違いは、人が正しいほうを決めてから反映します。どちらが正しいかをエージェントに決めさせないのがポイントです。
さきほどの分類表の (a) と (b) を AGENTS.md に統合する差分を提案してください。
(b) は私が指定した側の内容を採用します：［ここに採用する側を書く］
見出しは「概要／セットアップ／ビルドとテスト／コード規約／PR とコミット／セキュリティ」の順にそろえてください。
CLAUDE.md はまだ触らないでください。仮定した点は必ず「仮定」と明記してください。ステップ 3：CLAUDE.md を import と固有 3 項目に絞る
CLAUDE.md からは AGENTS.md に移した内容を削り、先頭の import 行と、Claude Code 固有の指示だけを残します。公式ドキュメントによれば、Claude は import されたファイルを先に読み、その後に残りを読みます。
@AGENTS.md
## Claude Code
- src/billing/ 配下の変更はプランモードを使う
- 調査だけの依頼はサブエージェントに任せ、編集はメインの会話で行う
- .claude/rules/ のパス別ルールとフックが前提。フックが止めた操作は回避せず、理由を報告する1 行目の書き方と「プランモード」の例は公式ドキュメントの記載例に沿っています。2 行目と 3 行目は構成例なので、自分のチームの運用に合わせて書き換えてください。Claude Code 固有の内容が何も無いなら、CLAUDE.md をシンボリックリンク（ln -s AGENTS.md CLAUDE.md）にする方法も公式に紹介されています。ただし Edit／Write ツールはシンボリックリンク越しの書き込みを拒否すること、Windows では管理者権限か開発者モードが要り、Git の core.symlinks が無効だと 1 行だけのテキストファイルとして checkout されることが注意点として挙げられています。Windows の開発者がいるチームは import 方式を選んでください。
ステップ 4：Project instructions の値を決める
| リポジトリの状態 | 選ぶ値 |
|---|---|
| import 入りの薄い CLAUDE.md を残す | 既定のままでよい（CLAUDE.md が読まれ、import 経由で AGENTS.md も読まれる） |
| CLAUDE.md を消して AGENTS.md だけにする | 既定のままでよい。ただし全員が対応環境であることが条件 |
| AGENTS.md だけのリポジトリで、個人の CLAUDE.local.md も使いたい | claude-md-and-agents-md |
| CLAUDE.md に import を書かず、2 つのファイルを並べて置く | claude-md-and-agents-md |
チームに Bedrock 経由の人やテレメトリを切っている人が 1 人でもいるなら、1 行目の「import 入りの薄い CLAUDE.md を残す」構成が最も安全です。この構成は Project instructions の値にも、Claude Code のバージョンにも依存しません。
ステップ 5：各ツールで読み込みを確認する
最後に、3 つのツールが同じ指示を読んでいるかを確かめます。
- Claude Code（import 方式）：次のセッションで
/contextを実行し、Memory files に CLAUDE.md が出ることを確認します（公式ドキュメントの確認手順）。 - Claude Code（AGENTS.md だけ）：対話セッションの会話に
no CLAUDE.md found; AGENTS.md loaded:の行が出ることを確認します。/memoryには出ないので、そこを探さないでください。 - Codex：公式ドキュメントの確認コマンド
codex --ask-for-approval never "Summarize the current instructions."で、読み込んだ指示を要約させます。 - Cursor：公式ドキュメントに確認専用のコマンドは載っていないため、エージェントのチャットで同じ質問を投げて、AGENTS.md の見出しが返るかを見ます。
いまプロジェクト指示として読み込んでいる内容を、読み込み元のファイルごとに要約してください。
AGENTS.md 由来の指示があれば、その見出し名を挙げてください。
読み込めていないファイルがあれば、推測で補わずに「読み込めていない」と答えてください。移行の想定例：二重管理から AGENTS.md 共通と CLAUDE.md 固有 3 項目へ
以下は想定シナリオ（構成例）です。実在の企業の事例や測定値ではありません。受託開発を行う開発チームで、メンバーが Codex・Cursor・Claude Code を各自の好みで併用している、という状況を置きます。
| Before | After | |
|---|---|---|
| 構成 | CLAUDE.md と AGENTS.md の二重管理 | AGENTS.md 共通と CLAUDE.md 固有 3 項目 |
| 規約の置き場所 | 同じ規約を 2 か所に書く | 規約は AGENTS.md の 1 か所 |
| 更新のされ方 | 片方だけ更新される | CLAUDE.md は import と固有 3 項目 |
| 結果 | ツールごとに挙動が割れる | レビュー対象は 1 ファイル |
Before の状態で起きるのは、たとえば次のような食い違いです。テストコマンドを npm test から pnpm test に切り替えた時、Cursor を使うメンバーが AGENTS.md だけを直し、CLAUDE.md には古いコマンドが残る。Claude Code は既定で CLAUDE.md だけを読むので古いコマンドを実行し、Codex と Cursor は新しいコマンドを実行する。レビューで「なぜ Claude Code だけ違う動きをするのか」を調べる時間が発生します。
After では、5 ステップに沿って規約を AGENTS.md に寄せ、CLAUDE.md は import 行と固有 3 項目（プランモードを使う範囲、サブエージェントとスキルの呼び分け、.claude/rules/ とフックの前提）だけにします。このチームには Bedrock 経由で Claude Code を使う CI があるという想定なので、CLAUDE.md は消さずに残し、Project instructions は既定のままにします。規約を変える Pull Request は AGENTS.md の差分だけを見ればよくなり、CLAUDE.md が変わるのは Claude Code の使い方を変える時だけになります。
チーム全体の設定を標準化する時の考え方は、Claude Code 開発環境標準化 7 項目の「設定ファイルの責任範囲を分ける」もあわせて参照してください。
コピペ用：AGENTS.md の雛形と、移行に使える指示例
AGENTS.md の雛形です。見出しは agents.md 公式サイトが挙げる定番の項目に沿っています。［ ］の中を自分のプロジェクトの内容に置き換えてください。
# AGENTS.md
## 概要
- ［このリポジトリが何をするものか。1〜3 行］
- 主要ディレクトリ：［src/ = アプリ本体、packages/ = 共有ライブラリ、docs/ = 設計資料］
## セットアップ
- 依存の導入：［pnpm install］
- 開発サーバー：［pnpm dev］
## ビルドとテスト
- テスト：［pnpm test］。変更したパッケージのテストは必ず実行する
- 静的検査：［pnpm lint］と［pnpm typecheck］。コミット前に両方を通す
## コード規約
- ［TypeScript strict。any を新しく増やさない］
- ［既存の命名とディレクトリの切り方に合わせる。新しい流儀を持ち込まない］
## PR とコミット
- コミットメッセージ：［Conventional Commits］
- PR の説明に「変更理由・確認方法・影響範囲」を書く
## セキュリティ
- 秘密値（API キー・トークン・パスワード・内部 URL）をこのファイルにもコードにも書かない
- 環境変数名だけを書く：［DATABASE_URL、PAYMENT_API_KEY］。値は各自の環境で設定する
## やらないこと
- ［本番データベースへの接続、main への直接 push、依存の大きなバージョン上げ］は人に確認する移行の最後に、機密の混入を点検する指示例も置いておきます。AGENTS.md は複数のツールに渡るファイルなので、CLAUDE.md より一段厳しく見ます。
AGENTS.md と CLAUDE.md、および両ファイルから @ で import しているファイルを確認し、
API キー・トークン・パスワード・内部ホスト名・個人名のような、リポジトリ外に出すべきでない情報が
書かれていないか点検してください。
見つけた場合は値そのものを出力せず、ファイル名と行番号、種類だけを報告してください。
判断に迷うものは「要確認」として別に挙げてください。注意点：AGENTS.md を直接読めない環境と、モノレポでの置き場所
AGENTS.md を直接読めないセッション
公式ドキュメント「When AGENTS.md support is unavailable」によれば、次のセッションでは Claude は CLAUDE.md だけを読み、/config の設定パネルに Project instructions の項目自体が表示されません。
- v2.1.277 より前のバージョン
- Bedrock などの第三者プロバイダ・テレメトリ無効：Anthropic から機能フラグを取得しないセッションが該当します。環境変数のドキュメントでは、Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、Microsoft Foundry といった第三者プロバイダのセッション、Claude apps gateway のセッション、そして
DISABLE_TELEMETRY・DO_NOT_TRACK・DISABLE_GROWTHBOOK・CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICを設定したセッションが挙げられています - 更新後の最初のセッション：対応バージョンへ上げた直後の 1 回目は機能フラグがまだ届いておらず、AGENTS.md は次のセッションから読まれます
- フック無効化・agents-md プラグイン無効：
disableAllHooksかallowManagedHooksOnlyを設定している、または/pluginで組み込みの agents-md プラグインを無効にしている場合
対処はどれも同じで、CLAUDE.md から import します。AGENTS.md と同じ場所に CLAUDE.md を置き、1 行目に @AGENTS.md と書くだけです。テレメトリの設定やクラウド事業者経由かどうかは、同じチームの中でも人や CI ごとに違うことがあります。「対応したから CLAUDE.md を消す」と決める前に、チーム全員と CI の接続経路を確認してください。
既存の回避策はどう片付けるか
公式ドキュメント「Remove an earlier AGENTS.md workaround」の整理を表にします。
| いまの構成 | 対応 |
|---|---|
CLAUDE.md に @AGENTS.md を書いている |
そのままでよい。どの値でも二重には読まれない。中身が import だけなら CLAUDE.md を消してもよいが、直接読めないセッションがあるなら残す |
| CLAUDE.md に文章で「AGENTS.md を読んで」と書いている | Claude がファイルを開くと判断した時しか読まれない。CLAUDE.md を消すか、文章を @AGENTS.md の import に置き換える |
| CLAUDE.md を AGENTS.md へのシンボリックリンクにしている | 何もしなくてよい（リンクを消してもよい）。どちらでも内容が読まれるのは 1 回 |
| SessionStart フックで AGENTS.md を出力している | フックを外す。直接読まれるようになると、同じ内容が 2 回コンテキストに入る |
モノレポでの置き場所
agents.md 公式サイトは、大きなモノレポではパッケージごとに入れ子の AGENTS.md を置き、編集対象に最も近いファイルを優先する使い方を案内しています。Codex はルートから作業ディレクトリまでの AGENTS.md を連結し、Cursor は入れ子の AGENTS.md を配下のファイルに適用します。Claude Code も上位ディレクトリとサブディレクトリの AGENTS.md を読みますが、既定値のままだと次の 2 点でつまずきます。
- 上位に CLAUDE.md が 1 つでもあると、AGENTS.md は読まれません。ルートに CLAUDE.md、各パッケージに AGENTS.md という混在構成では、パッケージの AGENTS.md が Claude Code に届きません。混在させるなら
claude-md-and-agents-mdにするか、パッケージごとに import 入りの CLAUDE.md を置きます。 AGENTS.override.mdは Codex だけの仕組みです。Claude Code は読まないと明記されているので、決済まわりの特別ルールのような重要な指示を override ファイルにだけ書くと、Claude Code には伝わりません。
ルートの AGENTS.md には全パッケージ共通の短い規約だけを置き、パッケージ固有のコマンドは各パッケージの AGENTS.md に分ける構成が、3 つのツールのどれでも素直に動きます。パッケージを絞って作業させる手順そのものは、Claude Code でモノレポを扱う実践ガイドを参照してください。
【要注意】よくある失敗パターンと回避策
失敗 1：両方置いたまま、中身が食い違う
❌ CLAUDE.md と AGENTS.md の両方に規約を書き、「AGENTS.md に対応したのだから AGENTS.md を直せば Claude Code にも伝わる」と考える。
⭕ 規約は AGENTS.md の 1 か所に置き、CLAUDE.md は import 行と固有の指示だけにする。並べて置くなら claude-md-and-agents-md を選ぶ。
なぜ重要か：既定値では、両方ある時に読まれるのは CLAUDE.md だけです。AGENTS.md の更新は Claude Code に届かず、ツールごとに挙動が割れます。公式ドキュメントも、矛盾する指示があると Claude がどちらかを任意に選ぶ可能性があると注意しています。
失敗 2：Bedrock 経由の環境で AGENTS.md だけにする
❌ 手元で動いたので CLAUDE.md を削除し、Bedrock 経由の CI やメンバーの環境でも同じように読まれると思い込む。
⭕ 直接読めないセッションが 1 つでもあるなら、@AGENTS.md を書いた CLAUDE.md を残す。
なぜ重要か：未対応のセッションでは Claude は CLAUDE.md だけを読むため、AGENTS.md だけのリポジトリではプロジェクト指示が無い状態で動きます。/config に Project instructions が出ているかどうかが、対応環境かを見分ける手がかりになります。
失敗 3：AGENTS.md に機密を書き込む
❌ 「エージェントが迷わないように」と、ステージング環境のパスワードや API キー、社内の URL を AGENTS.md に書く。
⭕ 書くのは環境変数名と手順だけにする。値は各自の環境か、シークレット管理の仕組みに置く。
なぜ重要か：AGENTS.md はリポジトリにコミットされ、Codex・Cursor・Claude Code など複数のツールのコンテキストに入ります。1 つのツールだけが読む前提だった CLAUDE.md より、内容が届く先が広くなります。CLAUDE.md の機密の扱いはCLAUDE.md 設計・運用ガイドの「200行・矛盾・機密の3原則」と同じ考え方です。
失敗 4：何でも書いて AGENTS.md を巨大にする
❌ 共通化を機に、設計資料や過去の経緯まで AGENTS.md に集約する。
⭕ 毎回必要な規約だけを残し、詳細は docs/ に置いて必要な時に読ませる。モノレポではパッケージごとの AGENTS.md に分ける。
なぜ重要か：Codex は連結した指示の合計が既定で 32 KiB に達すると、それ以降のファイルを追加しません。Claude Code の公式ドキュメントも CLAUDE.md について 1 ファイル 200 行未満を目安とし、長いファイルはコンテキストを消費して指示の守られ方が落ちると説明しています。@path の import は整理には役立ちますが、import 先も起動時に読み込まれるためコンテキストの節約にはなりません。
よくある質問
Claude Code は AGENTS.md に対応していますか？
v2.1.277（2026年9月18日公開）以降で対応しています。既定では、作業ディレクトリとその上位に CLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md のいずれも無い時に、AGENTS.md をプロジェクト指示として読みます。バージョンは claude --version で確認できます。
AGENTS.md と CLAUDE.md の両方がある時、どちらが優先されますか？
既定値（claude-md-or-agents-md）では CLAUDE.md だけが読まれます。両方を読ませたい時は、/config の Project instructions を claude-md-and-agents-md に変えるか、CLAUDE.md の中で @AGENTS.md を import します。
CLAUDE.md を無視して AGENTS.md だけを読ませる設定はありますか？
ありません。選べる値は 4 つで、AGENTS.md だけを読む専用の値は用意されていません。AGENTS.md だけにしたい場合は、プロジェクトの CLAUDE.md と CLAUDE.local.md を置かない構成にします。ユーザー全体の ~/.claude/CLAUDE.md と組織の管理 CLAUDE.md は、その場合も一緒に読み込まれます。
Bedrock や Vertex 経由でも AGENTS.md を読めますか？
2026年9月19日時点では読めません。リリースノートに「not yet on Bedrock, Vertex or Foundry」とあり、公式ドキュメントでも第三者プロバイダのセッションは対象外です。CLAUDE.md に @AGENTS.md と書いて import してください。
アップデートしたのに AGENTS.md が読まれません。どこを見ればよいですか？
公式ドキュメントの記述から、確認する順番は次のとおりです。更新後の最初のセッションではないか（次のセッションから有効）。作業ディレクトリかその上位に CLAUDE.md や CLAUDE.local.md が無いか。テレメトリを無効にする環境変数を設定していないか。フックの無効化設定や、agents-md プラグインの無効化をしていないか。/memory には表示されない仕様なので、会話に出る読み込み行で確認します。
まとめ：今日やること 3 つ
- バージョンと環境を確認する：
claude --versionで v2.1.277 以降かを見て、チームと CI に Bedrock 経由やテレメトリ無効のセッションが無いかを洗い出します。 - 規約を AGENTS.md に寄せる：5 ステップに沿って、CLAUDE.md を import 行と固有 3 項目まで薄くします。迷ったら CLAUDE.md は消さずに残すのが安全側です。
- 3 つのツールで読み込みを確認する：同じ質問を Claude Code・Codex・Cursor に投げて、同じ規約が返ることを確かめます。
AGENTS.md そのものの書き方やツール横断の考え方は、Uravation の解説「AGENTS.mdとは｜対応23ツールとClaude Codeの例外」と「Codex AGENTS.mdの書き方｜7パターンと階層設計」も参考になります（前者は Claude Code を例外として扱っていた v2.1.277 公開前の記事のため、Claude Code の扱いは本記事の内容が最新です）。チームでの指示ファイル設計や Claude Code の導入について相談したい場合は、Uravation のお問い合わせから連絡できます。
運営元 Uravation よりこの事例を自社の業務で試す場合のテーマ選定・評価・本番移行の確認項目を、無料のチェックリストにまとめています。 Claude Code業務自動化PoCチェックリストを受け取る（無料）
参考・出典
いずれも参照日は 2026年9月19日です。
- anthropics/claude-code Releases v2.1.277（GitHub、2026年9月18日公開）
- Claude Code changelog（Claude Code Docs、2.1.277 の項）
- How Claude remembers your project：AGENTS.md（Claude Code Docs）
- Environment variables：Features that need feature-flag fetching（Claude Code Docs）
- AGENTS.md 公式サイト（Agentic AI Foundation）
- Custom instructions with AGENTS.md（Codex 公式ドキュメント）
- Rules（Cursor 公式ドキュメント、AGENTS.md 節）
- Claude Code、AGENTS.md に対応（gihyo.jp、2026年9月19日）
- Claude Code now reads AGENTS.md if there is no Claude.md（Hacker News、2026年9月18日）
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation 代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向け AI 研修・導入支援。著書『AIエージェント仕事術』『Claude仕事術』（SBクリエイティブ・シリーズ累計50,000部突破）。SBクリエイティブ「ビジネス+IT」ほかで生成AI連載を執筆。
