本文へ移動
問い合わせ設計室相談する

CLAUDE.md と AGENTS.md の違いと併用の方法(Claude Code が AGENTS.md を読む条件)

公開: 著者: 問い合わせ設計室 運営事務局

CLAUDE.md は Claude Code が読む作業ルールのファイルで、AGENTS.md は特定のツールに限らない共通の作業ルールのファイルです。この記事では、2 つの違い、Claude Code が AGENTS.md を読む条件、併用するときの書き分けを説明します。

結論から書くと、Claude Code は、CLAUDE.md がないときだけ AGENTS.md を自動で読みます。両方を使うときは、共通のルールを AGENTS.md に書き、CLAUDE.md の先頭に @AGENTS.md と書いて読み込む形にすると、同じことを 2 か所に書かずに済みます。

この記事の仕様は、2026 年 11 月 21 日に各ツールの公式ドキュメントで確認した内容です。Claude Code が AGENTS.md を直接読むようになる前に書かれた記事には、「Claude Code は AGENTS.md を読まない」と説明しているものがあります。いまの公式ドキュメントとは内容が違うので、注意してください。

CLAUDE.md と AGENTS.md の違い

どちらも、AI のコーディングツールが作業の最初に読む「作業ルールのメモ」です。中身は普通の Markdown で、決まった項目はありません。違うのは、読むツールと、置き場所の数え方と、長さの上限です。

CLAUDE.md AGENTS.md
位置づけ Claude Code のためのファイル 複数のツールに共通の、公開された形式
読むツール Claude Code Codex など多くのツール。Claude Code も条件つきで読む
置き場所 作業フォルダ、その上の階層、ユーザー共通の場所(~/.claude/CLAUDE.md) プロジェクトの最上位と、その中の各フォルダ
長さの目安と上限 1 ファイル 200 行未満が目安 Codex は合計 32 KiB まで(初期設定)
管理している団体 Anthropic Linux Foundation の下にある Agentic AI Foundation

AGENTS.md の公式サイトは、必須の項目はなく、好きな見出しを使ってよいとしています。フォルダごとに置いた場合は、編集するファイルにいちばん近い AGENTS.md が優先されます。

Codex は、プロジェクトの最上位から作業フォルダまでをたどり、フォルダごとに 1 つずつファイルを読んでつなげます。同じフォルダに AGENTS.override.md があれば、そちらが使われます。

Claude Code が AGENTS.md を読む条件

初期設定の Claude Code は、作業フォルダにも、その上の階層にも CLAUDE.md がないときだけ、AGENTS.md を自動で読みます。この動作には Claude Code の v2.1.277 以降が必要です。

CLAUDE.md が 1 つでもあると、AGENTS.md は自動では読まれません。併用しているのに AGENTS.md のルールが効かないときは、まずここを疑ってください。

Claude Code が AGENTS.md を読むかどうかの流れ。CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md のどれもなければ AGENTS.md を自動で読む。どれかがあるときは、@AGENTS.md の指定か、両方を読む設定があれば AGENTS.md も読む

公式ドキュメントによると、「CLAUDE.md がある」と数えられるのは次の 3 つです。

  • 作業フォルダか、その上の階層にある CLAUDE.md
  • 同じ範囲にある .claude/CLAUDE.md
  • 同じ範囲にある CLAUDE.local.md(自分だけのメモ用のファイル)

ユーザー共通の ~/.claude/CLAUDE.md、組織が配る CLAUDE.md、.claude/rules/ のファイルは数えられません。これらは AGENTS.md と一緒に読まれます。

自分用に CLAUDE.local.md を 1 つ足しただけでも AGENTS.md が読まれなくなるので、注意が必要です。

バージョンによる違い

バージョン 変わったこと
v2.1.277 AGENTS.md を直接読むようになった
v2.1.280 直接読んだ AGENTS.md が、/memory と /context の一覧に出るようになった
v2.1.281 Amazon Bedrock 経由や、テレメトリを無効にしたセッションでも読むようになった

v2.1.276 以前から更新した直後の最初のセッションでは、読まれない場合があるとも書かれています。その場合は、次のセッションから読まれます。

読まれているかを確かめる方法

