3行でいうと

  • AGENTS.md は、Codexが作業の前に読む指示のファイルです。置き場所は3段階で、~/.codex/AGENTS.md(自分用)、リポジトリの根(チーム用)、サブフォルダ(そのフォルダ用)。根から作業フォルダへ順に連結され、作業フォルダに近いものが後ろに来て優先されます。合計の上限は既定で32 KiBです。
  • メモリ(Memories)は、既定でオフの実験的な機能です。公式は、メモリは思い出すための補助の層で、必ず適用したい規則の唯一の置き場にしてはいけない、チームに必要な指針は AGENTS.md かリポジトリの文書に書くように、と書いています。
  • プロジェクトごとの設定(.codex/config.toml、フック、ルール)は、そのプロジェクトを「信頼」したときだけ読まれます。メモリはリポジトリの外、~/.codex/memories/ に置かれます。
  • 作り始めるなら、Gitのフォルダで codex を起動し、/init で雛形を作らせ、短く削って、公式の確認コマンドで読まれているかを確かめます。公式は「短く正確なファイル」を勧め、同じ間違いが繰り返されたときに足す、という育て方を書いています。

この記事は、公式ドキュメントを2026年10月24日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。運営者はCodexを入れていますが、使い心地はこの記事には書いていません。コマンド、設定名、ファイルの例は、公式の記載を写したもの(または公式の記載に合わせてこの記事で組んだ例で、そのつど断ります)で、動作確認はしていません。公式の文章は要約の形で取得したため、長い引用はせず、ほとんど言い換えています。画面の名前や構成は更新で変わることがあります。

先に結論

前提:用語をそろえる

全体像:どこに何を置くか

公式の「Customization」のページは、Codexを自分たちの流儀に合わせる層として、AGENTS.md、メモリ、スキル、MCP、サブエージェントの5つを挙げています(プラグインはスキルを配る単位として出てきます)。次の表は、そのページの文章を僕らが整理したもので、「フックと設定」の行は公式のページにはなく、僕らが足したものです。この記事で扱うのは、上の2つと、置き場所(設定)です。スキルやMCP、フックは前のガイド(04)に書きました。

層 公式のページの趣旨(僕らの言い換え) この記事での扱い
AGENTS.md 作業の前に読み込まれる、続けて効かせたい案内 本論の中心
メモリ 過去の作業から学んだ有用な文脈 本論の2つめ
スキル 繰り返せる手順、専門知識、補助のスクリプト 04に書いた
MCP 作業フォルダの外の道具や共有の仕組みへの入口 04に書いた
サブエージェント 絞った仕事を別のエージェントに任せる 触れない
プラグイン スキルやコネクタをまとめて配るもの 04に書いた
フックと設定(公式の層の一覧にはない) 強制と設定の置き場所(僕らが足した行) 置き場所だけ扱う

公式が書いている「おすすめの順番」は、1番目がAGENTS.md(あわせてプリコミットのフックやリンターで守らせる)、2番目がプラグインかスキル、3番目がMCP、4番目がサブエージェントです。指示ファイルから始めるのが公式の流れ、ということです。

AGENTS.mdの読まれ方:階層と優先順位

公式の「Custom instructions with AGENTS.md」の内容を整理します(確認日10月24日。ページに日付の記載はありませんでした)。前のガイド(01、04)に書いた内容と重なる部分は短くし、今回は「どう組み合わさるか」に踏み込みます。

探す場所と、連結の順番

Codexは、実行のたびに(TUIでは1セッションにつき1回)、指示の連なりを作ります。

  1. 自分用(グローバル)。 Codexのホーム(既定 ~/.codex)で、AGENTS.override.md があればそれ、なければ AGENTS.md。この段では、最初の空でない1つだけが使われます。
  2. プロジェクト用。 プロジェクトの根(ふつうはGitの根)から、いま作業しているフォルダまで降りながら、各フォルダで AGENTS.override.md、AGENTS.md、project_doc_fallback_filenames に書いた名前、の順に調べます。1フォルダにつき多くて1つです。根が見つからないときは、いまのフォルダだけを調べます。
  3. 連結。 根に近いほうから作業フォルダに近いほうへ、空行でつないで並べます。作業フォルダに近い案内は後ろに来るので、前の案内を上書きするように働く、と公式は書いています。

