CodexのAGENTS.mdの書き方とは?置き場所・読み込まれる順番・書く内容と、/initでの作り方、読み込まれないときの対処を解説【2026年11月】
CodexのAGENTS.mdは、作業の前にCodexが必ず読む指示書で、書き方は普通のMarkdownです。自分用は「~/.codex」フォルダ、プロジェクト用は各フォルダに置き、上の階層から順につなげて読まれます。合計は既定で32KiBまでです(2026年11月19日時点)。
CodexのAGENTS.mdとは、OpenAIのAIエージェント「Codex」に、毎回守ってほしい決まりを伝えるためのファイルです。書き方は普通のMarkdownで、決まった項目はありません。
本記事では、AGENTS.mdの置き場所と読み込まれる順番、書く内容と書き方のコツを順に解説します。/initでの作り方や、読み込まれないときの対処もまとめました。
OpenAIの公式ドキュメント(2026年11月19日時点)をもとに、AIエージェントを日々の業務で使っている株式会社Pdien(プディン)がお伝えします。
公開日:2026年11月19日/最終更新日:2026年11月19日
- AGENTS.mdは、Codexが作業の前に読む指示書のファイルです
- 自分用とプロジェクト用があり、上の階層から順に読まれます
- 書き方は自由で、/initで下書きを作ってから直せます
この記事の結論
- AGENTS.mdは、Codexに毎回守ってほしい決まりを書くファイルです。
- 自分用は「~/.codex」、プロジェクト用は各フォルダに置きます。
- 作業中のフォルダに近いファイルほど、後から読まれて優先されます。
- 最初は/initで下書きを作り、自社の決まりに合わせて書き直します。
▲ 置き場所・読み込まれる順番・書く内容・作り方の4つを押さえます
Codexを会社の業務に取り入れたいときは、指示書づくりからご相談を承っています。AI社員(AIエージェント)導入のご相談はこちらからどうぞ。
CodexのAGENTS.mdとは?
AGENTS.mdとは、Codexが仕事を始める前に読む指示書のファイルです。公式ドキュメントでは、どのフォルダを開いても同じ前提で作業を始められるようにする仕組みと説明されています。
▲ 毎回同じ説明をしなくても、決まりを守って作業を始められます
AGENTS.mdは、Codexだけの決まりではありません。公式サイトでは、AIエージェントに向けた共通の形式として案内されています。
- 中身は普通のMarkdownで、必ず書く項目はない
- 人向けのREADMEとは分けて、AI向けの説明を書く
- Codexのほか、Cursor・Gemini CLI・GitHub Copilotなども対応している
- いまはLinux Foundation傘下の団体が管理している
出典: Custom instructions with AGENTS.md(OpenAI公式ドキュメント)、AGENTS.md(公式サイト)(2026年11月19日時点)
Codexそのものの始め方は、Codexの初期設定とは?で解説しています。
AGENTS.mdはどこに置く?
AGENTS.mdは、自分用とプロジェクト用の2か所に置けます。自分用はどのプロジェクトでも読まれ、プロジェクト用はそのフォルダで作業するときに読まれます。
| 置き場所 | 読まれる場面 | 書く内容の例 |
|---|---|---|
| ~/.codex/AGENTS.md | どのプロジェクトでも | 自分の共通の決まり |
| プロジェクトの最上位 | そのプロジェクトで | プロジェクト全体の決まり |
| 下の階層のフォルダ | そのフォルダで作業するとき | その作業だけの決まり |
▲ 自分用、プロジェクト全体、作業中のフォルダの3段で決まりを重ねます
▲ 自分用のフォルダは、設定で別の場所に変えることもできます
自分用のフォルダは、既定では「~/.codex」です。環境変数のCODEX_HOMEを設定すると、別のフォルダに変えられます。
プロジェクトの最上位は、多くの場合Gitで管理しているフォルダの一番上です。最上位が見つからないときは、作業中のフォルダだけが調べられます。
AGENTS.mdはどの順番で読み込まれる?
AGENTS.mdは、自分用から始めて、プロジェクトの最上位から作業中のフォルダへ順に読まれます。読んだファイルは空行をはさんで、1つにつなげられます。
~/.codex のAGENTS.mdを読む
プロジェクトの一番上のAGENTS.mdを読む
作業中のフォルダまで、途中の各フォルダのものを読む
▲ 作業中のフォルダに近いファイルほど後に読まれ、前の決まりより優先されます
作業中のフォルダに近いファイルほど、後に読まれます。そのため、前の決まりと食い違うときは近いほうが優先されます。
公式サイトでは、チャットで直接出した指示が、AGENTS.mdの決まりよりも優先されると案内されています。
読み込みには上限があります。合計が既定で32KiBに達すると、それより先のファイルは足されません。空のファイルは読み飛ばされます。
AGENTS.mdには何を書く?
AGENTS.mdには、新しく入った人に最初に伝えることを書きます。公式サイトでは、よく使われる項目として次のものが挙げられています。
| 項目 | 書く内容の例 |
|---|---|
| 全体の説明 | このプロジェクトが何のためのものか |
| 動かし方と確かめ方 | 作ったものを確かめる手順 |
| 書き方の決まり | 文体や名前の付け方 |
| 確認のしかた | 終わる前に必ず見ること |
| 安全の注意 | 触ってはいけないファイル |
▲ 新しく入った人に伝える内容を、AI向けに短く書きます
このほか、記録の残し方や、作業を人に渡すときの手順も書けます。決まった見出しはないため、自社で分かりやすい見出しを付けます。
プログラム以外の仕事でも考え方は同じです。たとえば資料を作るフォルダなら、文体・表記のゆれ・出す前の確認を書いておくと、毎回の説明が減ります。
自社の仕事に合わせたAGENTS.mdの書き方や、AIに任せる範囲の決め方を一緒に整えられます。
AGENTS.mdの書き方のコツは?
書き方のコツは、短く、具体的に、場所を分けて書くことです。長すぎると上限で読まれない部分が出るため、大事なことから書きます。
▲ 短く具体的に書き、作業ごとの決まりは近いフォルダに分けます
- 1つの決まりは1行で、具体的な動きとして書く
- 「確認して」ではなく、何を見るかまで書く
- 全体の決まりは最上位、作業ごとの決まりは下の階層に分ける
- してはいけないことと、代わりにどうするかを一緒に書く
公式ドキュメントでも、上限に届いたときは下の階層のフォルダに分けることがすすめられています。上限は設定で引き上げることもできます。
パスワードやAPIキーなどの秘密の情報は、AGENTS.mdに書かないようにします。指示書は、AIが毎回読む文章として扱われます。
AGENTS.mdを/initで作るには?
AGENTS.mdは、Codexの /init というコマンドで下書きを作れます。下書きは作業中のフォルダに作られるため、そのあと自社の決まりに合わせて書き直します。
決まりを置きたいフォルダでCodexを開く
入力欄に「/init」と打って送る
できたAGENTS.mdを読み、自社の決まりに書き直す
▲ 下書きはあくまで出発点なので、中身を読んで直してから使います
自分用のAGENTS.mdは、~/.codex のフォルダに自分で作ります。公式ドキュメントでは、よく使う好みや、確認してほしい場面を書く例が紹介されています。
出典: Slash commands in Codex CLI(OpenAI公式ドキュメント)(2026年11月19日時点)
AGENTS.mdが読み込まれたか確かめるには?
確かめるには、Codexに「いまの指示をまとめて」と頼みます。公式ドキュメントでは、読み込んだ決まりを順番どおりに答えると案内されています。
▲ 読み込んだ指示書の一覧をCodexに答えてもらうと確かめられます
- 「いまの指示をまとめて」と頼み、決まりが出てくるか見る
- 下の階層で「読み込んだ指示書を一覧にして」と頼む
- 書き直したあとは、Codexを開き直して読み込み直す
AGENTS.mdは、Codexを起動したときに1回読まれます。書き直した内容を反映するには、作業するフォルダでCodexを開き直します。
一時的に決まりを変えるには?
一時的に決まりを変えたいときは、AGENTS.override.mdというファイルを使います。同じ場所にあると、AGENTS.mdより先に読まれ、元のファイルの代わりになります。
| ファイル | 役割 |
|---|---|
| AGENTS.md | ふだんの決まり |
| AGENTS.override.md | 一時的に置き換える決まり |
▲ 置き換え用のファイルを消すと、ふだんの決まりに戻ります
元のAGENTS.mdを消さずに、決まりを入れ替えられるのが利点です。置き換え用のファイルを消すと、ふだんの決まりに戻ります。
すでに別の名前の指示書がある場合は、設定ファイルにその名前を足すと、指示書として読まれるようになります。
AGENTS.mdが読み込まれないときは?
読み込まれないときは、まず作業中のフォルダと、ファイルの中身が空でないかを確かめます。公式ドキュメントでは、次の順に見直す方法が案内されています。
▲ 上から順に確かめると、原因を絞り込めます
- 開いているフォルダが、思っている場所かを確かめる
- AGENTS.mdの中身が空になっていないかを見る
- 上の階層にAGENTS.override.mdが残っていないかを探す
- 長すぎて上限で切れていないかを確かめる
- 自分用のフォルダの設定が、別の場所を指していないかを見る
古い決まりのまま動くときは、Codexを開き直します。公式ドキュメントでは、起動のたびに読み直すため、消す必要のある保存データはないとされています。
会社でAGENTS.mdを使うときの注意点は?
一番の注意点は、AGENTS.mdに書いたことは毎回の作業に効くということです。書き間違いがあると、その間違いを守り続けます。
▲ 中身を確かめる、秘密を書かない、直す人を決めるの3つを守ります
- 書いた決まりは、人の目で読んで確かめてから使う
- パスワードや取引先の情報など、秘密の情報は書かない
- 誰が直すのかを決め、古い決まりを残さない
Claude Codeも使う会社では、指示書のファイル名が違う点に気をつけます。Claude Code側の書き方は、CLAUDE.mdの書き方とは?で解説しています。
2つのツールの違いは、Claude CodeとCodexの違いでまとめています。
よくある質問(FAQ)
Q. AGENTS.mdはどこに置けばいいですか?
自分用は ~/.codex のフォルダに置きます。プロジェクト用は、プロジェクトの最上位や、決まりを分けたい下の階層のフォルダに置きます。
Q. AGENTS.mdに決まった書き方はありますか?
ありません。普通のMarkdownで、見出しも自由に付けられます。説明・確かめ方・書き方の決まり・安全の注意などを書くのが一般的です。
Q. AGENTS.mdが複数あるときはどれが優先されますか?
作業中のフォルダに近いファイルほど後に読まれ、優先されます。チャットで直接出した指示は、AGENTS.mdよりも優先されます。
Q. AGENTS.mdに長さの上限はありますか?
読み込む合計は、既定で32KiBまでです。上限に届くときは、下の階層のフォルダに分けるか、設定で上限を引き上げます。
Q. AGENTS.mdを書き直したのに反映されないのはなぜですか?
AGENTS.mdは、Codexを起動したときに読まれるためです。作業するフォルダでCodexを開き直すと、読み込み直されます。
Q. AGENTS.mdは自動で作れますか?
Codexの /init で下書きを作れます。できた中身を読み、自社の決まりに合わせて書き直してから使います。
まとめ
CodexのAGENTS.mdは、作業の前にCodexが読む指示書です。置き場所と読み込まれる順番を押さえ、短く具体的に書くのが書き方の基本です。
▲ 置き場所・順番・書く内容・確かめ方の4つで使い始めます
- 置く:自分用は ~/.codex、プロジェクト用は各フォルダ
- 重ねる:作業中のフォルダに近いほど優先される
- 書く:/initで下書きを作り、短く具体的に直す
- 確かめる:「いまの指示をまとめて」と頼んで見る
株式会社Pdienは、愛知県岡崎市の会社です。SNSの運用とAIの使い方の両方を、自社で回せるようになるまで伴走支援しています。会社でのAIの使い方を整える支援は、AI内製化の顧問のページでご紹介しています。
ご相談はお問い合わせフォームから受け付けています。
AGENTS.mdの書き方から、毎日の作業をAIに任せる仕組みづくりまで、自社に合わせた進め方をご相談いただけます。












