AGENTS.md - AIコーディングエージェントのためのオープンフォーマット
(agents.md)- AGENTS.mdはREADMEを補完する役割を持ち、AIコーディングエージェントがプロジェクトで作業する際に必要な文脈と指示をまとめる専用ファイル
- 20,000件以上のオープンソースプロジェクトで使われており、ビルド/テスト/コードスタイルなど、人間には不要でもエージェントには重要な情報を整理
- 明確で予測可能な場所にエージェント専用の指示を提供し、READMEを簡潔に保ちながら協業効率を強化
- 単一のAGENTS.mdでさまざまなエージェントやツールと互換性があり、大規模なモノレポではサブプロジェクトごとの個別AGENTS.mdも利用可能
- OpenAI Codex、Cursor、Google Julesなど複数エコシステムの協業によって作られたオープン標準
Why AGENTS.md?
- README.mdは人間のためのドキュメントであり、クイックスタート、プロジェクト説明、コントリビューションガイドラインを提供
- AGENTS.mdはエージェント向けの補助ドキュメントで、ビルド/テスト/コード規則のような詳細な文脈を含めつつ、READMEを複雑にしない
- 別ファイルにしている理由
- エージェントが参照する予測可能な指示の場所を提供
- READMEは人間のコントリビューター中心に簡潔なまま維持
- 既存ドキュメントを補完する精密なエージェント専用指示を提供
- 独自フォーマットではなく、誰でも使えるオープン標準の名称を採用
- 1つのAGENTS.mdで複数のAIコーディングエージェントやツールと互換
How to use AGENTS.md?
- 1. AGENTS.mdファイルを作成
- リポジトリのルートに配置（多くのエージェントが自動生成をサポート）
- 2. 主要項目を記述
- プロジェクト概要
- ビルドおよびテストコマンド
- コードスタイルのガイドライン
- テスト方法
- セキュリティ上の考慮事項
- 3. 追加指示を含める
- コミット/PRルール、セキュリティ上の注意点、大規模データセット、デプロイ手順など、チームメンバーに伝える内容
- 4. モノレポへの対応
- 各パッケージごとにAGENTS.mdを配置可能
- エージェントは最も近いファイルを読んで、そのサブプロジェクトに適した指示に従う
- 例: OpenAIのリポジトリには88個のAGENTS.mdが存在
FAQ
- 必須項目: なし。一般的なMarkdown形式を自由に使用可能
- 競合が発生した場合: 最も近いAGENTS.mdが優先され、ユーザーが明示したプロンプトが最終適用
- 自動実行の有無: ファイルに記載されたテストコマンドは、エージェントが実行してエラー修正を試みる
- 更新可能性: いつでも変更可能で、生きたドキュメントとして管理
- 既存ドキュメントの移行: ファイル名変更後、シンボリックリンクで互換性を維持
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
1件のコメント
Hacker Newsの意見
小規模なプロジェクトなら 1 つの .md ファイルだけでも十分だが、複雑なプロジェクトでは階層的なフォルダー構造と index.md のほうがはるかに効果的だと感じた。
index.md と、その配下に auth.md や performance.md のようなファイルを置く構成は保守もしやすく、LLM やエージェントが不要なトークンを消費せずに関連する文脈だけを取り出せる。
.docs ファイルは人間にも LLM にも適したものになり、index.md には各ファイルの簡単な案内や構成ガイドも含められる。
ただし、
.agentsという名前よりは.codebotsや.contextなど、もっと直感的な名前のほうがよさそうだ。重要なファイルやディレクトリをわざわざ隠す必要はないと思う。
特にドキュメントは隠してしまうとかえって不透明になるし、伝統のせいかもしれないが、こういうやり方はよいパターンではない。
robot_docs のような名前はどうだろうかと考えている。
実際のところ、こうした情報はコントリビューターが知りたい内容とも重なるので、本来は CONTRIBUTING.md に入るべきだと思う。
この構造は、人間とロボットの両方のためのソフトウェア設計・コーディングスタイルガイド文書のようなものだ。
私はこうした .md ファイルを docs/ フォルダーに置いていて、Claude Code が直接書いている。
AGENTS.md と CLAUDE.md はロボット専用であるべきで、1 つの大きなファイルを h2 見出しで区切るにせよ、複数ファイルに分割するにせよ、それぞれに長所と短所がある。
Arc42 のように両方を支援するアーキテクチャ文書フォーマットもある。
大きな Markdown 内で特定セクションを参照するより、別ファイルにして @メンションするほうが簡単でミスも減る。
特定部分への集中が必要なときは、小さなファイルに分けるほうがコードエージェントにも向いている。
小さなファイルは diff/PR レビューのときも扱いやすい。
コードベース内に AGENTS.md ファイルを複数置くこともできる。
ツール側で現在のディレクトリとルートディレクトリの AGENTS.md を両方読むようにすれば、情報をコードの近くに置いておけるので、望むやり方と両立できる。
私も似た構造を使っていて、index.md に各ファイルの簡単な案内を追加してかなりよい結果を得てきた。
rules.md のようにディレクトリごとに望ましい動作ルールのファイルを置く方法も試している。
たとえば realtime-service.ts や queue-service.ts のようなさまざまなサービスが集まるディレクトリなら、その横に rules.md を置くといった具合だ。
プロンプトでこのルールファイルを指定して、新しいものを簡単に作れる。名前についてはまだ考える余地がある。
今は、エージェントにコードベースを理解させるために、人間が必要とする以上の特別なガイドを追加で書かなければならない過渡期だ。
もうすぐこうしたものは不要になると思う。
もともとプロジェクト文書が十分に充実していれば、AGENTS.md にある内容もすべて含められるはずだ。
私たちは常に人間向けに文書を書くべきで、LLM の利点は人間が書いた文章を読めることにある。
そういう観点で設計するのが正しいと思う。
単にコードベース理解のためだけでなく、特定のスタイル（たとえばどの assert ライブラリでテストを書くか、コメント禁止、構造化ログを使う、など）を明示する用途としてもかなり有用だ。
むしろコードがほとんどない新規プロジェクトのほうが役に立つかもしれない。
機械が読めるルールは、社会のあちこちでもっと導入されるようになると思う。
例として自動運転と交通法規があるが、実際には人間でも文脈をつかみにくい標識（例: 「赤信号で右折禁止、学期中の平日 7～9 時」）は、機械にはさらに難しい。
最終的には行政機関が文脈依存を減らすか、機械可読な信号（QR コードなど）に変える必要がある。
そうした変化がなければ、機械がルールを破ることは多くなるだろう。
ビジネスロジックのような領域では、今後もエージェント向けの特別な案内がどうしても必要だと思う。
何を作っているのか、意図は何か、プロジェクトの最終目的は何かといったことは、人間が具体的に伝えない限り機械には分からない。
アーキテクチャのようなものも、人によって基準が違うので、頭の中に構造ができていないと実際の変更を見るときの理解に役立たない。結局、本当のボトルネックはそこだ。
全体としては同意するが、特定の情報（たとえば毎回必ずコンテキストに入れたいもの）は別ファイルとして強制的に含めたくなることもある。
私たちが暗黙に前提としているルールや仮定を文書化しなければ、LLM には分からない。
コードからある程度推論はできても 100% は不可能なので、要件を明示的に書いておくことが重要だ。
AGENTS.md というのは結局 README.md と同じ役割をしつつ話題性を集め、そのおかげで実際に人々が内容を埋めているという点が興味深い。
人は他人のために文書を書くのは面倒がるのに、ロボットのためなら熱心に書いているのが面白い。
これは、少数のために人間工学設計をしたら結果的に全員にとって使いやすいハンドルデザインになった、というような話に似ている。
むしろ逆で、人々が文書を読まないから、誰も書く動機を持てなかったのだと思う。
エージェント向けの CLAUDE.md は一度書いておけば、すぐに 1000 個のエージェントに読まれるのだから書きがいがある。
どうせ README.md に最低限だけ書けばいいのでは、という気もする。
実際にはエージェントですらこの文書を読まなかったり、何度か追加で指示すると全部忘れたりする状況だ。
今の状況は、人々が人間の開発者（自分自身を含む）を開発プロセスから積極的に外そうとしているために、エージェントが適切な案内を必ず持っていなければならなくなっているということだ。
人間のソフトウェア開発への関与をすべてなくしたいという欲求が強まっているからだ。
最近の空気感そのものが vibe coding だ、という冗談を言っている。
ボット向けの文書を書くことは、結局よく書かれた文書と変わらないという意見も以前に出ていた気がする。
結局「AGENTS.md ファイルを作って魔法を詰め込んでください」とだけ書いて、実際のサイトにリンクしている感じがする。
私の場合、5,000 個以上のリポジトリを管理するコーディングエージェントを開発している。
エージェントの状態は隠し
.agentディレクトリ内に保存され、各エージェントの役割ごとの設定フォルダーと、明確な役割別指示を含んでいる。プロジェクトフォルダーに agents というフォルダーを置き、複数ファイルを役割ごとに分けて
<Role> <instruction>の形で管理している。エージェントは役割が定義されたファイルだけを読み、状態は dot<coding agent name> フォルダーに保存する。
初期化は /init で行い、リポジトリ全体のコードを単純にインデックス化する代わりに、全体アーキテクチャとロジックを要約した high-level summary を生成する。
この要約はエディター内で切り替え可能な「ghost comments」として提供され、実際のコードにはコミットされないメタデータだ。
精密なマッピングシステムにより、各要約はコード行と正確に結び付けられる。
最初に RAG をコードへ直接適用したときは望む結果が得られなかったので、現在の構造を導入した。
今は AST ベースの高速な構文検索と、要約に基づく意味探索（RAG）を組み合わせたハイブリッド検索モデルを使っている。
たとえば「このアプリの認証方式はどう動いているのか？」と尋ねると、構文検索は login のような単語を含む関数だけを見つけるが、意味検索は要約を通じて認証フロー全体を物語的に把握し、ファイルに散らばった内容をつなぎ合わせてくれるという点で、まるで魔法のように機能する。
これに加えて、要約の階層構造（B ツリーまたは通常のツリー）を作ることもできる。
つまり、メソッド/クラス/モジュールごとに summary が存在し、各階層がさらに下位階層を指すように設計する。
RAG は意味クエリに応じて必要な深さまで探索でき、各段階では下位内容を要約して情報量を減らしつつ、必要な意味だけを保てる。
この方式はコードの抽象化がうまくできているときに特に効果的だ。
例として add(n1, n2) のように名前だけで意味が十分伝わる関数なら実装を知らなくてもよいが、現実の関数はログ出力やキャッシュなど複数の役割を持つことが多く、状況によっては実コードもコンテキストに入れる必要があるかもしれない。
もっと詳しい説明を聞きたい。
人間が少しずつ、プロジェクト文書をきちんと書くよう仕向けられている感じがする。
冗談ではあるが、実際こういう点をチームにアピールしている。
LLM が本当に生産性を大きく上げなくても、結果として文書化がずっとよくなる効果はある。
"Mission. Fucking. Accomplished." xkcd 810
README.md と AGENTS.md をわざわざ分けるべきなのか、まだ確信が持てない。
関連まとめ によると、
分ける理由としては、
分けない理由は、
README.md は今や一種のマーケティング/ランディングページ用で、AGENTS.md や CLAUDE.md はコード/アーキテクチャ/使い方など実際の内容を得に行く場所、という感じがする。
例を読みながら私も同じことを考えていて、実際のところ、良い README.md ひとつにすべて入っていれば十分なのではないかと思う。
README は人間向け、AGENTS.md などは LLM 向けだ。
使用方法やインストール方法は README に、コンパイル/テスト方法、アーキテクチャ上の決定事項、コーディング標準、リポジトリ構造などはエージェント文書にまとめる。
LLM でコンテキストとして使う際の容量の問題も考えなければならない。
README.md は内容が多く、全部をコンテキストに入れるのは難しい。
AGENT.md には、LLM に本当に必要なテストやビルドコマンドなどの重要なコマンドだけを簡潔に入れる。
README と重複する部分があっても、不要な内容がコンテキストで繰り返し送られるのは避けたい。
AI の約束というのは、そもそもこちらが厳密なフォーマットにこだわらなくても、望む形で書けば機械が勝手に合わせてくれることではなかったのか？
実際にはファイル名だけを標準化し、内容については何の形式も強制せず、誰でも好きなやり方で書けるようにしたのが正しい選択だ。
AGENTS.md は標準 Markdown なので、好きな見出しを使えばよく、エージェントはそのテキストをパースする。
それでも、ある程度の構造や形式には重要性がある。
厳密なコード構文レベルではないにしても。
結局は内容を明確に書かなければならない、という結論になる。
文書が長くなるほど、構造的なアプローチのほうが人間にとって保守しやすい。
使うエージェントごとに（Claude Code、Gemini、Aider）ファイル名がそれぞれ違う。
標準化されるとよいが、今は ruler で複数フォーマットを自動生成する手間を受け入れている。
特にエージェントごとに MCP 設定ファイルの扱い方も違うので、すぐに標準化が実現するのは難しいと思う。
ruler
少しシニカルに見るなら、ベンダーロックインを作るための動きだと思う。
標準化は商品化につながりかねないので、各社はそれを嫌がっているように見える。
Jules は AGENTS.md を使っていて、Google がこの標準に加わっていることを示している。
Gemini Code Assist も今後存続するなら AGENTS.md をサポートするはずだ。
Aider の文書には特定のファイル名が書かれていないようだが、もしリンクがあれば教えてほしい。
標準ファイル名をまだサポートしていないのは Anthropic だけのように見える。
ruler のようなツールが実際に必要だというのは少し残念だ。
何だか奇妙に感じるウェブサイトだ。
OpenAI が作ったものなら、訪問者集めやマーケティング上のポジショニングが目的なのかと思ってしまう。
実際にはフォーマットはなく、ファイル名だけを指定している。
Anthropic/Claude が入っていないのも目立つ。symbolic link の手法で CLAUDE.md を AGENTS.md にリンクすることもできるが。
実際には sourcegraph が作ったもので、5 月から存在していた。
以前は agent.md だったが、今は agents.md に 301 リダイレクトされる。
過去リンク を参照。
公式発表 もある。
最近 OpenAI とパートナーシップを結んだようだ。
興味深いことに、最初は agent.md だったが今では agents.md に変わっている。
Claude が一覧にないのは、Claude だけがまだ標準ファイル名の規則をサポートしていないからだ。