AGENTS.md クロスツール統一管理ガイド【2026年2月最新】1ファイルで全AIエージェントを制御¶

Q: AGENTS.md と CLAUDE.md / copilot-instructions.md は競合しますか？

競合しません。AGENTS.mdは全ツール共通のプロジェクト情報、ツール固有ファイルはそのツール向けの差分という補完関係です。共通ルールをAGENTS.mdに書き、ツール固有の設定は固有ファイルに記述するのが推奨です。

この記事の対象者

複数のAIコーディングツールを併用しているチーム

⚡ 5分で始めるクイックスタート

# 1. AGENTS.mdを作成
cat << 'EOF' > AGENTS.md
# AGENTS.md
## Build & Run
npm install && npm run dev

## Code Style
- TypeScript strict mode
- ESLint + Prettier
- コンポーネント: PascalCase / 変数: camelCase
EOF

# 2. VS Code設定を追加
mkdir -p .vscode
cat << 'EOF' >> .vscode/settings.json
{ "chat.useAgentsMdFile": true }
EOF

# 3. （任意）シンボリックリンクで他ツールと共有
ln -s AGENTS.md CLAUDE.md

# 4. コミット
git add AGENTS.md .vscode/settings.json
git commit -m "feat: add AGENTS.md for cross-tool AI management"

検証: VS Code Copilot Chatで質問 → 「References」に AGENTS.md が表示されれば成功

この記事のポイント¶

1ファイルで全ツール統一管理
AGENTS.mdひとつでGitHub Copilot・Claude Code・Codex・Cursor等のAIエージェントに共通指示を提供
モノレポ完全対応
ルートとサブディレクトリにAGENTS.mdをネスト配置し、パッケージ固有のルールを階層的に管理
オープン標準の安心感
Linux Foundation傘下のAAIF（Agentic AI Foundation）が管轄。Anthropic・OpenAI・Google・Microsoft等が共同策定
シンボリックリンク戦略
AGENTS.mdをSource of Truthとして各ツール固有ファイルにリンクし、メンテナンスコストを最小化

📖 AGENTS.md とは¶

AIのためのREADMEを書け

AGENTS.mdは、AIコーディングエージェントのためのREADMEです。プロジェクト固有のビルド手順、コーディング規約、テスト方針、セキュリティルールなどを標準的なMarkdown形式で記述し、複数のAIツールに共通のコンテキストとして読み込ませる仕組みです。

標準化の経緯¶

時期	出来事
2025年8月	OpenAIがCodexのためにAGENTS.md形式を策定・公開
2025年後半	GitHub Copilot、Claude Code、Cursor等が相次いで対応を表明
2025年12月	Linux Foundation傘下にAAIF（Agentic AI Foundation）が設立され、AGENTS.md仕様の管轄を引き継ぎ
2026年2月現在	60,000以上のオープンソースプロジェクトが採用。20以上のツールが対応

AAIF（Agentic AI Foundation）の設立メンバー

Anthropic（Claude Code）
OpenAI（Codex）
Google（Gemini CLI / Jules）
Microsoft（GitHub Copilot）
Amazon
Block（goose）
Bloomberg
Cloudflare

公式仕様: https://agents.md/

AGENTS.mdの特徴¶

標準Markdown形式: 特別な構文やスキーマは不要。人間が読んでも理解できる
必須フィールドなし: プロジェクトに有益なセクションを自由に記述
バージョン管理と相性が良い: gitで差分管理・レビューが容易
人間とAIの共通ドキュメント: オンボーディング資料としても機能

🌐 ツール対応マトリクス¶

2026年2月時点で、主要なAIコーディングツールのほぼすべてがAGENTS.mdに対応しています。

ツール	AGENTS.md	固有ファイル	備考
GitHub Copilot	対応	`.github/copilot-instructions.md`	VS Code設定で有効化
Claude Code	対応	`CLAUDE.md`	自動読み込み
OpenAI Codex	対応	`AGENTS.md`（起源）	ネイティブ対応
Cursor	対応	`.cursor/rules/`	`.cursorrules` も対応
Gemini CLI	対応	`GEMINI.md`	Google Jules も対応
Windsurf	対応	`.windsurfrules`	—
Devin	対応	—	Cognition社
goose	対応	—	Block社（AAIFに寄贈）
Amp	対応	—	Sourcegraph社
Aider	対応	`.aider.conf.yml`	—

