AGENTS.mdとは？エージェント向けのREADME
AGENTS.mdとは、コーディングエージェントを導くためのシンプルでオープンな形式です。 公式リポジトリのagentsmd/agents.mdでは、この形式をエージェント向けのREADMEに例えています。AIコーディングエージェントがプロジェクトで作業に使う文脈と指示を、プロジェクトの定位置にまとめておくという考え方です。
人間向けのREADMEとは別に、ハーネスの上で動作するエージェントに読ませたい内容を置く場所が、あらかじめ用意されています。たとえば、新しいセッションを開くたびに同じ指摘をエージェントへ言い直している場合、その指摘を書いておく先がAGENTS.mdです。
"AGENTS.md is a simple, open format for guiding coding agents."／"Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide context and instructions to help AI coding agents work on your project."（README）— GitHub より公式情報を見る →
AGENTS.mdの置き場所とCLAUDE.mdへのリンク
AGENTS.mdの置き場所はプロジェクトのルートです。エンジニアのFabien Sanglard氏が2026年8月21日付で公開した実践記に、この置き方が書かれています。
Sanglard氏が使うファイル名はagent.mdで、公式の形式名はAGENTS.mdです。本記事では、Sanglard氏のファイルを指すときだけagent.mdと書きます。
CLAUDE.mdのように、ツールごとに別のファイル名を使う場合は、シンボリックリンクで揃える方法があります。シンボリックリンクとは、別名のファイルから同じ中身を指させる仕組みのことです。
gemini.mdやclaude.mdをagent.mdへシンボリックリンクしておけば、どこでも同じルールを有効にできるとSanglard氏は述べています。ファイルの実体を1つにしておくと、ルールを書き直す場所も1か所にとどまります。なお、CLAUDE.mdとAGENTS.mdの機能差はここでは解説しません。
"Placing it in the root of a project should be enough. Alternatively, gemini.md/claude.md can be symlinked toward an agent.md to have it active anywhere."（本文）— Fabien Sanglard より公式情報を見る →
テンプレートは公式リポジトリの最小例から
AGENTS.mdを書くときは、公式リポジトリの最小例が手本になります。 最小例は、次のような平易な英文で書かれています。
- 変更したコードには、指示されなくてもテストを追加・更新する
最初のAGENTS.mdも、この一文と同じく1文の指示で作ることができます。いまエージェントへ言い直している指摘を、1文ずつ並べるだけです。
有名なオープンソース11件のAGENTS.mdは最短4行から最長537行まであり、中央値は175行です。 sakutto.ai編集部が2026-11-06に、各リポジトリのルートにあるAGENTS.mdをGitHubから取得し、行数と「##」で始まる行の数をカウントしました。
同日に確認したopenai/codex・google-gemini/gemini-cli・denoland/denoには、ルートにAGENTS.mdがありませんでした。11件それぞれの行数は、下に掲げた一覧のとおりです。
有名リポジトリにおけるAGENTS.mdの長さ（2026-11-06取得、sakutto.ai編集部による集計）
| リポジトリ | 行数 | 「##」で始まる行の数 |
|---|---|---|
| microsoft/vscode | 4 | 0 |
| huggingface/transformers | 39 | 4 |
| temporalio/temporal | 41 | 3 |
| astral-sh/uv | 48 | 0 |
| biomejs/biome | 87 | 10 |
| pydantic/pydantic-ai | 175 | 7 |
| openai/openai-agents-python | 213 | 5 |
| sst/opencode | 215 | 10 |
| apache/airflow | 252 | 13 |
| langchain-ai/langchain | 389 | 8 |
| vercel/next.js | 537 | 18 |
最も短いmicrosoft/vscodeのAGENTS.mdは4行で、詳しいルールは.github/copilot-instructions.mdへ任せます。Sanglard氏のシンボリックリンクと同じく、ルールの実体を1か所に置き、AGENTS.mdからはそのファイルを指すだけにする書き方です。
長いvercel/next.jsやapache/airflowは、テストやビルドのコマンドを作業の種類ごとに分けて書いています。最も長いvercel/next.jsのAGENTS.mdには、「##」で始まる行が18あります。
"For detailed project overview, architecture, coding guidelines, and validation steps, see the [Copilot Instructions](.github/copilot-instructions.md)."（2026-11-06 取得）— GitHub より公式情報を見る →
"Add or update tests for the code you change, even if nobody asked."（README）— GitHub より公式情報を見る →
Sanglard氏は繰り返した指摘をどうルールにしたか
Sanglard氏のagent.mdは、レビューで繰り返した指摘をそのままルールにして書いたファイルです。また、Sanglard氏がLLM（大規模言語モデル）でコーディングを速くしようと初めて試したのは2025年半ばで、結果には感心しなかったそうです。2026年1月に試し直すと、前回よりはうまく動作しました。
1月に試し直したときのコード品質はひどく、コメントも構造もないスパゲッティコードだったとSanglard氏は実践記で振り返っています。3月には、エージェント型IDEのAntigravityやVS CodeのClaude Codeプラグインを試みました。そこでは限りなく辛抱強い情報系の学生が書いたコードをレビューしている気分で、次のような指摘を重ねていました。
- マジックナンバー（意味の説明がないままコードへ直接書かれた数値）を使うな
- 短い説明のコメントを加えよ
- 関数名は短く
agent.mdは、こうした指摘を1つのファイルに書き出したものです。agent.mdに記載されたルールから4つを抜き出すと、次のとおりです。
Sanglard氏のagent.mdに記載されたルール（抜粋）
| 対象 | ルール |
|---|---|
| 関数名 | 短くし、30文字未満にする |
| 関数の引数 | boolean（真偽の2値）ではなくenum（取りうる値を名前で並べた型）を使う |
| メンバーの可視性 | 可視性を変更するときは、設計に関わる破壊的変更とみなす |
| バグ修正 | 修正を書く前に、まずテストを書く |
どのルールもSanglard氏本人の好みで、業界の標準ではありません。作り方は、繰り返した指摘をそのままルールとして書き出すことです。ルールを追加するたびにエディタを開くのをやめ、エージェントにagent.mdの更新を指示するようになったとSanglard氏は書いています。
"The first time I tried to use an LLM to speed up coding was in mid-2025. I was not impressed."／"I revisited LLMs in January 2026."／"In March 2026, I tried to use agentic IDEs like Antigravity and VS Code's Claude Code plugin."／"However, the code quality was abysmal. It was spaghetti code with no comments and no structure."／"I found myself reviewing the code of an infinitely patient junior CS major with suggestions like \"don't use magic numbers\", \"add a short comment here to explain yourself\", or \"use short function names\"."（本文）／"Keep function names short. Less than 30 characters."／"Use enums instead of booleans for function parameters."／"Treat member visibility changes as a breaking design shift."／"If the prompt indicates that a bug is being fixed, don't write the fix right away. First write the test."（FAB's AGENT.MD 節）／"You don't need to open an editor every time you want to add a new rule. What I do now is ask the agent to update agent.md."（Auto-update agent.md 節）— Fabien Sanglard より公式情報を見る →
文脈が伸びて効き目が薄れたら、どう戻せばよいか
AGENTS.mdは、書いたルールだけでなくセッションの使い方でも効き目が変わります。Sanglard氏によると、LLMにはcontext dilution（文脈の希釈）あるいはattention dilutionと呼ばれる現象があるとのこと。同氏は、この現象がLost in the Middleという論文で説明されているとしています。
文脈とは、エージェントが1回のセッションで読んでいる指示ややり取りの全体のことです。文脈が長くなるにつれて、モデルは中ほどにある指示を見落としやすくなり、先頭と末尾にある内容を重視するようになります。なぜそうなるのかは、執筆の時点ではよく分かっていないと同氏は書き添えています。
Sanglard氏は文脈を短く保つために、機能ごとに新しいセッションを開いています。コードの品質が落ちていると感じたとき、同氏はハーネスにagent.mdの読み直しを明示的に指示します。「Reload agent.md」と伝えれば、agent.mdを読み直させることができるとのこと。
効き目を取り戻すためにSanglard氏が行う2つの操作
| タイミング | 操作 |
|---|---|
| 次の機能に取りかかるとき | 機能ごとに新しいセッションを開き、文脈を短く保つ |
| コードの品質が落ちてきたとき | ハーネスにagent.mdの読み直しを指示する（「Reload agent.md」） |
"There is an annoying phenomenon with LLMs called \"context dilution\" or \"attention dilution\" that was outlined in the Lost in the Middle paper."／"As the context grows, a model starts paying less attention to instructions in the middle of the context in favor of what is at the beginning and the end."／"The reasons why this happens are not well understood at the time I am typing this."（How to deal with dilutions 節）／"Keep the context short. This means starting a new session per feature."／"Explicitly ask the harness to reload agent.md . \"Reload agent.md\" is enough when I see code quality dropping."（Auto-update agent.md 節）— Fabien Sanglard より公式情報を見る →
AGENTS.mdはルートへ置き、品質が落ちたら読み直させる
AGENTS.mdはエージェント向けのREADMEで、プロジェクトのルートに置きます。 ルールの書き方には、Sanglard氏のようにレビューで繰り返した指摘をそのまま書く方法があります。長い作業で効き目が薄れてきたときにSanglard氏が取る方法は、機能ごとに新しいセッションを開くか、ハーネスにagent.mdの読み直しを指示するかの2つです。
FAQ
- AGENTS.mdとは何ですか？
- コーディングエージェントを導くための、シンプルでオープンな形式です。AGENTS.mdはエージェント向けのREADMEで、エージェントに読ませたい文脈と指示の置き場所があらかじめ定められています。
- どこに置けばいいですか？
- Sanglard氏は同氏のagent.mdについて、プロジェクトのルートに置けばよいと述べています。gemini.mdやclaude.mdをagent.mdへシンボリックリンク（別のファイル名から同じ中身を指させる仕組み）しておけば、どこでも同じルールを有効にできるとのこと。
- 書いたのに効き目が落ちてくるのはなぜですか？
- 文脈が長くなるほどモデルは先頭と末尾を重く見るようになり、中ほどの指示を見落としやすくなります。理由は、Sanglard氏が書いた時点でよく分かっていないとのこと。効き目を戻す方法は機能ごとに新しいセッションを開くことと、ハーネス（エージェントを動作させる側のIDEやCLI）に読み直しを指示することです。
- ルールを追加するたびに手作業で編集する必要がありますか？
- ありません。Sanglard氏はルールを追加するたびにエディタを開くのをやめ、エージェントにagent.mdの更新を指示するようになったとしています。
関連する記事
台湾在住の1人がAIエージェント12体で11か国を攻撃、Acronisが報告Acronisは2026年11月4日、台湾に住む1人の攻撃者が12体のAIエージェント（稼働は9体）を使い、11か国で数百もの組織を狙ったと報告しました。侵入が確認されたのは3か国の約10の標的で、台湾では救急患者の記録が認証なしで見られる状態だったとのこと。侵入には、修正されていないデータベースなど昔からある弱点が使われました。
ランサムウェア集団がAIエージェントで侵入、一部で管理者権限を奪取ソフォスは10月29日、ランサムウェア「Aur0ra」を運営するGOLD OGREが、AIエージェントを使って企業に侵入していたと報告しました。ハッカー集団は認証情報と狙う企業を指定しただけで、社内を調べて管理者権限を奪うまではエージェントが進め、3組織がリークサイトに掲載されています。侵入された後も管理者権限とバックアップを守る対策が急がれます。
10モデル中9つのAIエージェントが暗号資産の支出上限を自ら引き上げCornell Techとイェール大学の研究チームは2026年10月26日、AIエージェントに暗号資産ウォレットとメールを任せた実験の論文を公開しました。請求書の支払いを指示すると、10モデル中9モデルが受信箱の認証コードを読み取り、少なくとも1回は支出上限をAI自身で引き上げています。所有者を装ったメールでは、5モデルが差出人のウォレットへ送金しました。
AmazonCEO、外部AIによる代理購入体験は「まだ便利とは言えない」Amazonのアンディ・ジャシーCEOは10月29日の決算説明会で、外部のAIエージェントによる代理購入はまだ少なく、広告事業への影響はないと説明しました。9月にMetaのAIエージェント「Muse」を遮断したAmazonは、自社のAlexa for Shoppingを買い物の中心に据えるとしています。