【ITニュース解説】AGENTS.md vs CLAUDE.md vs .cursor/rules: which file does your AI agent read?

システムエンジニアを目指す皆さんにとって、開発現場でAIコーディングツール（AIエージェント）が使われる機会は増えています。これらのAIは、コードの生成、デバッグ、リファクタリングなど、様々な作業を支援してくれますが、AIが私たちの意図通りに動くためには、プロジェクトのルールや方針を正確に伝える必要があります。そのために使われるのが、AIエージェントが参照する指示ファイルです。複数のAIツールが乱立する中で、どのファイルにどんな情報を書けば、AIが正しく理解し、私たちも管理しやすくなるのか、その課題と解決策について解説します。

AIコーディングツールは、プロジェクトのファイルやコードを解析し、そのコンテキストに基づいて作業を行います。しかし、プロジェクト全体の方針や、特定の機能に関する詳細な指示は、コードだけでは伝えきれません。そこで登場するのが、プロジェクトのルールを記述したファイルです。現在、様々なAIツールが独自の指示ファイル形式を採用しており、そのせいで以下のような問題が発生しがちだ。

一つ目の問題は、「どのファイルに指示を書けばよいのか分からない」ことだ。もし、あるツールのフォーマットにだけルールを書いても、他のツールはそのルールを推測するしかなく、意図しない動作をする可能性がある。二つ目の問題は、「同じ内容の指示を複数のファイルにコピーしてしまう」ことだ。こうすると、後からルールを変更する際に、すべてのファイルを更新しなければならず、変更漏れや指示の食い違いが発生しやすくなり、プロジェクトの保守性が著しく低下する。

これらの課題を解決し、AIエージェントを効率的に活用するための標準的なアプローチと、具体的なファイルの種類について見ていこう。

まず、多くのAIコーディングツールが共通して参照できる「共有の真実の源（shared source of truth）」として推奨されるのが「AGENTS.md」というファイルだ。これは、プロジェクトのルートディレクトリ（一番上の階層）に配置される、シンプルなMarkdown形式のファイルで、いわば「AIエージェント向けのREADME」のようなものだ。AGENTS.mdには、プロジェクトの構築方法、テスト方法、推奨されるフォルダ構成、コーディング規約、決して行ってはならないこと（never-do list）、そして「何をもって作業完了とするか」といった、プロジェクト全体にわたる普遍的で永続的な指針を記述する。OpenAI CodexやCursorといった多くのAIツールがこのAGENTS.mdを読み込み、プロジェクトの基本方針として参考にすることで、複数のツールを使っても、共通のルールを一箇所で管理できるため、指示の統一が図れ、保守性が向上する。

次に、特定のAIツールに特化したファイルについて解説する。例えば、「Claude Code」というAIツールは、「CLAUDE.md」というファイルをプロジェクトのメモリファイルとして読み込む。このファイルもMarkdown形式だが、特徴的なのは「@path/to/file」という構文を使って、他のMarkdownファイルを取り込む（インポートする）ことができる点だ。この機能を利用して、CLAUDE.mdの冒頭に「@AGENTS.md」と記述することで、AGENTS.mdに書かれた共有のルールを取り込みつつ、その下にClaude Codeに特化した注意事項や指示（例えば、「認証、決済、データベースのマイグレーションを触る前に、必ず計画を立てて承認を得ること」など）を追記できる。これにより、共有ルールはAGENTS.mdで一元管理しつつ、Claude Code固有の振る舞いを細かく制御することが可能になる。

また、「Cursor」というAIツールには、さらにきめ細やかなルールを設定できる仕組みがある。それは、「.cursor/rules/」というディレクトリの下に配置される「*.mdc」ファイルだ。これらのファイルはMarkdown形式に加えて、ファイルの先頭に「フロントマター」と呼ばれるYAML形式の設定情報を含めることができる。このフロントマターには、ルールの説明（description）、ルールを適用するファイルのパターン（globs）、そしてルールを常に適用するかどうか（alwaysApply）といった設定を記述する。

