AGENTS.md とは — AI コーディングエージェント向けの README

AGENTS.md という名前のファイルが、最近主要な OSS リポジトリのルートで目に付くようになった。Next.js、Stripe、Resend あたりを覗くとだいたい置いてある。何のファイルだろう、と気になっていた方も多いんじゃないかと思う。

簡単に言うと AGENTS.md は AI コーディングエージェント向けの README だ。リポジトリのルートに置く Markdown 1 枚で、GitHub Copilot や Cursor や Claude Code が「このリポジトリどう使うんだっけ」をヒトに聞かずに把握するための情報源として機能する。本記事では、何が書かれているべきかと、姉妹仕様の llms.txt との違いをまとめておく。

なぜ AI に専用ドキュメントが必要なのか

開発者が新しいリポジトリを触るとき、たいてい README.md を読む。「依存関係をインストールするには pnpm install、テストを走らせるには pnpm test」のような情報が書いてあるので。

ところが README.md は人間向けに書かれている、というのが AI から見るとちょっと困った性質を持っている。マーケティング寄りの文章 (「世界最速のフレームワーク」みたいな) で本筋がぼやけていたり、スクリーンショットや GIF が多用されてテキストとして抽出すると意味が落ちたり、「クイックスタート」と「フルセットアップ」が混在していてどちらが正しい手順か判断しづらかったり。リンク先のドキュメントに情報が分散していて、AI が追加でフェッチしないと全体像が掴めないこともよくある。

AI コーディングエージェントは、ユーザーから「このリポジトリで X してほしい」と頼まれると、まずリポジトリ構造を理解しようとする。package.json を読み、ファイル構成を眺め、README.md を読む。このプロセスで誤読すると、npm を使っているのに yarn install を提案したり、本来テストが pnpm test:unit なのに npm test を実行して失敗したりする。

AGENTS.md は、リポジトリオーナーが「AI に向けて、こうやって使ってほしい」と直接書く場所、と理解するのが一番近い。マーケティング文言を省き、コードブロック中心で、推測の余地を残さない指示を書く。

最小構成

決まった仕様ドキュメントはまだ業界として統一されていないが、実態としての de-facto 標準は ## Installation ## Configuration ## Usage の 3 セクションを含む、というあたりに収まっている。たとえばこんな感じ。

# プロジェクト名

簡潔な 1-2 文の説明 (このリポジトリは何を提供するか)。

## Installation

