AIエージェントが自律的にコードを書く時代になって、あらたな問いが生まれた——「エージェントにプロジェクトのルールをどう教えるか？」
その答えとして各社が独自に定義したのが、今日の記事で解説するAGENTS.mdだ。OpenAI Codex CLIがセッション開始前に自動ロードするMarkdown形式の指示ファイルであり、「README.mdの機械向けバージョン」とも呼ばれる。
CLAUDE.mdがClaude Code向けの指示ファイルであるように、AGENTS.mdはOpenAI Codex向けの指示ファイルだ。しかし、その読み込みメカニズムは3層構造になっており、複数のファイルを階層的に結合するという、よりきめ細かい設計になっている。
AGENTS.mdを適切に設定することで、AIエージェントがプロジェクト固有のルールを把握した上でコードを書くようになる。テストコマンドを自動実行し、禁止ファイルへの書き込みを避け、コミットメッセージ規約を守る——これらはすべてAGENTS.mdで制御できる。
この記事では、AGENTS.mdの仕組みから書き方のテンプレート、Devinやその他のAIエージェントでの利用方法、そしてCLAUDE.mdや.cursorrulesとの違いまでを公式ドキュメントベースで体系的に解説する。
AGENTS.mdとは何か、なぜ必要なのか
3層ロードメカニズム（グローバル・プロジェクト・サービス別）
AGENTS.override.mdの使い方と優先順位
DevinとClaude CodeでのAGENTS.md活用方法
CLAUDE.md vs AGENTS.md vs .cursorrules の比較
すぐ使えるテンプレートとベストプラクティス
AGENTS.mdとは何か
AGENTS.mdは、OpenAI Codex CLIエージェントがタスクを開始する前に自動的に読み込むMarkdown形式の指示ファイルだ。一言で言えば、「README.mdの機械向けバージョン」——人間のための説明ではなく、AIエージェントへの指示書だ。
生まれた背景
従来のコーディング補助AIは、ユーザーが毎回「このプロジェクトではTypeScriptを使っています」「テストはnpm testで実行してください」と説明する必要があった。OpenAI Codex CLIはこの問題を解決するため、プロジェクト固有の指示を永続的に保持する仕組みとしてAGENTS.mdを導入した。
AGENTS.mdの中心的なコンセプトは「一度書けば毎回説明しなくていい」だ。テストコマンド、コーディング規約、禁止操作——これらをファイルに書いておけば、Codexは毎回のセッションで自動的にそれを読んでプロジェクトのルールを把握する。
README.mdとの違い
AGENTS.mdとREADME.mdは同じMarkdown形式だが、読者が根本的に異なる。
| ファイル | 読者 | 目的 | 書き方 |
|---|---|---|---|
| README.md | 人間（開発者・ユーザー） | プロジェクトの概要・使い方を説明 | 文章・説明重視 |
| AGENTS.md | AIエージェント | エージェントが守るべきルールを指示 | 命令・制約重視 |
README.mdは「このプロジェクトはAPIサーバーです。ユーザーが〜できます」という説明文スタイルで書く。AGENTS.mdは「npm testを必ず実行すること」「config/secrets/には絶対に書き込まない」という命令形で書く。AIが動作するための具体的なガイドラインを記述するのが目的だ。
CLAUDE.mdとの類似点
AI時代におけるMDファイルを整理する｜CLAUDE.md・.cursorrules・AGENTS.md完全対応表でも解説しているように、各AIコーディングツールはそれぞれ独自の指示ファイルを持っている。AGENTS.mdはその中でOpenAI Codex向けのファイルだ。
CLAUDE.mdとAGENTS.mdは思想的に非常に似ている。どちらも：
- Markdownで自由記述
- セッション開始前に自動ロード
- Gitで管理してチーム共有
- プロジェクトのルール・制約・コマンドを記述
ただし、読み込みメカニズムや機能に違いがある。この違いについては後の比較表で詳しく解説する。
OpenAI Codex CLIでのAGENTS.md——3層ロードメカニズム
AGENTS.mdの最大の特徴は、その3層構造のロードメカニズムだ。グローバル・プロジェクト・サービス別の3つの層でファイルを管理し、最終的にCodexはそれらを結合して一つのコンテキストとして受け取る。
グローバル上書き（最優先）"] -->|読み込み| E B["~/.codex/AGENTS.md
グローバル設定"] -->|読み込み| E C["Gitルート/AGENTS.md
プロジェクト設定"] -->|読み込み| E D["services/payments/AGENTS.md
サービス別設定"] -->|読み込み| E E["Codexに結合して渡す
（上限32 KiB）"] F["AGENTS.override.md
（各層で優先）"] -->|上書き| C F -->|上書き| D
層1: グローバル設定（~/.codex/）
グローバル設定は開発者のホームディレクトリの ~/.codex/ フォルダに置く。すべてのプロジェクトに共通で適用されるルールをここに記述する。
~/.codex/
├── AGENTS.override.md ← 最優先（上書き用）
├── AGENTS.md ← 通常のグローバル設定
└── config.toml ← Codexの動作設定
AGENTS.override.md は通常の AGENTS.md より優先される特別なファイルだ。一時的なルールや実験的な設定を素早く試したいときに使う。
グローバルAGENTS.mdの記述例：
## Global Defaults
- 常に `npm test` をJavaScriptファイル修正後に実行
- 依存追加は pnpm を優先
- 本番依存の追加前に確認を求める
- コミットメッセージはConventional Commits形式で書く
層2: プロジェクト設定（Gitルートから現在ディレクトリ）
プロジェクト設定は最も重要な層だ。Codexは現在の作業ディレクトリからGitリポジトリのルートまで、各ディレクトリを遡ってAGENTS.mdを探す。
具体的な動作：
- 現在ディレクトリから順にGitルートへ向かって各階層をスキャン
- 各ディレクトリで
AGENTS.override.md→AGENTS.md→ フォールバックファイル名の順に探索 - 1ディレクトリにつき最大1ファイルを読み込む
- ルートから現在ディレクトリの順に結合（後のファイルが優先）
myproject/ ← Gitルート
├── AGENTS.md ← プロジェクト全体のルール
├── src/
│ └── AGENTS.md ← src/以下のルール（オプション）
└── services/
└── payments/
├── AGENTS.md ← paymentsサービスのルール
└── AGENTS.override.md ← paymentsサービスの上書き
Codexが services/payments/ で作業する場合、上記すべてのファイルが結合されてコンテキストとして渡される。より下層のファイルが上層のルールを上書きできる設計になっている。
層3: フォールバックファイル名
~/.codex/config.toml に project_doc_fallback_filenames を設定することで、AGENTS.md 以外のファイル名もロード対象にできる。
# ~/.codex/config.toml
project_doc_max_bytes = 32768 # 32 KiB（デフォルト）
project_doc_fallback_filenames = ["RULES.md", "AI_CONTEXT.md"]
これにより、既存のプロジェクトで RULES.md や AI_CONTEXT.md を使っている場合も、AGENTS.mdを新たに作成せずにCodexに読み込ませることができる。
AGENTS.override.mdの使い方
AGENTS.override.mdは通常のAGENTS.mdより優先される。主な用途は2つだ：
- 個人環境の一時的な変更: チームのルールは変えずに、自分の開発環境だけで別のテストコマンドを使いたい場合
- 実験的なルールのテスト: 本番のAGENTS.mdに書く前に新しいルールを試したい場合
# ~/.codex/AGENTS.override.md
## Temporary Overrides
- テスト時は `npm test` ではなく `npm test -- --verbose` を使う（デバッグ中）
- PRレビューコメントを必ず日本語で書く（一時設定）
Devin・他のAIエージェントでのAGENTS.md利用
AGENTS.mdはOpenAI Codexだけのものではない。Cognition AIのDevinも同様のメカニズムでAGENTS.mdを活用している。
Devinでの動作
DevinはOpenAIとは独立した企業（Cognition AI）が開発したAIソフトウェアエンジニアだが、AGENTS.mdをサポートしている。Devinはプロジェクトルートの AGENTS.md をインストラクションファイルとして読み込み、タスク実行時の指針として使用する。
Devin向けのAGENTS.mdで特に有効な記述内容：
- ビルドコマンドとテストコマンドの明記
- PR作成時の規約（タイトル形式、説明テンプレート等）
- 環境変数の設定方法
- 禁止操作（本番DBへの直接アクセスなど）
agents.md公式サイト（agents.md）
agents.md という独自ドメインのサイトが存在し、AGENTS.mdのベストプラクティスと事例集を集めている。特定企業が運営する仕様サイトではなく、コミュニティが中心となって整備している。複数のAIエージェントで利用可能なAGENTS.mdの書き方ガイドラインを提供している。
将来的な標準化の動き
2026年現在、AGENTS.mdはOpenAI Codexが普及させた事実上のデファクトスタンダードとなりつつある。Devin以外にも、新しいAIコーディングエージェントが次々とAGENTS.mdのサポートを追加している。ただし、CLAUDE.mdやGEMINI.mdなど、各社が独自のファイル名を維持している状況も続いており、完全な標準化には至っていない。
OpenAI Codex CLI — ネイティブサポート（3層メカニズム）
Devin（Cognition AI） — AGENTS.mdを読み込んで指示として使用
Claude Code — CLAUDE.mdが主体。@AGENTS.mdでインポート可能
その他のエージェント — agents.md公式サイトのガイドライン準拠が増加中
CLAUDE.md vs AGENTS.md vs .cursorrules vs GEMINI.md 比較
AIコーディングツールの普及で、プロジェクトルートに複数のMDファイルが混在するようになった。それぞれの違いを把握しておくことが重要だ。
.cursor/rules/*.mdc"] GM["GEMINI.md"] end CC -->|読み込む| CM CX -->|読み込む| AM CU -->|読み込む| CR GE -->|読み込む| GM DV -->|読み込む| AM CC -->|@インポートで参照可| AM
詳細比較表
| 項目 | AGENTS.md | CLAUDE.md | .cursorrules | GEMINI.md |
|---|---|---|---|---|
| 対象ツール | OpenAI Codex, Devin | Claude Code | Cursor | Gemini CLI |
| 形式 | Markdown（自由記述） | Markdown（自由記述） | Markdown | Markdown |
| 読み込み | タスク開始前 | セッション開始時 | エディタ起動時 | セッション開始時 |
| 階層 | 3層（global/project/service） | 4層 | 2層 | 2層 |
| オーバーライド | AGENTS.override.md | CLAUDE.local.md | なし（新形式は条件指定可） | なし |
| サイズ制限 | 32 KiB（合計） | 制限なし（200行推奨） | - | - |
| チーム共有 | git管理推奨 | git管理推奨 | git管理推奨 | git管理推奨 |
| グローバル設定 | ~/.codex/AGENTS.md | ~/.claude/CLAUDE.md | なし | ~/.gemini/GEMINI.md |
| フォールバック | config.tomlで指定可 | なし | なし | なし |
書き方の哲学の違い
各ツールの指示ファイルは、書き方の哲学がわずかに異なる。
AGENTS.md（Codex向け）は、エージェントが完全自律で動くことを前提として、テストコマンドや禁止操作を具体的に記述することが重視される。Codexはユーザーの確認なしで多くの操作を自動実行するため、制約の明記が特に重要だ。
CLAUDE.md（Claude Code向け）は、Claude Code完全ガイド2026：インストールから本番運用まででも解説しているように、コーディング規約やアーキテクチャ方針を含む広範なコンテキストを記述することが推奨される。Claude Codeは対話的な確認を挟みながら動作するため、AIとの協働を前提とした記述スタイルになる。
.cursorrules（Cursor向け）はエディタ統合型のため、コードの補完動作やスニペット生成に関するルールが中心になりやすい。
どのファイルも「AIに繰り返し説明することを一度書いておく」という目的は共通だ。ツールが異なるため別々のファイルが必要になるが、内容の多くは重複する。複数ツールを使う場合は、共通ルールを1カ所（CONTEXT.mdなど）に書いて各ファイルから参照する戦略が有効だ。
AGENTS.mdの書き方テンプレート
実際のプロジェクトで使えるAGENTS.mdのテンプレートを3種類紹介する。コピーして自分のプロジェクトに合わせてカスタマイズしてほしい。
テンプレート1: グローバル設定（~/.codex/AGENTS.md）
個人の開発環境全体に適用するグローバル設定のテンプレートだ。すべてのプロジェクトで共通のルールをここに書く。
# Global Agent Instructions
## Language Preference
- コードコメントと変数名は英語で書く
- コミットメッセージとPRタイトルは英語
- ユーザーへの説明は日本語で行う
## Commit Style
- Conventional Commits形式を使う（feat:, fix:, docs:, refactor:等）
- コミットは論理的な単位に分割する（一度に大量変更しない）
- WIPコミットは避ける
## Dependency Management
- Node.jsプロジェクトでは pnpm を優先
- パッケージ追加前に必ずプロジェクトオーナーに確認を求める
- 本番依存（dependencies）への追加は特に慎重に
## Safety Defaults
- 本番環境に影響するコードを修正する前に確認を求める
- 秘密情報（APIキー、パスワード等）はコードに直接書かない
- 大量のファイル削除前に確認を求める
テンプレート2: プロジェクト設定（./AGENTS.md）
プロジェクトルートに置く、プロジェクト固有の設定テンプレートだ。チームで共有するためgit管理下に置く。
# Project Context
このプロジェクトはNode.js + TypeScriptで書かれたREST APIサーバーです。
PostgreSQLをデータストアとして使用し、Prismaでスキーマ管理しています。
## Tech Stack
- Runtime: Node.js 20 + TypeScript 5
- Framework: Fastify
- Database: PostgreSQL 16 + Prisma ORM
- Test: Vitest + Supertest
- Lint: ESLint + Prettier
## Working Agreements
- コードを修正したら必ず `npm test` を実行すること
- 本番環境の依存を追加する前に確認を求めること
- TypeScriptのany型は使用禁止
- コミットメッセージはConventional Commits形式で
## Repository Structure
- `src/` — メインソースコード
- `src/routes/` — APIエンドポイント定義
- `src/services/` — ビジネスロジック
- `tests/` — テストファイル
- `prisma/` — DBスキーマとマイグレーション
## Testing
\`\`\`bash
npm test # ユニットテスト（Vitest）
npm run test:e2e # E2Eテスト（実DB使用）
npm run lint # ESLint + Prettier チェック
npm run typecheck # TypeScript型チェック
\`\`\`
## Important Rules
- `config/secrets/` ディレクトリには絶対に書き込まない
- DBスキーマ変更はマイグレーションファイルを必ず作成する（prisma migrate dev）
- 環境変数は `.env.example` にも同時に追記する
- APIの破壊的変更はバージョニングを行ってから実施する
テンプレート3: サービス別オーバーライド（./services/payments/AGENTS.override.md）
マイクロサービス構成でサービス固有のルールを追加したいときに使うテンプレートだ。プロジェクト全体のAGENTS.mdを継承しつつ、このサービスだけのルールを上書き・追加できる。
## Payment Service Rules
### Testing
- ルートの `npm test` ではなく `make test-payments` を使用
- Stripeのテストには必ずテスト用APIキーを使う（`STRIPE_TEST_KEY`）
- 決済フローのE2Eテストは `make test-payments:e2e` で実行
### Security Rules
- APIキーをローテートする場合は必ずセキュリティチームに通知
- PCI DSS準拠のため、カード番号はログに出力しない
- Stripe SDKのメジャーバージョンアップは必ず要承認（セキュリティスキャン後）
### Forbidden Operations
- `payments_production` テーブルへの直接INSERT/UPDATE/DELETE禁止
- Webhookエンドポイントのシグネチャ検証をバイパスしない
- 本番のStripe APIキーをコードに直接記述しない
Claude CodeでAGENTS.mdを参照させる方法
Claude Code自体はAGENTS.mdではなくCLAUDE.mdを読み込む。しかし、チームでCodexとClaude Codeを両方使っている場合、同じルールを2つのファイルに書くのは非効率だ。
方法1: CLAUDE.mdからAGENTS.mdをインポート
CLAUDE.mdに @AGENTS.md と記述することで、Claudeがそのファイルを参照する。
# CLAUDE.md
## このプロジェクトの設定
プロジェクトのルールはAGENTS.mdに記述しています。
@AGENTS.md
## Claude固有の追加設定
（以下にClaudeCodeだけに適用したいルールを記述）
この方法のメリットは、AGENTS.mdをルールのシングルソースとして管理できる点だ。Codexを使うメンバーもClaude Codeを使うメンバーも、同じルールを参照することになる。
方法2: CLAUDE.mdに同じ内容を記述
チームがClaude Codeを主に使い、CodexはオプショナルというプロジェクトではCLAUDE.mdに主要ルールを書き、AGENTS.mdはCodex向けに簡略版を用意する方法もある。
# AGENTS.md（簡略版 - 詳細はCLAUDE.mdを参照）
## Quick Reference
- テスト: `npm test`
- Lint: `npm run lint`
- 詳細ルール: リポジトリのCLAUDE.mdを参照してください
どちらの方法でも重要なのは「ルールの二重管理を避ける」ことだ。Claude Skillsを徹底解説でも触れているように、コンテキストファイルの管理コストを下げることがチームの生産性向上につながる。
検証方法
AGENTS.mdが正しく読み込まれているか確認する方法：
# Codexに現在のインストラクションを要約させて確認
codex --ask-for-approval never 'Summarize current instructions.'
# ログでロードされたファイルを確認
cat ~/.codex/log/session_latest.jsonl | jq '.loaded_files'
ベストプラクティス——ファイル管理とチーム運用
AGENTS.mdを長期的に管理するためのベストプラクティスを紹介する。
ベストプラクティス1: サイズ制限を意識する
合計32 KiBの制限があるため、大きなルールセットはファイルを分割して管理する。1つのプロジェクトルートに巨大なAGENTS.mdを置くより、サービス・機能ごとにディレクトリを分けて小さなAGENTS.mdを配置する方が管理しやすい。
myproject/
├── AGENTS.md ← 全体ルール（小さく保つ）
├── services/
│ ├── auth/AGENTS.md ← 認証サービス固有のルール
│ ├── payments/AGENTS.md ← 決済サービス固有のルール
│ └── api/AGENTS.md ← APIサービス固有のルール
└── tools/
└── AGENTS.md ← ツール・スクリプト用のルール
ベストプラクティス2: テストコマンドを必ず明記する
AIエージェントはAGENTS.mdに書かれたテストコマンドを自動的に実行する。テストコマンドを明記しないと、エージェントは独自の方法でテストを発見しようとするが、プロジェクト固有のセットアップが必要な場合に失敗することがある。
## Testing（必ず記述する）
\`\`\`bash
npm test # ユニットテスト（毎回必須）
npm run test:integration # 統合テスト（DB必要）
npm run lint # コード品質チェック
\`\`\`
ベストプラクティス3: 禁止事項を明確に記述する
「〜しない」「〜禁止」といった禁止事項は、指示がなければエージェントが取りうる行動をあらかじめ除外するために重要だ。
## Forbidden Actions
- `node_modules/` を直接編集しない
- 本番DBに直接接続しない（必ず `DB_URL=test` を使用）
- `.env` ファイルをgitにコミットしない
- `dist/` フォルダのファイルを直接編集しない（生成物のため）
ベストプラクティス4: チームで共有し定期的に更新する
AGENTS.mdはgit管理下に置いてチームで共有することが前提だ。ルールが変わったらAGENTS.mdも更新する。更新を忘れると、AIエージェントが古いルールに従い続けるという問題が起きる。
決める"] --> B["AGENTS.mdに
記述する"] B --> C["git commit & push"] C --> D["チーム全員が
新しいルールを参照"] D --> E["エージェントが
ルールを遵守"] E -->|ルール変更が必要| A
ベストプラクティス5: AGENTS.override.mdは一時的な変更のみ
AGENTS.override.mdは便利だが、使いすぎると「なぜエージェントがこのルールで動いているのかわからない」という混乱を招く。常設のルール変更はAGENTS.mdに書き、AGENTS.override.mdは本当に一時的な変更のみに限定することを強くすすめる。
ベストプラクティス6: 段階的に充実させる
初めてAGENTS.mdを導入するプロジェクトでは、最低限のテストコマンドと禁止操作だけを書いた小さなファイルから始めることをすすめる。「完璧なAGENTS.mdを一度に書こう」とすると、チームの合意形成に時間がかかる。使いながら問題が出た都度、ルールを追記していく方が実用的だ。
AGENTS.md導入ロードマップ
| ステップ | 内容 | 目安の期間 |
|---|---|---|
| Step 1 | テストコマンドと禁止操作のみ記述 | 初日 |
| Step 2 | リポジトリ構造とTech Stackを追加 | 1週間後 |
| Step 3 | コーディング規約とコミット規約を追加 | 2週間後 |
| Step 4 | サービス別AGENTS.mdを追加 | 1ヶ月後 |
| Step 5 | チームのフィードバックを受けて最適化 | 継続的 |
まとめ——AGENTS.mdはAIエージェントの「ルールブック」
AGENTS.mdはシンプルなMarkdownファイルだが、AIエージェントと人間の協働において重要な役割を果たす。「テストを自動実行する」「秘密情報を書かない」「コミット規約を守る」——こうしたルールを一度書いておくだけで、毎回のセッションでエージェントが正しく動くようになる。
1. OpenAI Codexがタスク開始前に自動ロードするMarkdown指示ファイル
2. グローバル・プロジェクト・サービス別の3層構造（合計32 KiB上限）
3. AGENTS.override.mdで優先度付きの一時的な上書きが可能
4. DevinなどCodex以外のエージェントでも採用が広がっている
5. Claude Codeで使う場合はCLAUDE.mdに @AGENTS.md でインポート可能
AGENTS.mdとCLAUDE.mdはどちらも「AIにプロジェクトのルールを教える」という目的は同じだが、対象ツールと細かい仕組みが異なる。複数のAIコーディングツールを使うチームは、それぞれのファイルの役割を理解した上で、ルールの二重管理を避ける工夫をすることが、長期的な運用を楽にするカギになる。
