Codex AGENTS.mdとは？書き方・置き場所・読み込まれる順番を解説

「Codexに頼むたびに、テストの動かし方や守ってほしい書き方を毎回打ち込んでいる」「AGENTS.mdというファイルがあると聞いたが、何を書けばいいのか分からない」と感じている方は多いのではないでしょうか。

AGENTS.md（エージェンツ エムディー）は、Codexが作業を始める前に読む「引き継ぎメモ」のようなファイルです。ここに書いたルールは、会話のたびに言い直さなくても、毎回Codexに伝わります。人に仕事を頼むときに、新しく入った人へ「この会社ではこう進める」と渡す資料に近いものです。

この記事では、AGENTS.mdとは何か、どこに置くとどの順番で読まれるのか、作り方、書く内容、GitHubのレビューでの使い方、効かないときの確認方法までを順に解説します。内容は2026年10月時点のOpenAI公式ドキュメントをもとにしています。仕様は変わることがあるので、設定の前には公式ページもあわせて確認してください。

AGENTS.mdとは

AGENTS.mdは、Codexに「このプロジェクトでは、こう作業してほしい」と伝えるための、文字だけのファイルです。拡張子の「.md」はMarkdown（マークダウン）という書き方で、見出しや箇条書きをふつうの文字で書けます。メモ帳でも編集できます。

公式ドキュメントでは、Codexは作業を始める前にAGENTS.mdを読むと説明されています。ファイルはプロジェクトのフォルダに置くので、チームで共有でき、誰がCodexを使っても同じ前提で作業が始まります。

何を書くファイルか

公式のCustomizationのページでは、AGENTS.mdには「毎回守ってほしいルール」を書くとされています。例として、次の4つが挙がっています。

• ビルド（できあがりの形に組み立てる作業）やテストのコマンド
• レビューで見てほしい点
• そのリポジトリ（プロジェクトの保管場所）固有の決まりごと
• フォルダごとの指示

たとえば「作業が終わったら、必ずテストを動かして結果を報告する」「新しい部品（ライブラリ）を足すときは、先に確認する」といった内容です。公式の書き方のページでは、AGENTS.mdをエージェント向けのREADMEのようなものと表現しています。

README・スキル・プロンプトとの違い

似た役割のものがいくつかあるので、違いを整理します。

AGENTS.mdの公式サイトでは、READMEは人のためのもので、AGENTS.mdはエージェントが必要とする細かい情報（ビルドの手順、テスト、書き方の決まり）を置く場所だと説明されています。READMEに書くと人には長すぎる内容を、AGENTS.mdに分けておく考え方です。

公式のベストプラクティスでは、毎回守ってほしいことをプロンプトに書き続けるのは、よくある失敗の1つとされています。何度も同じことを頼んでいるなら、AGENTS.mdかスキルに移す合図です。スキルとの使い分けは、別の記事「Codex Skillsとは」で詳しく解説しています。

どの場面で読まれるか

AGENTS.mdは、Codexをどの形で使っていても働きます。公式ドキュメントで確認できた範囲では、次のとおりです。

IDE拡張機能での細かい動きは、今回確認した公式ページには詳しく書かれていないため、この記事では触れていません。

置き場所・読み込まれる順番

AGENTS.mdは、置く場所によって効く範囲が変わります。置き場所と読み込まれる順番は、公式ドキュメントで次のように決まっています。

3つの場所・探し方

Codexは、起動したときに「どのファイルを読むか」の順番表を作ります。作るのは、1回の起動につき1回です。探す場所は大きく2つに分かれます。

全体用の場所は、環境変数CODEX_HOMEを設定すると変えられます。仕事用と個人用で設定を分けたいときなどに使います。

読み込まれる順番と、後ろが優先される理由

公式ドキュメントの説明を、順に並べると次のとおりです。