空のファイルは飛ばされます。連結した合計が project_doc_max_bytes(既定32 KiB)に達すると、そこで読み込みが止まります。

具体例で見る(僕らの例)

次の図は、公式のページにある説明を、僕らが作った架空のリポジトリに当てはめたものです。公式の例そのものではなく、動作確認もしていません。

~/.codex/AGENTS.md                 自分用: 返事は簡潔に、など
my-repo/AGENTS.md                  チーム用: テストの動かし方、禁止事項
my-repo/services/payments/AGENTS.override.md   決済のフォルダ用
my-repo/services/payments/AGENTS.md            ← 同じフォルダにoverrideがあるので読まれない

my-repo/services/payments で作業を始めたとき、Codexが読むのは、①~/.codex/AGENTS.md、②my-repo/AGENTS.md、③my-repo/services/payments/AGENTS.override.md の3つで、この順に並びます。決済のフォルダの AGENTS.md は、公式の説明どおりなら、overrideがあるために読まれません。「AGENTS.override.md は、元のファイルを消さずに、そのフォルダだけ別のルールにする」ための仕組み、という読みですが、これは僕らの読みです。

公式の例の中身は次のとおりです(services/payments/AGENTS.override.md。公式の記載の写しで、動作確認はしていません)。

# services/payments/AGENTS.override.md

## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

公式の例では、決済のサービスのフォルダに別のテストコマンドを書き、APIキーを入れ替える前にセキュリティ用のチャンネルへ知らせる、という決まりを書いています。「テストの動かし方が違う」「触るときに手続きが要る」といった、そこだけの事情を書く場所だ、と読めます。

ファイル名の探し順

順 調べる名前 公式の補足
1 AGENTS.override.md あれば、同じフォルダの AGENTS.md は無視される
2 AGENTS.md 標準の名前
3 project_doc_fallback_filenames に書いた名前 例は TEAM_GUIDE.md と .agents.md。リストにない名前は無視される

別名を使うときの公式の例は、~/.codex/config.toml に次のように書き、Codexを再起動(または新しいコマンドで起動)する、というものです。値の65536(バイト)は、上限を上げる例として公式が載せています。

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

「プロジェクトの根」はどう決まるか

公式の「Advanced Configuration」によると、Codexは作業フォルダから親へたどって、既定では .git のあるフォルダを根とみなします。変えたいときは、次のように書きます(公式の例)。

project_root_markers = [".git", ".hg", ".sl"]

project_root_markers = [] にすると、親フォルダをたどらず、いまの作業フォルダが根になる、と書かれています。Gitを使っていないフォルダでAGENTS.mdが期待どおりに重ならないときは、ここを疑う材料になります(僕らの見立てです)。

「優先順位」は3か所で出てきて、別のもの
  • AGENTS.mdの後勝ち。 連結の順で、作業フォルダに近いものが後ろに来ます。指示の「文章」が重なるときの話です。
  • 設定ファイルの近い勝ち。 .codex/config.toml は、根から作業フォルダまでのものがすべて読まれ、同じキーがあれば一番近いものが勝ちます(公式のAdvanced Configuration)。設定の「値」の話で、公式の優先順位は7段(コマンドラインの旗が最強、組み込みの既定が最弱)です。
  • 会話の中の依頼。 AGENTS.mdの形式を紹介するサイト(agents.md)のよくある質問には、一番近いAGENTS.mdが勝ち、チャットでの明示的な依頼はすべてに優先する、とあります。ただし、これはCodexの公式ドキュメントではなく、形式の紹介サイトの記述です。Codexのドキュメントでこの点が明記されているかは、読んだ範囲では見つかりませんでした。
  • 「指示が衝突したときにどちらが守られるか」の保証は、どのページにも書かれていません。AGENTS.mdは「読ませる」ものです。止めたいコマンドがあるなら、サンドボックス、承認、ルールの出番です(02)。

