AGENTS.mdとは？Codexでの書き方や置き場所・優先順位までわかりやすく解説
Codexに毎回同じ注意をしているのに、また同じミスをされて、うんざりしていないでしょうか。「AGENTS.mdに書けばいい」と聞いても、解説はエンジニア向けの用語が多く、どこに置いて何を書けばいいのか分かりにくいものです。
この記事では、AGENTS.mdの意味・何を書くか・置き場所と優先順位・作り方・効かないときの対処・チームで運用するコツまでを、技術に詳しくない人にも分かる言葉で解説します。読み終えるころには、自分のプロジェクトに合ったAGENTS.mdを、迷わず用意できるようになるはずです。結論から言うと、AGENTS.mdはAIエージェント向けの説明書です。リポジトリ(コードの保管場所)の一番上に置き、守ってほしいルールを短く具体的に書くのが基本になります。
AGENTS.mdとは【AIエージェント向けの説明書】
まず、AGENTS.mdがどういうものかを次の3点で押さえます。
- プロジェクトのルールをAIに渡すファイル
- 多くのAIツールが読む共通フォーマット
- CLAUDE.mdやREADMEとの違い
プロジェクトのルールをAIに渡すファイル
AGENTS.mdは、そのプロジェクトでAIにどう働いてほしいかを書いておくファイルです。AGENTS.mdの公式仕様サイトは、AGENTS.mdを「エージェント向けのREADME」と表現しています。READMEが人向けの説明書なら、AGENTS.mdはAI向けの説明書です。
たとえば「テストはこのコマンドで動かす」「この書き方に合わせる」「ここは触らない」といった約束事を1か所にまとめておきます。すると、毎回口で指示しなくても、AIがファイルの内容を前提に作業してくれます。OpenAIの公式ドキュメントによると、AGENTS.mdはチームがCodexにリポジトリ内でどう動いてほしいかを書き込む最適な場所です。
多くのAIツールが読む共通フォーマット
見落とされがちですが、AGENTS.mdはCodex専用ではありません。AGENTS.mdの公式仕様サイトによると、AGENTS.mdはコーディングAI向けのオープンな共通形式です。CursorやGitHub Copilot、Gemini CLIなど、多くのツールが同じAGENTS.mdを読むと案内されています。
つまり、一度きちんと書いておけば、使うツールを変えても同じルールを使い回せるのです。ツールごとに別々の設定を書き直す手間がないのは、共通形式ならではの利点です。Codex自体の全体像は次の記事で解説しています。
Codexとは？読み方や旧モデルとの違い・できることまで徹底解説！
CLAUDE.mdやREADMEとの違い
似たファイルとの違いも整理しておきましょう。READMEは人が読む説明書で、AGENTS.mdはAIが読む指示書です。むしろ、両方を置いて併用するのが自然です。
なお、Claude Codeには同じ役割のCLAUDE.mdが別に用意されています。ツールごとに読むファイル名が違うだけで、狙いは共通です。また、繰り返す特定の作業の手順は、AGENTS.mdではなくスキルにまとめる方が向いています。AGENTS.mdは常に効かせる前提、スキルは必要なときに呼び出す手順、と使い分けてください。
Codex Skillsとは？使い方・作り方・保存場所とおすすめの始め方を解説
AGENTS.mdに何を書くのか
書く内容は、次の3点を軸に考えると迷いません。
- 最低限おさえる4つの項目
- やってほしくないこと(禁止事項)を書く
- 具体的に書くほど効く
最低限おさえる4つの項目
まず、最低限として次の4つを書けば形になります。1つ目はプロジェクトの概要で、何を作っているかを1〜2行で書く部分です。2つ目は動かし方で、ビルド(組み立て)やテストのコマンドを書きます。
3つ目はコードの書き方のルールで、命名や書式の決まりを書きます。4つ目は禁止事項です。公式ドキュメントも、リポジトリの構成・実行やテストの方法・規約・「何をもって完了とし、どう検証するか」を書く場所として挙げています。
やってほしくないこと(禁止事項)を書く
意外と大切なのが、やってほしくないことを書くことです。AIは書かれていないことは自由に判断してしまうため、「ここは変更しない」「この方法は使わない」といった禁止事項を明記しておくと、余計な事故を防げます。
たとえば「本番の設定ファイルは触らない」「勝手にライブラリを増やさない」などです。守ってほしい一線を先に伝えておけば、後から想定外の変更に驚くことが減ります。
具体的に書くほど効く
同じ内容でも、書き方で効き目が変わります。「きれいに書く」のような曖昧な言葉より、「1つのファイルは800行を超えたら分ける」のように、誰が読んでも同じ意味になる具体的な書き方が効果的です。
数字やコマンドで示せるものは、そのまま書くのがコツです。曖昧な精神論を並べるより、短くても具体的なルールのほうが、AIにも人にも伝わります。
AGENTS.mdの置き場所と優先順位
置き場所は混乱しやすい論点なので、公式の情報で整理します。
- 基本はリポジトリの一番上に置く
- 近い場所のファイルが優先される
- 全体に効かせるグローバル設定
基本はリポジトリの一番上に置く
まず基本は、リポジトリの一番上(ルート)にAGENTS.mdを1つ置くことです。公式ドキュメントによると、Codexは作業を始める前にルートから今の作業場所までの各フォルダを見ます。そのうえでAGENTS.mdを読み込みます。まずはルートに1枚置けば、プロジェクト全体に効くはずです。
大きなプロジェクトでは、フォルダごとにAGENTS.mdを分けて置くこともできます。共通ルールはルートに、その場所だけの細かいルールは各フォルダに、と分担させるイメージです。
近い場所のファイルが優先される
複数のAGENTS.mdがある場合の優先順位も、公式が定めた仕様です。公式ドキュメントによると、Codexはルートから下に向かってファイルをつなげます。作業場所に近いファイルほど後に読むため、近い場所の指示が優先されます。1つのフォルダにつき、読まれるAGENTS.mdは1つまでです。
つまり、全体のルールはルートに書きます。特定のフォルダだけ例外にしたいときは、そのフォルダのAGENTS.mdへ上書きのルールを書きます。近い場所が勝つ、と覚えておくと分かりやすいでしょう。
全体に効かせるグローバル設定
どのプロジェクトでも共通で効かせたいルールは、グローバル設定に書けます。公式ドキュメントによると、ホームフォルダの中の「~/.codex/AGENTS.md」に書いた内容は、すべてのプロジェクトの土台として読み込まれる仕組みです。
ただし、グローバル設定は優先順位が最も低く、各プロジェクトのAGENTS.mdによって上書きされます。自分の全プロジェクト共通の好みはグローバルに、プロジェクト固有のルールは各リポジトリに、と役割を分けるのがおすすめです。
AGENTS.mdの作り方と育て方
作り方は、最初から完璧を目指さないのがコツです。次の3点で進めましょう。
- まずは短く作って動かす
- /initで雛形を作る
- 同じ失敗をしたら1行足して育てる
まずは短く作って動かす
最初のAGENTS.mdは、短くて構いません。公式ドキュメントも、長くて曖昧なファイルより、短く正確なファイルのほうが役に立つと述べています。まずは概要・動かし方・コード規約・禁止事項の4項目を数行ずつ書き、実際にCodexを動かしてみてください。
いきなり全部を書こうとすると、使われないルールばかりが増えます。基本だけ書いて動かし、足りない部分を後から足す順番のほうが、実用的なファイルに育ちます。
/initで雛形を作る
ゼロから書くのが不安なら、雛形を自動で作れるので安心です。公式ドキュメントによると、Codexで「/init」コマンドを使うと、今のフォルダにAGENTS.mdのたたき台を作ってくれます。空のファイルとにらめっこせずに始められます。
できた雛形を見ながら、自分のプロジェクトに合わせて中身を直していけば十分です。まず形を用意し、そこから調整する進め方が、初めての人には向いています。
同じ失敗をしたら1行足して育てる
AGENTS.mdは、一度作って終わりではなく、育てるものです。公式ドキュメントは、Codexが同じミスを2回したら、振り返りをさせてAGENTS.mdを更新するとよいと勧めています。ミスのたびにルールを1行足していく育て方です。
失敗を起点にする進め方なら、無理に想像でルールを書き足さずに済みます。実際に困った点だけをルールにするので、ファイルが無駄に膨らまず、本当に効くルールだけが残ります。
AGENTS.mdが効かないときの確認
書いたのに効かない、と感じたときの確認ポイントは2つです。
- 反映は新しいセッションから
- 読み込まれた指示を確認する
反映は新しいセッションから
よくあるのが、編集がすぐ反映されないケースです。公式ドキュメントによると、CodexはAGENTS.mdを作業の開始時にまとめて読み込みます。裏を返すと、作業中に編集しても、その途中のセッション(一連の作業のまとまり)には反映されません。
編集したら、いったん終了して新しいセッションを始めてください。多くの「効かない」は、この読み込みのタイミングが原因です。まずは開き直してから、内容を疑うのが順番です。
読み込まれた指示を確認する
それでも不安なら、実際に何が読み込まれているかを確認できます。公式ドキュメントによると、Codexに現在の指示を要約するよう頼めば、読み込まれた内容が返ってきます。書いたはずのルールが含まれているかを、その場で確かめられるわけです。
もし含まれていなければ、置き場所かファイル名が違う可能性があります。リポジトリの一番上に、正しいファイル名で置けているかを見直してください。
非エンジニアのチームで運用するコツ
チームで使うなら、書き方以上に運用の仕組みが効いてきます。以下の3点を押さえましょう。
- 誰が書き、誰が承認し、どう配るか
- 機密情報と設定ファイルの扱い
- Gitが苦手なチームの配り方
誰が書き、誰が承認し、どう配るか
AGENTS.mdは、担当を決めておくとうまく回ります。誰が原案を書き、誰が承認するかを最初に決めます。見直しの時期もあわせて決めておくと、内容が古びたり人によってばらついたりしません。月に一度、15分だけ見直す軽い運用で十分です。
技術に詳しい人が原案を書き、現場の意思決定者が承認する分担なら、非エンジニア中心のチームでも無理なく続けられます。ルールを言葉にできる人がいれば、AGENTS.mdは書けます。
機密情報と設定ファイルの扱い
安全面で必ず守りたいのが、機密情報を書かないことです。AGENTS.mdはチームで共有しリポジトリに入れるため、パスワードやAPIキー(外部サービスの利用証)などを直接書くと、共有範囲に漏れる恐れがあります。手順は書いても、秘密の値は書かないでください。
秘密の値が必要なときは、実際の値の代わりに「ここに自分のキーを入れる」といった見本だけを書き、本物は各自の手元に置く形にします。共有していいものと、してはいけないものを、最初に線引きしておくと安心です。
Gitが苦手なチームの配り方
リポジトリでの共有が難しいチームには、別の配り方もあります。AGENTS.mdのひな形を社内の文書ツール(共有のメモ帳のようなもの)に置き、各自が自分の環境にコピーして使う方法です。Gitの操作に慣れていなくても始められます。
まずはコピーで配って運用に慣れ、体制が整ってからリポジトリ共有に移す段階的な進め方でも構いません。大切なのは、全員が同じAGENTS.mdを見ている状態を作ることです。
AGENTS.mdに関するよくある質問
最後に、迷いやすい点へまとめて答えます。
- CursorやCopilotのAGENTS.mdと同じですか？
- ファイルは長くしても大丈夫ですか？
- 何をどこまで書けばいいか分かりません
CursorやCopilotのAGENTS.mdと同じですか？
基本的に同じファイルです。AGENTS.mdは多くのAIツールが読む共通形式です。CursorやGitHub Copilotなどでも、同じAGENTS.mdが指示書として使えます。ツールごとに書き分ける必要は、基本的にありません。
そのため、複数のツールを併用しているなら、ルールをAGENTS.md 1本に集約しておくと管理が楽です。ツールを乗り換えても、書いた資産はそのまま活きます。
ファイルは長くしても大丈夫ですか？
長すぎるのは逆効果です。公式ドキュメントによると、読み込まれる合計サイズの上限は既定で32KiB(全角でおよそ1.6万字)です。上限を超えると以降のファイルは読み込まれません。何より、長く曖昧なルールより、短く具体的なルールのほうが効果的です。
分量が増えてきたら、内容ごとに別のファイルへ分けて、必要なときだけ参照させる方法もあります。まずは本当に必要なルールだけに絞るのが得策です。
何をどこまで書けばいいか分かりません
迷ったら、「新しく入った人に最初に伝えたいこと」を書く、と考えてください。プロジェクトの概要・動かし方・守ってほしいルール・触ってほしくない場所。4つは、人にもAIにも共通して必要な情報です。
最初から網羅しようとせず、短く始めて困った点を足していけば十分です。CodexとClaude Codeでの指示ファイルの考え方の違いは、別記事も参考になります。
CodexとClaude Codeの違いを徹底解説！料金比較と併用のコツも紹介
AGENTS.mdはリポジトリの一番上に短く置くところから始めましょう
AGENTS.mdは、AIエージェント向けの説明書で、CursorやCopilotなど多くのツールが読む共通形式です。書くのは、概要・動かし方・コード規約・禁止事項の4つが基本で、曖昧な言葉より具体的なルールが効きます。置き場所はリポジトリの一番上が基本で、近い場所のファイルが優先され、全体共通の設定はグローバルに書けます。
作り方は、/initで雛形を作って短く始め、同じ失敗をしたら1行足して育てるのが近道です。効かないと感じたら、まず新しいセッションで開き直し、現在の指示を要約させて確認してください。チームで使うなら、担当と見直しの仕組みを決め、機密情報は書かないことを徹底しましょう。まずはリポジトリの一番上に、短いAGENTS.mdを1つ置くところから始めてみてください。