1. 全体用を1つ読むホームフォルダで、AGENTS.override.mdがあればそれを、なければAGENTS.mdを読みます。このレベルでは、最初に見つかった中身のあるファイル1つだけを使います。
2. プロジェクトのいちばん上から、いま作業しているフォルダまで下りる通常はGitのルートから、Codexを起動したフォルダまでたどります。プロジェクトのいちばん上が見つからないときは、いまのフォルダだけを見ます。
3. 各フォルダで、決まった順に探して1つだけ使うフォルダごとに、AGENTS.override.md、AGENTS.md、設定で追加した別名の順に探し、最初に見つかったものを使います。1つのフォルダから読むのは、最大で1ファイルです。
4. 上から順につなげる見つかったファイルを、ルートに近い方から順に空行でつなぎます。

つなぐときの順番が大事です。作業しているフォルダに近いファイルほど、あとに置かれます。そのため、全体用とプロジェクト用で言っていることが食い違うときは、近い方の指示が優先されます。公式のベストプラクティスでも「より具体的なファイルが近くにあれば、そちらの指示が勝つ」と書かれています。

公式の例で見る、読み込まれ方

公式ドキュメントには、次のような構成の例が載っています。「services/payments」というフォルダだけ、別のルールにしたい場合です。

公式の手順どおり、services/paymentsの中でCodexを起動して「読み込んだ指示の出どころを教えて」と頼むと、全体用、ルートのAGENTS.md、決済用のoverrideの順に報告されるとされています。

読み込まれる量の上限

読み込むファイルの合計には上限があります。公式ドキュメントでは、空のファイルは飛ばされ、合計がproject_doc_max_bytesの上限に達するとそれ以上は追加されないと説明されています。初期値は32 KiB（日本語の文章なら、おおまかに1万字前後）です。

なお、公式の別のページ（詳細設定）では、この数字が「AGENTS.mdのファイルごとに読む量」と書かれており、ページによって説明が一致していません。どちらの場合でも、1つのファイルを短く保つ方針は変わりません。

上限に当たったときは、上限の数字を上げるか、指示をフォルダごとに分けるのが公式の案内です。ただ、そもそも長いファイルは守られにくくなります。上限を上げる前に、書く量を減らせないかを考える方が先です（書き方は後の章で説明します）。

プロジェクトのルートはどう決まるか

プロジェクトのいちばん上は、初期設定では.gitがあるフォルダです。公式の設定リファレンスでは、config.tomlのproject_root_markersで、この目印を変えられると説明されています。

# ~/.codex/config.toml
project_root_markers = [".git", ".hg", ".sl"]

これは公式のドキュメントにある例です。project_root_markers = []にすると、親のフォルダはたどらず、いまのフォルダをルートとして扱います。Gitを使っていないフォルダ（事務の資料置き場など）で使うときは、この点を知っておくと役立ちます。

AGENTS.mdの作り方

作り方は2通りあります。Codexに雛形を作らせる方法と、自分で書く方法です。どちらでも、できあがるのは同じ文字のファイルです。

「/init」で雛形を作る

CLIとデスクトップアプリでは、「/init」というコマンドで雛形を作れます。公式ドキュメントの手順は次のとおりです。

1. 作りたい場所でCodexを開くCodexに指示を読ませたいフォルダ（通常はプロジェクトのルート）で起動します。
2. 「/init」と入力するCodexが、そのフォルダにAGENTS.mdの雛形を作ります。
3. 中身を読んで、自分たちのやり方に直す公式でも「雛形をそのまま使わず、実際のビルド・テスト・レビューのやり方に合わせて直す」よう勧められています。
4. コミットして共有するリポジトリに含めておけば、次の作業からチーム全員のCodexに効きます。

全体用を手で作る

自分用の約束を書く全体用のファイルは、ホームフォルダの.codexの中に作ります。公式の手順では、次のように「Working agreements（作業の約束）」を書く例が紹介されています。

# ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

