AGENTS.mdは、AIのコーディングエージェントに「このプロジェクトではこう動いてほしい」と伝えるための説明書です。
フォルダの一番上に置いておくと、Claude CodeやCodexのようなエージェントが作業を始める前に読み、その内容を前提に動きます。
毎回のチャットで「テストはこのコマンドで」「この書き方は使わないで」と説明し直していた人ほど、置いた翌日から手間が減ります。
一方で、書いたのに読まれていないという声もよく聞きます。
原因は、たいてい書き方とは別のところにあります。ツールごとに「どの名前のファイルを、どの場所から、どんな条件で読むか」が少しずつ違うことにあります。
2026年9月18日には、Claude Codeのバージョン2.1.277がAGENTS.mdを直接読むようになりました。ただし、同じフォルダにCLAUDE.mdがあると、既定ではAGENTS.mdは読まれません。
この記事では、AGENTS.mdの役割と置き場所、最初に書く3項目、日本語で使えるひな形、そしてClaude CodeとCodexで実際に読まれているかを確かめる手順までを順番に整理します。
開発者だけでなく、記事制作や資料づくりにエージェントを使っている人にも使える形でまとめました。
AGENTS.mdとは AIエージェントのための説明書
中身は、Markdownという書式で書く、ただのテキストファイルです。
特別な設定項目や決まった欄はありません。見出しと箇条書きで、エージェントに知っておいてほしいことを書くだけです。
公式サイトでは、この形式を「コーディングエージェントを導くための、シンプルで開かれた形式」と説明しています。
開かれた形式というのは、特定の会社のツール専用ではないという意味です。1枚書けば、対応している複数のエージェントが同じ内容を読みます。
READMEとの違い
プロジェクトには、もともとREADMEという説明書があります。READMEは人間の読み手に向けたもので、概要や使い始め方を書く場所です。
こちらは、エージェントにしか必要のない細かい情報を置く場所として分けられています。
たとえば「コミット前にこのテストを必ず通す」「この古いフォルダは触らない」といった内容は、人間の新メンバーには口頭で伝えれば済みます。エージェントには毎回伝え直す必要があるので、ファイルに書いておく意味が大きくなります。
| ファイル | 主な読み手 | 書くこと |
|---|---|---|
| README | 人間（利用者・新しく入った人） | 何のためのプロジェクトか、使い始め方、問い合わせ先 |
| AGENTS.md | 複数のAIエージェント | 実行するコマンド、確認方法、守るべき書き方、触ってはいけない場所 |
| CLAUDE.md | Claude Code | AGENTS.mdと同じ種類の内容。Claude Codeにだけ伝えたい追加の指示 |
| チャットでの指示 | その場のエージェント | 今回の作業だけに関わる依頼。ファイルの内容より優先される |
どのツールが読むのか
AGENTS.mdは、OpenAIが2025年8月に専用サイトを公開して広めた形式です。Codexは最初から対応しており、その後、主なコーディングエージェントやエディタが次々に読み込みに対応しました。
Claude Codeは長くCLAUDE.mdだけを読む作りでしたが、2026年9月18日のバージョン2.1.277から、条件つきでAGENTS.mdを直接読むようになりました。
この記事では、利用者の多いClaude CodeとCodexの2つに絞って、読み込みの決まりを細かく見ていきます。
誰が管理している形式なのか
この形式は現在、Linux Foundationの下に設けられたAgentic AI Foundationが管理しています。
Linux Foundationが2025年12月9日に公表した発表では、設立時の中心となる取り組みとして、AnthropicのMCP、OpenAIのAGENTS.mdなど3つが挙げられました。
同じ発表には「AGENTS.mdは、すでに6万を超えるオープンソースのプロジェクトとエージェントの枠組みで採用されている」とあります（英語の原文を訳したもの）。
1つの会社の都合で仕様が急に変わりにくい場所に置かれたことで、長く使える前提で書き始めやすくなりました。
なぜ今AGENTS.mdを書くのか
理由は2つあります。1つ目は、エージェントを使う場面が増え、同じ説明を繰り返す回数が目に見えて増えたことです。
2つ目は、2026年9月のClaude Codeの対応で、CodexとClaude Codeの両方に1枚で伝えられるようになったことです。
毎回の説明が要らなくなる
エージェントは、会話を始めるたびに何も覚えていない状態から始まります。
Anthropicの公式ドキュメントも、Claude Codeの各セッションは「まっさらな状態から始まる」と書いています。前回の会話で教えたことは、ファイルに残しておかない限り次の会話には引き継がれません。
この「毎回ゼロから」の不便を埋めるのが、エージェント向けの説明書です。作業の前提を1回書いておけば、エージェントは会話の最初にそれを読み込みます。
1枚で複数のツールに伝わる
以前は、Claude Code用にCLAUDE.md、Codex用にAGENTS.md、エディタ用にまた別のファイルと、ツールの数だけ説明書を書き分ける必要がありました。
内容はほぼ同じなのに、片方だけ直してもう片方が古いまま残る、という事故も起きやすい形です。
1枚にまとめれば、直す場所は1か所になります。複数のツールを使い分けている人ほど、ここで手間が大きく減ります。
チームの中で動きがそろう
同じリポジトリを複数の人が触る場合、エージェントへの頼み方は人によって違います。ある人は毎回テストを指示し、別の人は何も言わない、ということが普通に起きます。
説明書をリポジトリに入れておけば、誰がどのツールで頼んでも、エージェントは同じ前提から作業を始めます。
決まりを変えたいときも、ファイルの変更として履歴に残るので、いつ誰が何を変えたのかを後から追えます。
| いまの状況 | 起きていること | 次にすること |
|---|---|---|
| Claude Codeだけを使っている | CLAUDE.mdで足りている | 急いで移す必要はない。他のツールを使い始めたら移す |
| CodexとClaude Codeを両方使う | 同じ説明を2つのファイルに書いている | 中身をAGENTS.mdにまとめ、CLAUDE.mdからは取り込む形にする |
| チームで別々のツールを使う | 人によってエージェントの動きが違う | AGENTS.mdを共通の決まりとして、リポジトリに入れて共有する |
| 説明書をまだ何も書いていない | 毎回チャットで前提を説明している | AGENTS.mdを1枚、3項目だけで作る |
| 説明書が長くなりすぎた | 書いたことが守られない場面が増えた | 200行を目安に削り、細かい手順は別ファイルへ分ける |
AGENTS.mdを置く場所と読み込まれる順番
基本は、プロジェクトのフォルダの一番上に1枚置くだけです。Gitで管理しているなら、リポジトリのルートがその場所になります。
まずは一番上に1枚
最初から複数のファイルに分ける必要はありません。一番上の1枚に、プロジェクト全体で守ることを書きます。
ファイル名は大文字で「AGENTS.md」とします。「Agents.md」や「agents.md」のように表記を変えると、読まないツールが出てきます。
下の階層ほど優先される
大きなプロジェクトでは、サブフォルダごとにも説明書を置けます。たとえば画面側と裏側の処理でルールが違う場合に、それぞれのフォルダへ1枚ずつ置く使い方です。
ルールがぶつかったときの決まりについて、公式サイトは「編集しているファイルにいちばん近いAGENTS.mdが優先され、チャットでの明示的な指示はすべてに優先する」と書いています。
家全体の決まりがあり、部屋ごとの決まりがあり、その場で頼まれたことが一番強い、という順番だと考えると覚えやすくなります。
たとえば、一番上の説明書に「テストは npm test で回す」と書き、画面側のフォルダの説明書に「このフォルダでは npm run test:web を使う」と書いたとします。
画面側のファイルを直しているあいだは、近いほうの「npm run test:web」が使われます。それ以外の場所では、一番上の決まりがそのまま効きます。
この仕組みを知っていれば、全体の決まりを細かい例外で埋めずに済みます。例外は、例外が起きる場所の近くに置けばよいからです。
自分だけの指示はどこに書くか
この説明書は、リポジトリに入れて共有するのが前提です。自分の端末だけで使う設定や、個人の好みは書かないほうが扱いやすくなります。
個人用の指示は、ツールごとの全体設定に書きます。Claude Codeならホームフォルダの「~/.claude/CLAUDE.md」、Codexなら「~/.codex/AGENTS.md」がその場所です。
| 置き場所 | 効く範囲 | 書くこと |
|---|---|---|
| リポジトリの一番上 | プロジェクト全体 | 全員が守る決まり、よく使うコマンド、確認の方法 |
| サブフォルダ | そのフォルダの中の作業 | その部分だけの書き方、使う道具の違い |
| ホームフォルダの全体設定 | 自分が開くすべてのプロジェクト | 自分の好み、言葉づかい、いつも使う手順 |
| チャットでの指示 | その会話だけ | 今回だけの依頼や例外。ファイルの決まりより優先される |
Claude CodeがAGENTS.mdを読む条件
Claude Codeを使っている人が一番つまずくのが、この読み込みの条件です。
Anthropicの公式ドキュメントには「既定では、作業フォルダかその上の階層にCLAUDE.mdが無いときだけ、ClaudeはAGENTS.mdを読む」と書かれています。
つまり、CLAUDE.mdとAGENTS.mdが両方あるプロジェクトでは、何も設定しなければCLAUDE.mdだけが読まれます。せっかく丁寧に書いても、その内容はClaude Codeに届きません。
図の点線の矢印が、両方を残したいときの逃げ道です。CLAUDE.mdの中に取り込みの1行を書いておけば、AGENTS.mdの内容もCLAUDE.mdと一緒に読まれます。
CLAUDE.mdがあるとAGENTS.mdは読まれない
「CLAUDE.mdがあるかどうか」を判定するときに数に入るファイルは決まっています。
作業フォルダか、その上の階層にあるCLAUDE.md、.claudeフォルダの中のCLAUDE.md、そしてCLAUDE.local.mdの3種類です。
ホームフォルダにある個人用の「~/.claude/CLAUDE.md」と、組織が配布する管理用のCLAUDE.mdは数に入りません。この2つはAGENTS.mdと一緒に読まれます。
見落としやすいのがCLAUDE.local.mdです。自分だけのメモのつもりで1枚置いただけで、AGENTS.mdが読まれなくなります。
| リポジトリにあるもの | Claude Codeが読むもの | 次にすること |
|---|---|---|
| AGENTS.mdだけ | AGENTS.md | そのままでよい。バージョンが2.1.277以降かだけ確かめる |
| AGENTS.mdとCLAUDE.md | CLAUDE.mdだけ | CLAUDE.mdの先頭に「@AGENTS.md」を書いて取り込む |
| AGENTS.mdとCLAUDE.local.md | CLAUDE.local.mdだけ | 設定で両方を読む形に変えるか、個人メモを全体設定へ移す |
| AGENTS.mdを取り込んだCLAUDE.md | CLAUDE.mdとAGENTS.mdの両方 | そのままでよい。二重には読まれない |
| CLAUDE.mdだけ | CLAUDE.md | 他のツールを使わないなら移す必要はない |
読まれない名前と置き場所
Claude Codeの公式ドキュメントには、読まないファイルもはっきり書かれています。AGENTS.local.md、AGENTS.override.md、そして「.agents」というフォルダの中にあるものは読みません。
とくに注意したいのが「.agents」フォルダです。ルールを整理するつもりで「.agents/AGENTS.md」のように1段下へしまうと、Claude Codeからは見えなくなります。
Claude Codeに読ませたいなら、置き場所はプロジェクトの一番上か、「.claude/AGENTS.md」に置きます。
サブフォルダに置いたものは、Claudeがそのフォルダの中のファイルを開いたときに追加で読まれます。ただし、そのフォルダに3種類のCLAUDE.mdのどれかがあれば、そちらが優先されます。
読む範囲を変える設定
既定の動きを変えたいときは、Claude Codeの中で「/config」と入力して設定画面を開き、「Project instructions」という項目を選びます。
| 設定の値 | 読むもの | 向いている人 |
|---|---|---|
| CLAUDE.mdかAGENTS.md（既定） | CLAUDE.mdがあればそれだけ。無ければAGENTS.md | どちらか一方だけを使っている人 |
| CLAUDE.mdとAGENTS.mdの両方 | フォルダごとにCLAUDE.mdを先に、AGENTS.mdを後に読む | 個人メモのCLAUDE.local.mdを残したい人 |
| CLAUDE.mdだけ | CLAUDE.mdだけ | Claude Code専用の書き方を続けたい人 |
| 組織の管理用だけ | 組織が配布したCLAUDE.mdと自動メモ | 会社の決まり以外を読ませたくない環境 |
設定を変えると、次に送るメッセージから反映されます。新しく始める会話にも同じ設定が使われます。
AGENTS.mdが読めない環境
次のような場合は、Claude CodeはCLAUDE.mdしか読みません。
バージョンが2.1.277より前のとき、設定画面で組み込みの「agents-md」プラグインを止めたとき、そして古い版から更新した直後の最初の会話です。公式ドキュメントでは、更新直後の会話では読まれないことがあり、次の会話から読まれると説明されています。
こうした環境でも中身を届けたいときは、CLAUDE.mdを1枚作り、その中で取り込みます。どの環境でも確実に届くので、迷ったときはこの形にしておくと安心です。
CodexでのAGENTS.mdの読み込み
Codexはこの形式を最初から使ってきたツールなので、読み込みの決まりはもう少し細かく作られています。
全体用と案件用の2段で読む
Codexは、まずホームフォルダの「~/.codex」にあるAGENTS.mdを読みます。ここが自分の全体設定にあたります。
次に案件側を読みます。OpenAIの公式ドキュメントは、その順番を「プロジェクトのルート（通常はGitのルート）から、現在の作業フォルダまで下りていく」と説明しています。
上から順に読んだ内容がつなげられ、下の階層に書かれたものほど後から効く形です。
たとえば、全体設定に「返事は日本語で」と書き、案件の説明書に「テストは npm test で回す」と書いておけば、Codexは両方を前提にして作業を始めます。
どの案件でも変わらない自分の好みは全体設定へ、案件ごとに違う決まりは案件側へ、と分けておくと、同じことを何か所にも書かずに済みます。
上書き用のファイルがある
Codexには、AGENTS.override.mdという上書き用のファイル名があります。同じフォルダにAGENTS.override.mdがあれば、AGENTS.mdよりそちらが先に選ばれます。
Codexが1つのフォルダから読むファイルは、多くても1枚です。上書き用、通常のAGENTS.md、設定で決めた別名の順に探し、見つかった1枚だけを使います。
先ほど見たとおり、Claude CodeはAGENTS.override.mdを読みません。両方のツールに届けたい決まりは、通常のAGENTS.mdのほうに書いておきます。
合計32KiBの上限
Codexには、読み込む指示の合計サイズに上限があります。既定は32KiBで、日本語ならおおよそ1万字前後です。
上限に届くと、そこから先のファイルは足されません。下の階層のファイルほど後から読まれるので、上の階層が長すぎると、一番近いはずの決まりが落ちてしまうことになります。
サブフォルダの決まりが急に効かなくなったと感じたら、まず上の階層の長さを疑います。
上限は設定ファイルで変えられますが、上げる前に削れる行がないかを先に見るほうが、エージェントの動きも安定します。
別の名前のファイルを読ませる
チームですでに別の名前の説明書を使っている場合は、Codexの設定ファイルに読み込む別名を登録できます。
OpenAIの公式ドキュメントでは、ホームフォルダの「~/.codex/config.toml」に別名を書く方法が紹介されています。登録した名前は、通常のAGENTS.mdが見つからないフォルダで使われます。
ただし、この別名はCodexだけの決まりです。Claude Codeにも同じ内容を届けたいなら、結局はAGENTS.mdという名前にそろえるのが近道です。
| 項目 | Claude Code | Codex |
|---|---|---|
| 個人の全体設定 | ~/.claude/CLAUDE.md | ~/.codex/AGENTS.md |
| AGENTS.mdを読む条件 | CLAUDE.mdが無いとき（設定で変更可） | 常に読む |
| 上書き用のファイル | 読まない | AGENTS.override.mdを優先して読む |
| サイズの目安・上限 | 1枚200行未満が目安 | 合計32KiBまで（設定で変更可） |
| 読まれたかの確かめ方 | /memory で一覧に出るか見る | 今の指示を要約させて確かめる |
AGENTS.mdに何を書くか 最初の3項目
書くことに迷ったら、最初は3項目だけで始めます。長く書くより、エージェントが作業中に何度も必要とする情報を短く置くほうが効きます。
1つ目は作業の目的と完成の条件
このプロジェクトが何のためのもので、どうなったら作業完了と言えるのかを書きます。
「テストがすべて通り、画面で表示が崩れていないこと」のように、終わりの形が分かると、エージェントは途中で止まらずに確認まで進みます。
2つ目は実行するコマンドと確認の方法
準備、実行、テスト、整形に使うコマンドを、そのままコピーできる形で書きます。
公式サイトでは、テストのコマンドを書いておけば、エージェントはそれを実行し、失敗したら直してから作業を終えようとすると説明されています。
確認の方法が書いていないと、エージェントは「たぶん動く」状態で作業を終えます。ここを書くだけで手戻りが目に見えて減ります。
3つ目はやってはいけないこと
触ってはいけないフォルダ、使わない書き方、勝手に実行してほしくない操作を書きます。
本番環境への反映や、データを消す操作のように、取り返しのつかないことは必ずここに入れます。ただし、後で説明するとおり、書いただけで確実に止められるわけではありません。
書かなくてよいこと
反対に、書かなくてよいものもあります。代表的なのは、ファイルを開けばエージェントが自分で読み取れる情報です。
フォルダの一覧、使っている部品の一覧、全体の作りの説明などは、書いても読み込みの量が増えるだけになりがちです。
Claude Codeの公式ドキュメントでも、点検の機能が削る候補として挙げるのは「コードから読み取れる内容」です。残すべきものとして挙げられているのは、つまずきやすい点、決まりの理由、一般的なやり方と違う約束ごとでした。
迷ったら「新しく入った人が、コードを読んでも分からないこと」だけを書く、と決めておくと線を引きやすくなります。
| 項目 | 書いていないと起きること | 書く内容の例 |
|---|---|---|
| 目的と完成の条件 | 途中で作業を止めて、こちらに確認を求めてくる | 何のためのものか、完了の判断基準 |
| コマンドと確認方法 | テストを回さずに「できました」と報告する | 準備・実行・テスト・整形のコマンド |
| やってはいけないこと | 古いフォルダや設定まで書き換えてしまう | 触らない場所、使わない書き方、事前に確認する操作 |
| （慣れてきたら）書き方の決まり | 人によって書き方がばらばらになる | 名前の付け方、文体、使う言葉 |
| （慣れてきたら）よくある失敗 | 同じ間違いを毎回くり返す | 過去に2回以上指摘したこと |
日本語で書くAGENTS.mdのひな形
説明書は日本語で書いてかまいません。チーム全員が日本語で読むなら、日本語のほうが直すときの手間も少なくなります。
ここでは、そのまま書き換えて使えるひな形を2つ用意しました。
開発プロジェクトの例
# このプロジェクトについて
- 予約受付のウェブアプリ。画面と裏側の処理を同じリポジトリで管理している
- 作業の完了は「テストがすべて通り、変更した画面を確認できたこと」
# よく使うコマンド
- 準備: npm install
- 開発用に起動: npm run dev
- テスト: npm test
- 整形: npm run lint
# 書き方の決まり
- 新しい関数には短い説明を日本語で付ける
- 画面の文言は src/messages にまとめ、直接書かない
# やってはいけないこと
- legacy フォルダは触らない（古い仕組みで、来年削除予定）
- 本番のデータベースにつながる操作は、実行前に必ず確認を取る
見出しは4つだけです。最初はこのくらいの量で十分で、使いながら足していきます。
「legacy フォルダは触らない」の後ろに理由を書いているのは、エージェントが似た古いフォルダを見つけたときにも、同じように慎重に扱ってもらうためです。
記事制作や資料づくりの例
エージェントは、プログラムを書く以外の仕事にも使われています。原稿や資料のフォルダに1枚置くと、文体や表記の決まりを毎回説明せずに済みます。
# このフォルダについて
- 自社ブログの原稿置き場。1記事1ファイルで、ファイル名は公開時のスラッグにする
- 完成の条件は「下の確認がすべて通っていること」
# 文章の決まり
- です・ます調で書く。1段落は2文まで
- 数字は算用数字。「1つ目」「2つ目」と書く
- 出典が確かめられない数字は書かない
# 確認の方法
- 書き終えたら check.py を実行し、表記ゆれと文字数を確かめる
# やってはいけないこと
- 公開済みの記事を上書きしない。直すときは別名で保存して知らせる
- 取引先の社名や個人名は書かない
こうした使い方では「確認の方法」が抜けやすくなります。目で見て確かめる項目でも、何を見れば完了かを1行で書いておくと、仕上がりがそろいます。
調べものやデータ整理の例
表計算のファイルや調査メモを扱うフォルダでも、考え方は同じです。どこに何を置き、何をしたら完了かを短く書きます。
# このフォルダについて
- 毎月の売上データを集計するための作業場所
- 元のデータは input に、集計結果は output に置く
# 作業の決まり
- input の中のファイルは書き換えない。必ず output に新しく作る
- 集計に使った条件は、結果のファイルの1行目に書く
# 確認の方法
- 合計の値が、元のデータの合計と一致しているかを最後に確かめる
元のデータを書き換えないという1行は、こうした作業で特に効きます。エージェントが元のファイルを直接直してしまう事故を、最初の段階で減らせます。
書き方のコツ 短く具体的に
この説明書は、長く書くほど良くなるものではありません。長くなるほど、肝心な決まりが埋もれていきます。
200行を目安にする
Anthropicの公式ドキュメントは、CLAUDE.mdについて「1つのファイルは200行未満を目安にする。長いファイルは文脈を多く消費し、指示が守られにくくなる」と書いています。
AGENTS.mdにも同じ考え方が当てはまります。Codexの合計32KiBという上限を考えても、一番上の1枚は短く保つのが安全です。
200行を超えそうになったら、それは分け方を考える合図です。次の章で分け方を説明します。
確かめられる書き方にする
同じドキュメントでは、書き方の例として「コードをきちんと整える」より「インデントは半角スペース2つ」のほうが良いと示しています。
エージェントが自分で守れたかどうかを判断できる書き方にすると、指示が通りやすくなります。
| あいまいな書き方 | 起きやすいこと | 確かめられる書き方 |
|---|---|---|
| テストをしてから終える | どのテストを回すか毎回ばらばらになる | 終える前に npm test を実行し、すべて通ったことを報告する |
| きれいなコードを書く | 判断の基準がなく、何も変わらない | 1つの関数は50行以内にする |
| ファイルを整理しておく | 好きな場所に新しいファイルが増える | 画面の部品は src/components に置く |
| 読みやすい文章にする | 長い段落が続いて読みにくい | 1段落は2文まで。60字を超える文は1文で1段落 |
| 危ない操作はしない | 何が危ないかの線引きが伝わらない | データを消す命令と本番への反映は、実行前に確認を取る |
決まり同士の矛盾をなくす
2つの決まりがぶつかると、エージェントはどちらか一方を選んで動きます。公式ドキュメントにも、矛盾する指示があると片方が勝手に選ばれることがあると書かれています。
一番上の説明書とサブフォルダの説明書、個人の全体設定の3か所に同じ話題が出てくるなら、どこか1か所にまとめます。
ファイルが長くなってきたときの分け方
使い続けると、説明書には少しずつ決まりが増えていきます。増えたものを全部一番上の1枚に積むと、先ほどの200行を超えてしまいます。
フォルダごとに分ける
一部のフォルダでしか使わない決まりは、そのフォルダのAGENTS.mdへ移します。
Claude Codeはサブフォルダのファイルを開いたときにそのフォルダの説明書を読み、Codexは作業フォルダまでの道のりにあるものを順に読みます。どちらでも、必要な場面でだけ読まれる形になります。
長い手順は別のファイルにする
何段階もある手順や、たまにしか使わない作業の説明は、説明書から外して別のファイルに書きます。
説明書のほうには「公開の手順は docs/release.md を読む」のように、どこを見ればよいかだけを1行で書きます。中身は必要になったときに読まれます。
Claude Codeには、決まったファイルを開いたときだけ読まれるルールや、必要なときだけ呼び出す手順書の仕組みもあります。Claude Codeを中心に使っているなら、こうした仕組みに移すのも1つの方法です。
| 増えてきた内容 | そのまま置くと起きること | 移す先 |
|---|---|---|
| 一部のフォルダだけの決まり | 関係ない作業のときにも毎回読まれる | そのフォルダのAGENTS.md |
| 何段階もある手順 | 一番上の1枚がすぐに200行を超える | 別のファイルに書き、場所だけを1行で示す |
| 自分だけの好み | チームの他の人の作業まで変わる | ホームフォルダの全体設定 |
| 今回の作業だけの事情 | 終わった後も古い指示が残り続ける | チャットで伝える |
| コードを読めば分かること | 読み込みの量だけが増える | 書かずに削る |
CLAUDE.mdとAGENTS.mdを両方使うときの運用
Claude Codeを使っていて、もともとCLAUDE.mdがあるプロジェクトでは、どちらか一方に寄せるか、取り込みでつなぐかを決めます。
@AGENTS.md で取り込む
一番おすすめなのは、共通の決まりをAGENTS.mdに書き、CLAUDE.mdの先頭に「@AGENTS.md」と1行だけ書く方法です。
Claude Codeは、CLAUDE.mdの中の「@ファイル名」を見つけると、そのファイルの中身を読み込みます。CLAUDE.mdの残りの部分には、Claude Codeにだけ伝えたい決まりを書けます。
公式ドキュメントによると、この形にしておけば、どの設定を選んでいても中身が二重に読まれることはありません。
CLAUDE.mdの中身は、たとえば次のような形になります。1行目で共通の決まりを取り込み、その下にClaude Codeにだけ伝えたいことを足しています。
@AGENTS.md
# Claude Code だけの決まり
- 支払いまわりのフォルダを直すときは、先に計画を見せてから作業する
共通の決まりを直すときはAGENTS.mdだけを書き換えればよく、2つのファイルの中身がずれる心配がなくなります。
シンボリックリンクでつなぐ
Claude Code専用の決まりが何もないなら、CLAUDE.mdをAGENTS.mdへのシンボリックリンク（別名で同じファイルを指す仕組み）にする方法もあります。
ただし、Windowsを使う人がチームにいる場合は向きません。公式ドキュメントでも、Windowsでは取り込みの形を使うよう案内されています。
以前の回避策を片付ける
Claude CodeがAGENTS.mdを直接読む前から、いろいろな回避策が使われてきました。今の版で何が要らなくなったかを整理しておきます。
| 以前の回避策 | 今の動き | 次にすること |
|---|---|---|
| CLAUDE.mdに「@AGENTS.md」と書いている | そのままで二重には読まれない | 残してよい。他に何も書いていなければ消してもよい |
| CLAUDE.mdに「AGENTS.mdを読んで」と文章で書いている | Claudeが自分で開いたときしか読まれない | CLAUDE.mdを消すか、取り込みの1行に書き換える |
| CLAUDE.mdをAGENTS.mdへのリンクにしている | 中身は1回だけ読まれる | そのままでも、リンクを消してもよい |
| 起動時にAGENTS.mdを表示する仕掛けを入れている | 直接の読み込みと合わせて2回入る | 仕掛けを外す |
書いたのに読まれていないときの確かめ方
説明書を置いたら、本当に読まれているかを1度は確かめます。読まれていないことに気づかないまま、「指示を守ってくれない」と悩む時間がいちばんの無駄です。
Claude Codeで確かめる
Claude Codeでは「/memory」と入力すると、読み込まれている指示ファイルの一覧が出ます。そこにAGENTS.mdの場所が出ていれば読まれています。
出ていなければ、公式ドキュメントの順番に沿って3つを確かめます。
1つ目は、作業フォルダかその上の階層にCLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.mdのどれかが無いかです。あれば、そちらが優先されています。
2つ目は、「claude –version」でバージョンが2.1.277以降かどうかです。一部の環境では2.1.281以降が必要です。
3つ目は、「/config」の「Project instructions」が、CLAUDE.mdだけ、または組織の管理用だけになっていないかです。項目そのものが無いなら、その環境ではAGENTS.mdを読めません。
Codexで確かめる
Codexでは、今読み込んでいる指示を要約させるのが手早い方法です。OpenAIの公式ドキュメントでも、指示の内容を要約させて確かめる方法が案内されています。
サブフォルダの決まりが効いているかは、そのフォルダを作業場所にしてCodexを起動し、同じように要約させると分かります。
会話の中で確かめる
道具の一覧が見られない環境でも、エージェント本人に聞く方法があります。会話の最初に「このプロジェクトの指示には何と書いてありますか」と尋ねるだけです。
Claude Codeの公式ドキュメントでも、一覧に出ない古い版では、この聞き方で確かめるよう案内されています。
返ってきた答えに、書いたはずの決まりが出てこなければ、そのファイルは読まれていません。上の表の原因を順に当たります。
| 症状 | よくある原因 | 直し方 |
|---|---|---|
| Claude Codeが中身を知らない | 同じ階層か上にCLAUDE.mdがある | CLAUDE.mdに「@AGENTS.md」を足す |
| 個人メモを置いたら急に読まれなくなった | CLAUDE.local.mdが数に入っている | 設定を「両方」に変えるか、メモを全体設定へ移す |
| 整理したら読まれなくなった | .agentsフォルダの中に移した | 一番上か .claude フォルダの中へ戻す |
| Codexで下の階層の決まりが効かない | 上の階層が長く、32KiBの上限に届いた | 上の階層を削り、細かい決まりを下へ移す |
| 更新した直後だけ読まれない | 更新後の最初の会話 | 会話を始め直す |
AGENTS.mdに書いても守られないことがある
説明書は強い味方ですが、書いたことが必ず守られる仕組みではありません。ここを知らないまま使うと、大事な場面で困ります。
指示は文脈として読まれる
Anthropicの公式ドキュメントには「ClaudeはCLAUDE.mdを文脈として扱い、強制される設定としては扱わない」とあります。AGENTS.mdも同じ扱いです。
エージェントはファイルの内容を読んで従おうとしますが、あいまいな指示や矛盾した指示があると、守られないことがあります。
守られやすくする工夫として、決まりに短い理由を添える方法があります。「legacy フォルダは触らない（来年削除予定のため）」のように書くと、エージェントが似た場面で判断する手がかりになります。
先に触れた点検の機能も、残すべきものの1つに「決まりの理由」を挙げています。
必ず止めたい操作は別の仕組みで止める
本番への反映やデータの削除のように、1回でも起きたら困る操作は、説明書に書くだけで終わらせません。
Claude Codeには、特定の操作の直前に自動で確認を走らせる仕組みや、使えるコマンドを設定で制限する仕組みがあります。公式ドキュメントも、決まった時点で必ず実行したいことはこうした仕組みで書くよう勧めています。
| 守らせたいこと | AGENTS.mdだけの場合 | あわせて使う仕組み |
|---|---|---|
| 書き方や文体の決まり | たいていは守られる | 整形の道具や検査用のスクリプト |
| 終える前のテスト | 忘れられることがある | 作業の終わりに自動でテストを回す設定 |
| 触ってはいけないフォルダ | うっかり書き換えることがある | そのフォルダへの書き込みを設定で禁止する |
| データを消す操作 | 1回でも起きたら取り返せない | 実行前に止める仕掛けと、使えるコマンドの制限 |
AGENTS.mdの育て方
説明書は1回書いて終わりのファイルではありません。使いながら少しずつ直していくものです。
同じ指摘を2回したら1行足す
Anthropicの公式ドキュメントは、指示ファイルに書き足す合図として「Claudeが同じ間違いを2回した」「前の会話で打ったのと同じ訂正をまたチャットで打っている」といった場面を挙げています。
1回目の指摘はチャットで済ませ、2回目が来たら説明書に1行足す、という線引きにしておくと、ファイルが無駄に膨らみません。
月に1度は読み返して削る
プロジェクトが進むと、もう使っていないコマンドや、消したフォルダについての決まりが残ります。古い決まりは、新しい決まりと矛盾する原因になります。
月に1度、上から読み返して、今は当てはまらない行を消します。Claude Codeを使っているなら、指示ファイルの古い部分や矛盾を洗い出す点検の機能も用意されています。
| こんなとき | 起きていること | AGENTS.mdでやること |
|---|---|---|
| 同じ訂正を2回した | 決まりが伝わっていない | その訂正を1行の決まりとして足す |
| 新しいメンバーが同じ質問をした | 前提が書かれていない | 答えを短く書き足す |
| 使うコマンドを変えた | 古いコマンドが残っている | その場で書き換える |
| 守られない決まりがある | あいまいか、他の決まりと矛盾している | 確かめられる書き方に直すか、別の仕組みで止める |
| 200行に近づいた | 大事な決まりが埋もれ始めている | フォルダごとに分けるか、手順を別のファイルへ移す |
よくある質問
英語で書かないといけませんか
日本語で問題ありません。このファイルには決まった欄も必須の項目もないので、チームが読みやすい言葉で書けば十分です。
コマンドやフォルダ名だけは、実際の表記のまま書きます。
CLAUDE.mdはもう要りませんか
Claude Codeだけを使っているなら、今のCLAUDE.mdをそのまま使い続けてかまいません。CodexなどほかのツールとClaude Codeを併用するなら、共通の中身をAGENTS.mdへ移し、CLAUDE.mdには「@AGENTS.md」とClaude Code専用の決まりだけを残す形が扱いやすくなります。
どのくらいの長さにすればよいですか
一番上の1枚は200行未満を目安にします。最初は「目的と完成の条件」「コマンドと確認方法」「やってはいけないこと」の3項目、20行前後から始めて、必要に応じて足していくのがおすすめです。
プログラムを書かない仕事でも使えますか
使えます。原稿、資料、表計算のファイルを置いたフォルダでエージェントを使うなら、文体や表記の決まり、ファイル名の付け方、終わったあとの確認方法を書いておくと、毎回の説明が要らなくなります。
秘密の情報を書いてもよいですか
書かないでください。リポジトリに入れてチームで共有するファイルなので、パスワードや鍵のような情報を書くと、見られてはいけない人にまで届きます。
秘密の情報は、それ専用の管理の仕組みに置きます。
まとめ
AGENTS.mdは、AIのコーディングエージェントに作業の前提を伝えるための、ツールをまたいで使える説明書です。
Linux Foundationの発表によると、すでに6万を超えるプロジェクトで使われており、2026年9月18日からはClaude Codeも直接読むようになりました。
気をつけたいのは、ツールごとに読まれる条件が違うことです。Claude Codeは、既定ではCLAUDE.mdがあるとAGENTS.mdを読みません。
Codexは上書き用のファイルを優先し、合計32KiBまでしか読みません。
まずは一番上に1枚、3項目だけの説明書を置き、本当に読まれているかを確かめるところから始めてください。
そのうえで、同じ指摘を2回したら1行足し、月に1度は読み返して削る。この繰り返しで、エージェントに任せられる作業の範囲が少しずつ広がっていきます。
今日できる点検
最後に、今日のうちに確かめられることを表にまとめました。上から順に5分ずつで終わります。
| 点検すること | 確かめ方 | 問題があったときにすること |
|---|---|---|
| AGENTS.mdが一番上にあるか | リポジトリのルートを開いて名前を確かめる | 大文字の「AGENTS.md」で一番上に置く |
| CLAUDE.mdと重なっていないか | 同じ階層と上の階層にCLAUDE.mdやCLAUDE.local.mdがないか見る | CLAUDE.mdの先頭に「@AGENTS.md」を足す |
| Claude Codeに読まれているか | /memory の一覧にAGENTS.mdの場所が出るか見る | バージョンと /config の設定を確かめる |
| Codexに読まれているか | 今の指示を要約させる | 置き場所と上書き用ファイルの有無を確かめる |
| 長くなりすぎていないか | 一番上の1枚の行数を数える | 200行を超えていたらフォルダごとに分ける |
| 秘密の情報が入っていないか | パスワードや鍵らしき文字列を検索する | すぐに消して、専用の管理の仕組みへ移す |