上限と、読み込みが「切れる」こと

合計が32 KiBに達すると読み込みが止まる、と公式は書いています。大きなモノレポでは、根のAGENTS.mdに全部を書かず、フォルダごとに分けるのが公式の勧めです(上限を上げる方法もあります)。なお、設定のリファレンスと「Advanced Configuration」は、この上限を「AGENTS.mdから読むバイト数」「各AGENTS.mdファイルで読む量」と書いていて、「合計」と書くAGENTS.mdのページと表現が違います。僕らが読んだのは要約なので、どちらが正確かは判断できませんでした。迷うときは、合計で考えて小さく保つのが安全、というのが僕らの見立てです。

何を書くか:公式の助言

公式の「Best practices」と「Customization」は、次のように書いています。

次は、公式の助言(コマンド、約束、やってはいけないこと)に合わせて、僕らが組んだ小さなリポジトリ用のAGENTS.mdの例です(公式の例ではなく、動作確認もしていません)。

# AGENTS.md

## Commands
- Install: `pnpm install`
- Test: `pnpm test --filter changed`

## Conventions
- Use named exports in `src/components/`.
- Never edit generated files in `src/gen/`.

「Never edit generated files」のような禁止の一文は、書いておけばCodexは参考にします。ただし、この文を書いたからといって「必ず守る」と公式が保証しているわけではありません(読んだ範囲では、そう書かれたページは見つかりませんでした)。本当に触らせたくないものは、設定のサンドボックスや承認で守る、と考えるのが無難です。

GitHubのコードレビュー用の節

公式は、GitHubでのコードレビュー用の案内を、AGENTS.mdの ## Code Review Rules という見出しの節に書くよう説明しています。置き場所は、対象のコードにいちばん近いAGENTS.mdで、リポジトリ全体の確認事項なら根です。公式の例は、実験の群の比較を「曝露の後の行動(コンバージョンや継続)で絞り込んでいたら指摘する」という内容でした。書き方の助言は、指摘したい挙動と安全な代わりの道を書く、書式やリンターのチェックはCIに任せる、というものです。この機能の使い方は、前のガイド(04)にあります。

最初の10分でAGENTS.mdを作る

ここは、公式に書かれている手順を並べた「僕らの整理」です。時間の目安は僕らが付けたもので、公式の数字ではありません。コマンドの動作は確認していません。

0分:練習の場所を決める。 Gitで管理している、小さなリポジトリを1つ選びます。Gitのフォルダなら、変更を元に戻しやすいからです(僕らの見立てです。承認とサンドボックスの面でのGitフォルダの扱いは、前のガイド01、02に書きました)。

1分:Codexを起動する。 プロジェクトのフォルダで codex を実行します(入れ方とログインは01)。

2分:雛形を作らせる。 セッションの中で /init を打ちます。公式のコマンド一覧には「いまのフォルダにAGENTS.mdの雛形を作る」と書かれています。公式の「Best practices」は、できた雛形を自分のチームの作り方、テスト、レビュー、リリースに合わせて直すよう書いています。/init が中身をどう決めるのか、詳しい挙動は、読んだ範囲では見つかりませんでした。

3〜6分:読んで、削って、足す。 できた雛形を開いて、次の3つだけに絞る、というのが僕らの勧めです。

  1. コマンド。 インストール、テスト、リンターの正しいコマンド。
  2. やらないこと。 触ってはいけないフォルダ、勝手に足してはいけないもの。
  3. 終わりの条件。 たとえば「テストが通ったら終わり」。

公式の助言どおり、最初から長く書かないことが大事です。1行ごとに「これがないと、Codexは間違えるか」と自分に聞いて、答えがいいえなら消します(僕らの見立てです)。

7分:読まれているか確かめる。 リポジトリの根から、公式の確認用の例を実行します。

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

Codexが、さっき書いた内容を要約できれば、読まれています。--ask-for-approval never は、承認の確認を出さない設定です。公式の例を写しましたが、意味は前のガイド(02)で確かめてから使ってください。