意味は、「JavaScriptのファイルを変えたら、必ずテストを動かす」「部品を入れるときは、pnpmを優先する」「本番で使う新しい部品を足す前に、確認する」です。公式のベストプラクティスでは、全体用のファイルは「Codexとのやりとりの好み（レビューの流儀、説明の細かさなど）」に使い、チームやコードの決まりはプロジェクト側に書くよう勧められています。

プロジェクト用と、フォルダ用を作る

プロジェクトのルートには、チームで共有する決まりごとを書きます。公式の例は次のとおりです。

# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

「プルリクエストを出す前に、lintを動かす」「挙動を変えたら、docsに書く」という内容です。さらに、特定のフォルダだけ違うルールにしたいときは、そのフォルダにoverrideを置きます。

# 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.

「決済サービスでは、npm testではなくmake test-payments を使う」「セキュリティ担当に知らせずにAPIキーを更新しない」という意味です。フォルダごとにテストの動かし方が違う場合や、扱いが慎重なフォルダがある場合に役立ちます。

読まれているかを確かめる

作ったあとは、Codexが実際に読んでいるかを確認しましょう。公式ドキュメントでは、次のコマンドが紹介されています。

最初の2つは、Codexに「いまの指示を要約して」「読み込んだ指示の出どころを挙げて」と頼むコマンドです（--ask-for-approval neverは、途中で承認を求めずに動かす指定です）。公式では、結果にAGENTS.mdの項目が引用されれば読み込まれていると説明されています。ふだん使っている画面の中で、同じ内容を日本語で頼んでも確かめられます。

書き換えたあとは、Codexを開き直して確認してください。公式によれば、指示の順番表は起動のたびに作り直され、手動で消すキャッシュはありません。つまり、変更を反映するには新しく起動すればよい、ということです。

何を書くか

空のAGENTS.mdを前にすると、何を書くか迷います。公式のベストプラクティスでは、「よいAGENTS.mdに入っているもの」として次の6つが挙げられています。

書くとよい6つの内容

公式は、Codexに「何をもって完了とするか」を知らせることを重視しています。テストの動かし方を知らないと、Codexは変更したあとに自分で確かめられません。公式のベストプラクティスにも、ビルドとテストの動かし方を伝えず、エージェントが自分の作業を確認できないのは、初心者が陥りやすい失敗として挙がっています。

書かない方がよいこと

公式は「短く、正確なAGENTS.mdは、あいまいなルールが並んだ長いファイルより役に立つ」と述べています。何を入れないかの一覧は公式にはありませんが、公式の考え方から、次のような内容は入れない方がよいでしょう。

• あいまいな心がけ：「きれいなコードを書く」「丁寧に作業する」など、守れたかどうか判断できないもの
• 書式やlintで機械的に確かめられること：字下げや引用符の種類などは、lintやCIに任せる方が確実です
• 特定の作業のときだけ必要な長い手順：リリースの手順書のようなものは、スキルに分けます
• パスワードやAPIキー：AGENTS.mdはリポジトリで共有されるファイルです。秘密情報は書かないでください
• すぐ古くなる情報：担当者名や、頻繁に変わる数字など

伝わりにくい書き方と、伝わりやすい書き方

同じ内容でも、書き方で守られやすさが変わります。判断できる形で、具体的に書くのがコツです。

「何をしてよいか・してはいけないか」「確かめる方法」「迷ったときの行き先（確認する／報告する）」の3つがそろうと、Codexが判断しやすくなります。

書き方の見本（Web制作チームの例）

次の例は、この記事用に作ったものです。公式のものではありません。コーポレートサイトを制作しているチームを想定しています。

# AGENTS.md

## このリポジトリについて
- 会社のコーポレートサイト。HTMLとCSSが中心で、一部にJavaScriptを使う。

## 作業のしかた
- 変更は小さく分け、1回の依頼で触るのは関連するファイルだけにする。
- 変更後は npm run build を動かし、エラーが出ないことを確認する。
- 画像は public/images/ に置き、ファイル名は半角英数字とハイフンにする。

## やってはいけないこと
- お問い合わせフォームの送信先（contact/send.php）は変更しない。
- 本番用の設定ファイル（.env）は読まない・書かない。