ポイント

AGENTS.mdは「最大公約数」として機能します。各ツール固有ファイルは「差分」の役割を担い、両者を組み合わせることでツールごとの最適化が可能です。

⚙️ VS Code / GitHub での設定¶

GitHub CopilotでAGENTS.mdを有効にするには、VS Codeのsettings.jsonに以下を追加します。

// .vscode/settings.json
{
  "chat.useAgentsMdFile": true,
  "chat.useNestedAgentsMdFiles": true
}

設定キー	説明
`chat.useAgentsMdFile`	AGENTS.mdをCopilot Chat / Agent Modeで読み込む
`chat.useNestedAgentsMdFiles`	サブディレクトリのAGENTS.mdも有効化（モノレポ対応）

設定の反映タイミング

設定変更後はVS Codeのリロード（Ctrl+Shift+P → Developer: Reload Window）が必要な場合があります。また、chat.useNestedAgentsMdFilesはモノレポ以外のプロジェクトでは不要です。

🏗️ 推奨ファイル構成¶

プロジェクトルートにAGENTS.mdをSource of Truthとして配置し、各ツール固有ファイルと組み合わせる構成を推奨します。

project-root/
├── AGENTS.md                              # Source of Truth（全ツール共通）
├── .github/
│   └── copilot-instructions.md            # Copilot固有の補足（またはシンボリックリンク）
├── CLAUDE.md                              # Claude Code固有（またはシンボリックリンク）
├── .cursor/
│   └── rules/
│       └── agents.md                      # Cursor固有（またはシンボリックリンク）
└── packages/
    ├── frontend/
    │   └── AGENTS.md                      # フロントエンド固有の指示
    └── backend/
        └── AGENTS.md                      # バックエンド固有の指示

ファイルの読み込み優先度

多くのツールでは、編集中のファイルに最も近いAGENTS.mdが優先されます。packages/frontend/AGENTS.mdとルートのAGENTS.mdが両方存在する場合、フロントエンドのファイルを編集中はパッケージレベルのAGENTS.mdが優先的に読み込まれます。

🔗 シンボリックリンク戦略¶

AGENTS.mdと各ツール固有ファイルの関係を管理する2つのアプローチを紹介します。

アプローチ1：シンボリックリンクで完全統一¶

# AGENTS.md を Source of Truth として他ツールのファイルにリンク
# ※ シンボリックリンクはリンク元からの相対パスで指定
ln -s ../AGENTS.md .github/copilot-instructions.md
ln -s AGENTS.md CLAUDE.md                           # 同階層なのでそのまま
ln -s ../../AGENTS.md .cursor/rules/agents.md

相対パスについて

ln -s の第1引数はリンクファイルの配置場所から見た相対パスです。.github/内に作るリンクは../AGENTS.md、.cursor/rules/内なら../../AGENTS.mdになります。プロジェクト構成に応じて調整してください。

メリット	デメリット
1ファイルのみ管理すればよい	ツール固有の機能差をカバーできない
完全な一貫性が保証される	Claude Code特有のMCP設定等が記述不可
gitでの差分管理がシンプル	シンボリックリンクに対応しないCI環境がある

アプローチ2：共通+差分の併存¶

AGENTS.md                    ← 共通ルール（ビルド手順、テスト、コーディング規約）
CLAUDE.md                    ← Claude固有（思考プロセス指示、MCP設定）
copilot-instructions.md      ← Copilot固有（コード補完スタイル、レビュー方針）

メリット	デメリット
ツール固有の最適化が可能	更新時に複数ファイルの同期が必要
各ツールの強みを最大限に活用	情報の重複リスク
段階的な導入が容易	ファイル数が増える

共通はAGENTS、差分は個別

推奨

アプローチ2（共通+差分の併存）を推奨します。AGENTS.mdに80%の共通ルール（ビルド手順、テスト方針、コーディング規約、セキュリティポリシー）を書き、ツール固有ファイルには差分のみを記載します。AGENTS.md内で以下のように参照先を明記するとよいでしょう。

