AGENTS.md は、慣例としてリポジトリのルートに置かれる Markdown ファイルで、プロンプトごとに AI コーディングエージェントのコンテキストに読み込まれ、プロジェクト固有の規約や制約を伝える。一般的なコーディングエージェントは /init のようなコマンドでこれを自動生成でき、そのコマンドはコードベースを走査して、ディレクトリ構造、技術スタック、テストの規約の説明を生成する。
このフォーマット自身のプロジェクトは、自らを一行で「コーディングエージェントを導くための、シンプルでオープンなフォーマット」と説明し、エージェントのための README、つまり AI コーディングエージェントがプロジェクトに取り組むのを助けるコンテキストと指示を提供するための、専用の予測可能な置き場所だと言い換えている。これは agentsmd/agents.md リポジトリから MIT ライセンスのもとで公開されており、プロジェクトの目的を説明するウェブサイト https://agents.md/ が併設され、リポジトリには技術憲章（technical charter）も置かれている。プロジェクトが提供する最小限の例は、三つの ## セクション（開発環境のヒント、テストの手順、プルリクエストの手順）を持つプレーンな Markdown ファイルで、その中身はコードベースについての散文ではなく、具体的なコマンドと規約（どのパッケージマネージャーのコマンドを使うか、CI の計画がどこにあるか、必須のタイトル形式、コミット前に実行するチェック）である。
起源と命名
このファイルがなぜ今の名前を持つに至ったかは、ある採用者の記録が補ってくれる。メルカリ Web モノレポでエージェントを飼いならす には、あるチームがこの標準を見つけたとき、それは単数形の AGENT.md であったことが記されている。そこでは、Sourcegraph が AmpCode プロジェクトを通じて提案した RFC と説明されており、チームは既存の Cursor と Claude のルールをそうしたファイル一つに統合したが、チームの他のメンバーはその RFC がどれだけ長続きするのかを気にしていた。同記事はその後、OpenAI が agents.md ドメインを確保したと報告している。同記事によれば、それこそが標準を複数形の表記へ移行させるのを妨げていた唯一の要因であり、またそれは OpenAI 自身の Codex がすでに使っていたファイル名でもあった。同記事は、OpenAI の後押しによって、このチームが使っていたツールの間で標準がはるかに広く受け入れられるようになったとし、チームは複数形の形式を唯一の信頼できる情報源（single source of truth）として採用した。これは、一つのチームが採用者として観察したことの記録であり、標準がどのように設計されたかについての当事者の記録ではない。また、同記事が言及している発表そのものは、このウィキの情報源には含まれていない。
同記事は、ツールごとのルールファイルをすでに持っていたコードベースにこれを導入したことの実際的な帰結も説明している。CLAUDE.md やその他多くのルールファイルは、単にメインのファイルへのシンボリックリンクとなり、既存のフォーマットは内容を二重に保守することなく動作し続けた。
後の記録は、この標準が最終的にどこに落ち着いたかを付け加えている。AIに渡す指示書の役割分担: AGENTS.md/SKILL.md/DESIGN.mdと仕様駆動開発の現在地 は、Sourcegraph の Amp チームをその出発点として挙げ（どこから始まったかについては上の採用者の記録と一致する）、その後 OpenAI、Google、Cursor、Factory などが共同で推進するようになり、2025 年 12 月に Linux Foundation に寄贈されたと説明している。つまり、上の採用者の記録が未解決のまま残していた問い、すなわち一つのベンダーの RFC が長続きするのかという問いは、標準を特定のベンダーの手から離すことによって答えられた。同記事はまた、シンボリックリンクによる構成を、一チームの便宜的な工夫ではなく、フォーマットのプロジェクト自身が推奨するパターンとして示している。Claude Code は AGENTS.md ではなく CLAUDE.md を読むため、AGENTS.md を実体のファイルとし、CLAUDE.md をそこへのシンボリックリンクにすることが推奨される。同記事は CLAUDE.md を、単に Claude 専用の AGENTS.md だと特徴づけている。
用法
情報源の中で要約されている引用研究によれば、本当に発見できない、運用上重要な事実（たとえば「パッケージ管理には uv を使う」）を記録した人間が書いた AGENTS.md は、エージェントの振る舞いを測定可能な形で変え、タスクの成功率を高めた。一方、自動生成されたファイル（典型的には、エージェントがリポジトリを直接読めば発見できるコードベースの概要）は、成功率を改善することなくコストを増やし、場合によっては成功率を下げさえしたことがわかった。情報源はまた「アンカリング効果」についても説明している。ある技術やパターンがファイルの中で一度言及されると、それは以後のすべてのプロンプトでコンテキストに残り続けるため、それがもはや現在の規約でなくなっている場合でも、エージェントをそちらへ偏らせることがある。
同じ著者による別の記事は、OpenAI の Codex のドキュメントを引き、実行すべきテスト、lint ルール、依存関係のポリシー、ドキュメントの要件について、エージェントに一貫した期待を与えるために AGENTS.md ファイルを用いることが推奨されていると紹介している。そこでは、新入社員がコードを書き始める前に規約の地図を渡してオンボーディングすることになぞらえられている。同記事はまた、AGENTS.md や関連するチェックリストを更新することを、反復可能なオーケストレーションループの最後の「振り返り（retro）」ステップと位置づけ、次の実行がより賢い状態から始まるようにするとしている（AI コーディングエージェントにはマネージャーが必要だ）。
GitHub は、Agent HQ とあわせて発表された VS Code のカスタムエージェント向けの設定面の一つとして、このファイルを採用した（Agent HQ の紹介：あらゆるエージェントを、あらゆる働き方で を参照）。GitHub はそこで AGENTS.md ファイルを、明確なルールとガードレールを設定するためのソース管理されたドキュメントと説明し、例として「このロガーを優先せよ」や「すべてのハンドラーでテーブル駆動テストを使え」を挙げ、その要点を、毎回プロンプトし直すことなく Copilot の振る舞いを方向づけることだとしている。
GitHub Copilot コードレビュー についての GitHub のドキュメントは、このファイルを四つのカスタマイズ面の一つに位置づけ、それらを適用範囲によって区別している。これは、このファイルを 使うべきでない のはどんな場合かについて、このウィキが持つ最も明確なベンダーの記述である。.github/copilot-instructions.md は Copilot 固有の、リポジトリ全体に常に適用されるルールを保持する。.github/instructions/ 以下のパス固有の *.instructions.md ファイルは、特定のパス、ファイルタイプ、ディレクトリに常に適用されるルールを保持する。リポジトリのルートから読まれる AGENTS.md は、AI ツールやエージェントの間で共有されることを意図した、常に適用されるルールを保持する。そして .github/skills/ 以下のスキルは、必要に応じて、または関連するときに実行されるタスク固有のワークフローを保持する。GitHub はこの区別を四つの経験則に凝縮している。「Copilot よ、このリポジトリについてはこれを常に知っておけ」「Copilot よ、これらのパスで作業するときはこれを常に知っておけ」「どのエージェントも、これを常に知っておけ」「必要なときにこれを行え」。したがってこの説明で AGENTS.md を際立たせているのは、リポジトリ内での適用範囲ではなくツールをまたいで届くことであり、それは上の採用者の記録がこれを選んだ理由と同じ性質である。同じドキュメントは、プルリクエストのレビュー中、Copilot はカスタム指示、エージェント指示、スキルをベースブランチではなくヘッドブランチから読むと述べている。そのため、いずれかへの変更は、先にマージすることなく、それを導入するプルリクエストの中でテストできる。
エージェント型ソフトウェアエンジニアリング：基盤となる柱と研究ロードマップ は、CLAUDE.md、.clinerules、AGENT.md といったプロジェクトレベルの設定ファイルを、あらゆるエージェントタスクの前に「組織の知識」を読み込ませる、初期の草の根的な実践として論じている。そこでは、スタイルガイド、アーキテクチャ上の制約、得られた教訓が、AI のチームメイトのための継続的に改善される「従業員ハンドブック」へと体系化される。同論文はこの実践を、自らが MentorScript として形式化を提案するものの初期の例と位置づけ、コミュニティにはそうしたファイルに何を含めるべきか、どの程度の詳しさが適切かについての合意がないと述べ、今後の課題は、この目的のためのより形式的な言語を定義することだけでなく、こうしたファイルを効果的に使うためのベストプラクティスを見いだすことでもあると論じている。
ある実践者の記録は、このファイルを他のどの記録もここまでの深さでは説明していない用途に使っている。エージェントが読むコンテキストとしてだけでなく、手続き そのもの を置く場所として使うのである。人間は意図、AIは実装：Codexが導く「要件を伝えるだけ」のAI駆動開発ワークフロー は、プロジェクトの初期化時に AGENTS.md を、同記事が AI のメモリと呼ぶものとして書き、そこにプロジェクトの概要、フォルダ構成、参照必須のドキュメント、作業ルール、現在の状況を保持させている。同記事がそこに記録している四つの作業ルールは、行動する前に計画を立て承認を得てから実行すること、計画や提案の際には三つの選択肢を提示すること、実装の前に関連する仕様を確認・更新すること、完了時にストーリーごとのコンテキストファイルを更新すること、である。それらと並んで、自動生成のルールそのもの、すなわちルーチンを起動するフレーズ、実行する手順、生成すべきフォルダとファイルの構成、結果として得られるファイルの形も保存されている。同記事が主張する帰結は、エージェントではなくプロンプトの側に表れる。配置と手続きがすでに書き留められているので、プロンプトは出力先のパスを列挙する代わりに要件を述べるだけでよい（「vision.md を読んでユーザーストーリーを生成せよ」）。著者の経験則は、こうしたルールファイルが充実するほどプロンプトは単純になり、出力は良くなるというものである。これはサンプルプロジェクトでの一人のエンジニアによる実演であり、測定の裏付けはない。
適用される場面
情報源は、良い AGENTS.md を恒久的な設定ではなく、コードベースの摩擦の生きた記録として位置づけている。エージェントが同じ誤りを繰り返したときに一行が追加され、根本的な問題（わかりにくいディレクトリ構造や、本来自動的に何かを検出すべきビルドパイプライン）が代わりに修正されたら、その行は削除される。情報源は実際的なフィルターを次のように述べている。エージェントがコードを読んで発見できる事実なら、それはこのファイルに属さない。情報源はまた、単一で静的な、リポジトリのルートに置かれた一つのファイルを、ある程度以上の複雑さを持つコードベースにとっての構造的な限界として扱っている。フラットな指示の集合は、どんな種類のタスクが実行されているかに応じて内容を変えることができないからであり、意図された代替として、自動的に保守されるディレクトリ単位またはモジュール単位のファイルの階層を提案している。さらに、このアイデアのより精緻な三層版（最小限のルーティングファイル、タスク単位のスキルファイル、保守用のサブエージェント）についても説明し、そのより完全なアーキテクチャをきれいに構築するのに必要なライフサイクルフックを公開している主要なコーディングエージェントはまだないと指摘している。
このウィキの情報源は、このファイルに何を書くべきかについて一致していない。 上の最初の情報源は発見可能性のフィルターを設けている。エージェントがコードを読んで得られる事実には一行を割く価値がない、というもので、その著者はこれを、LLM が生成したコンテキストファイルがタスクの成功率をわずかに下げ、コストを大幅に上げることを示した研究から引き出される実際的な教訓としている。上の実践者の記録は、フォルダ構成、作業ルール、自動生成の手続きをそこに保存しており、これはそのフィルターが認めるよりもかなり多い。そして、ルールファイルが充実するほどプロンプトは単純になり出力は良くなるという、逆方向の主張をしている。両者は同じものを測っているわけではない。一方はタスクの成功率についての実験結果を報告し、他方はサンプルプロジェクトでの一人のエンジニアの作業方法を報告しており、どちらも相手に言及していない。そのため、両者を調停するのではなく、どちらもここに記録している。両者を分けているのは目的かもしれない。発見可能性のフィルターはエージェントが何を 知る 必要があるかについてのものであり、起動されるように書かれた手続きはエージェントが何を 行う べきかについてのものであって、後者はどれだけコードを読んでも得られない。
あるチームは、その最初の情報源が提案する階層に近いものを実践に移しており、その形は記録しておく価値がある。それはこの不一致を解決するのではなく、回避しているからである。メルカリ Web モノレポでエージェントを飼いならす では、ルートの AGENTS.md 自体はほとんど何も保持していない。そのセクションはどれも、見出しと docs/ 以下の別のドキュメントへのポインタだけであり、ビルドとテストのコマンド、コードスタイルと標準、プロジェクトのアーキテクチャ、認証のパターン、テスト戦略がそれぞれ別のドキュメントになっている。同記事は、リポジトリがモジュール構造を持つことから、アーキテクチャのドキュメントを特に重要なものとして挙げ、そのコンテキストを省いた場合のコストを、毎回同じ初期コンテキストを慎重にプロンプトで与えない限り、ほとんどのツールの出力を開発者が完全に作り直さなければならなくなることだと述べている。また、エージェントにはプロジェクトのデザインシステムを、ALWAYS/NEVER という強調した表現で教えている。コンポーネントは常にソースファイルからではなくデザインシステムのパッケージからインポートすること、デザインシステムのコンポーネントやネイティブの HTML 要素にインラインスタイルを決して追加しないこと、といった具合である。その理由として、プロジェクトはそのデザインシステムに従わなければならず、バイブコーディングで書かれた CSS に頼ることはできないからだとされている。
こうしたファイルを最新に保つことについて、そのチームの答えは委任することである。上位の設計に大きな影響を与えるプルリクエストについては、エンジニアが変更セットとルールフォルダを対象にエージェントを実行し、モデル自身にルールへの修正を提案させるか、コード中の不整合を指摘させる。これを自動化する理由として述べられているのは、タスクに集中しているエンジニアにとって、別のフォルダにあるローカルでない Markdown ファイルを編集するのは面倒だということであり、同記事はその結果を、自己強制的で自己更新するドキュメントと呼んでいる。これはチーム自身による特徴づけであり、測定を伴わずに示されたものである。また、執筆時点でチームが構築していたもの、すなわちすべてのプルリクエストでルールから外れたコードを指摘するエージェントは、まだリリースされていなかった。
長時間稼働するエージェントについての後の記事は、長時間または夜通しのコーディングジョブを実行する開発者に向けて、同じファイルにさらなる設計原則を与えている。AGENTS.md をパイロットのチェックリストのように扱い、短く保ち、すべての行が実際の過去の失敗によって正当化されたものであるようにする、というものである。同記事はそれとは別に、Anthropic 自身の科学計算向けエージェントが CLAUDE.md を同様の役割で使っていることも説明している。そこでは CLAUDE.md はエージェント自身が学びながら編集する生きた計画であり、持ち運び可能な実験ノートとして機能する CHANGELOG.md と組み合わされている（Ralph Loop を参照）。
このようなファイルが実際にどのように解釈されるかについての最も明確な記述は、ベンダーの側から来ている。OpenAI は codex-1 のシステムメッセージを Codex の紹介 の付録として公開しており、その一節は、エージェントが従うルールとして書かれた AGENTS.md の仕様になっている。それはエージェントに次のように告げる。これらのファイルはコンテナのファイルシステムのどこにでも現れうる。典型的な場所はルート、ホームディレクトリ、git リポジトリ内のさまざまな場所であり、したがってリポジトリの中にある必要すらない。ファイルの適用範囲は、それを含むフォルダを根とするディレクトリツリー全体であり、最終的なパッチで触れるすべてのファイルについて、エージェントはそのファイルを適用範囲に含むあらゆる AGENTS.md に従わなければならない。コードのスタイル、構造、命名に関する指示は、ファイルが別途述べない限りその適用範囲の中でのみ適用される。指示が衝突する場合は、より深くネストしたファイルが優先される。そして、プロンプト内の直接のシステム、開発者、ユーザーの指示はファイルよりも優先される。さらに二つの規定は、ファイルがどこに適用されるかではなく、ファイルが何を求めうるかに関するものである。ファイルが指定するプログラムによるチェックは、すべてのコード変更の後に、ドキュメントのような単純な変更であっても、すべて実行し、それらが通ることを確認するよう最善を尽くさなければならない。また、プルリクエストのメッセージについてファイルが与える指示は尊重されなければならない。OpenAI は、開発者がモデルのデフォルトの振る舞いを理解し、Codex を自分のワークフローに合わせて調整できるようにするためにシステムメッセージを公開したと説明し、そうした変更の例として、時間がないときにそれらのテストを省略することを挙げている。したがって優先順位のルールは、単なる衝突解決の細部ではなく、ユーザーが頼りにできるものとして示されている。
セキュリティ上の考慮事項
このファイルを有用にしている性質は、同時にこれを標的にもしている。エージェントは設計上これらのファイルを信頼できるプロジェクトのコンテキストとして読み込むため、作業ツリーにこのファイルを書き込めるものなら何であれ、その地位を伴った指示を与えることができる。NVIDIA AI Red Team の報告は、これを Codex に対して実証した。悪意ある Go の依存関係が、どの依存関係でもそうでありうるようにビルドステップ中に実行され、ユーザー自身の要求よりも優先されると主張する指示を含んだ AGENTS.md を書き込み、エージェントは与えられていたタスクよりもそれらの指示に従った。報告は、このファイルの信頼モデルは欠陥ではなく意図的なものであること、そしてこの攻撃は侵害された依存関係、すなわちすでにコード実行ができている状態を前提としていることを明言している。したがってこの攻撃が付け加えるのは、そのアクセスを得る新しい方法ではなく、そのアクセスの新しい使い道である。
報告が提案する緩和策のうち、ファイルそのものを対象とするものは、その内容ではなく完全性に関するものである。エージェントが読み書きできるファイルを制限すること、エンドポイントセキュリティや集中型の構成管理を用いて設定ファイルに特化した完全性の管理を強制すること、予期しないファイルの変更に対してアラートを出すことである。報告はファイルとはまったく関係のない緩和策も提案している。依存関係のバージョンを厳密に固定しパッケージをスキャンすること、エージェントが生成したプルリクエストを専用のセキュリティエージェントで監査すること、そしてモデル自体をスキャンしガードレールを設けることである。攻撃そのものについては 間接 AGENTS.md インジェクション を参照。
これは上で説明した優先順位のルールに関わってくる。codex-1 の仕様は、直接のシステム、開発者、ユーザーの指示がファイルよりも優先されると述べている。しかし報告された攻撃では、エージェントはその逆を主張するファイルに従って行動した。したがってその順序は、文書化されたデフォルトであって、注入されたファイルが異を唱えられないものではない。
関連用語
ハーネスエンジニアリング, Agentic Context Engineering, Ralph Loop, 間接 AGENTS.md インジェクション, 間接プロンプトインジェクション, OpenAI Codex