## 完了の基準
- npm run build が成功し、変更したページをブラウザで表示して確認できている。
- 確認した内容と、確認できなかったことを最後に報告する。

全部で15行ほどですが、「どう動かすか」「何に触らないか」「どうなれば完了か」がそろっています。最初はこの程度の量から始めて、足りないと感じたときに増やしていくのがおすすめです。

大きくなったら「分ける」

公式のベストプラクティスでは、AGENTS.mdが大きくなりすぎたときの対処として、次の2つが挙げられています。

• メインのファイルは短く保ち、計画づくり・レビュー・設計といった作業ごとの説明は、別のMarkdownファイルに書いて参照する
• フォルダごとに、そのフォルダだけで必要なルールを置く（ネストしたAGENTS.md）

公式の使用量を抑えるコツの中でも、AGENTS.mdをリポジトリの中で入れ子にして置くことで、毎回読み込む量を減らせると紹介されています。すべてのルールをルートに集めるより、関係する場所の近くに置く方が、読み込む量も無駄も少なくなります。

育て方・更新のしかた

AGENTS.mdは、一度書いて終わりではありません。公式のCustomizationのページでは、AGENTS.mdを「フィードバックの輪」として扱うよう勧めています。Codexが間違った前提で作業したら、AGENTS.mdを直して、同じ間違いが起きないようにする、という考え方です。

更新するタイミング

公式ドキュメントが挙げている、AGENTS.mdを更新する目安は次のとおりです。

最初から完璧なものを書こうとせず、困ったことが起きるたびに1行ずつ足していくのが基本です。公式のベストプラクティスにも「同じ失敗を2回したら、振り返りをさせてAGENTS.mdを更新する」とあります。

更新をCodexに頼む

AGENTS.mdの更新は、手で書き換えなくても、Codexに頼めます。たとえば、作業中に訂正したあと、次のように頼みます。

さっきの訂正を、今後も守れるようにAGENTS.mdに追記してください。追記する場所は、関係のあるフォルダに近いAGENTS.mdにしてください。

GitHubのプルリクエストのコメントでも、@codex add this to AGENTS.mdのように頼むと、クラウドの作業として更新を任せられると公式で紹介されています。レビューの中で出てきた決まりを、その場でAGENTS.mdに残せます。

また、定期実行のタスク（スケジュール）で、たとえば毎日、指示の抜け漏れを調べさせて、追加したほうがよい内容を提案してもらう使い方も、公式では紹介されています。

ルールを「守らせる仕組み」と組み合わせる

AGENTS.mdに書いたルールは、Codexへの「お願い」です。確実に守らせたいことは、仕組みでも守る形にします。公式のCustomizationのページでは、AGENTS.mdと、コミット前のチェック（pre-commit hook）・lint・型チェックなどを組み合わせるよう勧められています。

AGENTS.mdと「メモリ」の違い

公式では、AGENTS.mdのほかに、過去の作業で学んだ文脈を持ち越す「メモリ（Memories）」という機能も紹介されています。ChatGPTのメモリの説明には、毎回必ず守ってほしい指示は、メモリではなくAGENTS.mdか、リポジトリに入れた資料に書くよう書かれています。チームで同じ前提にそろえたいなら、ファイルとして共有できるAGENTS.mdが向いています。

GitHubのレビュー・ほかのツールとの併用

AGENTS.mdは、Codexを単体で使うときだけでなく、GitHubでのレビューや、ほかのAIツールとの併用でも使われます。

コードレビューの基準を書く

CodexをGitHubにつないでプルリクエストのレビューをさせるときは、AGENTS.mdに## Code Review Rulesという見出しの節を作ると、それがレビューの基準になります。公式ドキュメントの例は次のとおりです。

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

書き方のポイントは、公式で次のように整理されています。