## Tool-Specific Files
- Claude Code: `CLAUDE.md` を参照（MCP設定、思考プロセス指示）
- GitHub Copilot: `.github/copilot-instructions.md` を参照（補完スタイル）

📝 AGENTS.md の書き方¶

以下は、TypeScript + Reactプロジェクトを想定したテンプレート例です。

# AGENTS.md

## Project Overview
TypeScript + React のWebアプリケーション。バックエンドはNode.js + Express。

## Build & Run
```bash
npm install
npm run dev        # 開発サーバー起動
npm run build      # プロダクションビルド
npm run test       # テスト実行

Code Style¶

TypeScript strict mode
ESLint + Prettier（設定は .eslintrc.js）
コンポーネントは関数コンポーネント + hooks
命名: camelCase（変数/関数）、PascalCase（コンポーネント/型）

Testing¶

Jest + React Testing Library
テストファイルは __tests__/ ディレクトリ
カバレッジ目標: 80%以上

PR Guidelines¶

1 PR = 1 機能 or 1 バグ修正
タイトル: conventional commits形式（feat:, fix:, docs: 等）
レビュー前にCI全パス必須

Security¶

.env ファイルはコミット禁止
APIキーは環境変数経由

ユーザー入力は必ずバリデーション

### 記述のコツ

!!! abstract "効果的なAGENTS.mdを書くための5原則"
    1. **具体的に書く** — 「きれいなコードを書いて」ではなく「ESLint + Prettierの設定に従う」
    2. **ビルド手順を最優先** — エージェントが最初に必要とする情報はビルド・テストの方法
    3. **禁止事項を明記** — 「.envをコミットしない」「anyは使わない」など
    4. **ディレクトリ構造を示す** — エージェントがファイルを探す手がかりになる
    5. **短く保つ** — 500行以内を推奨。長すぎるとコンテキストウィンドウを圧迫

## 🏢 モノレポでの活用

大規模なモノレポでは、階層的なAGENTS.md配置が効果的です。

monorepo/ ├── AGENTS.md # 全パッケージ共通（言語設定、CI、セキュリティ） ├── packages/ │ ├── web/ │ │ └── AGENTS.md # Webフロントエンド固有（React、CSS方針） │ ├── api/ │ │ └── AGENTS.md # APIサーバー固有（REST設計、DB操作） │ └── shared/ │ └── AGENTS.md # 共有ライブラリ固有（公開API設計方針） └── infra/ └── AGENTS.md # インフラ固有（Terraform、Docker）

### 優先度ルール

| 優先度 | ファイル位置 | 説明 |
|--------|------------|------|
| 高 | 編集ファイルと同階層のAGENTS.md | 最も近いファイルが最優先 |
| 中 | 上位ディレクトリのAGENTS.md | 親ディレクトリから順に適用 |
| 低 | ルートのAGENTS.md | 全体共通ルールとして常に適用 |

!!! example "実例: OpenAIリポジトリ"
    OpenAIの自社リポジトリでは**88個のAGENTS.md**ファイルが配置されています。ルートにプロジェクト全体の方針、各モジュールディレクトリにモジュール固有の指示が書かれており、大規模モノレポでの実践的な運用例として参考になります。

## 📊 copilot-instructions.md / CLAUDE.md / AGENTS.md 比較

3つのファイルの位置づけと特徴を整理します。

| 観点 | AGENTS.md | copilot-instructions.md | CLAUDE.md |
|------|-----------|------------------------|-----------|
| **管轄** | Linux Foundation（AAIF） | GitHub / Microsoft | Anthropic |
| **対応ツール** | 20+ツール | GitHub Copilotのみ | Claude Codeのみ |
| **フォーマット** | 自由形式Markdown | 自由形式Markdown | 自由形式Markdown |
| **読み込み優先度** | ツール設定依存 | Copilotで自動読み込み | Claude Codeで自動読み込み |
| **モノレポ対応** | :white_check_mark: ネスト対応 | :x: ルートのみ | :white_check_mark: ネスト対応 |
| **目的** | プロジェクト全体のエージェント指示 | Copilot固有の指示 | Claude固有の指示 |
| **独自機能** | クロスツール互換性 | Code Review統合 | MCP設定、`/`コマンド |

!!! info "3ファイルの関係性"
    - **AGENTS.md**: 全ツール共通の「プロジェクト情報」（ビルド手順、テスト方針、コーディング規約）
    - **copilot-instructions.md**: Copilotに特化した「補完スタイル・レビュー方針」
    - **CLAUDE.md**: Claude Codeに特化した「思考プロセス・MCP設定・スキル定義」

    3つは**競合ではなく補完関係**です。AGENTS.mdを土台に、ツール固有ファイルで差分を管理するのがベストプラクティスです。

### Before / After: 個別管理 vs AGENTS.md統一管理

=== "Before（ツールごとに個別管理）"

    ```
    CLAUDE.md        → Claude Code用ルール（120行）
    copilot-instructions.md → Copilot用ルール（100行）
    .cursorrules     → Cursor用ルール（90行）
    ─────────────────
    合計310行、80%が重複、更新時3ファイル同期が必要
    ```

=== "After（AGENTS.md統一管理）"

    ```
    AGENTS.md        → 共通ルール（100行）
    CLAUDE.md        → Claude固有の差分のみ（20行）
    copilot-instructions.md → シンボリックリンク
    ─────────────────
    合計120行、重複ゼロ、更新は1ファイルのみ
    ```

## 🚀 導入ステップ

既存プロジェクトにAGENTS.mdを導入する手順です。

### ステップ1：AGENTS.mdの作成

既存の`copilot-instructions.md`や`CLAUDE.md`がある場合は、まずそれらから**共通情報**（ビルド手順、テスト方針、コーディング規約）を抽出します。

```bash
# プロジェクトルートで作成
touch AGENTS.md
# 既存ファイルから共通部分をAGENTS.mdに集約し、固有ファイルには差分のみ残す