8〜9分:入れ子の確認(サブフォルダにも書いた場合)。 公式の例は次のとおりです。

codex --cd subdir --ask-for-approval never "Show which instruction files are active."

「どの指示ファイルが有効か」を聞く例です。ここで、根のファイルとサブフォルダのファイルの両方が出てくれば、連結は期待どおりです。

公式には、決済のフォルダを例にした確認コマンドもあります。

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

公式が書いている期待の順は、先に自分用のファイル、次にリポジトリの根の AGENTS.md、最後に決済のフォルダの AGENTS.override.md です。この順で並べば、「後ろほど作業フォルダに近い」という連結の順が目で確かめられます。順が違う、または決済のフォルダのファイルが出てこないときは、下の「うまく読まれないとき」の表を見てください。

10分:保存する。 作ったAGENTS.mdをGitに入れます(チームで共有するなら)。その後、同じ間違いが続いたら、公式の助言どおり、Codexに振り返りを頼んでAGENTS.mdを直します。

自分用のAGENTS.mdは、~/.codex/AGENTS.md に作ります。公式の例は、JavaScriptを変えたらテストを動かす、パッケージ管理は pnpm を使う、本番用の依存を足す前に聞く、という個人的な約束でした。リポジトリのファイルに「僕の好み」を入れるより、自分用のファイルに分けたほうが、チームに迷惑がかかりません(見立てです)。一時的に自分用の指示を差し替えたいときは ~/.codex/AGENTS.override.md を置き、元に戻すときはそのファイルを消す、と公式にあります。

うまく読まれないとき(公式のトラブルシュート)

症状 公式が挙げる確認
何も読み込まれない 作業しているフォルダを確かめる。codex status で見る(公式の表記。CLIの中の /status と同じものかは確認できていません)。ファイルが空でないか確かめる
違う案内が効いている 上の階層、またはホームの AGENTS.override.md がないか探す
別名のファイルが読まれない config.toml の綴りを確かめ、Codexを再起動する
途中で切れる project_doc_max_bytes を上げるか、フォルダごとにファイルを分ける
別のプロファイルを見ている CODEX_HOME の値を確かめる

古い指示が残っているように見えたら、そのフォルダでCodexを再起動します。消すキャッシュはない、と書かれています。読み込みの記録を見たいときは、設定の log_dir で平文のログ(codex-tui.log)を有効にするか、最新の session-*.jsonl を見る、という方法が書かれています。

メモリ:思い出す助けであって、唯一の置き場ではない

公式の「Memories」のページを整理します(確認日10月24日。ページに日付の記載はありませんでした)。

まず押さえる3点

どこに置かれ、どう作られるか

項目 公式の記載
保存場所 ~/.codex/memories/(要約、長く残る項目、最近の入力、過去の会話から集めた裏づけ)。ホームは CODEX_HOME で変わる
作られ方 有効にすると、条件に合う過去の会話から、役立つ文脈をローカルのファイルに変える
動くタイミング 背景で動く。会話が止まるのを待ってから要約するので、すぐには反映されない
飛ばされるもの 動いている会話、短い会話。レート制限の残りが、設定した割合を下回ると、背景の処理は飛ばされる
秘密情報 生成されるメモリの項目からは、秘密が伏せられる。それでも「秘密を入れないこと」と公式は書いている

これらのファイルは「生成された状態」で、調べるために見るのはよいが、手で直すことを主な操作にしないよう、公式は書いています。

有効にする

公式が書いている入口は2つです。

  1. ChatGPTデスクトップアプリの「Settings > Personalization」で「Enable Codex memories」をオンにする。
  2. 設定ファイルに、機能フラグを書く。
[features]
memories = true

Config basicsには、CLIの旗として codex --enable memories も載っています。

会話ごとの操作と、全体の設定

設定のキー

設定ファイルでは、memories の表にキーが並びます。公式の設定リファレンスに載っている主なものです(記載された既定値。更新で変わることがあります)。

