CodexのAGENTS.mdとは?書き方と置き場所を公式の例で確認

CodexのAGENTS.mdが作業の前にCodexが読み込む指示書であることを示す記事の表紙画像

Codexに作業を頼むたびに、テストのやり方や守ってほしい決まりを毎回書き添えていないでしょうか。

結論から言うと、AGENTS.mdは、Codexが作業を始める前に読み込む指示書のファイルです。一度書いておけば、依頼のたびに同じ前提を説明しなくても、Codexがその決まりに沿って作業します。

この記事では、/initでの作り方から、書く内容・置き場所・優先順位・読み込まれたかの確かめ方までを整理します。読み終えるころには、自分のプロジェクトに置く最初の1枚が書けます。

目次

CodexのAGENTS.mdとは?作業の前に読み込む指示書

AGENTS.mdに決まりやコマンドを書くと、Codexが作業の前に自動で読み込み、決まりどおりに作業する流れを示す図

AGENTS.mdは、Codexが作業を始める前に読み込む指示書のファイルです。プロジェクトの構成やテストのコマンド、守ってほしい決まりを書いておくと、依頼のたびに同じ説明を繰り返さずに済みます。

ChatGPT LearnのAGENTS.mdのページによると、全体向けの指示とプロジェクトごとの指示を重ねて使えるため、どのリポジトリを開いても同じ前提で作業を始められます。リポジトリは、プロジェクトのファイルをまとめて管理するフォルダのことです。

READMEとの違いは読み手がAIであること

README.mdが人に向けた説明書なのに対し、AGENTS.mdはCodexのようなAIに向けた説明書です。AGENTS.mdの公式サイトは、このファイルを「エージェントのためのREADME」と考えるよう説明しています。

READMEに書くと人には細かすぎるビルドの手順やテストのコマンドも、AGENTS.mdなら遠慮なく書けます。人向けの説明はREADME、AIに守らせたい手順はAGENTS.mdと分けると、どちらも読みやすいまま保てます。

書式はふつうのMarkdownです。Markdownは、# で見出し、- で箇条書きを表す、文字だけで書ける文書の書き方を指します。

Codexのスキルとの違いは読み込むタイミング

AGENTS.mdは作業の前に毎回読み込まれます。一方でCodexのスキルは、最初は名前と説明だけが読まれ、使うと決まったときに手順の全文が読み込まれます。

ChatGPT Learnのベストプラクティスのページも、長く使う指示はAGENTS.mdに、繰り返す作業はスキルにまとめる流れで整理しています。どの作業にも効かせたい決まりはAGENTS.md、特定の作業の手順はスキルと分けると、指示が散らかりません。

あわせて読みたい
Codex Skillsとは?決まった作業の手順をCodexに覚えさせる機能 Codexに同じ作業を頼むたびに、手順や注意点を毎回書き直していないでしょうか。 結論から言うと、Codex Skillsは、決まった作業の手順や資料を1つのフォルダにまとめ、...

Codex以外のAIツールでも同じファイルを使える

AGENTS.mdはCodex専用の形式ではありません。AGENTS.mdの公式サイトによると、コーディング用のAIに指示を渡すためのオープンな形式で、6万を超えるオープンソースのプロジェクトで使われています。

公式サイトの対応ツールの一覧には、Codexのほか、GoogleのJules、Cursor、Gemini CLI、GitHub Copilotのコーディングエージェント、Devinなどが並んでいます。公式サイトは1つのAGENTS.mdが多くのツールで使えるとしており、ほかのAIツールを併用しても同じ指示を使い回しやすい点も、このファイルを使う利点です。

対応するツールの一覧は更新されていくので、使っているツールが入っているかは公式サイトで確かめてください。

公式ページ
AGENTS.md AGENTS.md is a simple, open format for guiding coding agents. Think of it as a README for agents.

CodexのAGENTS.mdは/initで雛形を作るのが早い

読ませたいフォルダで/initを実行し、できた雛形を実際のやり方に合わせて直し、コミットして以後のセッションで使う3ステップを示す図

AGENTS.mdは、Codex CLIで /init を実行すると雛形が作られます。ChatGPT LearnのCodex CLIのスラッシュコマンドのページでは、次の2つの手順が示されています。

  1. 指示を読ませたいフォルダで /init を実行する
  2. できたAGENTS.mdを見直し、リポジトリの決まりに合わせて直す

