3行でいうと

  • AGENTS.mdは、特定の道具に縛られない共通のMarkdownファイル。必須の項目はなく、いちばん近いファイルが優先される。
  • Claude Codeは、CLAUDE.mdを200行未満に、Cursorのルールは500行未満にするよう勧める。Codexは合計32KiBで打ち切る。
  • Claude Codeの文書では、CLAUDE.mdは「守らせる設定」ではなく「文脈」。必ず守らせたいことはフックを使う。

この記事は、実際に使って確かめた記録ではありません。この記事は、公式の文書を読んでまとめたものです。内容は2026年10月22日に読んだ時点のもので、道具の更新で変わることがあります。

先に結論

前提：何の話か

名前は道具ごとに違います。

道具 ファイル 置き場所の例
Claude Code CLAUDE.md プロジェクトの根、.claude/、ホーム（~/.claude/）など
Codex（OpenAI） AGENTS.md プロジェクトの各ディレクトリ、~/.codex
Cursor ルール（.cursor/rules）、AGENTS.md プロジェクトの根、サブディレクトリ
共通形式 AGENTS.md プロジェクトの根、サブディレクトリ

AGENTS.md：共通の入れ物

公式サイト（agents.md）は、AGENTS.mdを「エージェント向けのREADME」と説明しています。主な点は次のとおりです。

Claude Code：CLAUDE.mdとAGENTS.md

どこに置き、どの順で読まれるか

公式文書では、CLAUDE.mdは次の4つの範囲に置けます。読み込みの順序は、広い範囲から狭い範囲です。

範囲 場所 用途
組織の管理 OSごとの決まった場所（Linux・WSLでは/etc/claude-code/CLAUDE.mdなど） 会社の規約。IT部門が管理
ユーザー ~/.claude/CLAUDE.md 個人の好み。全プロジェクト共通
プロジェクト ./CLAUDE.md か ./.claude/CLAUDE.md チームで共有。バージョン管理に入れる
ローカル ./CLAUDE.local.md 個人の、そのプロジェクト限りの好み。.gitignoreに入れる

作業ディレクトリと、その上の階層のファイルは、起動時にすべて連結されます。上書きではなく、ルートに近いものから順に並びます。つまり、作業場所に近い指示ほど、あとに読まれます。下の階層にあるCLAUDE.mdは、そのディレクトリのファイルをAIが読み書きしたときに追加で読み込まれます。

書き方の公式の注意

CLAUDE.mdは「強制」ではない

公式文書は、CLAUDE.mdとauto memory（Claude自身が書くメモ）を、文脈として読み込むものであり、強制する設定ではない、と明記しています。ある動作を確実にとめたいなら、PreToolUseフック（道具を使う直前に走らせる自動処理）を使うよう案内しています。ベストプラクティスのページでも、CLAUDE.mdの指示は助言、フックは決まった動作を保証する、と書き分けています。

手順や一部のフォルダだけの話は別の場所へ

複数ステップの手順や、コードベースの一部にだけ関わる内容は、スキル（必要なときだけ読み込まれる手順書）か、パスを指定したルール（.claude/rules/に置き、pathsの指定に合うファイルを扱うときだけ読み込まれる）に移す、と案内されています。スキルとプラグインの違いは、この記事では扱いません。

AGENTS.mdとの関係

Claude Codeは、作業ディレクトリとその上の階層にCLAUDE.md（CLAUDE.local.mdを含む）がなくAGENTS.mdだけがあるとき、AGENTS.mdをプロジェクトの指示として読みます（v2.1.277以降）。両方あるときは、既定ではCLAUDE.mdだけが読まれます。10月22日に読んだ文書には、/configの「Project instructions」設定が載っていて、claude-md-and-agents-mdにすると両方を読めます。設定を使わない方法として、CLAUDE.mdに@AGENTS.mdと書いて取り込むこともできます。

公式文書の例：CLAUDE.mdからAGENTS.mdを取り込む

公式文書の例です。この記事では、実行していません。

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude固有の指示だけを、取り込みの下に足す形です。足す指示が要らないなら、シンボリックリンク（ln -s AGENTS.md CLAUDE.md）でもよい、とあります。ただし、公式文書は次の2点を注意しています。

  • シンボリックリンクごしの書き込みは、編集ツールが拒否し、リンク先のAGENTS.mdを編集するよう促される。
  • Windowsでは、リンクの作成に管理者権限か開発者モードが必要で、Gitがリンクを普通のテキストファイルとして展開することがある。Windowsの人がいるチームには、@AGENTS.mdの取り込みを使うよう勧められている。

