Codex「AGENTS.md」の場所と書き方｜「CLAUDE.md」との違いと両方使う設定

Q: Codex AGENTS.mdはどこに置けばいいですか？

最初はプロジェクトのルート（通常はGitのルート）に置いてください。 全プロジェクト共通の約束は ~/.codex/AGENTS.md に、フォルダごとの特別なルールは各サブフォルダに置けます。

Q: AGENTS.mdはどのくらいの長さまで読まれますか？

結合サイズが既定の32KiBに達すると、追加が止まります。 長くなるときは、project_doc_max_bytes を上げるか、詳細を別ファイルに分けて、AGENTS.mdは索引にします。

2026年10月9日

当ページのリンクには広告が含まれている場合があります。

Codex AGENTS.mdの場所と書き方｜CLAUDE.mdとの違いと両方使う設定

こんにちは、ハックです。AIを相棒に、プログラミング未経験から今では様々なツールやアプリを開発している一人社長です。

「Codex AGENTS.mdって、どこに置けば読み込まれるの？」

「CLAUDE.mdと何が違うの？両方あると重複しない？」

Codexを使い始めると、Claude Codeで使っているCLAUDE.mdとは別に、AGENTS.mdというファイルが出てきます。

AGENTS.mdはCodexに読ませる指示ファイルで、置き場所は「ホームの ~/.codex」「プロジェクトのルート」「サブフォルダ」の3つです。

CLAUDE.mdとの関係は、CLAUDE.mdに @AGENTS.md と1行書くだけで、重複なしに両方使えます。

この記事では、置き場所と読み込み順、書き方のサンプル、読まれないときの確認方法までまとめます。

ハック（Hack）

最初はCLAUDE.mdとAGENTS.mdの両方にルールを書いて、どっちが最新か分からなくなったんですよね（汗）

今はルールを書く場所を1か所にして、もう片方から読み込ませています。

この形は絶対に取り入れたほうがいいですよ。

駆動愛

AGENTS.mdを正本にして、CLAUDE.mdには @AGENTS.md の1行だけ書くのが、いちばんずれない形です。

🧭 読み終えたとき、あなたはこうなっています

AGENTS.mdとCLAUDE.mdの違いを、1つの表で説明できる
Codexが ~/.codex・プロジェクトのルート・サブフォルダのどれを、どの順に読むか分かる
CLAUDE.mdに @AGENTS.md の1行を書いて、2つのツールで同じルールを使える
コピーして使えるAGENTS.mdのサンプルで、最初の1枚を作れる
読まれないときに、公式の手順で原因を切り分けられる

⚠️ この記事の信頼性について

筆者（ハック）は、プログラミング未経験からAI駆動開発を始め、いまは様々なツールやアプリを開発しています。CodexとClaude Codeを毎日使い、両方に同じルールを読ませる運用をしています。OpenAIとAnthropicの公式ドキュメントの記述に沿って書いています。出典は記事末尾にまとめています。また、各情報は2026年10月時点のものです。

Codex AGENTS.mdとは？CLAUDE.mdとの違い

AGENTS.mdとは

AGENTS.mdは、AIコーディングエージェントに読ませる指示書です。

公式サイト（agents.md）は、これを「コーディングエージェント向けのREADME」と説明しています。60,000以上のオープンソースが採用していると、公式サイトに書かれています。

Codex（OpenAIのAIコーディングエージェント）は、作業を始める前にAGENTS.mdを読みます。

読み込みは起動時に1回で、ターミナルで使うTUI（文字だけの操作画面）では1セッションに1回です。

「このプロジェクトでは npm test を実行して」「ファイルを消す前に確認して」といった、毎回言いたいことを書いておく場所です。

AGENTS.mdとCLAUDE.mdの違い

CLAUDE.mdは、Claude Code（AnthropicのAIコーディングエージェント）が読む指示ファイルです。

役割は同じで、読むツールと、読まれ方のルールが違います。

比べる点	AGENTS.md	CLAUDE.md
読むツール	Codex	Claude Code
他のツールが読めるか	Claude Codeも、CLAUDE.mdが無ければ読める	Codexは読まない
両方あるとき	Codex：AGENTS.mdを読む	Claude Code：CLAUDE.mdだけ読む
取り込み	–	`@AGENTS.md` と書くと中身を読み込める

ここで一つ注意があります。