雛形はあくまで出発点です。ベストプラクティスのページも、チームが実際にビルド・テスト・レビューしているやり方に合わせて雛形を書き直すよう勧めています。直したAGENTS.mdはコミットしておけば、以後のセッションでも使われます。

ターミナルでCodexを使う手順は、Codex CLIの始め方と基本のコマンドで詳しくまとめています。

あわせて読みたい
Codex CLIとは?ターミナルで開発作業を任せるOpenAIのツール Codex CLIという名前を見かけたものの、アプリと何が違うのか、無料で使えるのかが分からず手が止まっていないでしょうか。 結論から言うと、Codex CLIはOpenAIのAIエー...

CodexのAGENTS.mdに書くのは毎回伝えている前提

AGENTS.mdに書く前提の例として、フォルダの構成、テストのコマンド、守る決まり、完了の確かめ方の4つを示す図

AGENTS.mdには、Codexに毎回伝えている前提を書きます。公式は、フォルダの構成、動かし方、テストのコマンド、守る決まり、してはいけないこと、完了の確かめ方の6つを挙げています。

公式が挙げる6つの項目

ChatGPT Learnのベストプラクティスのページでは、よいAGENTS.mdが扱う内容として次の6つが挙がっています。

  1. リポジトリの構成と重要なフォルダ
  2. プロジェクトの動かし方
  3. ビルド・テスト・lintのコマンド
  4. 開発の決まりとプルリクエストに求めること
  5. 制約と禁止事項
  6. 完了の定義と確かめ方

lintは、コードの書き方の誤りや乱れを自動で見つける仕組みのことです。AGENTS.mdの公式サイトは、コミットメッセージの決まりやデプロイの手順など、新しいチームメンバーに伝えることも書いてよいとしています。

書き方の例は見出しと箇条書きで十分

AGENTS.mdに決まった項目や見出しはありません。AGENTS.mdの公式サイトによると、見出しは自由につけてよく、AIは書かれた文章をそのまま読み取ります。

ChatGPT LearnのAGENTS.mdのページに載っている全体用の例は、次のような3行の箇条書きです。

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

上から順に、JavaScriptのファイルを変えたらテストを実行する、部品の追加にはpnpmを使う、本番用の部品を足す前には確認を取る、という決まりです。自分が毎回チャットで伝えている一言を、そのまま箇条書きにするのが書き始めやすい方法です。

短く書き、同じ間違いが出たら足す

ベストプラクティスのページは、短く正確なAGENTS.mdのほうが、あいまいな決まりが並んだ長いファイルより役に立つとしています。最初は基本だけを書き、同じ間違いが繰り返されたときに決まりを足していきます。

同じページでは、Codexが同じ間違いを2回したら振り返りを頼み、AGENTS.mdを更新するやり方も紹介されています。実際に困ったことから決まりを足すと、使われない決まりで膨らまずに済みます。大きくなってきたら、計画やコードレビューなどの手順は別のMarkdownファイルに分け、AGENTS.mdからその場所を示します。

CodexのAGENTS.mdは全体用とプロジェクト用の2か所に置ける

AGENTS.mdの置き場所として、~/.codexに置きどのリポジトリでも効く全体用と、リポジトリに置きそのプロジェクトだけに効くプロジェクト用を対比した図

AGENTS.mdの置き場所は2つあります。どのリポジトリでも使う自分の決まりは ~/.codex に、そのプロジェクトだけの決まりはリポジトリのフォルダに置きます。

全体用は自分のホームフォルダに置く

~/.codex は、自分のホームフォルダの中にあるCodexの設定用のフォルダです。ChatGPT LearnのAGENTS.mdのページによると、ここに置いた ~/.codex/AGENTS.md の決まりは、どのリポジトリを開いても引き継がれます。

フォルダが無い場合は、ターミナルで mkdir -p ~/.codex を実行して作ります。テストの実行や依存関係の追加前の確認など、どのプロジェクトでも同じにしたい自分の好みを書く場所と考えると分かりやすくなります。

環境変数 CODEX_HOME を設定している場合は、~/.codex ではなくそこで指定したフォルダが使われます。

プロジェクト用はリポジトリのルートに置く

プロジェクトだけの決まりは、リポジトリのいちばん上のフォルダ(ルート)に置いたAGENTS.mdに書きます。ルートは、ふつうはGitで管理している範囲のいちばん上のフォルダを指します。