CLAUDE.mdの@パスの取り込みは、再帰的に最大4段までです。取り込んだファイルも起動時に読まれるため、整理には役立つが、文脈の消費は減らない、と書かれています。

Codex：AGENTS.mdの探し方と上限

Codexの公式文書では、次のように探します。

  1. 全体の設定：~/.codex（またはCODEX_HOME）で、AGENTS.override.mdがあればそれを、なければAGENTS.mdを読む。この階層では最初の空でない1つだけ。
  2. プロジェクト：プロジェクトの根（通常はGitの根）から現在のディレクトリまで下りながら、各ディレクトリでAGENTS.override.md、AGENTS.md、project_doc_fallback_filenamesに書いた別名の順に探し、1ディレクトリにつき最大1つを採用する。
  3. 連結：根から下へ、空行でつないで連結する。現在地に近いファイルは、あとに来るので、前の指示を上書きする形になる。
  4. 上限：project_doc_max_bytesが初期値32KiB。合計がこの量に達すると、追加を止める。上限を上げるか、ディレクトリごとに分けて避ける。

公式文書の設定例には、project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]とproject_doc_max_bytes = 65536が載っています。

見立てです。Claude Codeは「根から作業場所へ、近いほどあとに読む」、Codexは「根から現在地へ、近いほどあとに連結する」と、順序の考え方はよく似ています。ただし、片方は「全部連結」、片方は「容量で打ち切る」という違いがあり、長いファイルの扱いは同じではありません。

Cursor：ルールとAGENTS.md

Cursorの公式文書では、プロジェクトのルールは.cursor/rulesに置き、.mdc形式（メタデータを先頭に持つMarkdown）です。プロジェクトのルールには、適用のしかたで4つの種類があります。

注意点として、.mdcの拡張子でないファイルは、メタデータがないために無視される、と書かれています。10月22日に読んだページには、ほかに、管理画面から配る「Team Rules」（TeamとEnterpriseプラン。優先順位はTeam Rules、プロジェクトのルール、ユーザールールの順）と、チャットで使う全体用の「User Rules」も載っていました。AGENTS.mdはメタデータなしの、より単純な代わりとして使えます。長さは「500行未満」が目安で、大きいルールは小さく分けることを勧めています。よい習慣として、焦点を絞る、具体的に書く、内容をコピーせずファイルを参照する、スタイルガイド全文をコピーせずリンターに任せる、AIが同じ失敗を繰り返すときだけルールを足す、が挙がっています。

4つの道具の違いをまとめた表（僕らが整理したもの）
論点 Claude Code Codex Cursor AGENTS.md（共通）
主なファイル CLAUDE.md、.claude/rules/ AGENTS.md、AGENTS.override.md .cursor/rulesの.mdc、AGENTS.md AGENTS.md
長さの目安 1ファイル200行未満 合計32KiB（初期値）で打ち切り ルールは500行未満 決まりなし
複数ファイルの扱い 上の階層を連結。下の階層は必要時に読む 根から現在地まで、各階層で1つ連結 サブディレクトリのAGENTS.mdは、より具体的なものが優先 最も近いものが優先
条件つき読み込み pathsつきルール 文書に記載なし（確認できていません） 4種類のルール なし
強制力 助言。確実にとめるならフック 今回読んだ文書には記載なし 今回読んだ文書には記載なし 記載なし

行数とバイトは単位が違うので、数字を並べて優劣は言えません。

選び方の見立て

見立てです。公式文書を重ねると、次の整理が自然だと思います。

  1. まずAGENTS.mdに共通の決まりを書く。 複数の道具を使う可能性があるなら、正本を1つにすると、食い違いが起きにくいと思います。
  2. 道具固有の差分は、その道具の仕組みに置く。 Claude Codeならプランモードの使い方、Cursorなら適用範囲つきのルール、など。
  3. 「必ず守らせたい」はファイルに書くだけで済ませない。 Claude Codeの文書は、確実にしたいことはフックなどの仕組みに置くよう案内しています。
  4. 育てる。 失敗が起きたときに1行足し、効かなくなった行を消す。最初から完璧に書こうとしない（Claude Codeの/initは、雛形を作る機能として紹介されています）。

つまずきやすい点

気をつけること

出典

更新履歴