\`\`\`bash
pnpm install
\`\`\`

Node.js 20 以上が必要です。`.env` ファイルに以下を設定してください:

\`\`\`
DATABASE_URL=...
ANTHROPIC_API_KEY=...
\`\`\`

## Configuration

`config/app.ts` で主要な設定を上書きできます。

| 環境変数 | 必須 | 説明 |
|---|---|---|
| `DATABASE_URL` | はい | Postgres 接続文字列 |
| `ANTHROPIC_API_KEY` | はい | Claude API キー |
| `LOG_LEVEL` | いいえ | デフォルトは `info` |

## Usage

開発サーバ起動:

\`\`\`bash
pnpm dev
\`\`\`

テスト実行:

\`\`\`bash
pnpm test
\`\`\`

本番ビルド:

\`\`\`bash
pnpm build
\`\`\`

## Coding conventions

- TypeScript strict mode、`any` 禁止
- ファイルは kebab-case、変数・関数は camelCase
- 各機能に対応するテストを `tests/` に配置

書き方の勘所はいくつかある。まずコードブロックを多用すること。AI エージェントは Markdown のコードフェンスを「実行可能なコマンド」として認識するので、文中にコマンドを散らすよりブロックで囲った方が拾われる確率が上がる。環境変数の説明はリスト形式より表で書いた方が必須・任意の区別が明確になって誤読が減る。見出しは動詞ベースで揃える (## Installation ## Usage のように、何のセクションかが 1 単語で分かる形)。

誰が AGENTS.md を読むのか

2026 年現在、AGENTS.md を明示的に取得するエージェントは以下のあたり。

エージェント	補足
GitHub Copilot (workspace 機能)	workspace 内のコンテキストとして優先的に読む
Cursor	`.cursorrules` や `.cursor/rules/` も併用
Claude Code (Anthropic)	`CLAUDE.md` がある場合はそちらを優先
Continue.dev	プロジェクトルートを自動スキャン
OpenAI Codex	リポジトリ全体を読みに行く際に拾う

業界横断で見ると、AGENTS.md の代わりに .cursor/rules/、CLAUDE.md、.cursorrules 等を使うエージェントもあって、ファイル名は若干乱立気味だ。現実解としては「メイン情報を AGENTS.md に書きつつ、他のファイル (CLAUDE.md など) からは『詳細は AGENTS.md 参照』と参照する」構成にしておくと、どのエージェントでも問題なく読まれる。

実装ミスのパターン

実際に読みづらい AGENTS.md を見ていて、共通する失敗が 4 つくらいある。

1 つ目、README.md をそのままコピーしてしまうケース。README には導入事例、ライセンス、コミュニティリンクなど、エージェントが実行に使わない情報が大量に入っている。これをそのまま AGENTS.md に持ってくると、本筋のセットアップ手順がノイズに埋もれてエージェントが拾えなくなる。AGENTS.md は「実行に使う情報だけ」に絞るのが鉄則。

2 つ目、古い情報を放置するケース。AGENTS.md に書いた npm install が、その後 pnpm に移行されても更新されていない、というのはよくある。エージェントは AGENTS.md を信じて壊れたコマンドを実行してしまう。コミット時に AGENTS.md も一緒に更新するルールを CI チェックや PR テンプレートで強制しておくと事故が減る。

3 つ目、コードブロックに言語タグがないケース。

```
pnpm install
```

ではなく

```bash
pnpm install
```

と書く。エージェントは言語タグでコマンドの種類を判別する場合がある。これは YomuScore のスコアリングでも P21 (コードブロックの言語タグ) として独立した項目になっているくらい、地味だが効く。

4 つ目、これは少し性質が違うミスだが、コーポレートサイトに AGENTS.md を置こうとする、というケースがある。AGENTS.md はコードリポジトリ向けのものであって、会社紹介や採用情報のページには本質的に意味がない。コーポレートサイトに必要なのは llms.txt で、AGENTS.md は SaaS や OSS のように「ユーザーが API / SDK を叩く前提のプロダクト」向け、と棲み分けるのが正しい。YomuScore のスキャナーは、コーポレートサイトでも /AGENTS.md を S12 (チェック ID) で見に行くが、これは「あれば加点」であって「なくても問題ない」項目だ。

llms.txt と AGENTS.md の違い

姉妹仕様の llms.txt とよく混同される。違いを整理するとこんな感じ。

	llms.txt	AGENTS.md
対象読者	質問応答系の AI (ChatGPT, Claude, Perplexity, Gemini)	コーディングエージェント (Copilot, Cursor, Claude Code)
配置場所	サイトのルート	リポジトリのルート (またはサイトのルート)
書く対象	サイトの主要ページの目次	プロジェクトのビルド・テスト・使用方法
書き方	リンクの列挙が中心	コードブロックと表が中心
更新頻度	ページが増えた時	依存関係や手順が変わった時
典型的なサイズ	1〜3KB	3〜10KB

要するに llms.txt はユーザー向けのサイト紹介、AGENTS.md は開発者向けのセットアップガイド、という役割分担になる。両方持っておくのが理想だが、業種・サイト構造によっては片方だけで十分なケースもある。コーポレートサイトや LP やメディアなら llms.txt だけで OK、SaaS や OSS や API プロダクトなら両方、ドキュメントサイトなら両方、EC サイトなら llms.txt だけ (商品ページに AGENTS.md はあまり意味がない)、というのが筆者の判断基準だ。

雛形を作る

ゼロから書くより、雛形を生成してから埋める方が早い。YomuScore に AGENTS.md ジェネレーターを置いていて、サイト URL を入れると公開コンテンツから推測した AGENTS.md の雛形を Claude 経由で生成してくれる (1 日 5 回まで無料)。

出力には  のコメントが推測部分に挿入されているので、それを目印に実情に合わせて修正してから配置する流れになる。技術的なリポジトリで自分でしっかり書きたい場合は、Installation / Configuration / Usage の各セクションを直接編集した方が早い。

配置したら YomuScore でスキャンして S12 (/AGENTS.md が HTTP 200 で返るか) と S13 (Installation / Configuration / Usage のうち 2 つ以上が含まれているか) が pass しているかを確認しておくと、AI コーディングエージェント側からの読み取り性は十分整っているはず。

関連リンク

llms.txt とは何か — 質問応答 AI 向けの姉妹仕様
Vercel Agent Readability Spec 完全ガイド — AGENTS.md / llms.txt を統合した評価仕様
WordPress でグレード A を取る 7 つのチェックリスト
CMS別改善ガイド
YomuScore でサイトを診断する