AI 活用記事AIコーディングツール

AGENTS.mdとは?書き方・置き場所とCLAUDE.mdとの違い|Codexで37回試した結果

AGENTS.mdは、CodexなどのAIコーディングエージェントに毎回守らせたいルールを書くファイルです。置き場所と読まれる順番、CLAUDE.mdとの違い、効く書き方を、Codex CLIで37回試した結果(32KiBで警告なく切れる、Gitの外の親フォルダは読まない等)とあわせて解説します。

AIコーディングツール、、読了時間:16分

晩秋の霧の杉林で、落ち葉の積もった山道が二手に分かれ、分かれ目に苔むした平たい石を積んだ小さな道しるべが立っている

AGENTS.mdは、リポジトリのルートに置き、「コードを読んでも分からないルール」だけを具体的に書くと効きます。編集部が2026年11月2日にCodex CLIで同じ依頼を9回試したところ、具体的なAGENTS.mdを置いた3回だけが変更履歴を書き足し、最後に npm run check が通る状態で終えました。あいまいなAGENTS.mdは、置かない場合と結果が変わりませんでした。

AGENTS.mdとは、AIコーディングエージェントに作業のたびに読ませる指示を書く、Markdown形式のテキストファイルです。テストの実行方法、触ってはいけないフォルダ、コードの書き方といった、人間の新メンバーに最初に伝えるような内容を書きます。公式サイトagents.mdは、6万以上のオープンソースプロジェクトで使われている共通の形式だとしています(2026年11月2日確認)。

本記事の仕組みの説明は、Codex・Claude Code・agents.mdの公式ドキュメント(いずれも2026年11月2日確認)にもとづきます。実測はCodex CLI 0.163.0(ChatGPT アカウント)経由で、計37回行いました。Claude Codeの動きは公式ドキュメントの記載で、今回は実行していません。

AGENTS.mdで何が変わるか:同じ依頼を9回試した結果

AGENTS.mdが変えたのは、コードを読んでも分からないことだけでした。小さなNode.jsのプロジェクトに「税込金額を返す関数を追加して、テストも足して」と頼み、AGENTS.mdなし・具体的なAGENTS.md・あいまいなAGENTS.mdの3条件で3回ずつ実行した結果です。

結果 AGENTS.mdなし 具体的に書いた あいまいに書いた
関数が正しい(1,999円×8%=2,158円など) 3/3 3/3 3/3
コードの書き方(シングルクォート・セミコロンなし)を守った 3/3 3/3 3/3
「変更しない」とコメントのある古いコードに触れなかった 3/3 3/3 3/3
npm run check を実行した 3/3 3/3 3/3
最後に npm run check が成功する状態で終えた 0/3 3/3 0/3
CHANGELOG.md に1行書き足した 0/3 3/3 0/3
入力トークン(3回の範囲) 81,269〜103,271 77,941〜86,280 77,332〜102,379

具体的なAGENTS.mdには、「最後に必ず npm run check を実行して成功を確かめる。npm test だけでは不十分」「CHANGELOG.md の ## Unreleased に日本語で1行追加する」など5項目を書きました。あいまいなほうは「テストは適宜実行」「変更履歴も意識」のような5項目です。

コードの書き方や古いコードの扱いは、AGENTS.mdがなくても3回とも守られました。設定ファイル(.prettierrc)や既存コード、コード内のコメントから読み取れたためです。逆に、「変更履歴を書く」というチームの約束は、コードのどこにも書かれていないため、AGENTS.mdに書いた3回だけで実行されました。

