AGENTS.mdとは、コーディングエージェントにプロジェクト固有のルールを渡すためのMarkdownファイルだ。ビルドとテストのコマンド、コーディング規約、触ってはいけない場所を書いておくと、エージェントは毎回の説明なしにそれを前提として動く。
30秒でわかるAGENTS.md
・何ができる:テスト手順や禁止事項をエージェントに自動で伝える
・何を解決する:セッションのたびに同じ説明を繰り返す手間
・何を代替する:READMEに書けない「機械向けの注意書き」や、ツールごとの個別指示ファイルの二重管理
・Codexの読み込み順:グローバル、Gitルート、現在のディレクトリの順に連結する
・Claude Code:CLAUDE.mdが無ければAGENTS.mdを直接読む
LOAD ORDER読み込まれる順
Codex は広い順に連結し、現在地に近いほど後ろ=優先
-
グローバル
~/.codex の override.md か AGENTS.md のどちらか1枚
-
プロジェクトルート
Git ルートの override.md か AGENTS.md
-
途中のディレクトリ
1ディレクトリにつき最大1ファイル
-
現在のディレクトリ
最後に置かれ、衝突時に勝つ
Claude Code全般の運用は Claude Code|2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き にまとめている。本記事はAGENTS.mdに絞る。
AGENTS.mdとは|READMEとの違いと生まれた理由
AGENTS.mdは特定企業の独自仕様ではなく、agents.md が「コーディングエージェント向けのオープンなフォーマット」として公開している。同サイトの対応一覧にはCodex、Devin、Cursor、Jules、Gemini CLI、GitHub Copilotのコーディングエージェントなどが並ぶ。運営はLinux Foundation配下のAgentic AI Foundationだ。
READMEとは読者が違う。
| ファイル | 読者 | 書く内容 | 文体 |
|---|---|---|---|
| README.md | 人間 | 概要、使い方、背景 | 説明 |
| AGENTS.md | エージェント | コマンド、規約、禁止事項 | 命令 |
「npm test を実行する」「config/secrets/ には書き込まない」のように、そのまま実行できる形で書くのが要点だ。AGENTS.mdを置いてもモデルの重みは変わらない。セッション開始時にコンテキストの一部として読み込まれるだけで、強制力のある設定ではなく「指示」として扱われる。確実に止めたい操作は、サンドボックスや承認設定の側で制限する。
AGENTS.mdの置き場所と読み込み順|グローバル・プロジェクト・override
Codexの動作は公式ドキュメントと openai/codex の codex-rs/core/src/agents_md.rs で確認した。
グローバルとプロジェクトの探索
・グローバル:Codexホーム(既定 ~/.codex、CODEX_HOME で変更)の AGENTS.override.md があればそれを、なければ AGENTS.md を読む。このレベルで使うのは空でない最初の1枚だけ
・プロジェクト:Gitルート(見つからなければ現在のディレクトリ)から現在のディレクトリまで下る。各ディレクトリで AGENTS.override.md、AGENTS.md、project_doc_fallback_filenames の順に探し、最初に見つかった1枚を採用する
・結合:ルートから下へ連結する。現在地に近いファイルが後ろに来るため、ルールが衝突したときはそちらが優先される
ソースでは、ユーザー向けの指示とプロジェクトの指示の境目にだけ --- project-doc --- という区切りが入る。プロジェクト内のファイル同士は空行で連なる。つまり「各ファイルの間に区切りが入る」わけではない。
myproject/ ← Gitルート
├── AGENTS.md ← 全体ルール
└── services/payments/
├── AGENTS.md ← payments の追加ルール
└── AGENTS.override.md ← 同じ階層の AGENTS.md より先に採用される
services/payments/ で作業すると、ルートの AGENTS.md と、その階層の AGENTS.override.md が連結される。同じ階層の AGENTS.md は読まれない。
AGENTS.override.mdの使いどころ
overrideは「チームの AGENTS.md を変えずに、自分の環境だけ指示を差し替える」ためのファイルだ。実験的なルールを試すときにも使える。プロジェクト内に置く場合は、個人用なら .gitignore に入れる。チームに存在を知らせないまま残すと、エージェントの挙動の原因が追いにくくなる。
既存のファイル名を読ませる
RULES.md など別名のファイルをすでに運用している場合は、~/.codex/config.toml に project_doc_fallback_filenames = ["RULES.md"] を書く。AGENTS.mdを新規に作らずに済む。
AGENTS.mdの書き方|最初の1枚のテンプレート
WHAT TO WRITE書く3点
最初の1枚は実行コマンド・禁止・構成だけでよい
-
1.ビルドとテストのコマンド
エージェントが推測せずそのまま実行できる形で書く
-
2.触ってはいけない場所と操作
秘密情報のディレクトリ、生成物、本番への直接操作
-
3.ディレクトリ構成と規約
READMEに載せにくい細部。コミット規約もここ
agents.md が推奨する内容は、プロジェクト概要、ビルドとテストのコマンド、コーディング規約、セキュリティ上の注意だ。最初から網羅しようとせず、上の3点から始める。
# Project Context
Node.js + TypeScript の REST API サーバー。DB は PostgreSQL(Prisma)。
## Commands
- テスト: `npm test`
- Lint: `npm run lint`
- 型チェック: `npm run typecheck`
## Rules
- コード修正後は必ず `npm test` を実行する
- `config/secrets/` には書き込まない
- スキーマ変更は `prisma migrate dev` でマイグレーションを作る
- コミットメッセージは Conventional Commits 形式
## Layout
- `src/routes/` API 定義 / `src/services/` ビジネスロジック / `tests/` テスト
書いたコマンドはエージェントがそのまま実行する。存在しないコマンドを書くと失敗するので、掲載前に自分で叩いて確かめる。サービス別に変えたい指示は、そのディレクトリに小さな AGENTS.md を置いて分ける。
AGENTS.mdのベストプラクティス|32KiB上限と運用
サイズ上限を意識する
Codexの project_doc_max_bytes は既定で32KiB(32,768バイト)だ。公式ドキュメントでは、連結後のサイズが上限に達するとそれ以上ファイルを追加しない、と説明されている。ソースでも、残りの予算を超えるファイルは切り詰められ、警告を出す実装になっている。エラーで止まるのではなく、後ろの指示が読まれないまま進む点に注意したい。
ソースを読む限り、信頼していない(untrusted)プロジェクトではプロジェクト側のファイルは読まれない。また、この上限が数えるのはプロジェクト側のファイルだ。~/.codex のグローバル指示は別枠で渡される。ただしこれはソースからの読み取りで、実機で上限超過時の挙動までは再現していない。
運用のコツ
・小さく始める:コマンドと禁止事項だけの1枚から。問題が出た都度、ルールを足す
・禁止事項は具体的に書く:「dist/ は生成物なので編集しない」のように理由を添える
・変更したらコミットする:古い指示のままだと、エージェントは古いルールに従い続ける
・指示が効かないとき:対象のディレクトリでCodexを起動し直す。公式ドキュメントによると、指示のチェーンは実行ごとに再構築される
読み込まれたかを確かめるには、公式ドキュメントが挙げる次の形が使える。
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
返答はモデルが自分の文脈を要約したものなので、厳密なログではない。
CLAUDE.md・.cursorrulesとの違い|Claude CodeでAGENTS.mdを使う
各ツールは独自の指示ファイルを持つ。全体の対応表は AI時代におけるMDファイルを整理する|CLAUDE.md・.cursorrules・AGENTS.md完全対応表 にまとめた。
| ファイル | 主な対象 | 上書き用 | 備考 |
|---|---|---|---|
| AGENTS.md | Codex、Devin、Cursorなど多数 | AGENTS.override.md(Codex) | 階層で近いものが優先。Codexの上限は既定32KiB |
| CLAUDE.md | Claude Code | CLAUDE.local.md | @path で他ファイルを取り込める |
| .cursorrules | Cursor | なし | 新形式は .cursor/rules/ |
| GEMINI.md | Gemini CLI | なし | グローバルは ~/.gemini/GEMINI.md |
CLAUDE CODEどちらを読むか
Claude Code はCLAUDE.md があればそちらだけを読む
リポジトリの状態
Claude Code が読むもの
リポジトリの状態: AGENTS.md のみ
Claude Code が読むもの: AGENTS.md(v2.1.277 以降)
リポジトリの状態: AGENTS.md と CLAUDE.md
Claude Code が読むもの: CLAUDE.md だけ
リポジトリの状態: CLAUDE.md が @AGENTS.md を取り込む
Claude Code が読むもの: CLAUDE.md + AGENTS.md
Claude Codeの扱いは更新されている。公式ドキュメントでは、v2.1.277以降、作業ディレクトリとその上にCLAUDE.mdも CLAUDE.local.md も無い場合にAGENTS.mdを直接読む。CLAUDE.mdが1つでもあると、既定ではCLAUDE.mdだけが読まれる。
CodexとClaude Codeを併用するなら、AGENTS.mdを実体にして、CLAUDE.mdから取り込むのが手堅い。
# CLAUDE.md
@AGENTS.md
## Claude Code だけに効かせるルール
- ここに追記する
/config の Project instructions を claude-md-and-agents-md にする方法もある。なお AGENTS.override.md と AGENTS.local.md は、Claude Codeは読まない。overrideはCodex固有の仕組みだ。
迷ったら、リポジトリのルートに AGENTS.md を1枚置くところから始めればよい。CLAUDE.mdの運用との関係は Claude Skillsを徹底解説 も参考になる。
まとめ
・AGENTS.mdは、エージェント向けのプロジェクト指示書。命令形で、実行できるコマンドと禁止事項を書く
・Codexはグローバル、Gitルート、現在のディレクトリの順に連結し、近いものが勝つ。overrideは同じ階層のAGENTS.mdより先に採用される
・既定32KiBを超えると後ろの指示が読まれない。サブディレクトリに分けて小さく保つ
・Claude Codeは、CLAUDE.mdが無いときだけAGENTS.mdを直接読む。併用は @AGENTS.md で取り込む