例えば、「alwaysApply: true」と設定された.mdcファイルは、Cursorでのチャットセッション中に常に読み込まれ、ルールが適用される。一方で、「globs」を使って「supabase/**」（supabaseディレクトリ内のすべてのファイル）のように特定のファイルパスパターンを指定し、「alwaysApply: false」と設定すると、そのパターンに一致するファイルが作業コンテキストに含まれている場合にのみ、ルールがCursorに提供される。これを「パススコープのルール」と呼ぶ。これにより、データベースの行レベルセキュリティ（RLS）や決済処理（Stripe）など、特定の機能やファイルにのみ適用したい、より精密な指示を記述するのに役立つ。例えば、「新しいテーブルを作る際は、必ず同じマイグレーションファイル内でRLSとポリシーを有効にすること」といった具体的なデータベース操作のルールを、関連するファイルが編集される際にだけAIに意識させることができる。

Cursorにはかつて「.cursorrules」という単一のレガシーなルールファイルがあったが、これは非推奨となっており、.cursor/rules/*.mdc形式のファイルやAGENTS.mdへの移行が推奨されている。

他にも、「Windsurf Cascade」というツールも、「.windsurf/rules/」ディレクトリ以下にMarkdown形式のルールファイルを配置する。そのアクティベーションモード（常時、glob、手動）はCursorのルールと似ており、ここでもAGENTS.mdで定めた共有の指針を基盤とし、ツール固有の追加ルールを記述することが推奨される。

これらの情報から導き出される推奨される設定方法は、以下の通りだ。まず、プロジェクトの核となる普遍的なルール、例えば技術スタック、基本的なコマンド、決して行ってはならないこと、そして完了の定義などは、最優先でAGENTS.mdに記述する。これを「共有の真実の源」として位置づける。

次に、Claude Codeを使用する場合は、CLAUDE.mdを作成し、その先頭に「@AGENTS.md」と記述して共有ルールを取り込む。その下に、Claude Codeに特化した数行のメモや注意点を追記するだけに留める。AGENTS.mdの全内容をCLAUDE.mdにコピーしてはいけない。

Cursorを使用する場合は、特定のパスや機能に精密な指示が必要な場合にのみ、.cursor/rules/*.mdcファイルを追加する。例えば、認証、データベースの行レベルセキュリティ、決済処理などの領域だ。ここでも、AGENTS.mdの内容を丸ごとコピーするのではなく、AGENTS.mdの基本的な方針を前提としつつ、その特定の機能に特化した追加ルールや詳細なガイドラインを記述する。

Windsurfなどの他のツールを使う場合も同様に、AGENTS.mdの思想を反映させつつ、そのツール固有のレイアウトに合わせて、必要なルールを追加する。決して、同じ内容を複数のファイルにコピーして、別の「真実の源」を作ってはいけない。

そして、現在.cursorrulesのようなレガシーなファイルを使っている場合は、速やかに.cursor/rules/*.mdcまたはAGENTS.mdへ内容を移行し、古いファイルを削除することを強く推奨する。これにより、今後AIエージェントがそのレガシーファイルを無視してしまうリスクを避けられる。

この一元化された管理体制を構築することの最大のメリットは、ルールに問題が見つかった場合や、プロジェクトの要件が変更された場合に、修正を一箇所（AGENTS.md、または特定のスコープ付きルールファイル）で行えばよいという点だ。これにより、複数のファイルで内容が食い違ったり、修正漏れが発生したりするリスクを防ぎ、プロジェクト全体の保守性とAIエージェントの指示の一貫性を高く保つことができる。

まとめると、システムエンジニアとしてAIコーディングツールを効果的に活用するためには、プロジェクトのルールや方針を整理し、AGENTS.mdを共有の「真実の源」として活用することが重要だ。各AIツール固有のファイルは、その共有ルールを参照しつつ、ツールや特定の機能に特化した補足情報を追加する役割に限定することで、AIエージェントの理解を深め、開発プロセスをよりスムーズに、より正確に進めることができるようになる。これは、将来AIと協調しながら開発を進めていく上で、非常に重要な知識となるだろう。