npm run check の差は、予定していなかった条件から出ました。用意したプロジェクトのテスト指定(node --test test/)が、Codexの実行環境ではエラーになったのです。AGENTS.mdなしとあいまいの6回は、テストを直接実行して成功させ、「npm run check は既存の指定がエラーになるため直接実行した」と報告して終えました。具体的なAGENTS.mdの3回は、package.json のテスト指定を node --test test/*.test.js に直し、npm run check を通してから終えました。

この package.json の修正は、依頼文にはない変更です。「最後に必ず通す」と書けばそこまでやり、書かなければ報告で止める、という違いです。勝手に設定を直してほしくない場合は「通らないときは直さずに報告する」と書く必要があります。

AGENTS.mdの置き場所と読まれる順番

Codexは、作業を始めるときに、Gitのルートから作業フォルダまでの各階層のAGENTS.mdを上から順に読みます。編集部は、Codexのセッションログ(~/.codex/sessions)に実際に入った指示の本文を見て、どのファイルが読まれたかを判定しました。各条件2回ずつ、計20回で、2回とも同じ結果でした。

Codexが AGENTS.md を読むルールの実測まとめ。入れ子はルートから作業フォルダまで全部読み、近いほうが勝った(2/2)。AGENTS.override.md は同じフォルダの AGENTS.md と入れ替わった(2/2)。CLAUDE.md だけでは既定で読まず、fallback に足すと読んだ(2/2)。Git の外では親フォルダの AGENTS.md を読まなかった(0/2)。32KiB を超えると253項目目までで警告なく切れた(2/2)
図1 Codex が AGENTS.md を読むルール。出典: 編集部の実測(2026年11月2日、codex exec 20回)
置き場所 読まれる範囲 実測で確かめたこと
~/.codex/AGENTS.md Codexを使うすべてのプロジェクト 今回は置いていない(公式の記載のみ)
リポジトリのルート そのリポジトリ全体 下の階層で作業しても毎回読まれた
サブフォルダ(例:packages/api/) そのフォルダ以下で作業するとき ルートの後ろに連結され、テストの指示がぶつかると近いほうに従った
同じフォルダの AGENTS.override.md AGENTS.md の代わり 同じフォルダの AGENTS.md は読まれなかった。上の階層は読まれた
Gitで管理していないフォルダの親 読まれない すぐ上のフォルダに置いた AGENTS.md も読まれなかった

公式ドキュメントは、プロジェクトの範囲を「プロジェクトのルート(通常はGitのルート)から現在のフォルダまで」とし、ルートが見つからない場合は現在のフォルダだけを確認すると書いています。実測でも、Gitの外で作業したときは、すぐ上のフォルダに置いたAGENTS.mdが2回とも読まれませんでした。ホームフォルダに置いた共通ルールが読まれないと感じたら、Gitの外で作業していないかを確かめてください。

指示の連結は起動時に1回だけ行われます。作業の途中でAGENTS.mdを書き換えても、そのセッションには反映されません(公式ドキュメントの記載)。

AGENTS.mdとCLAUDE.mdの違い

CLAUDE.mdはClaude Code用、AGENTS.mdはCodexなど複数のツールが読む共通の形式です。両方のツールを使うなら、AGENTS.mdに本文を書き、CLAUDE.mdには @AGENTS.md の1行だけを書くのが、公式ドキュメントに沿った確実な方法です。

項目 Codex Claude Code
既定で読むファイル AGENTS.md(同じフォルダに override があればそちら) CLAUDE.md
もう一方のファイル CLAUDE.md は読まない(実測2/2)。設定で読ませられる CLAUDE.md がないときだけ AGENTS.md を読む(v2.1.277以降)
両方あるとき AGENTS.md だけ(実測2/2) CLAUDE.md だけ
長さの目安 合計32KiBまで(設定で変更可) 1ファイル200行以内を推奨
確認方法 セッションログ、または「今の指示を要約して」と聞く /memory、/context

Claude Codeの欄は、Claude Codeの公式ドキュメント「How Claude remembers your project」の記載です。CLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md のどれもないときにAGENTS.mdを読み、どれか1つでもあれば読みません。つまり、個人用に CLAUDE.local.md を足しただけで、それまで読まれていたAGENTS.mdが読まれなくなります。Claude Code 2.1.321で実際に確かめた結果(3回とも読まれなくなった・設定で直せた)は、CLAUDE.mdの書き方と置き場所にまとめています。

両方に読ませる書き方は次の2つです。

  • CLAUDE.md の1行目に @AGENTS.md と書く(Claude Codeの読み込み機能。その下にClaude Code専用の指示を足せる)
  • Codexの設定(~/.codex/config.toml)に project_doc_fallback_filenames = ["CLAUDE.md"] を書く(AGENTS.md がないフォルダで CLAUDE.md を読む)

編集部の実測では、CLAUDE.md だけを置いたフォルダで、Codexは2回とも合言葉を「不明」と答えました。-c 'project_doc_fallback_filenames=["CLAUDE.md"]' を付けて起動すると、2回とも CLAUDE.md の内容を答えました。

Claude Codeとの使い分けそのものは、CodexとClaude Codeを比較|同じ課題27回の実測と選び方にまとめています。

32KiBを超えると、警告なしで途中から切れる

Codexが読むAGENTS.mdは、既定で合計32KiB(32,768バイト)までで、超えた部分は何の表示もなく捨てられます。編集部は、310項目・40,099バイトのAGENTS.mdを置き、先頭と末尾に別々の合言葉を書いて試しました。

2回とも、読み込まれた指示は253項目目の途中で切れていました。末尾の合言葉と、254項目目以降の57項目は届いていません。切れ目は日本語の文字の途中で、ログには文字化けした1文字が残っていました。画面の出力にもログにも、切ったことを知らせる表示はありませんでした。

設定で project_doc_max_bytes = 65536 に上げると、2回とも全文が読み込まれ、末尾の合言葉も答えました。ただし、長いAGENTS.mdはそのまま毎回のトークン消費になります。まずは短くする方向で考えてください。

AGENTS.md の長さと1回目の入力トークンの横棒グラフ。なしが14,558、50行(6.6KB)が16,952、200行(26KB)が21,728、1000行(132KB)が23,565で、1000行は32KiBで切られて頭打ち。各2回の平均
図2 AGENTS.md の長さと入力トークン。出典: 編集部の実測(2026年11月2日、codex exec 8回)

「OK とだけ返して」と頼んだときの入力トークンは、AGENTS.mdなしの平均14,558に対し、50行で約2,400、200行で約7,200増えました。Codexは1つの作業の中でモデルを何度も呼ぶため、この差は呼ぶたびに加わります。

AGENTS.mdの作り方(5ステップ)

AGENTS.mdには決まった書式や必須の項目はありません(agents.mdの記載)。今回の結果から、効果が出やすかった作り方を5つの手順にまとめます。

1. リポジトリのルートに AGENTS.md を作る

まずはルートに1つだけ置きます。Codexはルートから作業フォルダまでを読むので、どこで作業しても届きます。フォルダごとに分けるのは、パッケージごとにテストの方法が違うときなど、必要になってからで十分です。

2. コードから分からないルールだけを書く

変更履歴の書き方、レビューの前に通すコマンド、本番の設定に触らないこと、報告の言語など、ファイルを読んでも分からない約束を書きます。今回の実測では、.prettierrc やコード内のコメントで分かることは、書かなくても守られました。

3. 「適宜」ではなく、コマンドと場所で書く

「テストは適宜実行」ではなく「最後に npm run check を実行して成功を確かめる」と書きます。あいまいに書いた3回は、何も置かなかった3回と同じ結果でした。

4. 守れないときの動きも書く

「通らないときは、設定を直さずに理由を報告する」のように、守れなかった場合の動きも決めておきます。書かないと、エージェントはルールを守るために依頼にない変更をすることがあります(今回は package.json を直しました)。

5. 読み込まれたかを確かめる

Codexなら、codex exec "今読み込んでいる指示を要約して" のように聞くか、~/.codex/sessions のログに入った本文を見ます。Claude Codeなら /memory で読み込まれたファイルを確認できます。32KiBを超えていないかは、ファイルの合計サイズで確かめます。

AGENTS.mdのテンプレート

小さなWebアプリのリポジトリを想定した例です。これをもとに、自分のプロジェクトのコマンドとルールに書き換えてください。

# AGENTS.md

## 作業の最後に
- `npm run check` を実行し、成功を確かめてから終える。`npm test` だけでは不十分。
- 通らないときは設定ファイルを直さず、失敗した内容を報告する。

## 触らない場所
- `src/legacy/` は変更しない。必要なら `src/` に新しい関数を作る。
- `.env` と `config/production.*` は読まない・書かない。

## 変更の記録
- CHANGELOG.md の `## Unreleased` に、日本語で1行追加する。

## 報告
- 日本語で3行以内。変更したファイルと、実行したコマンドの結果を書く。

自分で書いていないAGENTS.mdがあるフォルダ(ダウンロードしたファイルの中など)では、エージェントを起動しないでください。AGENTS.mdに書かれた内容は、そのまま指示として読まれます。2026年10月に報告された手口と確認方法はAGENTS.md攻撃とはにまとめました。

毎回ではなく、特定の作業のときだけ読ませたい手順をまとめる仕組みとしては、Agent Skillsがあります。違いはAgent Skillsとはで説明しています。

対応しているツール

agents.mdの公式サイトは、Codexのほか、Cursor、Gemini CLI、Jules、Aider、opencode、Zed、Warp、Windsurf などを対応ツールとして挙げています(2026年11月2日確認)。ただし、読み込み方はツールごとに異なります。Gemini CLIは .gemini/settings.json で読むファイル名に AGENTS.md を指定し、Aiderは設定の read: に AGENTS.md を指定する方法が紹介されています。

Claude Codeは v2.1.277 以降、CLAUDE.md がないときに AGENTS.md を読むようになりました。それより古いバージョンでは読まれないため、claude --version で確かめてください。

検証の方法と、まだ確かめていないこと

実行はすべて2026年11月2日、Codex CLI 0.163.0(ChatGPT アカウント)経由、モデルは gpt-6.1-sol です。読み込み(20回)は読み取り専用、依頼の比較(9回)は書き込み可、トークン(8回)は読み取り専用で実行しました。架空の小さなプロジェクトを使い、実在のコードは使っていません。

  • 読み込みの判定:セッションログに入った # AGENTS.md instructions for … の本文で、どのファイルの合言葉が含まれるかを数えた。
  • 依頼の比較:変更されたファイル、実行したコマンド、最後の npm run check の終了コード、関数の計算結果を、実行後のフォルダで機械的に確かめた。
  • 依頼の比較で使ったテスト指定(node --test test/)は、Codexの実行環境でエラーになりました。意図した条件ではありませんが、結果はそのまま載せています。

次の点は確かめていません。

  • Claude Codeでの実際の読み込み(本記事の Claude Code の説明は公式ドキュメントの記載です)。
  • 大きなリポジトリや、各条件3回より多い繰り返しでの差。
  • ~/.codex/AGENTS.md(全プロジェクト共通)と、プロジェクトの指示の組み合わせ。
  • Cursor・Gemini CLI など、ほかのツールでの読み込み。

Codex CLIそのものの導入と使い方は、Codex CLIの使い方、Claude Codeの料金はClaude Codeの料金にまとめています。社内でAIコーディングツールを入れるかどうかで迷っている場合は、AI活用診断で今の業務に合う使い方を確かめられます。

よくある質問

Q. AGENTS.mdとは何ですか?

AIコーディングエージェントに、作業のたびに読ませる指示を書くMarkdownファイルです。テストの実行方法、触ってはいけない場所、コードの書き方などを書きます。Codex、Cursor、Gemini CLI、Claude Code(CLAUDE.md がない場合)などが読みます。

Q. AGENTS.mdはどこに置けばいいですか?

まずはリポジトリのルートに1つ置きます。Codexは、Gitのルートから作業フォルダまでの各階層のAGENTS.mdを上から順に読み、近いものほど優先します。編集部の実測では、Gitで管理していないフォルダでは、親フォルダのAGENTS.mdは読まれませんでした。

Q. CLAUDE.mdとAGENTS.mdは両方必要ですか?

両方のツールを使うなら、本文はAGENTS.mdに書き、CLAUDE.mdには @AGENTS.md と1行書く方法が確実です。Claude Codeは CLAUDE.md があると AGENTS.md を読まず、Codexは既定で CLAUDE.md を読まないためです。

Q. AGENTS.mdはどのくらいの長さまで読まれますか?

Codexでは既定で合計32KiB(32,768バイト)までです。編集部が40KBのファイルで試すと、310項目中253項目目の途中で警告なく切れました。project_doc_max_bytes で上限は上げられますが、長いほど毎回の入力トークンが増えます。

Q. AGENTS.mdを書き換えたのに反映されません。なぜですか?

Codexは、指示の読み込みを起動時に1回だけ行います。作業中のセッションには反映されないため、新しく起動し直してください。Gitの外で作業している、同じフォルダに AGENTS.override.md がある、32KiBを超えている、の3点も確かめてください。

Q. AGENTS.mdに何を書けば効果がありますか?

コードを読んでも分からないルールを、コマンドや場所まで具体的に書くと効きます。編集部の実測では、「最後に npm run check を通す」「CHANGELOG に1行書く」と書いた3回だけがそのとおりに動き、「適宜テスト」のようなあいまいな書き方は、書かない場合と結果が同じでした。

確認元(2026-11-02 確認)

仕様は変わることがあるため、最新情報は公式で確認してください。取得日はいずれも2026年11月2日(日本時間)です。

自社の業務にどのAIツールの使い方が合うか、約3分で確かめる

全8問に答えると、AI 導入の準備度と、最初に試す活用アイデアがわかります。無料・登録不要です。

関連記事

すべてを表示