公式ドキュメントに書かれている方法は 2 つです。

  • Claude Code で /memory を実行し、一覧に AGENTS.md の場所が出るかを見る。
  • AGENTS.md を直接読んだ対話のセッションでは、会話に「no CLAUDE.md found; AGENTS.md loaded:」と、読み込んだファイルの場所が表示される。

読み込まれた CLAUDE.md を確かめるときは、/context all を実行して「Memory files」の一覧を見ます。

手元で確かめた結果

2026 年 11 月 21 日に、macOS の Claude Code 2.1.321 で確かめました。分かったのは起動時の記録までで、AI の返答では確かめられていません。

やり方は次のとおりです。空の一時フォルダを 4 つ作り、AGENTS.md には「合言葉を聞かれたら決まった言葉で答える」というルールを 1 行だけ書きました。それぞれのフォルダで claude -p に --debug-file をつけて実行し、起動時の記録(デバッグログ)を読みました。

フォルダの中身 起動時の記録
AGENTS.md だけ CLAUDE.md を探して 0 件、AGENTS.md を探して 1 件。「no CLAUDE.md found; AGENTS.md loaded」と、読み込んだファイルの場所が記録された
CLAUDE.md と AGENTS.md(読み込みの指定なし) AGENTS.md を探した記録も、読み込んだ記録も出なかった
CLAUDE.md(1 行目が @AGENTS.md)と AGENTS.md AGENTS.md を自動で読んだ記録は出なかった。@ による読み込みは記録に出ないため、この方法では確かめられなかった
どちらもなし CLAUDE.md を探して 0 件、AGENTS.md を探して 0 件

AGENTS.md だけのときは読み込まれ、CLAUDE.md があるときは自動では読み込まれない、という公式ドキュメントの説明と合う結果でした。

確かめられなかったことが 2 つあります。

  • AI が実際に AGENTS.md のルールに従って答えるか。確認に使った Claude Code はログインの期限が切れていて、4 つとも認証のエラーで終わり、返答を受け取れませんでした。
  • @AGENTS.md と書いた CLAUDE.md を通して、AGENTS.md の内容が読み込まれるか。上の表のとおり、起動時の記録からは分かりませんでした。

併用する 3 つの方法

CLAUDE.md と AGENTS.md の両方を Claude Code に読ませる方法は、公式ドキュメントに 3 つ載っています。Claude Code だけに関係する指示を書きたいなら、1 つ目の @AGENTS.md が扱いやすい形です。

方法 やること 注意点
@AGENTS.md で読み込む CLAUDE.md に @AGENTS.md と書く 公式ドキュメントの例では 1 行目に書いている
シンボリックリンク CLAUDE.md を AGENTS.md へのリンクにする Claude Code だけの指示を書く場所がなくなる。Windows では扱いにくい
設定を変える /config の「Project instructions」を claude-md-and-agents-md にする プロジェクトの設定ファイルでは指定できない。使う人ごとの設定か、組織の管理設定が必要

@AGENTS.md で読み込む

手順は次の 3 つです。

  1. 共通のルールは AGENTS.md に書く。
  2. CLAUDE.md に @AGENTS.md と書いて読み込む。
  3. Claude Code だけに関係することを、その下に書く。

Claude Code は、読み込んだ AGENTS.md を先に読み、そのあとで CLAUDE.md の残りを読みます。

読み込みの指定には、次の決まりがあります。

  • 相対パスは、その行を書いたファイルの場所から解決されます。作業フォルダからではありません。
  • コードブロックの中や、バッククォートで囲んだ中に書いた場合は読み込まれません。
  • 読み込んだファイルが、さらに別のファイルを読み込めます。深さは 4 段までです。

併用するときの 2 つのファイルの役割。Claude Code は CLAUDE.md を読み、その中の @AGENTS.md の指定で AGENTS.md を読み込む。Codex は AGENTS.md を直接読む。共通のルールは AGENTS.md に、Claude Code だけに関係することは CLAUDE.md に書く

この形の雛形は、AGENTS.md・CLAUDE.md ジェネレーターで作れます。

シンボリックリンクにする

Claude Code だけに関係する内容がなければ、CLAUDE.md を AGENTS.md へのシンボリックリンクにする方法もあります。公式ドキュメントには、注意点が 2 つ書かれています。

  • Claude Code の編集ツールは、シンボリックリンクを通した書き込みを拒否します。編集するときは、リンク先の AGENTS.md を直接編集することになります。
  • Windows では、リンクの作成に管理者の権限か開発者モードが必要です。Git の設定によっては、リンクではなく 1 行だけのテキストファイルとして取得されます。Windows で作業する人がいる場合は、@AGENTS.md を使うよう勧められています。