キー 既定 公式の説明の要点
memories.generate_memories true falseだと、新しい会話をメモリの材料にしない
memories.use_memories true falseだと、既存のメモリを新しい会話に入れない
memories.disable_on_external_context false MCP、検索、ツール検索を使った会話を材料から外す。古い別名 memories.no_memories_if_mcp_or_web_search も受け付ける
memories.min_rate_limit_remaining_percent 25 生成を始めるのに必要な、レート制限の残りの割合(0〜100)
memories.min_rollout_idle_hours 6 会話が止まってから、対象になるまでの最短の時間(1〜48)
memories.max_rollout_age_days 30 材料にする会話の最大の古さ(0〜90日)
memories.max_unused_days 30 使われないまま、まとめの対象から外れるまでの日数(0〜365)
memories.extract_model、memories.consolidation_model 記載なし 個々の会話からの抽出と、全体のまとめに使うモデルの上書き

この表には、ほかに回数の上限のキーもありますが省きました。features.memories が false のままなら、これらの設定は意味を持ちません(機能そのものがオフだからです。これは僕らの読みです)。「外部の情報に触れた会話を材料から外したい」ときの設定例を、キー名だけ公式から借りて組むと次のようになります。値は僕らが置いた例で、公式の推奨ではありません。

[features]
memories = true

[memories]
disable_on_external_context = true

AGENTS.mdとメモリの使い分け

観点 AGENTS.md メモリ
公式の位置づけ 作業の前に読み込まれる、続けて効かせたい案内 過去の作業から学んだ文脈
置き場所 ~/.codex/AGENTS.md、リポジトリ内 ~/.codex/memories/(自分のマシンの中)
チームで共有 リポジトリに入れれば共有できる 共有の仕組みは読んだ範囲では見つからなかった
中身を自分で決められるか 書いたとおり 自動で生成される。手での編集は主な操作にしない
既定 ファイルがあれば読まれる オフ
公式の使い分けの助言 必ず適用したい、明示して見直せる指示 過去のセッションからの、ローカルの文脈

僕らの見立てです。レビューできる形でチームに配りたいものは、メモリではなくAGENTS.mdに置くのがよさそうです。公式がメモリを規則の唯一の置き場にしないよう書き、「秘密を入れない」と注意しているのも、同じ方向です。

プロジェクトごとの設定の置き場所

ここまでは「指示」の話でした。次は「設定」と、守らせる仕組みの置き場所です。

置き場所の一覧

何を置くか 場所(公式の記載) 「信頼」が要るか
自分用の設定 ~/.codex/config.toml 要らない
プロジェクトの設定 <リポジトリ>/.codex/config.toml(根から作業フォルダまで、各階層のものが読まれる) 要る
用途別の設定 ~/.codex/<名前>.config.toml(--profile <名前> で選ぶ) 要らない
システム全体の設定 /etc/codex/config.toml(Unix) 要らない
フック ~/.codex/hooks.json、~/.codex/config.toml、<リポジトリ>/.codex/hooks.json、<リポジトリ>/.codex/config.toml プロジェクトのものは要る
ルール ~/.codex/rules/ と <リポジトリ>/.codex/rules/ の .rules ファイル プロジェクトのものは要る
スキル 自分用は ~/.agents/skills、リポジトリは .agents/skills(Customizationの表より) 読んだ範囲では記載なし
AGENTS.md 上の「読まれ方」の節のとおり 読んだ範囲では記載なし
メモリ ~/.codex/memories/ リポジトリの外なので該当しない

AGENTS.mdとスキルの「信頼」の扱いは、読んだページには書かれていませんでした。「信頼していないプロジェクトで何が読まれるか」を知りたい場合は、公式で確かめてください。

設定の優先順位と、プロジェクトの信頼

公式の「Config basics」の優先順位は、強い順に、①コマンドラインの旗と --config の上書き、②プロジェクトの設定(信頼したプロジェクトのみ)、③プロファイル、④自分用の ~/.codex/config.toml、⑤クラウドから配られる管理用の既定(サインインしたワークスペース向けに配られるとき)、⑥システムの設定、⑦組み込みの既定、の7段です。1回だけ変えたいときは、codex -c log_dir=./.codex-log のように -c を使います。

