AGENTS.md は「AIコーディングエージェント向けの README」です。
リポジトリにこのファイルを置くことで、Codex CLI・Cursor・GitHub Copilot など多くのツールが共通の指示を読み取れます。ただし、ツールごとに対応状況や読み込み条件には差があります。
この記事では、AGENTS.md が生まれた背景、ツールごとの対応差、実践的な導入ノウハウまでを体系的に解説します。
1. なぜ AGENTS.md が必要になったのか
ツールごとに設定ファイルが分断された現実
AIコーディングエージェントの普及に伴い、各ツールが独自の設定ファイルを要求するようになりました。
| ツール | 設定ファイル |
|---|---|
| Claude Code | CLAUDE.md |
| Cursor |
.cursorrules / .cursor/rules/
|
| GitHub Copilot | .github/copilot-instructions.md |
| Windsurf | .windsurfrules |
書く内容はほぼ同じです。
「TypeScriptを使う」「テストはVitestで書く」「.envを変更しない」。
しかし、ファイル形式も配置場所もツールごとに異なります。
開発者が直面した具体的な痛み
筆者自身、Claude Code 用に CLAUDE.md を丁寧に書いていました。
コーディング規約、ビルドコマンド、禁止事項。
数十行にわたる指示を整備し、エージェントの出力品質は確実に上がりました。
しかし、チームメンバーが Cursor を使い始めた途端、問題が起きます。
CLAUDE.md は Cursor に無視されます。
同じ内容を .cursorrules に転記する必要がありました。
さらに GitHub Copilot を使うメンバーが加わると、.github/copilot-instructions.md も必要になります。
3つのファイルに同じ内容を書き、1つ更新したら残り2つも同期する。
この作業は明らかに不毛です。
設定ファイルの同期漏れは静かに品質を蝕みます。Cursor で作業するメンバーだけテストコマンドが古い、Copilot ユーザーだけ禁止ディレクトリの指定がない、といった不整合が現場では頻繁に起きていました。
AGENTS.md はこの「設定ファイルの分断」を解決するために生まれました。
1つのMarkdownファイルに指示を書けば、対応するすべてのエージェントが読み取ります。
2. AGENTS.md とは何か
基本情報
| 項目 | 内容 |
|---|---|
| 正式名称 |
AGENTS.md（大文字、複数形） |
| フォーマット | 標準 Markdown |
| エンコーディング | UTF-8 推奨 |
| 配置場所 | リポジトリルート（サブディレクトリにも配置可） |
| 必須セクション | なし（完全に自由） |
| ライセンス | MIT |
背景と採用状況
AGENTS.md は、OpenAI Codex、Amp（Sourcegraph）、Jules（Google）、Cursor、Factory など複数のチームの協働から生まれたオープンフォーマットです。2025年8月に OpenAI が公開し、エコシステム全体で普及が進みました。
2025年12月、Linux Foundation が設立した Agentic AI Foundation（AAIF） の創設プロジェクトの1つとして正式に採択されています。
AAIF の創設プロジェクトは以下の3つです。
- Anthropic の Model Context Protocol（MCP）
- Block の goose
- OpenAI の AGENTS.md
Platinum メンバーには AWS、Anthropic、Block、Bloomberg、Cloudflare、Google、Microsoft、OpenAI が名を連ねます。
60,000リポジトリ採用の裏側
現時点で 60,000以上のリポジトリ が AGENTS.md を採用しています。
この急速な普及を後押しした要因は3つあります。
1. ツール側のネイティブサポート
GitHub Copilot が AGENTS.md の読み取りに対応したことが大きな転換点でした。
GitLab も Duo での対応を発表しています。
ツール側が「置けば読む」という状態を作ったことで、導入の心理的障壁が消えました。
2. Linux Foundation による信頼性の担保
個人やスタートアップの提唱ではなく、Linux Foundation の傘下に入ったことで、企業での採用判断が容易になりました。
「また別の設定ファイルが増えるだけでは」という懸念に対して、業界標準としての正当性が与えられた形です。
3. 導入コストの低さ
特別なツールのインストールも、スキーマの学習も不要です。
AGENTS.md という名前のMarkdownファイルを1つ置くだけ。
既存の CLAUDE.md や .cursorrules の内容をコピーするだけでも機能します。
対応ツールは Codex CLI、Cursor、GitHub Copilot、Gemini CLI、Devin、Factory、Jules など多岐にわたります。
ツールごとの対応状況
ただし「置けばどのツールでも同じように読む」とは限りません。ツールごとに対応状況は異なります。
| ツール | 対応状況 | 備考 |
|---|---|---|
| OpenAI Codex CLI | ネイティブ対応 | ディレクトリ階層の走査、AGENTS.override.md にも対応。32KiB 上限あり |
| Cursor | ルートのみ対応 | サブディレクトリの AGENTS.md は読み取らない（v1.5 時点） |
| GitHub Copilot | 対応 | agents.md をリポジトリ指示として読み取る。独自の .github/copilot-instructions.md や .instructions.md も併存 |
| Gemini CLI | 設定変更で対応 | デフォルトでは GEMINI.md を読む。AGENTS.md の読み取りには設定が必要 |
| Claude Code | AGENTS.md の直接対応は公式未確認 | 公式ドキュメントでは CLAUDE.md のみ記載。AGENTS.md のフォールバック読み取りは未確認 |
| Amp, Jules, Factory, Devin 等 | 対応 | agents.md 公式サイトに互換ツールとして記載 |
AGENTS.md を導入する際は、チームで使用しているツールの対応状況を確認してください。
3. 既存の設定ファイルとの違い
比較表
| 観点 | AGENTS.md | CLAUDE.md | .cursorrules | copilot-instructions.md |
|---|---|---|---|---|
| 配置場所 | ルート＋サブディレクトリ | ルート＋サブディレクトリ | ルートのみ | .github/ |
| クロスツール対応 | あり | Claude Code のみ | Cursor のみ | Copilot のみ |
| 階層的な上書き | あり | あり | なし | glob パターンで対応 |
| 特殊構文 | なし（素の Markdown） |
@import 対応 |
プレーンテキスト | プレーン Markdown（※ .instructions.md は YAML frontmatter） |
| Linux Foundation 標準 | あり | なし | なし | なし |
CLAUDE.md と AGENTS.md の具体的な違い
機能比較だけでは分かりにくいので、同じ指示を両方で書いた場合の違いを示します。
CLAUDE.md の場合（Claude Code 固有機能を活用）
# CLAUDE.md
## Memory
- `/agent-memory` スキルで重要情報を保存する
- `@import 00_context/memories/preferences.md`
## Boundaries
- `.env*` ファイルを変更・コミットしない
- 本番環境の設定ファイルを変更する場合は必ず確認を求める
## Workflow
- 3ステップ以上のタスクはPlanモードで開始する
- リサーチ・調査はサブエージェントに任せる
AGENTS.md の場合（ツール非依存の書き方）
# AGENTS.md
## Project Context
- TypeScript + React 18 のWebアプリケーション
- バックエンド: Node.js + Express
## Boundaries
- `.env*` ファイルを変更・コミットしない
- 本番環境の設定ファイルを変更する場合は必ず確認を求める
## Workflow
- 変更前にテストを実行し、既存テストが通ることを確認する
- コミットメッセージは Conventional Commits に従う
違いのポイントは3つあります。
-
ツール固有機能は AGENTS.md に書かない:
@import、Planモード、サブエージェントは Claude Code 固有の概念です。AGENTS.md に書いても他のツールは解釈できません - AGENTS.md はより宣言的になる: 「Planモードで開始する」ではなく「テストを実行してから変更する」のように、ツールに依存しない行動指示を書きます
- プロジェクト情報は AGENTS.md に集約する: 技術スタック、ビルドコマンド、コーディング規約はどのツールでも共通なので、AGENTS.md に書くのが合理的です
使い分けの方針
複数ツールを併用するチームでは、共通指示を AGENTS.md に書き、ツール固有の設定のみを CLAUDE.md 等に書くのが実用的です。なお、Claude Code が AGENTS.md をフォールバックで読み取るかどうかは、公式ドキュメントでは確認できていません（2026年3月時点）。Claude Code を使う場合は CLAUDE.md も併置するのが確実です。
単一ツールしか使わない場合は、そのツール専用ファイルだけでも問題ありません。
ただし、将来的なツール乗り換えやチーム拡大を見据えるなら、AGENTS.md への一本化を検討する価値があります。
4. AGENTS.md の主要セクション解説
AGENTS.md には必須セクションがありません。
しかし、GitHub Blog の記事「How to write a great agents.md」で 2,500以上のリポジトリの agents.md ファイルを分析した結果、効果的なファイルには共通して以下の6領域が含まれていたと報告されています。
4-1. Project Overview（プロジェクト概要）
プロジェクトの目的と技術スタックを簡潔に記述します。
エージェントに「何のためのリポジトリか」を伝える役割を果たします。
## Project Overview
- TypeScript + React 18 のWebアプリケーション
- バックエンド: Node.js + Express
- データベース: PostgreSQL + Prisma ORM
- テスト: Vitest + Playwright
「便利なツールです」のような曖昧な説明は避けてください。技術スタックとバージョンを具体的に書くことで、エージェントの出力精度が上がります。
4-2. Build & Test Commands（ビルド・テストコマンド）
エージェントが実行すべきコマンドをフラグ付きで記載します。
ツール名だけでなく、完全なコマンドを書くことが重要です。
## Commands
- Install dependencies: `pnpm install`
- Run dev server: `pnpm dev`
- Run all tests: `pnpm test`
- Run single test file: `pnpm test -- path/to/test.ts`
- Lint: `pnpm lint`
- Type check: `pnpm typecheck`
- Build for production: `pnpm build`
4-3. Code Style Guidelines（コーディング規約）
命名規則、フォルダ構成、コードスタイルを記述します。
説明文よりも、実際のコード例を示すほうが効果的です。
## Code Style
- ファイル名: kebab-case (`user-profile.tsx`)
- コンポーネント: PascalCase の関数コンポーネント
- 状態管理: useState + useReducer を優先、グローバル状態は Zustand
- API呼び出し: `src/lib/api/` 配下に集約
「良い例」セクションとしてコードスニペットを添えると効果的です。
// src/components/user-profile.tsx
export function UserProfile({ userId }: { userId: string }) {
const { data, isLoading } = useUser(userId);
if (isLoading) return <Skeleton />;
return <div>{data.name}</div>;
}
4-4. Testing Instructions（テスト指示）
テストの書き方、実行方法、カバレッジ要件を明記します。
## Testing
- フレームワーク: Vitest
- カバレッジ目標: 80% 以上
- テストファイル: `*.test.ts` を同一ディレクトリに配置
- モック: `vi.mock()` を使用、外部APIは必ずモック化
- E2Eテスト: `tests/e2e/` に Playwright で記述
4-5. Git Workflow（Git ワークフロー）
コミットメッセージやPRの規約を指定します。
## Git
- コミットメッセージ: Conventional Commits 準拠
- `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
- ブランチ名: `feature/xxx`, `fix/xxx`
- PRは必ずテストを通してから作成
4-6. Boundaries（境界・禁止事項）
エージェントが触れてはいけない領域を明示します。
この指定がないと、エージェントが本番設定や秘密情報を変更するリスクがあります。
## Boundaries
- `.env*` ファイルを変更・コミットしない
- `vendor/` ディレクトリの中身を編集しない
- データベースのマイグレーションを自動実行しない
- 本番環境の設定ファイルを変更する場合は必ず確認を求める
Boundaries セクションの省略は推奨しません。エージェントに「やってはいけないこと」を明示することで、意図しない変更を防げます。
5. 実際のプロジェクトでの AGENTS.md 実例
概念的な説明だけでは伝わりにくいので、筆者が実際に運用しているプロジェクトの AGENTS.md を紹介します。
実例: 複数サービスを並行運営するプロジェクト
以下は、事業管理リポジトリに配置している AGENTS.md の抜粋です。
CLAUDE.md で運用していた内容を AGENTS.md に移行した実例になります。
# AGENTS.md
## Project Overview
複数サービスを並行運営する事業管理リポジトリ。
ソフトウェア開発、コンサルティング、コンテンツ発信を横断管理する。
## Directory Structure
| ディレクトリ | 役割 |
|-------------|------|
| `00_context/` | プロフィール・経歴・スキル情報 |
| `01_strategy/` | 事業戦略・方針・中長期計画 |
| `02_finance/` | 経理・請求管理・収支記録 |
| `output/` | AI出力ファイル（trends/digest/articles） |
## Commands
- Lint Markdown: `npx markdownlint-cli2 "**/*.md"`
- Search content: `grep -r "keyword" output/`
## Code Style
- ファイル名: `[YYYYMMDD]-[topic].md` 形式
- 見出し: `##` から開始、`#` はファイルタイトルのみ
- 言語: 日本語。です/ます調で統一
## Boundaries
- `.env*` ファイルを変更・コミットしない
- `02_finance/` 内の金額情報を外部出力に含めない
- クライアント名・契約内容を output/ 以下のファイルに記載しない
- 重要な判断を独断で進めない。必ず確認を求める
## Workflow
- 変更前に既存ファイルの内容を確認する
- 長時間タスクはステップ分割し、各完了後にファイル保存
- 説明には必ず具体例を含める
ポイントは、ツール固有の概念（Planモード、サブエージェント、@import 等）を排除し、どのエージェントでも解釈できる形にしていることです。
有名OSSの動向
agents.md 公式サイトによると、OpenAI のメインリポジトリには88個の AGENTS.md が配置されています。
ルートには全体方針を書き、各パッケージディレクトリに固有の指示を分散させる構成です。
この「1ファイルに詰め込まず、階層的に分割する」アプローチは、モノレポでの手本になります。
6. 自分のプロジェクトに導入する手順
Step 1: ファイルを作成する
リポジトリルートに AGENTS.md を作成します。
touch AGENTS.md
Step 2: 最小構成から始める
最初から完璧を目指す必要はありません。
以下の3セクションから始めるのが実用的です。
# AGENTS.md
## Project Overview
Python 3.12 + FastAPI のREST APIサーバー。
PostgreSQL をデータベースとして使用。
## Commands
- Install: `pip install -e ".[dev]"`
- Test: `pytest -v`
- Lint: `ruff check .`
- Format: `ruff format .`
- Type check: `mypy src/`
## Boundaries
- `.env` ファイルを変更しない
- `alembic/versions/` のマイグレーションを自動生成しない
- `requirements.lock` を手動編集しない
Step 3: サブディレクトリに配置する（モノレポ向け）
モノレポでは、パッケージごとに個別の AGENTS.md を配置できます。
エージェントは編集対象のファイルから最も近い AGENTS.md を優先して読み取ります。
my-monorepo/
├── AGENTS.md ← プロジェクト全体の共通指示
├── packages/
│ ├── frontend/
│ │ └── AGENTS.md ← フロントエンド固有の指示
│ └── backend/
│ └── AGENTS.md ← バックエンド固有の指示
└── services/
└── payments/
└── AGENTS.md ← 決済サービス固有の指示
優先順位はツールによって異なります。以下は Codex CLI の場合の例です。
Codex CLI の場合
- ユーザーのチャット入力（最優先）
- 編集対象ファイルに最も近い
AGENTS.md - 親ディレクトリの
AGENTS.md - リポジトリルートの
AGENTS.md - グローバル
~/.codex/AGENTS.md（最低優先）
この優先順位は Codex CLI 固有の仕様です。Cursor はルートの AGENTS.md のみを読み取り、サブディレクトリの階層走査は行いません。使用するツールのドキュメントを確認してください。
Step 4: グローバル設定を追加する（任意）
Codex CLI を使う場合は、ユーザーレベルの共通指示も設定できます。
mkdir -p ~/.codex
# ~/.codex/AGENTS.md
## Working agreements
- テスト実行後にコミットする
- 依存パッケージの追加時は確認を求める
- pnpm を優先する
Step 5: 既存ファイルと共存させる
AGENTS.md と CLAUDE.md 等を共存させる場合の構成例です。
project-root/
├── AGENTS.md ← 全ツール共通の指示
├── CLAUDE.md ← Claude Code 固有の設定（@import 等）
├── .cursor/rules/ ← Cursor 固有のルール
└── .github/
└── copilot-instructions.md ← Copilot 固有の設定
共通部分を AGENTS.md に集約し、各ツール固有ファイルにはそのツールでしか使えない機能だけを書くのがベストです。重複管理のコストを最小化できます。
7. 導入のつまづきポイントと対策
実際に AGENTS.md を書いて運用する中で、よくある失敗パターンをまとめます。
書きすぎてエージェントが混乱する
最も多い失敗です。
200行を超える AGENTS.md を書いた結果、指示同士が矛盾したり、エージェントが重要な指示を見落としたりします。
<!-- 失敗例: 情報過多 -->
## Code Style
- 変数名はキャメルケース
- ただし定数はアッパースネークケース
- ただしReactコンポーネントのpropsはキャメルケース
- ただしCSSモジュールのクラス名はケバブケース
- ただしAPI のレスポンス型はパスカルケース
- ただしテストのdescribeブロックは日本語OK
- ただしE2Eテストのテスト名は英語で統一
- ...（以下30行続く）
LLM が確実に従える指示数には限界があります。経験的に、指示が多すぎると遵守率が下がる傾向があります。優先度の高い指示から順に書き、例外規則は最小限にしてください。
対策: まず5から10個の最重要ルールだけを書きます。
1週間運用してエージェントの出力を観察し、必要なルールだけを追加していきます。
セクションの粒度が合わない
「Project Overview」に技術スタックだけでなく、ビジネスロジックの詳細まで書いてしまうケースがあります。
エージェントは AGENTS.md を「作業指示書」として読みます。
ビジネス背景の長い説明は、理解ではなくノイズになります。
<!-- 失敗例: Overview にビジネス背景を詰め込む -->
## Project Overview
このプロジェクトは2024年に開始されました。
当初はPythonで書かれていましたが、パフォーマンス要件の
変更によりTypeScriptに移行しました。
移行の経緯としては...（300文字の背景説明）
現在のアーキテクチャはマイクロサービス構成で...
<!-- 改善例: 技術情報に絞る -->
## Project Overview
- TypeScript + Next.js 14 のWebアプリケーション
- マイクロサービス構成（API Gateway + 3サービス）
- Python から移行済み。旧コードは `legacy/` に残存
対策: 各セクションは「エージェントがこの情報で何をできるか」を基準に書きます。
行動に結びつかない情報は削ります。
既存の設定ファイルと矛盾する
AGENTS.md と CLAUDE.md に矛盾する指示が書かれていると、エージェントの挙動が不安定になります。
<!-- AGENTS.md -->
## Code Style
- インデント: タブ
<!-- CLAUDE.md -->
## Code Style
- インデント: スペース2つ
対策: AGENTS.md を Single Source of Truth とし、ツール固有ファイルには AGENTS.md に書けない指示だけを書きます。
移行期間は CLAUDE.md の先頭に「共通指示は AGENTS.md を参照」と明記するのも有効です。
Codex CLI のサイズ上限に引っかかる
Codex CLI のデフォルト上限は 32KiB です。
これを超えるとファイルが途中で切られます。
対策: 長くなる場合はサブディレクトリへの分割を検討してください。
1つの AGENTS.md は「スクロールせずに読める長さ」が目安です。
8. AGENTS.md 導入の Before / After
実際に AGENTS.md を導入した前後で、何が変わるのかを示します。
Before: AGENTS.md なし
エージェントはリポジトリの構造から推測して動きます。
-
package.jsonを見てnpmを使うが、プロジェクトはpnpmを指定している - テストファイルの配置場所が分からず、
__tests__/に作成するが、規約は同一ディレクトリ配置 - コミットメッセージが自由形式になり、Conventional Commits に従わない
-
.env.exampleを.envにコピーして変更してしまう
PRを出すたびに「pnpm を使ってください」「テストファイルの場所が違います」といったレビューコメントが繰り返されます。
After: AGENTS.md あり
エージェントは AGENTS.md の指示に従って動きます。
-
pnpm installを使い、正しいロックファイルを維持する - テストファイルを実装ファイルと同じディレクトリに作成する
-
feat:/fix:等のプレフィックス付きでコミットする -
.env*に触れず、確認を求めてくる
筆者の体感での変化です（個人の運用環境での実感値であり、定量的な計測結果ではありません）。
| 観点 | Before | After |
|---|---|---|
| PRのレビュー指摘数 | 平均3から5件/PR | 平均0から1件/PR |
| ビルドコマンドの誤り | 週に2から3回 | ほぼゼロ |
| 禁止ファイルの変更 | 月に1から2回 | ゼロ |
| 新メンバー参加時の設定時間 | 30分から1時間 | ファイルを置くだけ |
特に効果が大きいのは、チームメンバーが異なるツールを使っている場合です。
AGENTS.md の導入前は「Claude Code ユーザーだけPRの品質が高い」という偏りがありました。
AGENTS.md で指示を統一した後は、ツールに関わらず一定の品質が担保されるようになりました。
9. ベストプラクティス
具体的なコマンドを書く
<!-- 良い例 -->
- Test: `pytest -v --cov=src --cov-report=term-missing`
<!-- 悪い例 -->
- テストを実行してください
コード例で規約を伝える
規約を文章で説明するよりも、実際のコード例を1つ示すほうが効果的です。
前述の GitHub Blog 記事でも、コード例を含む agents.md のほうが効果的であると報告されています。
定期的に更新する
AGENTS.md がコードベースと乖離すると、エージェントの出力が劣化します。
依存関係の変更やディレクトリ構成の変更時に、AGENTS.md も合わせて更新してください。
AGENTS.md の更新を忘れないために、PRテンプレートに「AGENTS.md の更新が必要か」のチェック項目を入れるのが有効です。
簡潔に保つ
agents.md 公式サイトによると、OpenAI のメインリポジトリには88個の AGENTS.md が存在しますが、それぞれは短く焦点を絞っています。
1つのファイルに全情報を詰め込むより、階層的に分割するほうが効果的です。
README と役割を分ける
AGENTS.md は README を補完するものであり、置き換えるものではありません。
人間向けの説明は README に、エージェント向けの技術指示は AGENTS.md に書きます。
10. まとめ
AGENTS.md は「AIエージェント向けのREADME」です。
標準 Markdown で書け、必須セクションもなく、導入コストは極めて低いです。
導入のポイントを整理します。
- まずはルートに1ファイル作成し、コマンド・規約・禁止事項の3セクションから始める
- 書きすぎない。5から10個のルールで始めて、必要に応じて追加する
- モノレポではサブディレクトリに追加ファイルを配置して階層化する
- 既存の CLAUDE.md 等とは共存可能。共通部分を AGENTS.md に集約する
- ツール固有の機能（
@import、Planモード等）は AGENTS.md に書かない - ツールごとに対応状況が異なるため、チームで使うツールのドキュメントを確認する
- 定期的にコードベースとの整合性を確認し、更新する
Linux Foundation の AAIF による標準化が進んでおり、対応ツールは今後さらに増える見込みです。
ただし、現時点ではツールごとに対応の深さや読み込み条件に差があります。「1つ置けば全ツールで完璧に動く」という段階ではなく、各ツールの対応状況を把握したうえで活用するのが現実的です。