Codexは、ルートから今作業しているフォルダまで順に下りながら、各フォルダのAGENTS.mdを探します。そのため、特定のサービスや部署だけの決まりは、そのフォルダの中に別のAGENTS.mdを置いて分けられます。

1つのフォルダから読まれるのは1つだけで、作業しているフォルダに着いたところで探すのをやめます。

別の名前のファイルも設定で読ませられる

すでにTEAM_GUIDE.mdのような別の名前でAIへの指示を書いているなら、名前を変えずに読ませる方法があります。設定ファイル ~/.codex/config.toml に、次のように別名の一覧を書きます。

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

設定を変えたら、Codexを起動し直します。この一覧に無い名前のファイルは、指示ファイルとして扱われないので、名前の綴りを間違えないよう注意してください。

CodexのAGENTS.mdは作業するフォルダに近いものが優先される

Codexが全体用、リポジトリのルート、作業するサブフォルダの順にAGENTS.mdを読み込み、後ろほど優先されることを示す図

複数のAGENTS.mdがあるときは、作業しているフォルダに近いものほど優先されます。Codexは上のフォルダから順にファイルをつなげて読み込み、後ろに来た指示が前の指示を上書きするためです。

ChatGPT LearnのAGENTS.mdのページの例では、全体用、リポジトリのルート、サブフォルダの順に読み込まれます。なお、AGENTS.mdの公式サイトによると、チャットで直接伝えた指示はAGENTS.mdよりも優先されます。

スクロールできます
読み込む順番 置き場所 用途
1 ~/.codex 自分の全体の決まり
2 リポジトリのルート プロジェクト共通の決まり
3 作業するサブフォルダ そのフォルダだけの決まり

AGENTS.override.mdは同じ場所で先に読まれる

AGENTS.override.mdは、同じフォルダにあるAGENTS.mdより先に探される上書き用のファイルです。同じフォルダに両方あれば、AGENTS.override.mdだけが読まれ、AGENTS.mdは無視されます。

全体用の ~/.codex/AGENTS.override.md は、元のファイルを消さずに、一時的に指示を差し替えたいときに使います。上書きをやめたいときはAGENTS.override.mdを消せば、元のAGENTS.mdの指示に戻ります。

読み込む量の上限は既定で32 KiB

AGENTS.mdには、読み込む量に上限があります。ChatGPT LearnのAGENTS.mdのページによると、上限は設定項目project_doc_max_bytesで決まり、既定は32 KiBです。

上限に達すると、それ以上の指示は読み込まれません。長くなったら上限を上げるより、下のフォルダへ分けるか別のMarkdownファイルに逃がすほうが、短く正確にという勧めにも合います。

CodexがAGENTS.mdを読んだかは1行の依頼で確かめる

リポジトリのルートで指示の要約を頼み、優先順に返ってきた内容を確かめ、古いままなら起動し直す3ステップを示す図

AGENTS.mdが読み込まれたかは、Codexに今の指示を要約させると確かめられます。ChatGPT LearnのAGENTS.mdのページでは、リポジトリのルートで次のコマンドを実行する方法が紹介されています。

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

Codexが、読み込んだ全体用とプロジェクト用の指示を優先順に要約して返します。サブフォルダの指示を確かめるときは、--cd でフォルダを指定して「Show which instruction files are active.」と頼みます。

読み込まれないときは、同じページの確認点を次の表の順に見ていきます。

スクロールできます
症状 確かめること
何も読み込まれない 目的のリポジトリにいるか・ファイルが空でないか
思っていない指示が出る 上のフォルダや ~/.codex にAGENTS.override.mdがないか
別名のファイルが無視される config.tomlの綴りを直してCodexを起動し直したか
指示が途中で切れる 上限を上げるかファイルを分けたか
書き換えが反映されない 目的のフォルダでCodexを起動し直したか

指示は起動のたびに組み直されるので、消すべきキャッシュはありません。書き換えたのに古い指示のままに見えるときは、Codexを起動し直すだけで済みます。

確認の手順や設定の名前は変わることがあるので、困ったときは公式のページで最新の内容を確かめてください。

公式ページ
Custom instructions with AGENTS.md | ChatGPT Learn Give Codex extra instructions and context for your project

CodexのAGENTS.mdはGitHubのレビューのルールにも使える

AGENTS.mdが作業の決まりだけでなく、GitHubのコードレビューやサービス別のルールにも使えることを示す図