信頼していないプロジェクトでは、Codexは、プロジェクトの設定、フック、ルールを読み飛ばします。自分用とシステムの設定は読まれます。信頼の記録は [projects."<絶対パス>"] の trust_level("trusted" か "untrusted")で、設定のリファレンスに載っています。

プロジェクトの設定では効かないキー。 公式は、プロジェクトの設定の中にある一部のキーを無視し、起動時に警告を出すと書いています(理由は読んだ範囲では書かれていません。認証の送り先などを勝手に書き換えさせないための仕組みだろう、というのは僕らの見立てです)。openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url、otel です。これらは ~/.codex/config.toml に書き、プロファイルは --profile で選びます。

プロジェクトの設定の中の相対パスは、その設定ファイルが入っている .codex/ フォルダを基準に読まれる、とも書かれています。

ルール:コマンドの扱いを、ファイルで決める

ルールは、Codexがサンドボックスの外でコマンドを動かしたいときの扱いを決めるファイルです。公式のページは「実験的で、変わることがある」と明記しています。次は、公式の例を短くしたものです(動作確認はしていません)。

prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "Viewing PRs is allowed with approval",
)

公式の例には、ルールを読み込むときにCodexが検査する例(match と not_match)も書かれています。match には、そのルールに当てはまるべきコマンド(公式の例は gh pr view 7888)、not_match には、当てはまってはいけないコマンド(公式の例は gh pr --repo openai/codex view 7888。パターンは先頭からの一致でなければならないため)を書きます。どちらも省略できます。

prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "Viewing PRs is allowed with approval",
    match = ["gh pr view 7888"],
    not_match = ["gh pr --repo openai/codex view 7888"],
)

上は、公式の説明に合わせて僕らが match と not_match を書き足した形です(公式のコードそのものではなく、動作確認もしていません)。落とし穴として、decision を省略すると既定は allow(聞かずに外で動かす)になる、と公式は書いています。慎重に始めたいなら、decision を毎回はっきり書くのが無難です(僕らの見立てです)。

.rules ファイルは、Starlarkという書き方です。decision は allow(聞かずに外で動かす)、prompt(毎回聞く)、forbidden(聞かずに止める)のどれかで、複数が当てはまったら、いちばん厳しいものが採用されると書かれています。codex execpolicy check で、ルールの判定を確かめる例もあります。ルールの考え方は前のガイド(02)に書きました。置き場所は、~/.codex/rules/default.rules、プロジェクトなら <リポジトリ>/.codex/rules/ です。公式は、TUIで「聞かずに許可」を選ぶと、~/.codex/rules/default.rules に書き込まれる、とも説明しています。

「AGENTS.mdにはこう書いてあるのに、ルールでは許可されている」といった食い違いが起きたときにどちらが優先されるかは、読んだページには書かれていませんでした。

置き分けの早見(僕らの整理)

ここからは、公式の記載を読んだうえでの僕らの整理で、見立てです。

書きたいこと 置く場所の候補 理由
テストの動かし方、フォルダの決まり リポジトリの AGENTS.md チームで共有され、レビューできる
返事の長さ、レビューの好み ~/.codex/AGENTS.md 自分だけに効かせる(公式もこの分け方)
決済のフォルダだけ別の決まり そのフォルダの AGENTS.override.md または AGENTS.md 近いほうが後ろに来て優先される
使うモデル、承認、サンドボックス ~/.codex/config.toml、チームの既定は .codex/config.toml 値は設定、案内は指示、と分ける
「このコマンドは絶対に聞いて」 ルール、承認、サンドボックス 文章のお願いよりも、仕組みのほうが確実(02)
繰り返す手順 スキル 公式が、同じプロンプトの使い回しはスキルに、と書いている(04)
「この前の続き」の文脈 メモリ(使うなら) 規則の唯一の置き場にはしない

気をつけること

出典