AGENTS.mdとは、Codexが作業を始める前に必ず読む「プロジェクトの指示書」のことだ。ビルドとテストのコマンド、レビューで見てほしい点、そのリポジトリ独自の決まりを短く書き、リポジトリのルートに置く。Codexは起動時に、ホームの ~/.codex → リポジトリのルート → 作業中のフォルダの順にAGENTS.mdを集めてつなげ、後に読んだもの（作業フォルダに近いもの）を優先する。合計は初期設定で32KiBまでで、超えた分は読まれない。本記事では、OpenAIの公式ドキュメントで確認した仕様をもとに、置き場所・書き方の手順・テンプレート・確認方法、Claude Codeと1つのファイルを共有する方法までを整理する。
この記事の前提：仕様はOpenAIのCodex公式ドキュメント（developers.openai.com/codex。2026年11月時点の正規URLはlearn.chatgpt.com/docs）と、GitHubのopenai/codex、Claude Codeの部分はAnthropicの公式ドキュメント（code.claude.com/docs）で、2026年11月7日に確認した。コマンドは公式ドキュメントに載っている手順をそのまま示している。CLIの仕様は更新が速いため、実行前にリンク先で最新の記載を確かめてほしい。
この記事でわかること
- AGENTS.mdの役割と、READMEとの違い
- Codexが読み込む順番（グローバル・ルート・サブフォルダ・override）と32KiBの上限
- AGENTS.mdを作る手順と、そのまま使えるテンプレート
- 読み込まれたかの確かめ方と、読まれないときの対処
- Claude Codeと同じAGENTS.mdを使い回す方法
執筆：佐藤 祐介（株式会社LIFRELL 代表取締役／業界歴15年・マーケティング支援 累計500社以上）1. AGENTS.mdとは
AGENTS.mdとは、Codexが毎回の作業の前に読む指示書で、リポジトリと一緒に持ち運べる「そのプロジェクトのルール」だ。
OpenAIの公式ドキュメントは「Codexは作業を始める前にAGENTS.mdを読む」と説明している（OpenAI「Custom instructions with AGENTS.md」）。毎回同じ説明をチャットに書かなくても、ビルドの手順やコードの決まりを守った状態で作業が始まる。
READMEとの違いは、読み手だ。READMEは人がプロジェクトを理解するための文書で、AGENTS.mdはエージェントが作業を正しく進めるための文書になる。そのため、背景の説明よりも「どのコマンドで確認するか」「どこを触ってはいけないか」といった、作業のたびに必要な決まりを書く。
公式は、AGENTS.mdに向いている内容として次の4つを挙げている（OpenAI「Customization」）。
- ビルドとテストのコマンド
- レビューで期待すること
- そのリポジトリ独自の決まり
- フォルダごとの指示
また、公式は「小さく保つ」ことを繰り返し求めている。複数の手順からなる作業はSkills（再利用できる手順のまとまり）に、外部のツールとの接続はMCPに分けるのが公式の整理だ。AGENTS.mdは振る舞いを決めるもの、Skillsは繰り返す手順を詰めたもの、MCPは外部のシステムとつなぐものという役割分担になる。
AGENTS.mdはCodex専用の名前ではない。公式サイト（agents.md）があり、Claude Codeも条件付きで読み込む（7章で解説）。Codex全体の使い方はCodex CLI使い方完全ガイドにまとめている。
2. Codexが読み込む順番と上限
Codexは起動時に「グローバル → プロジェクトのルート → 作業中のフォルダ」の順にAGENTS.mdを集め、上からつなげる。後に来るもの（作業フォルダに近いもの）ほど優先される。
図の内容を、公式ドキュメントの記載に沿って文章でも整理する（OpenAI「Custom instructions with AGENTS.md」）。
- グローバル：Codexのホーム（初期設定は ~/.codex。環境変数 CODEX_HOME で変更可）で、AGENTS.override.md があればそれを、なければ AGENTS.md を読む。この階層で使うのは、中身のある最初の1ファイルだけ。
- プロジェクト：プロジェクトのルート（通常はGitのルート）から作業中のフォルダまで、1階層ずつ下りながら探す。各フォルダでは AGENTS.override.md → AGENTS.md → 代替ファイル名（設定した場合）の順に確認し、1フォルダにつき1ファイルまで読む。ルートが見つからない場合は、作業中のフォルダだけを確認する。
- つなげ方：ルートから下に向かって、空行をはさんでつなげる。作業フォルダに近いファイルほど後ろに来るため、前の指示を上書きする形になる。
上限と読み込みのタイミングについても決まりがある。
- 空のファイルは無視される。
- つないだ合計が
project_doc_max_bytes（初期値32KiB）に達すると、それ以降のファイルは足されない。上限に当たったら、値を上げるかフォルダごとに分ける。 - 指示の組み立ては起動時に1回（対話画面なら起動したセッションごとに1回）。手動で消すキャッシュはなく、内容を変えたらCodexを起動し直せば反映される。
- 作業中のフォルダより下のフォルダは探さない。特定の作業向けの上書きは、その作業をするフォルダのなるべく近くに置く。
信頼していないプロジェクトでは読まれない：Codex CLI 0.150.0（2026年8月26日）の変更履歴に、信頼されていないプロジェクトはプロジェクトのAGENTS.mdを提供しなくなったと記載がある（Codex changelog）。新しく開いたフォルダで指示が効かない場合は、そのフォルダを信頼済みにしているかを確かめる。
3. AGENTS.mdを作る手順
まず自分用のグローバルファイルを作り、次にリポジトリのルートに共有用のファイルを置き、必要なフォルダだけに上書き用のファイルを足す。最後にコマンドで読み込みを確かめる。
STEP 1：自分用のグローバルファイルを作る
どのリポジトリでも守ってほしい自分の好み（返答の言語、使うパッケージマネージャーなど）は、ホームに置く。公式は、グローバルのファイルは「Codexがあなたとどうやり取りするか」に、リポジトリのファイルは「チームとコードの決まり」に使い分けるよう勧めている。
mkdir -p ~/.codex
# ~/.codex/AGENTS.md を作成し、下のように書く
## Working agreements
- JavaScriptのファイルを変えたら npm test を実行する
- 依存関係は pnpm で入れる
- 本番用の依存関係を追加する前に確認を取るSTEP 2：リポジトリのルートに共有用のファイルを置く
チーム全員に効かせたい決まりは、リポジトリのルートの AGENTS.md に書いてコミットする。
# AGENTS.md（リポジトリのルート）
## Repository expectations
- プルリクエストを出す前に npm run lint を実行する
- 公開している関数の挙動を変えたら docs/ に記録するSTEP 3：特定のフォルダだけ違う決まりを足す
決済のサービスだけテストのコマンドが違う、といった場合は、そのフォルダに AGENTS.override.md を置く。同じフォルダの AGENTS.md より優先され、AGENTS.md のほうは読まれなくなる。
# services/payments/AGENTS.override.md
## Payments service rules
- npm test ではなく make test-payments を使う
- APIキーの入れ替えは、セキュリティ担当のチャンネルに連絡してから行うSTEP 4：読み込まれたかを確かめる
公式ドキュメントにある確認用のコマンドを使う。承認を求めずに、読み込んだ指示を要約させる。
# リポジトリのルートで、読み込んだ指示を要約させる
codex --ask-for-approval never "Summarize the current instructions."
# サブフォルダから起動し、読み込んだファイルの一覧を出させる
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."2つ目のコマンドでは、グローバルのファイル、ルートの AGENTS.md、payments の上書きファイルの順に報告されれば想定どおりだ（OpenAI「Custom instructions with AGENTS.md」）。
STEP 5：間違いを見つけたら書き足す
公式は、Codexがコードについて誤った思い込みをしたら AGENTS.md で正し、Codex自身にAGENTS.mdを更新させるよう勧めている。そうすれば次のセッションにも修正が引き継がれる。この「直したら書き残す」の繰り返しが、AGENTS.mdを育てる基本の流れになる。
4. 何を書くか：テンプレート
書くのは「毎回守ってほしい、確かめられる決まり」だけだ。目安は、コマンド・場所・禁止事項・完了の条件の4つ。
次のテンプレートは、公式が挙げる項目（ビルドとテストのコマンド、レビューで期待すること、独自の決まり、フォルダごとの指示）に沿って、編集部が日本語で組み立てたものだ。プロジェクトに合わせて書き換えて使う。
# AGENTS.md
## このリポジトリについて
- Next.js と TypeScript のWebアプリ。画面は src/app/、共通部品は src/components/
## 作業の前後に実行するコマンド
- 依存関係の追加：pnpm add（npm は使わない）
- 変更後に必ず実行：pnpm lint と pnpm test
- 型の確認：pnpm typecheck
## コードの決まり
- 新しいファイルは TypeScript で書く。any は使わない
- APIの処理は src/app/api/ に置く
## してはいけないこと
- .env と secrets/ の中身を読まない・表示しない
- 本番のデータベースにつながるコマンドを実行しない
- 依存関係のメジャーバージョンを勝手に上げない
## 完了の条件
- lint・test・typecheck がすべて通っている
- 変更内容と、確かめたコマンドを最後に箇条書きで報告する
## Code Review Rules
- 金額の計算を変える変更は、端数処理のテストがあるかを確認する書くときのコツは3つある。
- 確かめられる書き方にする：「きれいに書く」ではなく「pnpm lint が通る」のように、守れたかを判定できる形にする。
- 短く保つ：公式は「小さく保つ」ことを求めている。長い手順はSkillsに、外部ツールの使い方はMCPに移す。料金ページでも、AGENTS.mdを小さくすることが利用枠を長持ちさせる方法に挙げられている（Codexの料金と利用上限）。
- 仕組みで止めるものは仕組みに任せる：公式は、AGENTS.mdにpre-commitフック・リンター・型チェックを組み合わせるよう勧めている。AGENTS.mdは「指示」であって、強制する設定ではないからだ。危ない操作は、承認モードとサンドボックスでも止めておく。
GitHubのコードレビュー用のルール
GitHubでCodexにコードレビューをさせる場合、## Code Review Rules という見出しの節を、そのルールが対象とするコードに最も近い AGENTS.md に書く。リポジトリ全体のチェックはルートに、サービスごとのチェックはサブフォルダのファイルに置く。公式は、ルールを短くし、指摘してほしい振る舞いと安全な書き方（例外）を説明し、書式やlintのチェックはCIに任せるよう勧めている（OpenAI「Custom instructions with AGENTS.md」）。
5. いつ書き足すか：公式が挙げる5つのタイミング
同じ失敗が2回起きたら書き足す。これが基本の判断だ。公式は次の5つを挙げている（OpenAI「Customization」）。
| タイミング | 書き足す内容 |
|---|---|
| 同じ間違いを繰り返す | その間違いを防ぐルールを1行足す |
| 正しいファイルにたどり着くが、資料を読みすぎる | どのフォルダ・ファイルを優先するかの道案内を書く |
| プルリクエストで同じ指摘を2回以上した | その指摘をルールにする |
| GitHub上で直したい | プルリクエストのコメントで @codex に「add this to AGENTS.md」と頼み、クラウドで更新させる |
| ずれを定期的に見つけたい | スケジュール実行（毎日など）で、指示の抜けを探して追加案を出させる |
6. 既存のファイル名を使う・上限を変える（config.toml）
すでに TEAM_GUIDE.md のような別名の指示書があるなら、設定ファイルに代替のファイル名として登録すれば、AGENTS.mdと同じように読ませられる。
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536この設定では、各フォルダで AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md の順に探す。一覧にない名前は、指示書としては無視される。project_doc_max_bytes を65536（64KiB）に上げると、打ち切られる前により多くの指示を読める。設定を変えたら、Codexを起動し直す（OpenAI「Custom instructions with AGENTS.md」）。
自動化用のユーザーなど、別のプロファイルを使いたい場合は、環境変数 CODEX_HOME でホームのフォルダを切り替えられる。
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"7. Claude Codeと同じAGENTS.mdを使う方法
Claude Code v2.1.277以降は、CLAUDE.mdがなければAGENTS.mdをそのまま読む。CLAUDE.mdもある場合は、CLAUDE.mdの先頭に @AGENTS.md と書いて取り込むのが確実だ。
Anthropicの公式ドキュメントによると、Claude Codeが読むファイルは次のように決まる（Anthropic「How Claude remembers your project」）。
| リポジトリの状態 | Claude Codeが読むもの（初期設定） |
|---|---|
| AGENTS.mdがあり、作業フォルダとその上にCLAUDE.md・CLAUDE.local.mdがない | AGENTS.md |
| AGENTS.mdとCLAUDE.md（またはCLAUDE.local.md）の両方がある | CLAUDE.mdだけ |
| CLAUDE.mdが @AGENTS.md を取り込んでいる | CLAUDE.md（AGENTS.mdも取り込まれる） |
両方のツールで1つのファイルを使う場合の手順は次のとおり。
- 共通のルールは AGENTS.md に書く。
- Claude Code専用の指示がないなら、CLAUDE.mdは作らない（v2.1.277以降はAGENTS.mdが読まれる）。
- Claude Code専用の指示があるなら、CLAUDE.mdの1行目に
@AGENTS.mdと書き、その下にClaude Code用の指示を足す。 - Claude Codeのセッションで
/context allを実行し、Memory files に読み込まれているかを確かめる。
# CLAUDE.md
@AGENTS.md
## Claude Code
- src/billing/ の変更は plan mode で進める違いに注意：Claude Codeは AGENTS.override.md、AGENTS.local.md、.agents/ フォルダの中身を読まない。Codexで override を使ってフォルダごとのルールを書いている場合、Claude Codeには効かない。また、個人用の CLAUDE.local.md を置くと、それだけでClaude CodeがAGENTS.mdを読まなくなる（設定の Project instructions を claude-md-and-agents-md に変えれば両方読む）。Windowsで作業する人がいる場合は、シンボリックリンクではなく @AGENTS.md の取り込みを使うよう公式は勧めている。
Codex側にも、Claude CodeやCursorの設定を取り込む機能がある。Codex CLIで /import を実行すると、Claude Codeの指示ファイルがAGENTS.mdに、settings.jsonがconfig.tomlに取り込まれる（OpenAI「Import from another agent」）。2つのツールの違いはCodexとClaude Codeの違いで詳しく比べている。
8. 読み込まれないときの対処
まず「どのフォルダで起動したか」「overrideが上の階層にないか」「CODEX_HOMEが変わっていないか」の3つを疑う。公式のトラブルシューティングをもとに整理した（OpenAI「Custom instructions with AGENTS.md」）。
| 症状 | 原因 | 対処 |
|---|---|---|
| 何も読み込まれない | 別のリポジトリで起動している／ファイルが空 | codex status で作業のルートが想定どおりかを確かめる。空のファイルは無視されるので中身を書く |
| 想定と違う指示が効いている | 上の階層かCodexのホームに AGENTS.override.md がある | overrideの名前を変えるか削除して、通常のファイルに戻す |
| 代替のファイル名が無視される | project_doc_fallback_filenames の書き間違い／設定の再読み込み前 | 名前のつづりを確認し、Codexを起動し直す |
| 指示の後半が効かない | 合計が project_doc_max_bytes（初期値32KiB）を超えて打ち切られた | 上限を上げるか、フォルダごとにファイルを分ける |
| 編集したはずの内容が反映されない | 起動中のセッションは古い指示のまま | 対象のフォルダでCodexを起動し直す（手動で消すキャッシュはない） |
| 別のホームの設定が読まれている | CODEX_HOME に既定以外の値が入っている | 起動前に echo $CODEX_HOME で確認する |
| 新しいフォルダでプロジェクトの指示が効かない | フォルダを信頼済みにしていない | 起動時の確認か /permissions でフォルダを信頼する |
どのファイルを読んだかを記録で確かめたい場合は、codex -c log_dir=./.codex-log で起動して ./.codex-log/codex-tui.log を見る方法が公式に案内されている。
9. 欠点・制限事項（わからないこと）
- AGENTS.mdは強制力のある設定ではない。あくまでCodexに渡す指示で、書いたことが必ず守られる保証はない。.envを読ませない、本番に触らせないといった事故防止は、サンドボックス・承認の設定・リンターやフックで止める必要がある。
- Codexについて、推奨の行数は公式に記載がない。公式が示すのは「小さく保つ」と、合計32KiBの上限だけだ（Claude Codeの公式ドキュメントはCLAUDE.mdを200行未満にする目安を示しているが、これはClaude Code向けの記載）。
- サブフォルダは作業フォルダまでしか探さない。ルートで起動すると、下のフォルダにあるAGENTS.mdは起動時には読まれない。フォルダごとのルールを効かせたいなら、そのフォルダで起動するか
--cdで指定する。 - ツール間で読み方が違う。override・ファイルの優先順位・上限の扱いは、CodexとClaude Codeで一致しない。1つのファイルを共有するなら、どちらでも効く書き方（overrideに頼らない）にしておく。
- Codex Cloudやデスクトップアプリでの細かな読み込みの差は、本記事で確認した範囲の公式ドキュメントには、CLIほど詳しい記載がない。
10. よくある質問
AGENTS.mdはどこに置けばいい？
チームで共有するルールはリポジトリのルート（通常はGitのルート）に置く。自分だけの好みは ~/.codex/AGENTS.md に、特定のフォルダだけ違うルールはそのフォルダに置く。Codexは作業フォルダに近いものほど優先する。
AGENTS.mdとAGENTS.override.mdの違いは？
同じフォルダに両方あると、AGENTS.override.mdが優先され、AGENTS.mdは読まれない。元のファイルを消さずに一時的に指示を差し替えたいときに使い、overrideを削除すれば通常のファイルに戻る。
AGENTS.mdはどれくらいの長さまで書ける？
Codexは複数のAGENTS.mdをつないだ合計が32KiB（初期値）に達すると、それ以降を読まない。config.tomlの project_doc_max_bytes で上限を上げられるが、公式は小さく保つことを勧めている。
書き換えた内容はすぐ反映される？
反映されない。Codexは起動時（対話画面ならセッションの開始時）に指示を組み立てるため、編集したら対象のフォルダでCodexを起動し直す。手動で消すキャッシュはない。
Claude CodeでもAGENTS.mdは使える？
使える。Claude Code v2.1.277以降は、CLAUDE.mdとCLAUDE.local.mdがなければAGENTS.mdを読む。CLAUDE.mdもある場合は、CLAUDE.mdに @AGENTS.md と書いて取り込む。ただし、Claude CodeはAGENTS.override.mdを読まない。
CLAUDE.mdをCodexで使い回せる？
Codexの設定ファイル config.toml の project_doc_fallback_filenames に CLAUDE.md を加えれば、代替の指示書として読ませられる。Claude Codeの設定ごと移すなら、Codex CLIの /import で取り込む方法もある。
まとめ
AGENTS.mdは、Codexが作業前に読むプロジェクトの指示書だ。グローバル → ルート → 作業フォルダの順に読まれ、近いものほど優先され、合計32KiBで打ち切られる。書くのは、コマンド・場所・禁止事項・完了の条件のような「確かめられる決まり」だけにして小さく保ち、事故を防ぐ部分はサンドボックスやリンターでも止める。
今すぐできるアクション：
- 今日：よく触るリポジトリのルートに、ビルド・テストのコマンドと「してはいけないこと」だけを書いた短いAGENTS.mdを置き、
codex --ask-for-approval never "Summarize the current instructions."で読み込みを確かめる。 - 今週：Codexが同じ間違いをしたら、その場でAGENTS.mdに1行足すよう頼む。プルリクエストで2回同じ指摘をしたら、Code Review Rules に移す。
- 来月：ファイルの大きさとルールの重複を見直し、長い手順はSkillsに分ける。Claude Codeも使うなら、CLAUDE.mdを @AGENTS.md の取り込みにまとめる。
本記事の内容は、2026年11月7日にOpenAIのCodex公式ドキュメント（Custom instructions with AGENTS.md・Customization・Import from another agent・changelog）とAnthropicのClaude Code公式ドキュメントで確認したもの。CLIの仕様・既定値は更新で変わることがある。最新の情報は本文中のリンク先で確認できる。掲載のコマンドとテンプレートは考え方を示す例であり、実行前に承認モードとサンドボックスの設定を確認してほしい。
関連記事
- Codex CLI使い方完全ガイド｜インストール・Windows・承認モード【2026年】（Codexのまとめ記事）
- Codexの料金と利用上限【2026年11月】プラン別の違いと選び方
- CodexとClaude Codeの違い【2026年】料金と使い分け
- Codexの並列実行（Parallel Agents）とは？
- Codexに作業を任せる依頼文の書き方
- Claude Code完全ガイド【2026年10月】
- Claude CodeのMCP設定方法｜claude mcp addの使い方・スコープ・.mcp.json
出典
- OpenAI「Custom instructions with AGENTS.md」（正規URL：learn.chatgpt.com/docs/agent-configuration/agents-md。2026年11月7日確認：読み込み順、override、32KiB、代替ファイル名、確認コマンド、トラブルシューティング、Code Review Rules）
- OpenAI「Customization」（2026年11月7日確認：AGENTS.mdに書く内容、更新のタイミング、Skills・MCPとの役割分担）
- OpenAI「Import from another agent」（2026年11月7日確認：/import で取り込める項目）
- OpenAI「Codex Pricing」（2026年11月7日確認：利用枠を長持ちさせる方法）
- OpenAI「Codex changelog」（Codex CLI 0.150.0、2026年8月26日：信頼されていないプロジェクトの扱い）
- Anthropic「How Claude remembers your project」（2026年11月7日確認：Claude CodeのAGENTS.md対応、@AGENTS.md の取り込み）
- AGENTS.md 公式サイト／GitHub openai/codex（2026年11月7日確認）
AGENTS.mdと権限設定の「社内標準」づくりを相談できます
チームでCodexやClaude Codeを使うときのAGENTS.mdのひな形、禁止事項と承認モードの設計、運用の見直しまで、ご相談をお受けします。まずは無料でご相談ください。
運営：株式会社LIFRELL
