AGENTS.md: すべてのコーディングエージェントに効く唯一のコンテキストファイル（Codex、Gemini、Claude）

午後をまるごと使って、きれいな CLAUDE.md を書き上げたとします。エージェントはようやくスタックを推測するのをやめ、正しいテストコマンドを実行するようになりました。ところが、同僚が同じリポジトリを Codex で開き、あなたがサイドブランチで Gemini CLI を試すと、苦労して積み上げたコンテキストはまったく引き継がれません。どのツールも、自分専用のファイルを、自分専用の場所に欲しがるのです。

AGENTS.md は、この混乱に対する答えです。リポジトリのルートに置く、ただ 1 つのプレーンな Markdown ファイル。どんなコーディングエージェントも、あなたのコードに触れる前にこれを読み込みます。

AGENTS.md とは結局のところ何なのか

魔法ではありません。AGENTS.md という名前の Markdown ファイルで、通常はリポジトリのルートに置かれ、エージェントが作業を始める前に常設の指示として読み込みます。人間のチームメイトではなく、AI のチームメイトのために書く README だと考えてください。プロジェクトが何であるか、どうビルドしてテストするか、守るべき規約、そして避けるべき落とし穴です。

これはオープンな規約であり、すでに Codex をはじめ増え続けるエージェントツールに読み込まれています。狙いは明確で、ツール間で持ち運べることです。ツールごとに専用ファイルを用意するのではなく、1 つのファイルを多くのエージェントが共有するのです。

AGENTS.md vs CLAUDE.md vs GEMINI.md

今のところ、状況はツールごとに分断されています。

• CLAUDE.md は Claude Code が探すファイルです。
• GEMINI.md は Gemini CLI の規約です。
• AGENTS.md は、Codex やその他のツールが読むツール横断の標準で、中立な存在として設計されています。

内容は 3 つともほぼ同じです。プロジェクトのコンテキスト、コマンド、規約。本当の違いは、各ツールがデフォルトで読み込むファイル名だけです。だからこそ、同じルールを手作業で 3 つのファイルに複製するのは、最初から負けが見えた戦いなのです（同期を保つ方法については後ほど触れます）。

主に Claude Code で作業しているなら、CLAUDE.md ガイドが Claude 固有の構造を詳しく掘り下げています。AGENTS.md は、そのファイルのプロバイダー中立な兄弟分だと考えてください。

何を書くべきか

短く、シグナルの濃い内容に保ちましょう。エージェントはタスクのたびにこれを読みます。だから、どの 1 行も注意を奪い合っているのです。要点はこちら。

• スタックを一息で。 「Next.js 16、TypeScript、Prisma、MariaDB」。沿革も、宣伝もいりません。
• 重要なコマンド。 インストール、起動、ビルド、テスト、lint のやり方を。正確なコマンドで。「テストを実行する」ではなく npm test と書きます。
• 規約。 命名、ファイル配置、エラーハンドリング、レビューで実際に徹底しているパターン。
• ディレクトリマップ。 何がどこにあるかを 2 行で。エージェントが闇雲に grep するのをやめさせます。
• 「触れる前に読む」ルール。 「billing/ 配下を編集する前に docs/payments.md を読むこと」。この習慣 1 つで、多くの損害を防げます。
• 絶対にやってはいけないこと。 「頼まれない限りブランチを作らないこと」「コミットするファイルにマシン固有の絶対パスを書かないこと」。

エージェントに無視させてしまうミス

コンテキストファイルは、静かに失敗します。エージェントはエラーを投げず、ただじわじわとずれていくのです。よくある原因は次のとおり。

1. 長すぎる。 600 行のファイルは、本当に効く 5 つのルールを埋もれさせます。エージェントがコード自体から推測できることは、すべて削りましょう。
2. 矛盾。 あるセクションでは「常にテストを書く」、別のセクションでは「プロトタイプではテストを飛ばす」。エージェントはどちらか一方をランダムに選びます。
3. マシン固有のパス。 コミットしたファイルに /Users/you/project/... があると、すべての同僚にとって、そして別のマシン上のすべてのエージェントにとって壊れます。パスは相対で保ちましょう。
4. 古くなったコマンド。 テストコマンドは半年前に変わったのに、ファイルは変わっていない。今やエージェントは、まったくの自信を持って間違ったものを実行します。
5. 優先順位がない。 すべてが「重要」なら、何も重要ではありません。譲れないものを先頭に置き、ラベルを付けましょう。
6. ドキュメントの丸写し。 これは指示であって、wiki ではありません。ドキュメントへリンクを張るだけにして、中身を貼り付けないこと。

プロバイダーをまたいで単一のコンテキストを保つ

ここからが、たいていのガイドが飛ばす実践的なパートです。あなた自身、あるいはチームが複数のエージェント CLI を使うなら、同じルールが 3 つに分かれてずれていくコピーなど欲しくないはずです。

クリーンなアプローチは 2 つあります。

• 正典となる 1 ファイル、薄いポインタ。 すべてを AGENTS.md に集約し、CLAUDE.md と GEMINI.md は「AGENTS.md を参照」と書いただけの 1 行ファイルにする、あるいはシンボリックリンクにします。信頼できる情報源は 1 つ、すべてのツールに行き渡ります。
• 規約で共有する 1 ファイル。 ツールにカスタムパスを指定できるなら、すべてを AGENTS.md に向け、残りは削除します。

どちらにせよ、ルールは同じです。コンテキストは 1 度だけ書く。プロバイダーごとに書くのではありません。それが正しさを保つ唯一の方法でもあります。なぜなら、人が実際にメンテナンスするのは、単一のファイルだけだからです。

複数のエージェントを同時に走らせるとき

リポジトリレベルの AGENTS.md は「このプロジェクトは何か」に答えます。けれども「このエージェントは誰か」には答えません。同じコードに対して Backend エージェント、Frontend エージェント、QA エージェントを並行して走らせるとき、それぞれには共有のプロジェクトコンテキストに加えて、自分自身の役割が必要です。

それが、AgentsRoom があなたの AGENTS.md の上に重ねるレイヤーです。各エージェントは独自のシステムプロンプトを持つ専用の役割（DevOps、Frontend、Security など）を与えられるので、共有ファイルはスリムなまま、各エージェントは自分の仕事をきちんと把握できます。設計からしてプロバイダー非依存なので、同じセットアップで Claude、Codex、Gemini を並べて動かせますし、繰り返し使う指示はセッションごとに打ち直すのではなくプロンプトライブラリに置けます。

ここまで来たら、次に自然に読みたくなるのは複数のエージェントを見失わずに並行して走らせる方法でしょう。

まとめ

AGENTS.md を 1 つ書きましょう。短く、最新に、ポータブルに保つこと。エージェントごとにファイルを抱えるのではなく、すべてのツールをそこに向けます。あなたのコンテキストは、たまたま最初に使い始めた CLI に縛られなくなり、どのエージェントを走らせても、みんな同じ前提からスタートします。

すべてのエージェントを 1 つの画面に、それぞれの役割と共有コンテキストとともに並べたいですか？ AgentsRoom をダウンロードして、プロバイダーをつなぎ、あなたのフリートを仕事に投入しましょう。