Codex に何か頼むたびに、「テストを実行してから終わって」「.env は触らないで」と書き添えていないでしょうか。毎回同じことを言っているなら、それは AGENTS.md に書いておく内容です。

AGENTS.md は、AI のコーディングエージェントに向けた説明書のファイルです。形式をまとめているサイト（agents.md）は、これを「エージェント向けの README」と呼んでいます。中身はふつうの Markdown で、必ず書く項目は決まっていません。Codex のほかに、Cursor、Gemini CLI、GitHub Copilot なども、このファイルを読みます。以下は、2026年11月時点の Codex の公式ドキュメントに沿って書いています。

置く場所と、読まれる順番

Codex が読む AGENTS.md は、大きく分けて2種類あります。

一つは、自分用の全体の指示です。Codex のホームフォルダ（標準では ~/.codex）に置いた AGENTS.md は、どのプロジェクトで作業するときも読まれます。「返事は日本語で」のような、自分の好みを書いておく場所です。

もう一つが、プロジェクトの指示です。Codex は、プロジェクトのいちばん上のフォルダ（ふつうは Git のリポジトリのいちばん上）から、いま作業しているフォルダまで、順にたどって AGENTS.md を探します。見つかったものは上のフォルダから順につなげて読み、作業中のフォルダに近いものほど優先されます。リポジトリのいちばん上に全体の決まりを書き、supabase/ フォルダの AGENTS.md にはデータベースの変更のしかただけを書く、という分け方ができます。

同じフォルダに AGENTS.override.md があると、AGENTS.md の代わりにそちらが読まれます。一時的に指示を差し替えたいときの仕組みなので、最初は気にしなくて大丈夫です。

気をつけたいのは、読むのが起動したときの一度だけだという点です。AGENTS.md を書き直したら、Codex を起動し直さないと反映されません。

大きさの上限は32KiB

読み込む AGENTS.md の大きさには上限があって、すべてのファイルを合わせて標準で32KiBまでです。日本語だと、だいたい1万字を少し超えるくらいです。

そこまで書くことはあまりないと思いますが、長く書けばよく守られる、というわけでもありません。公式のドキュメントも、決まりは短く書くよう勧めています。指示が何十行も並ぶと、どれが大事なのかが伝わりにくくなります。最初は少なめに書いて、「書いていなくて困ったこと」が起きるたびに1行ずつ足していくやり方が、結局いちばん長続きします。

書くのは、毎回口で言っていること

agents.md のサイトには、プロジェクトの概要、ビルドとテストのコマンド、コードの書き方、テストの手順、セキュリティの注意を書く例が載っています。エンジニアでない人が作るアプリに置き換えると、書くことは次の5つです。

  1. 何を作っているか。誰が使うのか、今回は作らないものは何か。
  2. 動かし方と確かめ方。開発用のサーバーを起動するコマンドと、テストのコマンド。
  3. 守ってほしい作り方。使うライブラリや、ファイルの置き場所。
  4. 触ってはいけないもの。秘密の鍵、本番のデータ、消すと戻せない操作。
  5. 終わったら報告してほしいこと。変えたファイル、確かめた方法、気になった点。

見落とされがちなのが最後の報告です。何を変えて、どう確かめたかを毎回書いてもらえば、コードが読めなくても、その変更を受け入れてよいかを判断する手がかりになります。

見本：予約サイトの AGENTS.md

保護者が教室の空きを見て予約する、小さな予約サイトを例にしました。Next.js と Supabase で作っている想定です。コマンドや決まりは、自分のアプリに合わせて書き換えてください。

# 予約サイト

## このアプリについて
- 地域の習い事教室の予約サイト。保護者がログインして、空いている枠を予約する。
- 今回は作らない：決済、管理者用の画面、英語対応。

## 動かし方と確かめ方
- 開発用サーバー：npm run dev
- テスト：npm test（変更したら必ず実行し、通ってから終える）
- 書き方のチェック：npm run lint

## 守ってほしいこと
- データベースの変更は、supabase/migrations に SQL のファイルとして足す。管理画面から直接変えない。
- 新しく作る表には、必ず RLS（行単位のアクセス制御）を付ける。保護者が読めるのは、自分の家庭の予約だけ。
- service_role キーと secret key は、ブラウザで動くコードに書かない。

## 触らないもの
- .env と .env.* は読まない。書き換えない。
- 本番のデータベースにつながる操作はしない。
- データを消す SQL は、実行する前に中身を説明して、必ず確認を取る。

## 終わったら
- 変えたファイルと、その理由を短く書く。
- 確かめた方法（実行したコマンドと結果）を書く。
- 気になったが直していない所があれば書く。

「必ず」は、外されると困る3か所にだけ付けました。全部に付けると、どれも同じ強さに見えてしまいます。

書いただけでは守られないこともある

AGENTS.md は Codex への指示で、鍵のかかった設定ではありません。ふだんはよく従いますが、長い作業の途中で忘れたり、ほかの指示と食い違ったときに別の判断をしたりすることはあります。

なので、破られると本当に困ることは、書くだけで済ませず、仕組みのほうでも止めておきます。本番のデータベースの鍵を手元に置かない。作業はブランチを分けて進め、取り込む前に差分を読む。AGENTS.md はふだんの振る舞いをそろえるためのもので、最後の守りは別に用意しておく、という分担です。

Cursor や Claude Code と同じファイルを使う

AGENTS.md は Codex だけのものではありません。Cursor はプロジェクトのいちばん上とサブフォルダの AGENTS.md を読み、サブフォルダのものは親フォルダの内容と合わせて使います。一つのファイルで、Codex と Cursor の両方に同じ決まりを伝えられます。

Claude Code は少し事情が違います。Claude Code が主に読むのは CLAUDE.md です。AGENTS.md を読むのは、作業中のフォルダかその上に CLAUDE.md がないときだけです（2026年11月時点の標準の動き）。両方を置いているなら、CLAUDE.md に次の1行を書いておくと、AGENTS.md の中身も読み込まれます。

@AGENTS.md

Claude Code は AGENTS.override.md を読みません。差し替えの仕組みは Codex のときだけ使う、と決めておくと混乱しません。

目的や権限の決め方といった計画そのものの見直しは、「AIに渡す計画書の見直し方」に書きました。AGENTS.md を書く前に、そちらで中身を固めておくと書きやすくなります。