ステップ2：VS Code設定の追加¶

// .vscode/settings.json に追加
{
  "chat.useAgentsMdFile": true
}

ステップ3：既存ツール固有ファイルの整理¶

# 固有ファイルには差分のみ残す（推奨）
# または完全統一ならシンボリックリンクに置き換え
ln -s AGENTS.md CLAUDE.md
ln -s ../AGENTS.md .github/copilot-instructions.md

ステップ4：チームへの共有¶

# AGENTS.mdをgitにコミット
git add AGENTS.md .vscode/settings.json
git commit -m "feat: add AGENTS.md for cross-tool AI agent management"

注意: .gitignoreの確認

AGENTS.mdが.gitignoreに含まれていないことを確認してください。チーム全員がAGENTS.mdを参照できることが重要です。

❓ よくある質問 (FAQ)¶

Q: AGENTS.md と CLAUDE.md / copilot-instructions.md は競合しますか？

競合しません。AGENTS.mdは全ツール共通の「プロジェクト情報」、ツール固有ファイルは「そのツール向けの差分」という補完関係です。共通ルールをAGENTS.mdに書き、ツール固有の設定（MCP、Hooks等）は固有ファイルに記述するのが推奨です。

Q: AGENTS.md の推奨行数は？

500行以内を推奨します。長すぎるとコンテキストウィンドウを圧迫し、エージェントの回答精度が下がります。詳細な手順はAgent Skillsに分離し、AGENTS.mdには概要と参照リンクを記載する構成が効果的です。

Q: シンボリックリンクと実体ファイルのどちらが良い？

ツール間でルールの80%以上が共通なら完全統一（シンボリックリンク）、ツール固有の構文が必要な場合は共通＋差分（実体ファイル併存）を推奨します。CIでシンボリックリンクが使えない環境もあるため、チームのインフラ状況も考慮してください。

マルチエージェント協働ガイド →

統一設定の次は、複数エージェントの実運用に進む

🔗 関連記事¶

カスタムインストラクション完全ガイド
.github/copilot-instructions.mdの詳細な書き方とベストプラクティス - applyToパターンガイド
ファイルパスベースの条件分岐でインストラクションを最適化 - Agent Skillsガイド
SKILL.mdフォーマット、Progressive Disclosure、オンデマンド起動の手順知識 - マルチエージェント協働ガイド
GitHub CopilotとClaude Codeの組み合わせによる開発自動化戦略