AGENTS.mdとは・意味、仕組み・由来・研究
最終確認日：2026年10月28日
AGENTS.mdとは？
AGENTS.mdとは、AIのコーディングエージェントにプロジェクトの決まりや作業の手順を伝えるため、リポジトリに置くMarkdown形式のファイルのこと。コーディングエージェントは、指示を受けてコードを書き、テストなどのコマンドを実行するAIを指す。
リポジトリはプログラムのファイルをまとめて管理する保管場所で、Markdown は見出しや箇条書きを記号で表す文章の形式だ。AGENTS.md の公式サイトは、このファイルをエージェント向けの README にたとえている。README は、プロジェクトの概要や使い方を人に向けて書くファイルだ（※1）。
AGENTS.md は OpenAI が2025年8月に公開した形式で、今は Linux Foundation の傘下にある Agentic AI Foundation（AAIF）が管理している（※1、※2）。
OpenAI によると、GitHub Copilot や Cursor、Google の Gemini CLI・Jules、同社の Codex などのコーディングエージェントが AGENTS.md を採用した。2025年12月の発表の時点で、採用したオープンソースのプロジェクトやエージェントの枠組みは6万を超えていたという（※2）。
これまでは、Claude Code の CLAUDE.md や Cursor の .cursorrules のように、道具ごとに名前の違うファイルが使われてきた（※5、※8）。
AGENTS.md の作成に加わった Factory によると、作業部会の狙いは、こうした会社ごとのファイルをどのエージェントも読める1つの文書に置き換えることだ（※8）。GitHub の日本語の文書は、AGENTS.md を「エージェントの指示」を書くファイルとして紹介している（※3）。
AGENTS.mdに書く内容と読み込みの仕組み
AGENTS.md に必須項目はなく、よく書くのはコマンドやコードの決まり
公式サイトによると、AGENTS.md には必ず書く項目がない。見出しは自由に付けてよく、エージェントは書かれた文章をそのまま読み取る。公式サイトは、よく書かれる中身として次のものを挙げている。
- プロジェクトの概要。
- ビルドとテストのコマンド。
- コードの書き方の決まり。
- テストの手順。
- セキュリティで気をつけること。
ビルドは、プログラムを動かせる形にまとめる作業だ。このほか、コミットのメッセージの書き方やプルリクエストの決まり、デプロイの手順など、新しく加わった仲間に伝えることも書いてよいという。プルリクエストは、コードの変更を取り込むよう求める依頼を指す（※1）。
編集するファイルにいちばん近いAGENTS.mdが優先される
大きなリポジトリでは、フォルダごとに AGENTS.md を置ける。公式サイトによると、エージェントは編集するファイルにいちばん近い AGENTS.md を読み、指示が食い違うときはそのファイルの指示が優先される。利用者がチャットで出した指示は、どのファイルよりも優先される。公式サイトは、執筆の時点で OpenAI のメインのリポジトリ1つに88個の AGENTS.md があったと紹介している（※1）。
Codex は全体の指示とフォルダごとの指示をつないで読む
OpenAI の文書によると、Codex は作業を始める前に AGENTS.md を読み、指示を1つにつなげる。読む順は、利用者のすべての作業に当てはまる全体の指示、プロジェクトの最上位のフォルダの指示、作業中のフォルダに近い指示の順だ（※4）。
出典：OpenAI「Custom instructions with AGENTS.md」
つないだ指示では、作業中のフォルダに近いファイルほど後ろに来る。そのため、近いファイルの指示が前の指示より優先される。Codex は、つないだファイルの大きさが上限に達すると、それより先のファイルを足さない。上限は、初期設定では32KiBだ。全体の指示を一時的に差し替えたいときは、AGENTS.override.md という名前のファイルも使える（※4）。
AGENTS.mdとほかの指示ファイルとの違い
エージェントに指示を渡すファイルは、AGENTS.md のほかにも道具ごとにある。主なファイルを読む道具と読まれる場面は、各社の文書によると次の表のように違う。
| ファイル | 主に読む道具 | 読まれる場面 |
|---|---|---|
| AGENTS.md | Codex、GitHub Copilot、Cursor、Jules、Claude Code など | エージェントがリポジトリで作業するとき。多くの道具で、編集するファイルに近いものが優先される |
| CLAUDE.md | Claude Code | セッションを始めるたびに読む |
| .github/copilot-instructions.md | GitHub Copilot | リポジトリの中で出したすべての依頼に使う |
| .cursor/rules の中の .mdc ファイル | Cursor | ファイルの頭に書いた説明や対象のファイル、常に使うかどうかの設定に従う |
| エージェントスキル | Codex など | 名前と説明は常にモデルが読み、作業の種類に合うときに中身を使う |
※2026年10月時点。AGENTS.md は※1・※3・※4・※5・※6・※7、CLAUDE.md は※5、.github/copilot-instructions.md は※3、.cursor/rules は※6、エージェントスキルは※11 による。
OpenAI の開発者向けブログで、Eric Provencher 氏は、スキルを特定の作業の流れに向く指示として説明している。一方の AGENTS.md は、モデルがそのリポジトリで作業するときに常に使われる指示だという（※11）。GitHub Copilot のクラウドエージェント（旧称コーディングエージェント）は、AGENTS.md と並べて CLAUDE.md や GEMINI.md も読める（※9、※16）。
AGENTS.mdの由来と広まった経緯
OpenAI によると、AGENTS.md は Codex の必要から生まれた。Codex には、コードの書き方の決まりやビルドの手順、テストの条件といったプロジェクトごとの指示を、決まった場所で見つける方法が要った（※2）。Jai Lal Lulla 氏らの論文も、AGENTS.md は誰でも使える形式になる前に、まず Codex で使われていたと書いている（※13）。
公式サイトによると、AGENTS.md は、OpenAI の Codex や Amp、Google の Jules、Cursor、Factory など、AIによるソフトウェア開発の分野の各社が協力して生まれた。名前と形式は、特定の会社だけのファイルを新しく増やすのではなく、誰でも使えるものとして選んだという（※1）。
OpenAI は2025年12月9日、AGENTS.md を AAIF に寄贈した。同社が挙げる寄贈の理由は、開発者や企業がほかの道具にも持っていける形でエージェントに文脈を渡せること、形式を公開の場で育てられること、1社が方向を決めないことだ。同じ日に、Anthropic は MCP を AAIF に寄贈すると発表した（※15）。
OpenAI と Anthropic によると、Block の goose も設立時のプロジェクトとして AAIF に加わった（※2、※15）。
AGENTS.mdに関する主な出来事・ニュース
- 2025年8月19日 Factory「Factory joins AGENTS.md collaboration with OpenAI」：Factory は、OpenAI が呼びかけた業界の作業部会に加わり、AGENTS.md の仕様の案づくりに参加すると発表した。
- 2025年8月28日 GitHub「Copilot coding agent now supports AGENTS.md custom instructions」：GitHub は、Copilot のコーディングエージェントが AGENTS.md の指示を読めるようにした。
- 2025年12月9日 OpenAI、Agentic AI Foundation の設立に加わり AGENTS.md を寄贈：OpenAI は、Anthropic や Block とともに Linux Foundation の傘下で Agentic AI Foundation を設立し、AGENTS.md を寄贈した。
- 2026年9月18日 Anthropic、Claude Code 2.1.277 で AGENTS.md に対応：Anthropic は、CLAUDE.md のないプロジェクトで Claude Code が AGENTS.md を読む機能を加えた。
AGENTS.mdに関する事例・研究
初期設定の Claude Code は CLAUDE.md がなければ AGENTS.md を読む
Anthropic の文書によると、Claude Code はバージョン2.1.277から、AGENTS.md をプロジェクトの指示として読める。初期設定の Claude Code が AGENTS.md を読むのは、作業中のフォルダとその上の階層に CLAUDE.md や CLAUDE.local.md がないときだけだ。
両方のファイルを読ませたいときは、設定の「Project instructions」を変える。同じ文書は、CLAUDE.md の中から AGENTS.md を取り込み、1つのファイルをほかの道具と共有する方法も示している（※5）。
GitHub Copilot はフォルダごとの AGENTS.md に対応
GitHub によると、Copilot のクラウドエージェントでは、リポジトリの最上位に AGENTS.md を1つ置くほか、特定の部分にだけ当てはまるファイルを下のフォルダに置ける（※9）。GitHub の日本語の文書によると、Copilot が動くときは、ディレクトリのツリーでいちばん近い AGENTS.md が優先される（※3）。
Cursor と Jules も AGENTS.md に対応
Cursor の文書は、AGENTS.md を、細かい設定の要らない簡単な指示を書くためのファイルと位置づけている。Cursor は、最上位のフォルダのほか、下のフォルダに置いた AGENTS.md にも対応する（※6）。Google の Jules は、リポジトリの最上位にある AGENTS.md を自動で探し、コードの理解や作業の計画・生成する内容に生かす（※7）。
指示ファイルで成功率は上がらないと Gloaguen 氏らが報告
ETH チューリッヒの Thibaud Gloaguen 氏と LogicStar.ai などの研究者は、AGENTS.md などの指示ファイルがコーディングエージェントの課題の解決に役立つかを調べ、論文の公開サイト arXiv で発表した。
実験では、Claude Code や Codex などのエージェントを、Sonnet 4.5 や GPT-5.2 などのモデルで動かした。指示ファイルを渡しても、課題の成功率は全体として上がらなかった。推論の費用は、平均で20%を超えて増えた（※12）。
Gloaguen 氏らによると、エージェントは指示ファイルの指示によく従い、そのぶん探索やテストが増えた。リポジトリの概要を書いても、エージェントが直すべきファイルにたどり着くまでの手数は、ほとんど減らなかった。著者らは、AIに作らせた指示ファイルを当面は使わず、人が書くファイルには README にない指示だけを入れるよう勧めている（※12）。
Lulla 氏らは AGENTS.md による実行時間の短縮を報告
Jai Lal Lulla 氏らは、10のリポジトリにある124件のプルリクエストを題材に、Codex を AGENTS.md がある場合とない場合で動かして比べた。使ったモデルは gpt-5.2-codex だ。
AGENTS.md があると、中央値で比べて実行時間は28.64%短く、出力のトークンの消費は16.58%少なかった。トークンは、AIが文章を扱うときの単位だ。課題を終える度合いは、どちらの場合もほぼ同じだった（※13）。
指示ファイルにセキュリティの記述は少ないという分析も
タイの Kasetsart University や奈良先端科学技術大学院大学などの Worawalan Chatlatanagulchai 氏らは、1,925のリポジトリから集めた2,303個の指示ファイルを分析した。対象は、Claude Code の CLAUDE.md、Codex の AGENTS.md、GitHub Copilot の copilot-instructions.md だ。
著者らによると、指示ファイルは一度書いて終わる文書ではなく、小さな追記を重ねて変わっていく（※14）。
Chatlatanagulchai 氏らが選んだ332個の中身を分けると、テストの手順は75.9%、実装の詳細は70.8%、システムの設計は68.1%のファイルに書かれていた。セキュリティを書いたファイルは14.8%、性能を書いたファイルは14.5%にとどまった（※14）。
AGENTS.mdを書くときの注意
Provencher 氏は、AGENTS.md の指示がまだ要るかを度々見直すよう勧めている。同氏によると、編集のたびに複数の文書を読ませる指示は、誤字の直しのような小さな作業には多すぎる。前のモデルのために書いたテストを促す指示が、GPT-6 Astra では余計なテストにつながることもあるという（※11）。
指示ファイルの効果は、研究によって費用が増えた結果も、実行時間が短くなった結果も出ている（※12、※13）。書いた指示が作業に役立っているかを確かめることが大切だ。
公式サイトによると、AGENTS.md にテストのコマンドを書いておけば、エージェントはそれを実行して失敗を直してから作業を終えようとする（※1）。書くコマンドは、エージェントが実際に動かす前提で選ぶと良いだろう。
AGENTS.md の周りのどのファイルまで読むかは、道具によって違う。例えば Codex は AGENTS.override.md を読むが、Claude Code はこのファイルを読まない（※4、※5）。複数の道具を使うチームは、それぞれの道具の文書で読み込みの決まりを確かめておきたい。
AGENTS.mdに関連する用語
- エージェントスキル：仕事の手順や専門の知識をファイルにまとめ、AIエージェントが必要なときに読み込んで使えるようにする仕組み。
- エージェントハーネス：AIエージェントのうちモデル以外の部分で、道具の実行や文脈の管理を受け持つ仕組み。
- コンテキストエンジニアリング：AIモデルが答えを作るときに読む情報の全体を、作業の段階ごとに選んで整える技術。
- MCP（Model Context Protocol）：AIのアプリを外部のデータや道具とつなぐための、オープンソースの共通の規格。
AGENTS.mdに関する出典
※1 AGENTS.md「AGENTS.md」
※2 OpenAI「OpenAI co-founds the Agentic AI Foundation under the Linux Foundation」（2025年12月9日）
※3 GitHub「GitHub Copilot用のリポジトリカスタム命令の追加」
※4 OpenAI「Custom instructions with AGENTS.md」
※5 Anthropic「How Claude remembers your project」
※6 Cursor「Rules」
※7 Google「Getting started | Jules」
※8 Factory「Factory joins AGENTS.md collaboration with OpenAI」（2025年8月19日）
※9 GitHub「Copilot coding agent now supports AGENTS.md custom instructions」（2025年8月28日）
※10 Anthropic「Claude Code changelog」
※11 Eric Provencher「Rethinking skills and prompts for GPT-6 Astra」（2026年9月11日、OpenAI の開発者向けブログ）
※12 Thibaud Gloaguen ほか「Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?」（2026年2月12日、2026年9月29日改訂、arXiv）
※13 Jai Lal Lulla ほか「On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents」（2026年1月28日、2026年3月30日改訂、arXiv）
※14 Worawalan Chatlatanagulchai ほか「Agent READMEs: An Empirical Study of Context Files for Agentic Coding」（2025年11月17日、2026年8月9日改訂、arXiv）
※15 Anthropic「Donating the Model Context Protocol and establishing the Agentic AI Foundation」（2025年12月9日）
※16 GitHub「Research, plan, and code with Copilot cloud agent」（2026年4月1日）
