AGENTS.md 完全入門——60,000 リポジトリが採用した事実上の共通フォーマット

2026 年 3 月、AGENTS.mdが AI コーディングエージェントの設定ファイルとして事実上の標準になりつつある。

AGENTS.md は「AI コーディングエージェント向けの README」です。 リポジトリにこのファイルを置くことで、Codex CLI・Cursor・GitHub Copilot など多くのツールが共通の指示を読み取れます。

2025 年 8 月に OpenAI が公開し、2025 年 12 月にはLinux Foundationの**Agentic AI Foundation（AAIF）**の創設プロジェクトとして正式採択された。

現時点で60,000 以上のリポジトリが AGENTS.md を採用している。

本稿は AGENTS.md の概要、既存設定ファイルとの違い、主要セクション解説、実装例を解説する。

なぜ AGENTS.md が必要になったのか

ツールごとに設定ファイルが分断された現実

AI コーディングエージェントの普及に伴い、各ツールが独自の設定ファイルを要求するようになった。

書く内容はほぼ同じだ。

「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 ファイルに指示を書けば、対応するすべてのエージェントが読み取る。

AGENTS.md とは何か

基本情報

背景と採用状況

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 など多岐にわたる。

ツールごとの対応状況

ただし「置けばどのツールでも同じように読む」とは限らない。ツールごとに対応状況は異なる。

AGENTS.md を導入する際は、チームで使用しているツールの対応状況を確認してほしい。

既存の設定ファイルとの違い

比較表

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 への一本化を検討する価値がある。

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 セクションの省略は推奨しない。エージェントに「やってはいけないこと」を明示することで、意図しない変更を防げる。

結論：設定ファイルの統一で開発者体験を向上

AGENTS.md は、ツールごとに分断された AI エージェント設定ファイルを統一する事実上の標準フォーマットだ。

• 60,000 以上のリポジトリで採用 - 事実上の標準
• Linux Foundation 標準 - 業界標準としての正当性
• クロスツール対応 - 1 つのファイルで複数のツールに対応
• 導入コストが低い - Markdown ファイルを 1 つ置くだけ

複数ツールを併用するチームほど、AGENTS.md の導入メリットは大きい。

設定ファイルの同期作業から解放され、開発者体験を向上できる。

参考：

• AGENTS.md 完全入門 ── 60,000 リポジトリが採用した事実上の共通フォーマット
• How to write a great agents.md