CLAUDE.mdとAGENTS.mdの違い：どのエージェントがどのファイルを読むか。

それぞれのファイルとは

どちらも、エージェントがセッションの開始時にコンテキストに読み込む、ふつうのMarkdownです。ビルドとテストのコマンド、コードスタイル、プロジェクトの構成、「生成されたファイルは編集しない」といったルールを書きます。これらは強制される設定ではなく指示で、エージェントは指針として扱います。

• CLAUDE.mdはClaude Code専用です。プロジェクトのルート（./CLAUDE.mdまたは./.claude/CLAUDE.md）、すべてのプロジェクト向けの~/.claude/CLAUDE.md、サブフォルダに置けます。CLAUDE.local.mdには、1つのプロジェクトの個人用メモを書きます。
• AGENTS.mdは、agents.mdで説明されているオープンな形式で、エージェント向けのREADMEです。Codex、Cursor、GitHub Copilotのコーディングエージェント、Gemini CLI、Zedなど多くが読みます。モノレポでは、サブフォルダのAGENTS.mdがその部分に適用され、最も近いファイルが優先されます。

内容は同じ種類のものです。違うのは、どのツールがそのファイルを拾うかです。

Claude CodeがAGENTS.mdをどう扱うか

Claude Codeのドキュメントでは、バージョン2.1.277以降について、3つのケースが説明されています。

• プロジェクトにAGENTS.mdだけがあり、CLAUDE.mdがない場合：Claude CodeはAGENTS.mdを読みます。
• プロジェクトに両方のファイルがある場合：Claude CodeはCLAUDE.mdのファイルだけを読みます。
• CLAUDE.mdが@AGENTS.mdでAGENTS.mdをインポートしている場合：ClaudeはAGENTS.mdを含めてCLAUDE.mdを読みます。

2番目のケースは、驚く人が多いところです。AGENTS.mdのあるリポジトリにCLAUDE.mdを追加すると、たとえ小さなものでも、CLAUDE.mdがインポートしない限り、ClaudeはAGENTS.mdを読まなくなります。CLAUDE.local.mdも同様です。古いバージョンのClaude CodeはCLAUDE.mdしか読まないため、インポートが今も安全な選択です。ドキュメントには、/configのProject instructions設定で、Claudeに両方のファイルをまとめて読ませる方法も書かれています。

指示を1つにまとめる

どちらかのファイルを、正とするファイルに決めます。ドキュメントには2つの方法があります。

1. CLAUDE.mdからAGENTS.mdをインポートする

   AGENTS.mdの隣にCLAUDE.mdを作り、1行目を@AGENTS.mdにして、その下にClaude専用の指示を追加します。インポートは@pathの構文で、相対パスはそれを含むファイルから解決され、インポートされたファイルがさらに別のファイルをインポートでき、深さは4階層までです。

2. CLAUDE.mdからAGENTS.mdへシンボリックリンクを張る

   Claude専用に加えるものがなければ、ln -s AGENTS.md CLAUDE.mdを実行します。ただしドキュメントによると、ClaudeのEditツールはシンボリックリンクを通して書き込みません。また、Windowsではコミットしたシンボリックリンクが1行のテキストファイルとしてチェックアウトされることがあるため、共有リポジトリではインポートのほうが安全です。

3つ目の方法は避けてください。CLAUDE.mdに「AGENTS.mdを読むこと」と言葉で書く方法です。Claudeがそのファイルを見るのは、自分で開くと判断したときだけですが、インポートなら毎回読み込まれます。

共有するAGENTS.md

どのエージェントにも必要なことを、AGENTS.mdに書きます。

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript, strict mode. No default exports.
- Update the tests with every change.

## Do not
- Edit files under `generated/`.
- Commit without running the tests.

短く、具体的にします。Claude Codeのドキュメントでは、CLAUDE.mdは1つあたり約200行以内を勧めています。長いファイルはコンテキストを消費し、守られる確実性も下がるためです。

よくある間違い

• 2つのファイルがずれていく。片方だけが更新されます。インポートを使いましょう。
• CLAUDE.mdを追加してAGENTS.mdが読まれなくなる。上記のとおり、インポートします。
• どちらのファイルにも秘密情報を書く。コミットされ、すべてのセッションに読み込まれます。
• あいまいなルール。「きれいなコードを書く」では何も変わりません。「完了と言う前にnpm testを実行する」なら変わります。
• 矛盾するルールが、親フォルダのファイルとサブフォルダのファイルにある。

これらのファイルを読み、レビューする

どちらもふつうのMarkdownなので、DotMDはCLAUDE.mdとAGENTS.mdを開き、ほかの.mdファイルと同じようにアウトラインとすべての変更の履歴を表示し、エージェントがそこで何を変えたかも示します。閲覧は無料です。Claude CodeとCodexでのDotMDの使い方もご覧ください。

CLAUDE.mdとAGENTS.mdに関するよくある質問

その他の質問