Claude Codeは、AGENTS.mdとCLAUDE.mdの両方があるとCLAUDE.mdだけを読みます。AGENTS.mdは読まれません。

だから「両方置いておけば、どちらのツールも読んでくれる」とはなりません。次の章以降で、その対処を出します。

CLAUDE.mdそのものの書き方は、以下の記事にまとめています。

Codex AGENTS.mdの場所｜どこに置くと読み込まれるか

Codexは起動すると、決まった場所を順にたどってAGENTS.mdを集め、1つの指示にまとめます。

読み込み順は、次の3段階です。

グローバル（Codexのホーム ~/.codex）
プロジェクトのルートから、いま作業しているフォルダまで
集めたファイルを、ルートから順に空行でつなぐ

プロジェクトのルートに置く

最初の1枚は、プロジェクトのルート（通常はGitのルート）に置くのが基本です。

Codexはルートから現在の作業フォルダまで下りながら、各フォルダで次の順にファイルを探します。

AGENTS.override.md
AGENTS.md
project_doc_fallback_filenames に登録した別名

1つのフォルダで読むのは最大1ファイルです。

ルートが見つからないときは、現在のフォルダだけを見ます。

空のファイルは読まれません。

Codex AGENTS.mdをグローバルに置く（ホーム）

どのプロジェクトでも守ってほしいことは、Codexのホームに置きます。

ホームの既定は ~/.codex で、環境変数 CODEX_HOME で変えられます。

作り方は、ターミナルで次の1行を実行します。

mkdir -p ~/.codex

続けて ~/.codex/AGENTS.md を作り、「Working agreements（作業の約束）」として常に守ることを書きます。

公式の例は、次の3つです。

JavaScriptを変えたら npm test を実行する
依存パッケージは pnpm を優先する
本番の依存を足す前に確認する

この階層は、AGENTS.override.md があればそちらを、無ければ AGENTS.md を使います。最初の空でないファイル1つだけが読まれます。

フォルダごとに複数置いたときの優先順位

サブフォルダにもAGENTS.mdを置けます。

結合はルートから順に行い、現在地に近いファイルほど後ろに来ます。後ろのほうが上書きとして働くので、近いフォルダのルールが優先されます。

たとえば、ルートに全体のルール、docs/ の下に文書専用のルールを置く、という分け方ができます。

サイズには上限があります。

結合した大きさが project_doc_max_bytes（既定は32KiB）に達すると、そこで追加を止めます。

足りないときは、上限を上げるか、下のフォルダへ分けます。

別名のファイルを読ませたいときは、~/.codex/config.toml に次のように書きます。

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Codexの使い方そのものは、以下の記事でまとめています。

CLAUDE.mdとAGENTS.mdを両方使う設定

CodexとClaude Codeの両方を使うなら、ルールを書く場所を1か所にします。

2つのファイルに同じことを書くと、片方だけ更新して食い違います。

CLAUDE.mdから AGENTS.md を読み込む

やり方は単純で、AGENTS.mdを正本にして、CLAUDE.mdの中身を1行にします。

@AGENTS.md

CLAUDE.mdにこの1行を書くと、Claude CodeはCLAUDE.mdを読み、取り込みでAGENTS.mdの中身も読みます。

CodexはAGENTS.mdを直接読みます。

Codexは CLAUDE.md を読まないので、正本をAGENTS.mdに置くわけです。

僕のサイト運営でも、この形にしています。

CLAUDE.mdの中身は @AGENTS.md の1行と、短い注記だけ（225バイト）
ルールはAGENTS.mdにだけ書き、CLAUDE.mdには足さない
Claude CodeはCLAUDE.mdの1行経由で、CodexはAGENTS.mdを直接読む

ルールを書く場所が1か所なので、2つのツールで食い違いません。

正本のAGENTS.md（約7.5KB）に入っているのは、次の項目です。

絶対ルール（言葉遣い）
役割
基本情報
セッション開始の手順
ルールの層（憲法・絶対ルール・正典・実物・手順・記録）
作業ごとの「これを開く」索引表
参照ファイル一覧

判断基準や手順の全文は書かず、索引に徹するのがコツです。

ハック（Hack）

CLAUDE.mdが1行って、最初は「これで足りるの？」と思ったんですが、ちゃんと全部読んでくれてます。

駆動愛

画面の最初に「AGENTS.md loaded」のような行が出れば、取り込みは成功です。出なければ読み込みの確認方法の章へ進んでください。

