AGENTS.mdを共通指示に使う方法：Copilot・Codex・Claude Codeの対応差¶

対象 / ポイント

対象: GitHub Copilot、Codex、Claude Codeを同じリポジトリで運用し、ビルド・テスト・規約の重複管理を減らしたいチーム

ポイント:

AGENTS.mdはCodexと複数のCopilot機能が読めるが、対応範囲は製品・画面ごとに異なる
Claude CodeはAGENTS.mdを直接読まないため、CLAUDE.mdから@AGENTS.mdで取り込む
共通ファイルは短い索引として保ち、実行必須の検査はCIやフックで強制する

結論：1ファイルに寄せられるが、1ファイルだけでは終わらない¶

AGENTS.mdは、エージェントへリポジトリの構造、コマンド、規約、検証方法を伝えるMarkdownファイルだ。Codexはリポジトリ階層のAGENTS.mdをネイティブに読み、GitHub CopilotもIDE、CLI、cloud agent、code reviewの一部で利用する¹²。

ただし「すべてのAIツールが同じ規則で自動的に動く」という意味ではない。Claude Codeの公式仕様はCLAUDE.mdであり、Copilotも機能によって読み込むファイルが違う。実務ではAGENTS.mdを共通の核にし、各製品の入口だけ薄く残す構成が安定する。

AGENTS.md                         # 共通のビルド・テスト・規約
CLAUDE.md                         # @AGENTS.md + Claude固有事項
.github/copilot-instructions.md   # Copilot固有事項がある場合だけ
.github/instructions/             # Copilotのパス別指示が必要な場合

現在の対応範囲¶

GitHubの公式対応表では、同じCopilotでも機能ごとに差がある²。

利用面	`AGENTS.md`	補足
Codex CLI / IDE / cloud	対応	ルートから作業ディレクトリまで探索し、より具体的な指示を後段へ積む
Copilot Chat in VS Code	対応	ワークスペース内のagent instructionsとして扱う
Copilot CLI	対応	`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`を扱う
Copilot cloud agent	対応	リポジトリ指示、パス別指示、agent instructionsを併用できる
Copilot code review	対応	ルート`AGENTS.md`対応は2026年6月に一般提供。現在は追加ファイルにも対応
Visual Studio / JetBrainsのCopilot Chat	一部差あり	対応表を利用中のIDE・機能単位で確認する
Claude Code	直接は非対応	`CLAUDE.md`からimportするか、シンボリックリンクを使う

Copilot code reviewは2026年7月時点で、feature branch上のAGENTS.mdやSkillもPRレビュー時に読み、REVIEW.md、GEMINI.md、CLAUDE.mdにも対応している³。過去の「ルートAGENTS.mdだけ」という前提で設計を固定しない方がよい。

最小のAGENTS.mdを書く¶

長い設計書を丸ごと貼るのではなく、エージェントが次に読む場所と、必ず使うコマンドを置く。

# Repository Guide

## Scope
- Web application code lives in `src/`.
- Architecture decisions live in `docs/architecture/`.

## Setup
- Install dependencies with `pnpm install --frozen-lockfile`.
- Copy `.env.example` to `.env`; never commit credentials.

## Checks
- Run `pnpm lint` after source changes.
- Run `pnpm test` before proposing a pull request.
- Run `pnpm test:e2e` when routes or authentication change.

## Conventions
- Use TypeScript strict mode.
- Keep API handlers in `src/api/handlers/`.
- Do not edit generated files under `src/generated/`.

## Pull requests
- Explain the user-visible change and tests run.
- Call out migrations, security boundaries, and rollback steps.

良い指示は検証可能だ。「適切にテストする」ではなく、対象とコマンドを書く。「既存規約に従う」ではなく、規約の場所を示す。

OpenAIも、巨大なAGENTS.mdを百科事典にせず、約100行の索引として深い文書へ誘導する運用を紹介している⁴。情報を詰め込むほど従いやすくなるわけではない。

Claude Codeから共通指示を読む¶

Claude CodeはCLAUDE.mdを読み、AGENTS.mdは直接読まない。公式に案内されている最小構成はimportだ⁵。

@AGENTS.md

## Claude Code
- Use plan mode before changing `src/billing/`.
- Ask before running production migrations.

重複なく完全に同じ内容だけを使うなら、macOS/Linuxではシンボリックリンクも使える。

ln -s AGENTS.md CLAUDE.md

Windowsでは権限やDeveloper Modeが必要になるため、@AGENTS.md importの方が移植しやすい。importならClaude固有の規則も追記できる。

Copilot固有の指示を分ける¶

Copilotの全機能に共通する追加事項がある場合だけ、.github/copilot-instructions.mdを置く。

# Copilot-specific instructions

- Link the originating issue in the pull request body.
- Do not change files under `infra/prod/` unless the task names them.

特定パスだけに適用する規則は.github/instructions/*.instructions.mdへ分ける。Copilotはリポジトリ全体の指示とパス別指示を併用できる⁶。

同じ規則をAGENTS.mdとcopilot-instructions.mdへコピーしない。片方の更新漏れで矛盾が起きるためだ。共通事項はAGENTS.md、製品固有事項だけ専用ファイルへ置く。

モノレポでは責任範囲ごとに分ける¶

ルートには全体規則を置き、パッケージ固有のコマンドだけを近い階層へ置く。

AGENTS.md
packages/
├── web/
│   └── AGENTS.md
└── api/
    └── AGENTS.md

Codexや対応するCopilot機能は、作業対象に近い指示を利用する。ただし探索・優先順位の細部は製品ごとに同一ではない。衝突する規則を階層へ置くより、ルートを共通方針、下位を追加コマンドに限定する方が安全だ。

導入後に4面で検証する¶

ファイルが存在するだけでは十分ではない。次の読み取り専用タスクを、実際に使う面ごとに試す。

「このリポジトリで変更後に実行すべきチェックを列挙して」と尋ねる
Codex、Copilot Chat、cloud agent、code reviewのうち利用する面で回答を比較する
Claude Codeでは/memoryを開き、CLAUDE.mdとimportが読み込まれたことを確認する
誤答した規則を短く具体化し、重複や矛盾を削る

AGENTS.mdはモデルへ渡す文脈であり、強制ポリシーではない。秘密情報検査、必須テスト、承認、保護ブランチなど、失敗を許容できない条件はCI、フック、rulesetで強制する。

まとめ¶

AGENTS.mdはCodexと対応するCopilot機能の共通核にできる
Claude CodeはCLAUDE.mdから@AGENTS.mdで取り込む
対応は製品名ではなく利用面単位で確認する
共通指示は短い索引にし、必須条件は機械的なガードレールへ移す

この構成なら、同じ規則を何度もコピーせず、ツール固有の差も隠さずに運用できる。