AGENTS.mdとは？AIエージェントに毎回読ませる指示ファイルの形式

Claude Codeの配置：2026年10月9日に再確認

プログラミング用のAIエージェントを使い始めると、「テストはこのコマンドで実行する」「この書き方は使わない」と、同じ注意を何度も伝えることになります。そうした決まりをファイルに書いておき、毎回の作業の最初にAIへ読ませるための共通の形式が、AGENTS.mdです。

本記事では、AGENTS.mdの公式サイトと、AIエージェントの開発元の公式ドキュメントをもとに、AGENTS.mdの仕組みと書き方の注意を解説しましょう。

AGENTS.mdとは

AGENTS.mdは、AIエージェントに作業の前提や決まりを伝えるための、Markdownのファイルです。公式サイトは、コーディングエージェントを導くための、シンプルでオープンな形式と説明していました。リポジトリの一番上に AGENTS.md という名前で置けば、対応するAIエージェントが作業を始めるときに読み込みます。

書く内容は、ビルドやテストのコマンド、フォルダーの構成、コードの書き方の決まりなど、どの作業でも守ってほしいことです。必須の項目も決まった見出しもないので、新しく加わった開発者に伝えるような内容を、普通のMarkdownで書けば足ります。

セッションは互いに独立していて、新しいセッションは前の会話を覚えていません。昨日伝えた注意も、今日のセッションには引き継がれないのです。AGENTS.mdは、セッションの最初に毎回コンテキストウィンドウへ読み込まれるため、伝え直さなくても同じ決まりで作業を始められます。

AIに毎回読ませる指示を書いたこのようなファイルを、本記事では「指示ファイル」と呼ぶことにしましょう。AGENTS.mdは、指示ファイルの共通の形式という位置づけです。

生まれた背景

指示ファイルの名前は、もともと製品ごとにばらばらでした。複数のAIエージェントを使うと、同じ内容を、製品ごとに別の名前のファイルへ書き写す手間がかかっていました。

AGENTS.mdは、この名前をそろえるために、OpenAIのCodex、Amp、GoogleのJules、Cursor、Factoryといった開発元の協力から生まれた形式です。公式サイトによると対応するツールは25以上あり、今はLinux Foundation傘下のAgentic AI Foundationが管理しています。

読み込まれる順番

AGENTS.mdは、1つのリポジトリに1つとは限りません。利用者全体の設定、プロジェクトの一番上、作業しているフォルダーと、複数の場所に置けます。

AIエージェントは、広い範囲のファイルから順に読み、つなげてモデルに渡す仕組みです。内容がぶつかったときは、作業しているファイルに近いフォルダーの指示が優先されます。たとえば、プロジェクト全体では「テストは npm test」と決め、一部のフォルダーだけ別のコマンドを使うなら、そのフォルダーに置いたAGENTS.mdで上書きできるわけです。

公式サイトは、複数のパッケージを1つのリポジトリで管理する場合、パッケージごとにAGENTS.mdを置くよう勧めていました。チャットで利用者が直接伝えた指示は、すべてのファイルより優先されます。

指示ファイルは「守らせる」仕組みではない

AGENTS.mdに限らず、指示ファイルについて一番知っておきたいのは、書いたことが必ず守られるわけではない点です。

指示ファイルの中身は、モデルに読ませる文章です。読んだうえでどう動くかは、モデルの判断に任されます。Claude Codeのドキュメントも、指示ファイルを「強制される設定ではなく、コンテキストとして扱う」と明記しており、どんな場合でも止めたい操作にはフックを使うよう案内していました。

守られやすい指示にするために、同じドキュメントは次の点を勧めています。

• 「きれいに書く」ではなく「インデントは2文字」のように、確かめられる形で書く
• 1つのファイルは200行未満を目安にする。長いほどコンテキストを使い、守られにくくなる
• 矛盾する指示を残さない。2つがぶつかると、モデルがどちらかを任意に選ぶことがある

Codexも、読み込む指示ファイルの合計に初期設定で32KiBの上限を設けています。何でも書き足すのではなく、毎回の作業で必要なことに絞るのが基本です。

スキル・フック・権限との違い

AIエージェントの設定には、指示ファイルのほかにスキル、フック、権限があります。「モデルに読ませるのか、モデルの外で守らせるのか」と「いつ働くのか」の2つで分けると、区別しやすいでしょう。

「事実と決まり」はAGENTS.mdに、「手順」はスキルに書くのが目安です。「絶対にしてはいけないこと」は、AGENTS.mdに書くだけでなく、フックか権限で止めておきましょう。

製品での使われ方

ここでは、Codexと、独自の名前の指示ファイルを持つClaude Codeを例に挙げます。

Codex

Codexが読むのは、プロジェクトの AGENTS.md です。利用者全体の指示は ~/.codex/AGENTS.md に置き、プロジェクトの一番上から作業しているフォルダーまで、順にファイルをつなげて読み込みます。

同じ「ルール」という言葉でも、Codexの「Rules」（.rules ファイル）は指示ファイルではありません。どのコマンドを実行してよいかを決める、権限の設定を指します。こちらは権限の記事で扱いました。

Claude Code（CLAUDE.md）

Claude Codeでは、指示ファイルの名前は CLAUDE.md です。AGENTS.mdと同じく、置く場所によって指示が及ぶ範囲が変わります。

このほか、組織の管理者が全員に配る CLAUDE.md もあります。

CLAUDE.md と AGENTS.md の両方があるとき、初期設定のClaude Codeが読むのは CLAUDE.md だけです。AGENTS.md を読むのは、作業しているフォルダーとその上に CLAUDE.md がない場合に限られます。設定で、両方を読ませることも可能です。

複数の製品で同じ指示を使いたいときのために、Claude Codeのドキュメントは、CLAUDE.md から AGENTS.md を読み込ませる方法を案内していました。CLAUDE.md の先頭に @AGENTS.md と書くと、AGENTS.md の中身が読み込まれ、その下にClaude Code専用の指示を書き足せます。

@AGENTS.md

## Claude Code

（ここに、Claude Codeだけに伝えたい指示を書く）

こうしておけば、共通の指示は AGENTS.md の1か所で管理でき、ほかの製品にも同じ内容が伝わります。

指示を話題ごとに分けたいときの置き場所は、.claude/rules/ というフォルダーです。特定のフォルダーのファイルを扱うときだけ読み込ませる設定もでき、Codexのドキュメントには、同じ仕組みの説明はありませんでした。

Claude Codeのプロジェクトで、指示ファイルとルールを置く場所は次のとおりです。これは配置例であり、すべてのファイルを作る必要はありません。AGENTS.md はClaude Code専用のファイルではなく、上で説明した条件で読み込まれます。

Claude Code全体の説明とフォルダー構成は、Claude Codeとはにまとめました。

project/
├── AGENTS.md                  # 複数のAIエージェントで共有する指示
├── CLAUDE.md                  # Claude Code向けの指示。@AGENTS.mdで取り込み可能
└── .claude/
    ├── rules/
    │   └── coding.md           # 話題別の指示。pathsで対象ファイルを限定可能
    └── skills/
        └── review/
            └── SKILL.md        # 特定の作業の手順

.claude/skills/ に置くものは、スキルの記事で説明しています。自分のすべてのプロジェクト向けの指示とルールの置き場所は、プロジェクトの外にある ~/.claude/CLAUDE.md と ~/.claude/rules/ です。

参考にした一次情報

• AGENTS.md
• Codex「Custom instructions with AGENTS.md」
• Claude Code「How Claude remembers your project」
• Claude Code「Explore the .claude directory」