💡 補足解説：@（アットマーク）での取り込みとは

CLAUDE.mdの中に @ファイル名 と書くと、そのファイルの中身をCLAUDE.mdの一部として読み込みます。

コピーではなく参照なので、AGENTS.mdを直すだけで両方に反映されます。

Claude Codeの設定で、読み方を変えることもできます。

/config の Project instructions で選べます。

値	動き
`claude-md-or-agents-md`（既定）	CLAUDE.mdがあればCLAUDE.md、無ければAGENTS.md
`claude-md-and-agents-md`	両方を読む（CLAUDE.mdが先、AGENTS.mdがあと。取り込み済みなら二重に読まない）
`claude-md`	CLAUDE.mdだけ
`managed-only`	管理者が配った設定だけ

AGENTS.mdを直接読ませるには、Claude Code v2.1.277以降が必要です。セッションによっては読めないことがあり、その場合はCLAUDE.mdから取り込みます。

重複しない置き分けのコツ

置き分けは、次の4つで足ります。

正本はAGENTS.mdにする。Codexは CLAUDE.md を読まないので、こちらに置くと両方が読める
CLAUDE.mdには @AGENTS.md の1行だけ書く。ルールを足さない
Claude Code専用の指示があるときだけ、CLAUDE.mdに足す。足した分はCodexには届かない
CLAUDE.local.md を作ると、AGENTS.mdだけの設定では読まれなくなる。ファイルがあるだけで「CLAUDE.mdがある」扱いになるため

Claude Codeは、AGENTS.local.md・AGENTS.override.md・.agents/ 配下を読みません。

Codex用の AGENTS.override.md を作っても、Claude Codeには届かない点も覚えておくと安心です。

Codex AGENTS.mdの書き方｜サンプルとテンプレート

最初に書く3項目

最初は、次の3項目から書き始めます。

役割・前提：何のプロジェクトか
守ること・禁止：作業の範囲、消さない、承認が要る操作
作業の進め方と、詳細ファイルの索引：どの作業でどのファイルを開くか

長くしないのも大事です。Codexは結合サイズが32KiBに達すると打ち切ります。

判断基準や手順の全文は別ファイルに置き、AGENTS.mdは索引に徹します。

Codex AGENTS.mdのサンプル（コピーして使える）

次の形をそのままコピーして、◯◯を自分のプロジェクトに書き換えてください。

# AGENTS.md

## 役割
このリポジトリは◯◯のブログ（または◯◯アプリ）です。あなたは◯◯を手伝います。

## 守ること
- 依頼した範囲だけ作業する。範囲外は先に一言伝えて止まる
- ファイルを消す・上書きする前に、中身を見て確認する
- 公開・送信・お金に関わる操作は、承認を得てから行う

## 作業の進め方
- 作業を始める前に、`docs/` の該当ファイルを開く
- 変更したら、`npm test` を実行して結果を伝える

## どこに何があるか
| 作業 | 開くファイル |
|---|---|
| 記事を書く | docs/writing.md |
| デプロイ | docs/deploy.md |

「どこに何があるか」の表が、索引の役目です。

詳しい手順は docs/ に書いて、AGENTS.mdからは行き先だけ示します。

Codex AGENTS.mdを読まないときの確認方法

まず、Codexが何を読んでいるかを本人に聞いて確かめます。

プロジェクトのフォルダでターミナルを開き、次を実行します。

codex --ask-for-approval never "Summarize the current instructions."

読み込んだ指示を引用して返してくれるので、書いたはずの内容が入っているか見比べます。

サブフォルダの確認は、次のコマンドです。

codex --cd サブフォルダ --ask-for-approval never "Show which instruction files are active."

ログで確かめたいときは、次の方法です。

codex -c log_dir=./.codex-log

./.codex-log/codex-tui.log に記録が残ります。

それでも読まれないときは、症状ごとに次を見ます。

症状	確認すること
何も読まれない	意図したリポジトリで起動しているか。`codex status` でルートを確認。ファイルが空でないか
違う指示が出る	上の階層やホームに `AGENTS.override.md` が無いか
別名のファイルを無視する	`project_doc_fallback_filenames` の綴り。変更後は再起動
途中で切れる	`project_doc_max_bytes` を上げるか、下のフォルダへ分ける
プロファイルが違う	`echo $CODEX_HOME` で参照先を確認