AGENTS.mdは、GitHubでのCodexのコードレビューにも使われます。対象のコードに近いAGENTS.mdに ## Code Review Rules の節を足すと、Codexがそのルールに沿ってプルリクエストを確認します。

ChatGPT LearnのGitHubのレビューのページによると、リポジトリ全体のルールはルートのAGENTS.mdに、特定のサービスだけのルールは下のフォルダのAGENTS.mdに置きます。最初は、レビューでいつも指摘している点を2〜3個だけ簡潔に書くのが勧められた始め方です。書式やlintの確認は、自動テストの仕組み(CI)に任せます。

レビューの設定方法は、CodexとGitHubを連携してレビューを任せる手順で解説しています。

あわせて読みたい
CodexとGitHubの連携方法は?プルリクエストのレビューを3ステップで設定 GitHubで変更を出すたびにレビューを待つ時間が長く、AIに一次チェックを任せられないかと考える場面があります。 CodexとGitHubの連携は、プルリクエストのレビューをC...

CodexのAGENTS.mdに関するよくある質問

AGENTS.mdに決まった見出しや必須の項目はありますか?

決まった見出しや必須の項目はありません。AGENTS.mdはふつうのMarkdownで書くファイルで、見出しは自由につけられると公式サイトに書かれています。迷ったら、公式の例のように「テストのコマンド」「コードの書き方」などの見出しを立てて箇条書きで並べると、Codexにも人にも読みやすくなります。

AGENTS.mdを書き換えたらCodexの再起動は必要ですか?

書き換えた内容は、次にCodexを起動したときから使われます。Codexは起動のたびに指示を組み直し、ターミナルの画面で使う場合は起動した1回のセッションごとに組み直します。古い指示のままに見えるときは、目的のフォルダでCodexを起動し直してください。手で消すキャッシュはありません。

AGENTS.mdとチャットで頼んだ内容が食い違ったらどちらが優先されますか?

チャットで直接頼んだ内容が優先されます。AGENTS.mdの公式サイトは、チャットでの明示的な指示がすべてに優先すると説明しています。いつもの決まりはAGENTS.mdに書いておき、その回だけ変えたいことはチャットで伝える、と使い分けると混乱しません。

ファイル名は小文字のagents.mdでも読み込まれますか?

公式の表記どおり大文字のAGENTS.mdで作るのが確実です。Codexが探すのはAGENTS.override.mdとAGENTS.md、それに設定で足した別名だけで、一覧にない名前は指示ファイルとして扱わないと公式は説明しています。小文字の名前の扱いは公式に明記がないため、名前を変えたい場合は設定の別名の一覧に加えてください。

AGENTS.mdはGitにコミットして共有したほうがいいですか?

チームで同じ決まりを使うなら、リポジトリのAGENTS.mdはコミットして共有するのが公式の想定です。/initの説明でも、できた雛形を直してコミットし、以後のセッションで使う流れが示されています。自分だけの好みは、リポジトリではなく~/.codexのAGENTS.mdに書くと分けられます。

まとめ:CodexのAGENTS.mdは/initの雛形から短く始める

AGENTS.mdは/initで雛形を作って直し、指示の要約で読み込みを確かめ、同じ間違いが出たら1行ずつ足して育てることを示すまとめの図

AGENTS.mdは、Codexが作業の前に読み込む指示書です。全体用は ~/.codex に、プロジェクト用はリポジトリに置き、作業するフォルダに近いものほど優先されます。

長い決まりを最初から書くより、/initの雛形を直して短く始め、困ったときに1行ずつ足すほうが、Codexにとっても読みやすいファイルに育ちます。次の順で試してみてください。

  1. 毎回チャットで伝えている一言を書き出す
  2. /initで雛形を作り、書き出した一言を足す
  3. Summarize the current instructionsの依頼で読み込みを確かめる
  4. 同じ間違いが出たら決まりを1行足す

Codexそのものの使い方や、ほかのAIツールとの違いは次の記事が役立ちます。

SNSでシェアする
  • URLをコピーしました!

この記事を書いた人

生成AIテックを運営する編集部です。SEOを専門とするデジタルマーケティングの実務家が、生成AIツールを仕事で毎日使う立場から記事を制作しています。料金や機能などの事実は公式の情報で確かめ、公開したあとも内容を見直して更新しています。

目次