AGENTS.mdとは?書き方と置き場所、Codex・Claude Codeでの読まれ方【2026年11月】
AGENTS.mdはAIのコーディングエージェントに渡すプロジェクトの説明書です。何を書くか・書かない方がよいこと、置き場所と読み込み順、Codex・Claude Code・Cursor・GitHub Copilotでの読まれ方の違い、CLAUDE.mdとの使い分け、コピーして使える雛形、効かないときの確認点を公式ドキュメントで整理します。

本記事の情報について: 本記事は2026年11月12日時点で、AGENTS.mdの公式サイト(agents.md)、OpenAIのCodexのドキュメント、Claude Code・Cursor・GitHub Copilot・Google Antigravityの公式ドキュメント、AGENTS.mdの効果を調べた論文(arXiv 2602.11988)を確認して整理しています。公式資料を読み比べた内容で、筆者の環境ですべてのツールの動きを確かめたものではありません。各ツールは数週間おきに読み込みの仕組みが変わるため、使う前に各出典の最新の記載もご確認ください。
AGENTS.md(エージェンツ・エムディー)は、AIのコーディングエージェントに「このプロジェクトではこうしてほしい」を伝えるためのファイルです。テストを動かすコマンド、守ってほしいコードの書き方、触ってはいけないフォルダなどを書いてリポジトリに置いておくと、CodexやCursorなどのエージェントが作業を始めるときに自動で読み込みます。毎回チャットで同じ説明をしなくて済むようになります。
2026年の秋には、このファイルの扱いが大きく変わりました。Claude Codeは長くCLAUDE.mdという自分専用のファイルだけを読んでいましたが、2026年9月18日(米国時間)に公開された版から、CLAUDE.mdがないリポジトリではAGENTS.mdを読むようになりました。これで、主なコーディングエージェントのほとんどが同じファイルを読める状態になっています。一方で、「どこに置けば読まれるのか」「CLAUDE.mdと両方あるとどうなるのか」「何を書けば効くのか」は、ツールごとに少しずつ違います。
この記事では、AGENTS.mdとは何かから始めて、各ツールでの読まれ方、置き場所と読み込み順、書くべき項目と書かない方がよいこと、そのまま使える雛形、CLAUDE.mdと一緒に使うときの決め方、効かないときの確認点までを順に説明します。
この記事を読むとわかること
- AGENTS.mdとは: コーディングエージェント向けのREADMEのようなMarkdownのファイルです。決まった項目や書式はなく、見出しも自由に付けられます
- 読むツール: Codex、Cursor、GitHub Copilot、Google Antigravityなどが読みます。Claude Codeも、2026年9月の版から、CLAUDE.mdがないときに限ってAGENTS.mdを読みます
- 置き場所: 基本はリポジトリの直下です。下のフォルダに置くと、そのフォルダの作業だけに効く決まりを足せます。Codexには自分用の
~/.codex/AGENTS.mdもあります - 読み込み順: Codexは「自分用 → リポジトリの直下 → 作業中のフォルダ」の順につなげ、後ろに来るものほど優先します。合計は既定で32KiBまでです
- 書くべきこと: テストやビルドのコマンド、そのプロジェクトだけの決まり、やってはいけないことです。フォルダの一覧のような説明は、効果が小さいという研究があります
- CLAUDE.mdとの関係: 両方あると、Claude CodeはCLAUDE.mdだけを読みます。1つにまとめたいなら、CLAUDE.mdに
@AGENTS.mdと書いて取り込むのが確実です
どこから読むか
目的が決まっている方は、次の表から必要な節へ進んでください。
| 当てはまる状況 | 次に読むところ |
|---|---|
| AGENTS.mdが何か、まず知りたい | AGENTS.mdとは |
| 使っているツールが読むか確かめたい | AGENTS.mdを読むツールと読み方の違い |
| Codexでどこに置けばよいか知りたい | Codexでの置き場所と読み込み順 |
| Claude CodeでもAGENTS.mdを使いたい | Claude CodeでAGENTS.mdを使う |
| 何を書けばよいかわからない | 書くべきことと、書かない方がよいこと |
| すぐに使えるひな形がほしい | コピーして使える雛形 |
| CLAUDE.mdもあって、どちらに書くか迷う | CLAUDE.mdと一緒に使うときの決め方 |
| 書いたのに守られない | 効かないときの確認点 |
AGENTS.mdとは:コーディングエージェントに渡すプロジェクトの説明書
AGENTS.mdは、コーディングエージェントに作業の前提を伝えるための、決まった形のないMarkdownのファイルです。公式サイトのagents.mdは、自らを「エージェントのためのREADME」と説明しています。
ここで言うコーディングエージェントは、指示を受けて自分でファイルを読み書きし、テストなどのコマンドを実行しながら作業を進めるAIのことです。OpenAIのCodex、AnthropicのClaude Code、Cursor、GitHub Copilotなどが当てはまります。エージェントは賢くても、そのリポジトリのことは何も知らない状態で作業を始めます。テストのコマンドが npm test なのか pnpm test なのか、どのフォルダを触ってはいけないのかを知らないまま作業すると、的外れな変更が返ってきます。AGENTS.mdは、その前提を毎回自動で渡すための置き手紙です。
READMEとの違い
人のために書くREADMEと、エージェントのために書くAGENTS.mdは、読み手が違うため書く中身も変わります。agents.mdの公式サイトでは、READMEは人の読み手のためにすっきりさせておき、エージェントが要るビルドの手順やテスト、コードの決まりはAGENTS.mdに分けるよう勧めています。
| README | AGENTS.md | |
|---|---|---|
| 主な読み手 | 人(使う人・新しく入る開発者) | コーディングエージェント |
| 書く中身 | 何のためのものか、使い方、始め方 | コマンド、コードの決まり、やってはいけないこと |
| 読まれ方 | 人が必要なときに開く | エージェントが作業の始めに自動で読む |
| 長さの考え方 | 読みやすければ長くてもよい | 毎回読まれるので短く保つ |
形式の決まりと、管理している団体
AGENTS.mdには、必ず入れる項目や決まった書式がありません。公式サイトのよくある質問でも、ただのMarkdownで、見出しは何を使ってもよいと答えています。CLAUDE.mdのように取り込みの書き方(@ でほかのファイルを読む)を持つツールもありますが、それはツールごとの機能で、AGENTS.mdそのものの決まりではありません。
2026年11月時点の公式サイトには、AGENTS.mdはLinux Foundationの下にあるAgentic AI Foundationが管理していると書かれ、6万を超えるオープンソースのプロジェクトで使われているとあります。特定の会社のファイルではなくなったため、ツールを乗り換えても書いた内容をそのまま使い続けられるのが大きな利点です。
AGENTS.mdを読むツールと読み方の違い
主なコーディングエージェントはAGENTS.mdを読みますが、どこまで読むかと、ほかの指示ファイルとの関係はツールごとに違います。2026年11月12日時点の各社の公式ドキュメントで確かめた内容は次のとおりです。
| ツール | AGENTS.mdを読む場所 | ほかの指示ファイルとの関係 | 出典 |
|---|---|---|---|
| Codex(OpenAI) | ~/.codex/AGENTS.md、リポジトリの直下から作業中のフォルダまでの各フォルダ | フォルダごとに1つだけ読み、AGENTS.override.md があればそちらを優先 | Custom instructions with AGENTS.md |
| Claude Code(Anthropic) | 作業中のフォルダとその上、作業中に開いた下のフォルダ | 既定ではCLAUDE.mdがないときだけ読む。設定で両方読ませることもできる | Claude Code Docs - Memory |
| Cursor | プロジェクトの直下と下のフォルダ | .cursor/rules の代わりに使える、設定項目のないルールとして扱う | Cursor Docs - Rules |
| GitHub Copilot | リポジトリの中のどこでも(いちばん近いものを優先) | .github/copilot-instructions.md などと並ぶ指示ファイルの1つ | GitHub Docs - Adding repository custom instructions |
| GitHub Copilot CLI | リポジトリの直下、作業中のフォルダ、その間のフォルダ | CLAUDE.md・GEMINI.mdと組み合わせて読み、決まった優先順はない | GitHub Docs - Copilot CLI custom instructions |
| Google Antigravity | ~/.gemini/AGENTS.md、作業フォルダとその上(リポジトリの直下まで) | GEMINI.mdと足し合わせて読む。作業フォルダより下は読まない | Antigravity Docs - Rules |
このほか、agents.mdの公式サイトには、GoogleのJules、Aider、Zed、Warp、Devin、JetBrainsのJunie、Windsurfなど20を超えるツールの名前が載っています。Aiderのように、設定ファイルでAGENTS.mdを読むよう指定する必要があるツールもあります。
表を見ると、違いは大きく2つに分かれます。1つは「下のフォルダのAGENTS.mdを読むか」です。CodexやCursorは下のフォルダの分も読みますが、Antigravityは作業フォルダより下を読みません。もう1つは「ほかの指示ファイルと並んだときにどうなるか」です。Claude CodeはCLAUDE.mdがあるとAGENTS.mdを読まず、Copilot CLIやAntigravityは全部を足し合わせます。複数のツールを使うチームでは、この違いを知らないと「あるツールでは効くのに別のツールでは効かない」が起きます。
Cursorでの決まりの書き方(.cursor/rules とAGENTS.mdの使い分け)は、Cursorの使い方のルールの節でも説明しています。
Codexでの置き場所と読み込み順
Codexは、自分用・リポジトリの直下・作業中のフォルダの順にAGENTS.mdを集め、1つの指示につなげてから作業を始めます。読み込みの決まりは、OpenAIのドキュメント「Custom instructions with AGENTS.md」に書かれています。以前の developers.openai.com のページは、2026年11月時点でこのページに転送されます。
3つの置き場所
| 置き場所 | 効く範囲 | 主な使い道 |
|---|---|---|
~/.codex/AGENTS.md | 自分のすべてのプロジェクト | 返答の言語、自分の作業の好み |
リポジトリの直下の AGENTS.md | そのリポジトリ全体 | チームで共有するコマンドと決まり |
下のフォルダの AGENTS.md | そのフォルダで作業するとき | モノレポの各パッケージだけの決まり |
自分用の置き場所は、Codexの設定を置くフォルダ(既定は ~/.codex)です。環境変数 CODEX_HOME で場所を変えている場合はそちらが使われるため、思った場所のファイルが読まれないときは echo $CODEX_HOME で確かめるよう公式は勧めています。
つなげる順番と優先
Codexの読み込みには、次の決まりがあります。
- 自分用は1つだけ:
~/.codexではAGENTS.override.mdがあればそれを、なければAGENTS.mdを読みます。中身が空でない最初の1つだけを使います - リポジトリはGitの直下から下りていく: プロジェクトの直下(ふつうはGitのリポジトリの直下)から、作業中のフォルダまで1つずつ下りながら探します。作業中のフォルダに着いたら探すのをやめるので、それより下のフォルダのファイルは、そこで起動しない限り読まれません
- 1つのフォルダから読むのは1つだけ: 各フォルダで
AGENTS.override.md、AGENTS.md、設定で足したファイル名の順に探し、最初に見つかった1つだけを読みます。上の図のpackages/webのように override があると、同じフォルダのAGENTS.mdは読まれません - 後ろに来るものほど優先: 見つかったファイルは上のフォルダから順に、空行をはさんでつなげられます。作業中のフォルダに近いファイルほど後ろに入るため、前の指示より優先されます
- 合計の上限は32KiB: つなげた合計が設定
project_doc_max_bytes(既定は32KiB=32,768バイト)に達すると、それ以降のファイルは足されません。日本語は1文字がおよそ3バイトなので、日本語だけで書くと1万文字ほどが目安です
AGENTS.override.md は、一時的に別の決まりで作業したいときや、そのフォルダだけ上の決まりと違う運用をしたいときに使います。ただし、override を置くと同じフォルダの AGENTS.md は完全に無視されるので、残したい内容は override 側にも書き写す必要があります。
ほかのファイル名を読ませる設定
チームですでに別の名前の指示ファイルを使っている場合は、~/.codex/config.toml の project_doc_fallback_filenames に名前を足すと、AGENTS.mdがないフォルダでそのファイルを読みます。
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
この一覧にない名前のファイルは、指示ファイルとしては読まれません。たとえば AGENTS.frontend.md のように名前を変えて分けても、Codexは読み込みません。決まりを分けたいときは、ファイル名ではなく置くフォルダで分けます。config.toml のほかの設定は、Codexのconfig.tomlの書き方にまとめています。
コードレビューの決まりも書ける
Codexのドキュメントには、コードレビューのときに守らせたい決まりを、対象のコードにいちばん近いAGENTS.mdの ## Code Review Rules という見出しの下に書く方法も載っています。「レビューでは、テストを足していない変更を必ず指摘する」のような決まりを、普段の作業の決まりとは分けて書けます。
Claude CodeでAGENTS.mdを使う
Claude Codeは、2026年9月18日(米国時間)公開のv2.1.277から、CLAUDE.mdがないリポジトリではAGENTS.mdを読むようになりました。Claude Codeの変更履歴のv2.1.277の項に、CLAUDE.mdがないプロジェクトではAGENTS.mdを代わりに読み、/config の「Project instructions」で変えられると書かれています(公開日はnpmの公開記録で確認)。
どの組み合わせで何が読まれるか
Claude Codeの公式ドキュメントによると、既定の設定で読まれるファイルは上の図の3つの場合に分かれます。注意したいのは真ん中の場合です。作業中のフォルダかその上に CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md のどれかが1つでもあると、AGENTS.mdは読まれません。
特に見落としやすいのが CLAUDE.local.md です。これはGitに入れない自分用のメモとして使うファイルですが、これを1つ置いただけで、チームのAGENTS.mdが自分だけ読まれなくなります。一方、~/.claude/CLAUDE.md(自分用の全体の設定)、会社が配る管理用のCLAUDE.md、.claude/rules/ のファイルは判定に数えられず、AGENTS.mdと一緒に読まれます。
読み込まれたかどうかは、会話の中に表示される no CLAUDE.md found; AGENTS.md loaded: のあとにファイルの場所が続く1行で確かめられます。作業中に下のフォルダのファイルを開いたときは、そのフォルダに自分のCLAUDE.mdがなければ、そのフォルダのAGENTS.mdも読まれます。
読むファイルを設定で変える
セッションの中で /config を開き、「Project instructions」を次のどれかにすると、読むファイルを変えられます。
| 設定の値 | 読むもの |
|---|---|
claude-md-or-agents-md | CLAUDE.md。ない場合だけAGENTS.md(既定) |
claude-md-and-agents-md | CLAUDE.mdとAGENTS.mdの両方。各フォルダでCLAUDE.mdを先に、AGENTS.mdを後に読む |
claude-md | CLAUDE.mdだけ |
managed-only | 会社が配る管理用のCLAUDE.mdと自動メモだけ |
CLAUDE.local.md を使いながらAGENTS.mdも読ませたい場合は、claude-md-and-agents-md にします。同じAGENTS.mdを取り込みやリンクですでに読んでいる場合は、二重には読まれません。
AGENTS.mdを読めない場合
次の場合、Claude CodeはCLAUDE.mdしか読まず、「Project instructions」の設定も表示されません。
- v2.1.277より前の版を使っている
/pluginで、AGENTS.mdを読む組み込みのプラグインを止めている- v2.1.276以前から更新した直後の最初のセッション(次のセッションから読みます)
v2.1.281より前は、Amazon Bedrockを使うセッションや、利用状況の送信を止めたセッションでも読めませんでした。古い版を使い続ける事情がある場合は、次の章で説明する @AGENTS.md の取り込みを使います。
CLAUDE.mdとの違い
設定で読ませたAGENTS.mdは、CLAUDE.mdとまったく同じには扱われません。公式ドキュメントでは、指示ファイルが読み込まれたときに動く InstructionsLoaded のフックが動かない点と、環境変数 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD を設定して --add-dir で足したフォルダでは、CLAUDE.mdは読まれるのにAGENTS.mdは読まれない点が違いとして挙げられています。フックを使って読み込みを記録している場合や、複数のフォルダをまたいで作業する場合は、CLAUDE.mdからの取り込みにしておく方が確実です。
書くべきことと、書かない方がよいこと
AGENTS.mdには、エージェントが自分では調べにくい、そのプロジェクトだけの事情を短く書きます。agents.mdの公式サイトは、プロジェクトの概要、ビルドとテストのコマンド、コードの書き方、テストの方法、セキュリティの注意を書く例に挙げ、コミットやプルリクエストの決まり、デプロイの手順を足してもよいとしています。
書きすぎると逆効果になるという研究
一方で、AGENTS.mdを入れれば作業がうまくいくとは限らない、という研究もあります。スイス連邦工科大学チューリッヒ校(ETH Zurich)とLogicStar.aiの研究者が2026年2月に公開し、9月に改訂した論文「Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?」は、AGENTS.mdのような指示ファイルを渡しても、課題を解ける割合は全体としては上がらず、処理にかかる費用は平均で20%以上増えたと報告しています。
論文によると、エージェントは指示ファイルに書かれたことをよく守ります。ただ、「リポジトリの全体の説明」のように、各社が書くよう勧めてきた内容は役に立っていませんでした。指示に従って余計に広く調べるぶん、手間と費用が増えるためです。著者らは、指示ファイルが役に立つのは「そのプロジェクトだけの、一般的ではないやり方」を伝える場面だとまとめています。また、開発者が書いたファイルはAIが作ったファイルより平均で7%よい結果でした。著者らは、AIが作った指示ファイルは当面使わず、人が書くファイルもREADMEに書かれていない決まり(独自の書き方や、機能以外の要件)に絞るよう勧めています。
この研究はPythonのリポジトリを対象にしたもので、すべてのプロジェクトに当てはまるとは限りません。それでも、「長く詳しく書くほど良い」わけではないことははっきりしています。AIがリポジトリを見ればわかることは書かず、見てもわからないことだけを書くのが基本です。
書くこと・書かないことの目安
| 書くこと | 書かない方がよいこと |
|---|---|
| テスト・ビルド・型チェック・lintの正確なコマンド | フォルダの一覧や、ファイルを見ればわかる構成の説明 |
| 1ファイルだけテストするときのコマンド | 「きれいなコードを書く」のような誰にでも当てはまる心がけ |
| そのプロジェクトだけの決まり(使うライブラリ、命名の例外) | 言語やフレームワークの一般的な使い方の説明 |
| 触ってはいけないフォルダやファイル | パスワードやAPIキーなどの秘密の情報 |
| 社内の用語と、その意味 | 日によって変わる作業の指示(その都度チャットで伝える) |
| 変更が終わったときに必ず実行する確認 | ほかのファイルと食い違う古い決まり |
あいまいな書き方を、確かめられる書き方に直す
守られにくい指示の多くは、エージェントが「できたかどうか」を自分で確かめられない書き方になっています。次のように、実行できるコマンドや、ファイルの場所が入った書き方に直すと守られやすくなります。
| 守られにくい書き方 | 直した書き方 |
|---|---|
| テストをしっかり書くこと | 関数を足したら、同じフォルダに 〇〇.test.ts を作り、pnpm test -- そのファイル が通ることを確かめる |
| 既存のコードに合わせること | 日付の処理は src/lib/date.ts の関数を使う。新しい日付のライブラリは入れない |
| 危ない操作はしないこと | git push と、本番のデータベースにつながるコマンドは実行しない。必要なときは実行せずに手順を書いて返す |
| わかりやすい名前を付けること | 予約の時間の単位は「枠(frame)」と呼び、「slot」という名前は使わない |
直した書き方には、共通点が2つあります。1つは、守れたかどうかを見ればわかることです。もう1つは、そのプロジェクトを知らないと書けないことです。「テストをしっかり書く」はどのプロジェクトにも当てはまるため、エージェントにとっては新しい情報になりません。先の論文が役に立つとした「そのプロジェクトだけの、一般的ではないやり方」は、このような具体的な決まりのことです。
秘密の情報は、AGENTS.mdに書くとリポジトリを見られる人全員に見えるうえ、エージェントに毎回渡されます。キーの置き場所を書く必要があるときも、「.env.local に置く。中身は読まない」のように場所と扱いだけを書きます。
また、指示ファイルはエージェントへの「お願い」で、必ず守らせる仕組みではありません。Claude Codeの公式ドキュメントも、指示ファイルは設定ではなく文脈として扱われるため、どうしても止めたい操作はフックで防ぐよう書いています。「本番のデータベースに接続しない」のように絶対に守らせたいことは、AGENTS.mdに書いたうえで、権限やフックなどの仕組みでも止めておきます。
コピーして使える雛形
ここでは、小さなリポジトリ用と、複数のパッケージをまとめたモノレポ用の2つの雛形を紹介します。コマンドやフォルダ名は、自分のプロジェクトに合わせて書き換えてください。エージェントはコマンドをそのまま実行するので、実際に手元で動くことを確かめたものだけを書きます。
小さなリポジトリ用
# AGENTS.md
## このリポジトリについて
- 社内の予約管理画面。Next.js(App Router)と TypeScript で書いている
- パッケージ管理は pnpm。npm と yarn は使わない
## コマンド
- 開発サーバー: `pnpm dev`
- テスト(すべて): `pnpm test`
- テスト(1ファイル): `pnpm test -- src/lib/reserve.test.ts`
- 型チェック: `pnpm typecheck`
- lint: `pnpm lint`
## 変更を終える前に必ずすること
- 変えたファイルに関係するテストと `pnpm typecheck` を実行し、通ることを確かめる
- テストが通らないまま作業を終えない
## コードの決まり
- 入力のチェックは zod を使う(ほかのライブラリを足さない)
- 日付の処理は src/lib/date.ts の関数を使い、直接 Date を組み立てない
## やってはいけないこと
- src/legacy/ は触らない(2027年に削除予定)
- .env と .env.local の中身を読まない・書き換えない
- 新しいパッケージを入れるときは、入れる前に理由を書いて確認を取る
## 用語
- 枠: 予約を受け付ける時間の単位(30分)。「スロット」とは呼ばない
モノレポ用(リポジトリの直下)
# AGENTS.md
## 構成
- apps/web: 利用者向けの画面(このフォルダに AGENTS.md あり)
- apps/api: API サーバー(このフォルダに AGENTS.md あり)
- packages/shared: 共通の型と関数。apps 以外から import しない
## 全体で共通のコマンド
- すべてのテスト: `pnpm -r test`
- 1つのパッケージだけ: `pnpm --filter web test`
## 全体で共通の決まり
- 共通の型は packages/shared に置き、apps の中で同じ型を作らない
- コミットのメッセージは「feat: 〜」「fix: 〜」の形にする
モノレポ用(下のフォルダ、apps/api/AGENTS.md)
# apps/api の決まり
## コマンド
- テスト: `pnpm --filter api test`
- データベースを使うテストは `pnpm --filter api test:db`(Docker が必要)
## 決まり
- データベースの変更は migrations/ にファイルを足して行う。既存のファイルは書き換えない
- 外部のAPIを呼ぶ処理は src/clients/ に置く
## Code Review Rules
- データベースの変更にロールバックの手順が書かれていなければ指摘する
下のフォルダのAGENTS.mdには、そのフォルダだけの決まりを書き、直下と同じことは繰り返しません。CodexやCursorは上のフォルダの内容とつなげて読むため、同じことを2回書くとそのぶん上限を使い、片方だけ直したときに食い違いの原因になります。なお、AntigravityやClaude Codeの既定の動きでは、下のフォルダのファイルが読まれる条件が違います。どのツールでも必ず守らせたいことは、直下のAGENTS.mdに書いておきます。
AIにリポジトリを調べさせてAGENTS.mdの下書きを作ることもできます。ただし先の論文では、AIが作ったファイルは開発者が書いたファイルより結果が悪く、著者らはそのまま使わないよう勧めています。下書きを使う場合も、フォルダの説明のような部分は削り、人が知っている「そのプロジェクトだけの事情」に書き直してから使います。
CLAUDE.mdと一緒に使うときの決め方
CodexとClaude Codeの両方を使うチームでは、AGENTS.mdを決まりの正本にし、CLAUDE.mdからはそれを取り込むだけにするのが、2026年11月時点でいちばん食い違いが起きにくい形です。両方のファイルに同じ内容を書き写すと、片方だけが更新されて、ツールによって守る決まりが違う状態になりがちです。
3つのやり方の比べ方
| やり方 | 書き方 | 向いている場合 | 注意点 |
|---|---|---|---|
| AGENTS.mdだけを置く | CLAUDE.mdを置かない | Claude Codeをv2.1.277以降で使い、Claude Code専用の決まりがない | 誰かが CLAUDE.local.md を置くと、その人だけAGENTS.mdが読まれなくなる |
| CLAUDE.mdから取り込む | CLAUDE.mdの先頭に @AGENTS.md と書く | Claude Code専用の決まりもある、古い版の人もいる | CLAUDE.mdの方にAGENTS.mdと同じ内容を書かない |
| リンクを張る | ln -s AGENTS.md CLAUDE.md | 全員がmacOSかLinux | Windowsではリンクが普通のファイルとして取り出されることがある |
Claude Codeの公式ドキュメントがすすめる取り込みの書き方は、次のとおりです。
@AGENTS.md
## Claude Code だけの決まり
- 計画が必要な作業は plan mode で始める
- src/billing/ の変更は、変更の前に必ず確認を取る
Claude Codeは取り込んだAGENTS.mdを先に読み、そのあとにCLAUDE.mdの残りの部分を読みます。取り込みは何重にもできますが、深さは4段までです。
リンクを張るやり方には、2つの注意点があります。1つは、Claude Codeはリンク経由でCLAUDE.mdを読めますが、書き換えるときはリンク先のAGENTS.mdを直すよう案内される点です。もう1つはWindowsです。Windowsでリンクを作るには管理者の権限か開発者モードが要り、Gitの設定によってはリンクが1行だけの普通のファイルとして取り出されて、その人のCLAUDE.mdが中身のないファイルになります。Windowsを使う人がいるなら、取り込みのやり方にします。
以前の回避策の片付け方
Claude CodeがAGENTS.mdを読むようになる前に、別の方法で読ませていた場合は、公式ドキュメントに片付け方が載っています。
- CLAUDE.mdに
@AGENTS.mdと書いている: そのままでかまいません。二重に読まれることはありません - CLAUDE.mdに「AGENTS.mdを読むこと」と文章で書いている: Claude Codeがそのファイルを開こうと判断したときしか読まれません。CLAUDE.mdを消すか、
@AGENTS.mdの取り込みに書き換えます - CLAUDE.mdをAGENTS.mdへのリンクにしている: そのままでも、リンクを消してもかまいません
- セッションの開始時にAGENTS.mdを表示するフックを入れている: 外します。そのままだと、同じ内容が2回渡されます
2つ目の「文章で読むよう頼む」やり方は、以前はよく紹介されていましたが、確実ではありません。いま使っている場合は、取り込みの形に直しておくのがおすすめです。CLAUDE.md自体に何を書くかはCLAUDE.mdの書き方で、CodexとClaude Codeを仕事でどう振り分けるかはClaude CodeとCodexの併用ワークフローで説明しています。
効かないときの確認点
AGENTS.mdを書いたのに守られないときは、まず「そもそも読まれているか」を確かめ、読まれているなら「中身が食い違っていないか」を見ます。よくある原因と確かめ方は次のとおりです。
| 起きていること | 考えられる原因 | 確かめること |
|---|---|---|
| Claude Codeがまったく従わない | CLAUDE.mdかCLAUDE.local.mdがあり、AGENTS.mdが読まれていない | 会話の最初の AGENTS.md loaded の表示、/config の「Project instructions」 |
| Claude Codeの版が古い | v2.1.277より前の版を使っている | claude --version。古い版を使い続けるなら @AGENTS.md で取り込む |
| Codexで下のフォルダの決まりが効かない | 上のフォルダでCodexを起動している | 決まりを効かせたいフォルダで起動し直す(codex --cd でも指定できる) |
| Codexでファイルの後半が効かない | 合計が32KiBを超えて、途中から足されていない | ファイルの大きさを確かめ、短くするか下のフォルダに分ける |
| 名前を変えたファイルが読まれない | AGENTS.frontend.md など、読む一覧にない名前 | ファイル名を AGENTS.md に戻すか、project_doc_fallback_filenames に足す |
| 自分用の設定が読まれない | CODEX_HOME で設定のフォルダが変わっている | echo $CODEX_HOME |
| 直したのに前の内容で動く | 作業の途中で書き換えた | 新しいセッションを始める(Codexは起動のたびに読み直す) |
| ツールによって守ったり守らなかったりする | ツールごとに読むファイルと範囲が違う | 守らせたいことを直下のAGENTS.mdに書き、ほかの指示ファイルと食い違いがないか見る |
Codexでは、何が読まれているかをCodex自身に確かめさせる方法が公式に載っています。リポジトリの直下で codex --ask-for-approval never "Summarize the current instructions." のように頼むと、自分用とリポジトリの決まりをまとめて答えます。Codexは指示ファイルを覚えておく仕組みを持たず、起動のたびに読み直すため、書き換えたあとは起動し直せば反映されます。
GitHub Copilot CLIでは、/instructions で今のセッションが読んでいる指示ファイルを一覧でき、1つずつ外すこともできます。Copilot CLIは複数の指示ファイルを組み合わせて読みますが、どれを優先するかの順番は決まっていないと公式が書いています。CLAUDE.mdとAGENTS.mdに逆のことが書いてあると、どちらに従うかはわかりません。
チームで使い続けるための決まり
AGENTS.mdは、一度書いて終わりではなく、コマンドや決まりが変わるたびに直していくファイルです。チームで使い続けるには、次の点を決めておくと食い違いが起きにくくなります。
- 普通のコードと同じように確認を通す: AGENTS.mdの変更は、チーム全員のエージェントの動きを変えます。コードと同じく、変更は誰かが読んでから取り込みます
- コマンドを変えたら同じ変更で直す: テストのコマンドやパッケージ管理の道具を変えたときに、AGENTS.mdを直し忘れるのがいちばん多い食い違いです。コマンドを変える変更の中で、AGENTS.mdも一緒に直します
- エージェントが同じ間違いを繰り返したら1行足す: 毎回同じ指摘をしている決まりは、AGENTS.mdに足す候補です。逆に、誰も困っていない決まりは消して短く保ちます
- 正本を1つに決める: AGENTS.md、CLAUDE.md、
.github/copilot-instructions.md、.cursor/rulesのどれを正本にするかを決め、ほかからはそれを取り込むか、ツール専用のことだけを書きます
複数のツールを並べて使う場合は、どの決まりをどのファイルに書いたかを1か所にまとめておくと、新しく入った人も迷いません。
よくある質問
まとめ
- AGENTS.mdは、コーディングエージェントにプロジェクトの決まりを伝える、決まった形のないMarkdownのファイル。Linux Foundationの下のAgentic AI Foundationが管理している
- Codex・Cursor・GitHub Copilot・Antigravityなどが読む。Claude Codeはv2.1.277(2026年9月18日公開)から、CLAUDE.mdがないときだけ読む
- Codexは自分用 → リポジトリの直下 → 作業中のフォルダの順につなげ、後ろほど優先する。フォルダごとに1つだけ読み、合計は既定で32KiBまで
- 書くのは、正確なコマンド、プロジェクトだけの決まり、やってはいけないこと。フォルダの説明のような見ればわかることは書かない
- CLAUDE.mdもある場合は、AGENTS.mdを正本にしてCLAUDE.mdに
@AGENTS.mdと書くのが確実。CLAUDE.local.mdを置くとAGENTS.mdが読まれなくなる点に注意する - 効かないときは、読まれているかを先に確かめ、次にファイル同士の食い違いを見る
Claude CodeやCodexを社内に導入するときの指示ファイルの決め方や、どこまでエージェントに任せるかの線引きについて相談先をお探しの場合は、koromoのAI 顧問サービスをご覧ください。
参考:
- AGENTS.md 公式サイト・agentsmd/agents.md(GitHub)
- OpenAI「Custom instructions with AGENTS.md」
- Claude Code Docs - How Claude remembers your project・Claude Code 変更履歴・npm @anthropic-ai/claude-code の公開記録
- Cursor Docs - Rules
- GitHub Docs - Adding repository custom instructions for GitHub Copilot・Copilot CLI のカスタム指示
- Google Antigravity Docs - Rules
- Gloaguen ほか「Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?」(arXiv 2602.11988)
Codex をチームや自社の開発に広げるなら
Codex を個人の開発環境で使っていて、手元で解決できたなら、ここまでで十分です。
チームへの展開や、開発そのものの依頼を検討している立場の方は、次の窓口から相談できます。
初回の壁打ち(30分)は無料です。





