AGENTS.md vs Custom Agents【5つの比較表で混乱解消】2026年版

1 はじめに
2 結論（先出し）
3 Custom Agents とは
4 AGENTS.md とは
5 比較表
6 AGENTS.md の配置と優先順位
- 6.1 ネスト可能
- 6.2 優先順位
7 どちらを使うべきか
8 よくある誤解
9 まとめ
10 参考リンク
- 10.1 公式ドキュメント
- 10.2 関連記事

はじめに

ども！GitHub Copilot の設定ファイルを夜な夜なこねくり回している龍ちゃんです。Claude Code での経験があるので、この「こねる作業」が後々の開発体験につながると信じて頑張っております。

今回は、GitHub Copilot の「Custom Agents」と「AGENTS.md」という2つの似た名前の機能について解説します。

正直に言うと、僕も最初は混乱していました。というか同じ機能だと思っていました。「agents」で検索しても情報が混在していて、AIに聞いても誤認されることがあります（ChatGPT、Gemini、Perplexity で実際に試しました）。

そんな方のために、この記事では両者の違いを明確にし、どのように使い分けるべきかを説明します。

前回の記事（設定5種を網羅）では概要レベルで触れましたが、今回はその深掘り版です。

検証環境

検証日: 2026年1月30日

環境: VS Code + Dev Container

GitHub Copilot: 2026年1月時点の機能

結論（先出し）

最初に結論をお伝えします。

名前	正体
Custom Agents	GitHub Copilot 専用のフェーズ別作業空間
AGENTS.md	クロスツール互換のオープンフォーマット

名前が似ているだけで、全く別物です。

Custom Agents とは

基本情報

項目	内容
配置場所	`.github/agents/*.agent.md`
用途	設計/実装/レビューなどフェーズ別に切り替え
呼び出し	ドロップダウンから手動選択
対応	GitHub Copilot 専用

注: 拡張子は .agent.md が公式推奨です。内部的には .md も認識されますが、明示的に .agent.md を使用してください。

特徴

セッションを通じて有効（単発ではない）
独立したコンテキストで作業
YAML Frontmatter で tools / description を定義

僕は Custom Agents を「人格設定」だと思っています。設計者、実装者、レビュアーなどの人格を切り替えて使うイメージですね。

使用例

---
name: design-reviewer
description: 設計レビュー専門
tools: ["read", "search"]
---

あなたは設計レビューの専門家です。
アーキテクチャの整合性をチェックしてください。

AGENTS.md とは

基本情報

項目	内容
配置場所	リポジトリルート or サブディレクトリ
用途	AI エージェント向けの README
読み込み	Coding Agent 実行時に自動
対応	主要なAIコーディングツール

対応ツール一覧

AGENTS.md は GitHub Copilot だけのものではありません。以下のツールで共通して使えます。

GitHub Copilot Coding Agent
Claude Code（CLAUDE.md も読む）
OpenAI Codex
Google Jules / Gemini CLI
Cursor, VS Code, Zed, Warp
Aider, Devin, Factory, RooCode など

管理団体

Linux Foundation / Agentic AI Foundation が管理
オープンフォーマットとして標準化
6万以上のOSSプロジェクトで採用

対応ファイル名

ファイル名	対象ツール
AGENTS.md	標準（全ツール共通）
CLAUDE.md	Claude Code
GEMINI.md	Gemini CLI

注意: Copilot Coding Agent はすべて読み込んでマージします。

正直、すべて読むのはやめてほしいですね。複数の AI サービスを導入しているプロジェクトでは、意図しない指示が混ざる可能性があるので気をつけてください。

何を書くべきか

公式ブログでは、以下の6セクションが推奨されています。

セクション	内容
コマンド	ビルド、テスト、リントの実行方法
テスト	フレームワーク、書き方のルール
プロジェクト構造	ディレクトリ構成の説明
コードスタイル	命名規則、良い例/悪い例
Gitワークフロー	ブランチ命名、コミットメッセージ
境界線	Always / Ask First / Never の3層

特に「境界線」が重要です。AI が勝手にやってはいけないこと（Never Do）を明示しておくと、破壊的な操作を防げます。

詳細は公式ブログを参照してください。

比較表

項目	Custom Agents	AGENTS.md
配置場所	`.github/agents/`	リポジトリ任意
適用方法	手動選択	自動読み込み
互換性	Copilot専用	クロスツール
ネスト	不可	可能（近い方優先）
用途	フェーズ別ペルソナ	プロジェクト指示
管理	GitHub	Linux Foundation

AGENTS.md はリポジトリ単位での配置なので、Claude Code の CLAUDE.md みたいな運用ができますね。

AGENTS.md の配置と優先順位

ネスト可能

AGENTS.md はサブディレクトリにも配置できます。

repo/
├── AGENTS.md              # リポジトリ全体
├── packages/
│   └── frontend/
│       └── AGENTS.md      # frontend 固有（こちらが優先）

優先順位

AGENTS.md 公式サイトによると、近い方が優先されます。

編集対象ファイルに最も近い AGENTS.md
親ディレクトリの AGENTS.md
リポジトリルートの AGENTS.md

“the nearest file in the directory tree takes precedence, creating a hierarchical configuration system”
— agents.md

注意: VS Code Issue #271489 で、ネストされた AGENTS.md が無視されるバグが報告されています。理論上は近い方優先ですが、環境によっては動作が異なる可能性があります。これからのアップデート情報は注視していかないといけないです。

どちらを使うべきか

新しい指示を追加したい
    │
    ├─ フェーズ別に切り替えたい？
    │     └─ Yes → Custom Agents
    │
    ├─ 他のAIツールでも使いたい？
    │     └─ Yes → AGENTS.md
    │
    └─ Copilot専用でOK、自動適用したい
          └─ AGENTS.md（または copilot-instructions.md）

ポイント:

Custom Agents: 設計モード、実装モード、レビューモードなど「モードの切り替え」に使う
AGENTS.md: プロジェクト固有の指示（コマンド、テスト方法、境界線など）を書く

よくある誤解

誤解	実際
AGENTS.md は Custom Agents の設定ファイル	別物。AGENTS.md はクロスツール互換フォーマット
Custom Agents は AGENTS.md を読み込む	Custom Agents は独立したペルソナ定義
AGENTS.md は GitHub Copilot 専用	主要なAIコーディングツールで共通利用可能

まとめ

項目	Custom Agents	AGENTS.md
一言で言うと	フェーズ別の人格設定	AI向けREADME
対応ツール	Copilot専用	主要ツール対応（クロスツール）
適用方法	手動選択	自動読み込み

Custom Agents: フェーズ別の作業空間（Copilot専用、手動選択）
AGENTS.md: AI向けREADME（クロスツール、自動読み込み）
名前が似ているが全く別の概念
目的に応じて使い分け、両方併用も可能