設定で両方を読ませる

/config の「Project instructions」には、4 つの値があります。

値 読むもの
claude-md-or-agents-md(初期設定) CLAUDE.md。CLAUDE.md がなければ AGENTS.md
claude-md-and-agents-md CLAUDE.md と AGENTS.md の両方
claude-md CLAUDE.md だけ
managed-only 組織が配る CLAUDE.md だけ

自分用の CLAUDE.local.md を残したまま AGENTS.md も読ませたい場合は、claude-md-and-agents-md にします。CLAUDE.md が @AGENTS.md で読み込んでいる AGENTS.md は、この設定にしても二重には読まれません。

すでに @AGENTS.md を書いている場合

AGENTS.md を直接読む機能が入る前から @AGENTS.md を書いていた場合、その行は残してかまいません。公式ドキュメントは、残しても AGENTS.md が二重に読まれることはないとしています。CLAUDE.md にほかの内容がなければ、CLAUDE.md を消して AGENTS.md だけにすることもできます。

CLAUDE.md に「AGENTS.md を読むこと」と文章で書いているだけの場合は、@AGENTS.md に書き換えます。文章での指示では、Claude Code が自分でファイルを開くと決めたときしか読まれないためです。

自分の運用

運営している占い SaaS「Stellica」のリポジトリでは、Claude Code と Codex を併用していて、@AGENTS.md で読み込む形にしています。サービスの概要は事例ページにあります。

どちらのファイルに何を置いているか

ファイル 行数 置いているもの
AGENTS.md 195 行 行動規範、ツールごとの役割分担、重い手順を使う作業の境界、検証コマンド、触ってはいけない場所、コーディング規約、Git の決まり
CLAUDE.md 37 行 @AGENTS.md の指定、Claude Code 自身の役割と作業の流れ、禁止事項、スキルの使い分け

分け方の基準は「Codex も読む必要があるか」です。役割分担は、どちらのツールも知っている必要があるので AGENTS.md に置いています。Claude Code が Codex に作業を渡す手順は、Codex が読む必要がないので CLAUDE.md に置いています。

各項目の中身と、入れた理由は実際に使っている AGENTS.md の公開にまとめました。

この形にした経緯

作業の記録とリポジトリの履歴から分かる経緯は、次のとおりです。

  • 2026 年 7 月 5 日より前: CLAUDE.md が 431 行、AGENTS.md が 423 行あり、行の 9 割ほどが同じ内容でした。同じルールを 2 つのファイルに書いていたことになります。
  • 2026 年 7 月 5 日: 共通のルールを AGENTS.md にまとめ、CLAUDE.md を @AGENTS.md と Claude Code 用のメモだけの 14 行にしました。同じ日に、スキルの置き場所も 1 か所にまとめています。この時点の AGENTS.md は 478 行でした。
  • 2026 年 7 月 25 日: AGENTS.md を整理し、400 行あまりを削りました。作業の記録には「境界付きの検証へ整理」とあり、検証や手順をどこまで求めるかに境界をつけた変更です。
  • 2026 年 8 月 2 日: 通常の開発の決まりをさらに短くし、検証のための仕組みを増やしすぎない決まりを足しました。

2 つのファイルの行数の推移。2026 年 7 月 5 日より前は AGENTS.md が 423 行、CLAUDE.md が 431 行。7 月 5 日にまとめた直後は 478 行と 14 行。11 月 21 日は 195 行と 37 行

困ったことと直し方

1 つ目は、同じルールの二重管理です。2 つのファイルに同じ内容を書いていると、片方だけを直したときに内容が食い違います。直し方は、この記事に書いた形そのものです。AGENTS.md の冒頭にも「ルールの変更は必ずこのファイルに対して行い、二重管理しない」と書いて、AI がルールを足すときの行き先を決めています。

2 つ目は、1 か所にまとめたあとの長さです。まとめた直後の AGENTS.md は 478 行で、Claude Code の目安の 2 倍を超えていました。機能の一覧や作業の履歴を外し、手順の長い作業をスキルに分けて、いまは 195 行です。