最初は、レビューのたびに口頭で説明している点を、2〜3個書くところから始めるよう勧められています。ルールは、実際のプルリクエストで@codex reviewを試し、指摘が多すぎたり的外れだったりしたら絞っていきます。なお、公式は「レビューのルールはCodexへの案内であり、テストやブランチの保護、必須の承認の代わりにはならない」と書いています。

GitHubとの連携の設定方法は、別の記事「CodexとGitHubを連携する方法」で解説しています。

Claude Codeと併用する

Claude Codeを使うチームでは、指示ファイルが「CLAUDE.md」と「AGENTS.md」の2つに分かれます。Claude Codeの公式ドキュメントでは、AGENTS.mdの読み込みは次のように説明されています（v2.1.277以降）。

つまり、両方のファイルを置くだけでは、Claude CodeはAGENTS.mdを読みません。公式が紹介している方法は、決まりごとをAGENTS.mdに書き、CLAUDE.mdの先頭に@AGENTS.mdと書いて取り込む形です。Codex用とClaude Code用で、同じ指示を二重に管理せずに済みます。詳しくは、別の記事「Claude CodeとCodexを併用する方法」で解説しています。

別のファイル名を使う・ほかのツールから取り込む

すでに「TEAM_GUIDE.md」のように別の名前の指示書を持っているチームは、名前を変えずにCodexに読ませられます。設定ファイル~/.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の順に探します。一覧に書いていない名前は、指示書として扱われません。設定を変えたら、Codexを再起動してください。

Claude CodeやCursorの設定からの乗り換えには、「/import」（CLI）や、デスクトップアプリの「設定」→「Import」から取り込む方法があります。公式の対応表では、指示ファイルがAGENTS.mdとして取り込まれると説明されています。取り込み後は、権限やコマンドの書き方がそのままで動くとは限らないため、中身を見直すよう案内されています。

AGENTS.mdが読まれないとき

「書いたのに守られない」ときは、読み込まれていない場合と、読み込まれているが他の指示に負けている場合があります。公式のトラブルシューティングを、症状から探せる形に整理しました。

症状から探す

同じファイル名が複数あるときの見方

プロジェクトが大きいと、AGENTS.mdが複数の階層にあり、「どれが効いているのか」が分かりにくくなります。そのときは、次の順で確認します。

1. Codexを起動した場所を確認するどのフォルダで起動したかで、読まれるファイルの範囲が変わります。
2. Codexに読み込んだファイルを答えさせる「読み込んだ指示の出どころを、順番に教えて」と頼み、全体用・ルート・フォルダ用の順に並んでいるかを見ます。
3. 各フォルダにoverrideが無いかを探すoverrideがあると、同じフォルダのAGENTS.mdは読まれません。
4. 近いファイルと遠いファイルで食い違いが無いかを見る近い方が優先されるので、近くのファイルに別の指示がないかを確認します。

仕事で使うときに決めておくこと

チームで使う場合は、AGENTS.mdも会社の資料と同じように、管理のルールを決めておくと安心です。

• AGENTS.mdは、誰が・いつ・どのように更新するか（通常のレビューを通す）
• パスワード・個人情報・社外秘の数字を書かない
• 個人用の全体ファイル（~/.codex/AGENTS.md）に書く内容と、チーム共有のファイルに書く内容を分ける
• 定期的に見直す人を決める（古い情報が残ると、かえって間違った作業につながる）

AGENTS.mdはリポジトリに入るファイルです。リポジトリを社外の人と共有するときは、書いた内容も一緒に見えるという前提で書きましょう。

よくある質問

まとめ

AGENTS.mdは、Codexに仕事を任せるうえで、いちばん手軽に効果が出る設定の1つです。最初は10行ほどから始めて、Codexが同じ間違いをしたら足していく、という進め方で十分です。

社内に広げる段階では、どの決まりをどこに書くか、誰が見直すか、ほかのAIツールの指示ファイルとどう両立するかなど、決めることが増えます。INTERCREATE JAPANでは、Codex・Claude Codeの導入から、社内で使い続けられる指示書づくりまでをお手伝いしています。