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

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

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

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

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

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

AGENTS.md vs CLAUDE.md vs GEMINI.md

このガイドを最初に書いた時点では、各ツールがそれぞれ専用のファイルを探していました。その後、ほとんどのツールが AGENTS.md に集約されています。

• Codex は AGENTS.md を読みます。GitHub Copilot CLI、Cursor、Amp、そして新しいエージェント CLI の多くも同様です。
• Claude Code は CLAUDE.md を読みます。さらにバージョン 2.1.277 以降は、作業ディレクトリとその上位のディレクトリに CLAUDE.md も CLAUDE.local.md もない場合、AGENTS.md も自動で読み込みます。CLAUDE.md がある場合、Claude はそのファイルだけを読みます。ただし /config で Project instructions の設定を変えた場合は別です。
• Antigravity CLI は、リポジトリのルートまたは任意のサブディレクトリにある AGENTS.md か GEMINI.md を読み、加えて .agents/rules/ フォルダと ~/.gemini/ 配下のグローバルルールも読みます。

内容は 3 つともほぼ同じです。プロジェクトのコンテキスト、コマンド、規約。今も違うのは、複数のファイルがあるときにツールがどれを選ぶかです。だからこそ、同じルールを手作業で 3 つのファイルに複製するのは、最初から負けが見えた戦いなのです（同期を保つ方法については後ほど触れます）。これらの挙動は、2026年10月10日に Claude Code のメモリに関するドキュメントと Antigravity のルールに関するドキュメントで確認しました。

主に 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 つあります。

• AGENTS.md を 1 つだけ、ほかには何も置かない。 Claude 専用のルールが誰にも必要ないなら、AGENTS.md を 1 つだけ置きましょう。Codex、Antigravity CLI、Claude Code 2.1.277 以降のすべてがこれを読みます。落とし穴は静かです。あとから CLAUDE.md、あるいは個人用の CLAUDE.local.md を追加すると、Claude Code は AGENTS.md を読まなくなります。
• 正典となる 1 ファイル、1 つのインポート。 すべてを AGENTS.md に集約し、CLAUDE.md を @AGENTS.md という行で始めて、その下に Claude 専用のルールを書きます。Claude はインポートされたファイルを先に読みます。私たち自身のリポジトリもこの方式で、CLAUDE.md はその 1 行だけです。シンボリックリンク（ln -s AGENTS.md CLAUDE.md）でも動きますが、Windows ではうまくいきません。Windows では作成に管理者権限か開発者モードが必要で、core.symlinks なしのクローンでは、あなたの指示の代わりに 1 行のテキストファイルが届きます。

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

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

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

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

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

まとめ

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

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

よくある質問

AGENTS.md とは何ですか？

Markdown ファイルで、通常はリポジトリのルートに置かれ、コーディングエージェントが作業を始める前に常設の指示として読み込みます。プロジェクトが何であるか、どうビルドしてテストするか、守るべき規約、そして避けるべき落とし穴です。1 つのツール専用のファイルではなく、ツール間で共有されるオープンな規約で、Codex、Antigravity CLI、GitHub Copilot CLI、Cursor、Amp、そしてバージョン 2.1.277 以降の Claude Code が読み込みます。

Claude Code は AGENTS.md を読みますか？

はい、Claude Code 2.1.277 以降で読みます。ただし、作業ディレクトリとその上位に CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md のいずれもない場合に限ります。そのとき Claude Code は作業ディレクトリから上に向かってすべての AGENTS.md を読み込み、サブディレクトリのファイルを開いたときはそのサブディレクトリの AGENTS.md も読み込みます。CLAUDE.md がある場合、Claude はそのファイルだけを読みます。ただし /config で Project instructions を claude-md-and-agents-md に設定した場合は別です。古いバージョンでは、CLAUDE.md の先頭に @AGENTS.md という 1 行を置いてください。

Antigravity が使うのは AGENTS.md ですか、GEMINI.md ですか？

両方です。Antigravity は、リポジトリのルートまたは任意のサブディレクトリにある AGENTS.md、GEMINI.md、.agents/rules/ フォルダを読み込み、グローバルルールは ~/.gemini/ から読み込みます。ルールは互いを置き換えるのではなく積み重なり、2 つのルールが矛盾するときは、より具体的なディレクトリのルールが優先されます。

AGENTS.md と CLAUDE.md、どちらを残すべきですか？

メンテナンスする唯一のファイルとして AGENTS.md を残しましょう。Claude 専用のルールも必要なら、1 行目が @AGENTS.md の CLAUDE.md を追加し、その下にそのルールを書きます。Claude はインポートされたファイルを先に読みます。必要なければ、Claude Code 2.1.277 以降なら AGENTS.md だけで十分です。同じルールの完全なコピーを 2 つ持つのは避けましょう。誰も編集しない方が古くなっていきます。

AGENTS.md はどこに置くべきですか？

どこにでも適用されるルールは、リポジトリのルートに置きます。Claude Code と Antigravity はサブディレクトリの AGENTS.md ファイルも読むので、独自のコマンドを持つパッケージやサービスは自分専用のファイルを持てます。そのファイルは、エージェントがそのフォルダで作業するときに読み込まれます。