3 つ目は、スキルの置き場所です。Claude Code の公式ドキュメントによると、Claude Code は AGENTS.override.md や .agents/ フォルダの中身を読みません。このリポジトリではスキルの実体を .agents/skills/ の 1 か所に置き、Claude Code が読む .claude/skills/ には、そこへのシンボリックリンクを置いています。

長くしすぎない

どちらのファイルも、長くなるほど守られにくくなります。書くのは「AI がフォルダを読んでも分からないこと」に絞ります。

ツール 目安と上限
Claude Code CLAUDE.md は 1 ファイル 200 行未満が目安。4 MiB を超えるファイルは読み込まれない
Codex 読み込む AGENTS.md の合計が 32 KiB まで(初期設定。設定で変えられる)

Claude Code の公式ドキュメントは、長いファイルは読み込みの負担が増え、指示が守られにくくなると説明しています。@ で読み込んだファイルは、読み込む側と一緒に読まれます。ファイルを分けて整理することはできますが、負担は減りません。

このリポジトリの場合、AGENTS.md の 195 行と CLAUDE.md の 37 行は、どちらも 1 ファイルの目安に収まっています。ただし、Claude Code が毎回読むのは、合わせた 232 行です。

Codex は、合計が上限に達すると、それ以降のファイルを足しません。

手順の長い作業や、一部のフォルダにだけ関係する決まりは、スキルや、対象のパスを決めたルール(.claude/rules/)に分けるよう、Claude Code の公式ドキュメントは勧めています。

よくある質問

Claude Code は AGENTS.md を読む?

読みます。v2.1.277 以降の Claude Code は、作業フォルダとその上の階層に CLAUDE.md がなければ、AGENTS.md を自動で読みます。CLAUDE.md があるときは、初期設定では読みません。

CLAUDE.md と AGENTS.md の両方があると、どちらが読まれる?

初期設定では CLAUDE.md だけが読まれます。両方を読ませるには、CLAUDE.md に @AGENTS.md と書くか、/config の「Project instructions」を claude-md-and-agents-md にします。

AGENTS.md だけにして、CLAUDE.md をやめられる?

やめられます。CLAUDE.md がなければ、Claude Code は AGENTS.md を直接読みます。Claude Code だけに関係する指示を書きたい場合は、CLAUDE.md を残して @AGENTS.md で読み込む形にします。

@AGENTS.md とシンボリックリンクは、どちらがよい?

Claude Code だけの指示を書くなら @AGENTS.md です。Windows で作業する人がいる場合も、公式ドキュメントは @AGENTS.md を勧めています。シンボリックリンクは、2 つのファイルの中身がまったく同じでよい場合の方法です。

AGENTS.md が読まれないときは、どこを見る?

公式ドキュメントが挙げている順番は、次の 3 つです。作業フォルダか上の階層に、CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md がないか。Claude Code のバージョンが v2.1.277 以降か。/config の「Project instructions」が claude-md や managed-only になっていないか。

まとめ

  • CLAUDE.md は Claude Code のためのファイル、AGENTS.md は複数のツールに共通のファイルです。
  • Claude Code は、CLAUDE.md がないときだけ AGENTS.md を自動で読みます(v2.1.277 以降、初期設定の場合)。
  • CLAUDE.local.md を 1 つ置いただけでも、AGENTS.md は自動では読まれなくなります。
  • 併用するときは、共通のルールを AGENTS.md に書き、CLAUDE.md に @AGENTS.md と書いて読み込みます。
  • ファイルを分けても、読み込みの負担は減りません。書く内容を絞ります。

チームで Claude Code を契約するときの席の選び方は、Team プランの Standard 席と Premium 席の違いにまとめています。ルールの文書化を含めて、AI エージェントの導入を相談したい場合は、AI エージェント導入・伴走支援をご覧ください。

出典

いずれも 2026 年 11 月 21 日に確認しました。

この記事に関連する無料ツール

集客や AI 導入の進め方を相談する

状況をうかがったうえで、合う進め方を提案します。まだ依頼するか決めていない段階でもかまいません。

  • 初回 30 分は無料
  • オンライン
  • 返信は 2、3 営業日以内

書いていただけると助かること

  1. 会社または事業の概要と、関わる人数
  2. 相談したい内容(マーケティング、SEO、AI 導入、研修など)
  3. いま困っていること、いつまでに進めたいか