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.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 つです。
- 共通のルールは AGENTS.md に書く。
- CLAUDE.md に
@AGENTS.mdと書いて読み込む。 - Claude Code だけに関係することを、その下に書く。
Claude Code は、読み込んだ AGENTS.md を先に読み、そのあとで CLAUDE.md の残りを読みます。
読み込みの指定には、次の決まりがあります。
- 相対パスは、その行を書いたファイルの場所から解決されます。作業フォルダからではありません。
- コードブロックの中や、バッククォートで囲んだ中に書いた場合は読み込まれません。
- 読み込んだファイルが、さらに別のファイルを読み込めます。深さは 4 段までです。
この形の雛形は、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 日: 通常の開発の決まりをさらに短くし、検証のための仕組みを増やしすぎない決まりを足しました。
困ったことと直し方
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 日に確認しました。
- Claude Code 公式ドキュメント: メモリ(CLAUDE.md と AGENTS.md)
- Claude Code 公式ドキュメント: ベストプラクティス
- AGENTS.md の公式サイト
- OpenAI Codex の AGENTS.md ガイド(developers.openai.com/codex/guides/agents-md から転送されます)