AGENTS.md vs CLAUDE.md vs SKILL.md:どのエージェントにどのファイル?研究が示す答え(2026)

- 本記事の研究データやツールの状況(クロスツール標準としてのAGENTS.md、インポート構文)は、執筆時点の情報源と照合しています。これらのツールは変化が速いため、最新の公式ドキュメントで確認してください。

AGENTS.md と CLAUDE.md——同じもの?

本質的には同じ発想です——エージェントがプロジェクトの規約を学ぶために読むファイルで、ツールごとに名前が違うだけ。 CLAUDE.md は Claude Code の規約です。AGENTS.md は台頭しつつあるクロスツール標準で、Codex CLI、Copilot CLI、Gemini CLI、Cursor、そして Claude Code でも読み込まれます。

どちらも役割は同じで、チャットのセッションをまたいで残り続ける恒久的なブリーフィングをエージェントに与えます。だから毎回あなたの規約を聞き直さずに済むのです。覚えておく価値のある唯一の違いは、CLAUDE.md には AGENTS.md が標準化していない Claude Code 固有の機能がいくつか残っている点——とりわけ階層的な読み込みとインポートです。テンプレート付きで CLAUDE.md を最初から最後まで書く方法は、CLAUDE.md ガイドをご覧ください。

よく似た3つを混同しないための一言:AGENTS.md(ファイル標準)は、AgentKit(Claude Code 向けのキット、agentkit.best)とも、OpenAI AgentKit(Agent Builder/ChatKit)とも別物です。

AGENTS.md vs CLAUDE.md vs SKILL.md:どのファイルがどの役割?

AGENTS.md と CLAUDE.md は、いまやエージェントが読むプロジェクトファイルの唯一の存在ではありません。SKILL.md はまったく種類の異なるファイルです。SKILL.md ファイルを含むフォルダ(name/description を持つ YAML フロントマターと Markdown 本文、任意で scripts/、references/、assets/ を併置)で、常時読み込まれるコンテキストではなく、再利用可能でオンデマンドな機能をパッケージ化します。エージェントはタスクをスキルの description と照合し、関連する場合にのみ読み込みます(または明示的に呼び出します)。Anthropic はこのフォーマットを Claude Code 向けに作成し(2025年10月)、オープンな Agent Skills 標準として公開しました(agentskills.io)。Codex は数週間のうちに採用し——OpenAI 自身のドキュメントも、Codex の「skills build on the open agent skills standard」と認めています(learn.chatgpt.com/docs/build-skills)。

AGENTS.md/CLAUDE.md との違いは、単なる名前ではなく種類の違いです。AGENTS.md と CLAUDE.md は常時読み込まれる恒久的なコンテキスト——まさに以下の研究が測定した対象であり、肥大化させると推論コストが20%以上増える理由そのものです。SKILL.md はタスクが一致したときにのみオンデマンドで読み込まれます——後の節が執筆テクニックとして借用するプログレッシブ・ディスクロージャーのモデルです。これでそのテクニックが効く理由が分かります。今まさに使っていない機能にコンテキストを浪費しないための、スキルそのものの仕組みなのです。

3つのファイルは、誰が読むのか、どんなフォーマットを使うのか、何に向いているのかという点でも異なります:

はっきり述べておくべき事実がひとつ:Codex は AGENTS.md を読みます——CLAUDE.md はまったく読みません。 Codex がツールチェーンに含まれるなら、実際に見られるファイルは AGENTS.md です。読み込み順の詳細はCodex の AGENTS.md 設定の仕組みをご覧ください。Codex がスキルを具体的にどう読み込むかは、Codex Skills の仕組みをご覧ください。

手早い選び方:テスト/ビルドのコマンドや壊してはいけないルールを、エージェントに常に把握しておいてほしい?なら AGENTS.md(Claude Code なら CLAUDE.md)を使いましょう。ときどきしか起動しない再利用可能な機能——ワークフローやスクリプトの束——が必要?なら代わりに SKILL.md を使いましょう。

研究で分かったこと——役立つ、ただしごくわずか

「コンテキストファイルは本当に役立つのか」という問いに、いまやデータがあります。Gloaguen ほかによる研究「Evaluating AGENTS.md」(2026年2月投稿)は、多数のエージェント、モデル、リポジトリにわたってコンテキストファイルを測定しました。その結果は、立ち止まって考える価値があります:

• タスク成功率に全般的な改善は見られなかった——これは LLM が生成したファイルにも、開発者がコミットしたファイルにも両方とも当てはまります。これは一般的な推奨とは逆の結果です。
• 推論コストは平均で20%以上上昇した。
• リポジトリの概要——人気があり、モデルプロバイダーも推奨——は役に立たなかった。 対照的に、コンテキストファイル内の指示はエージェントに適切に守られました。

誇張されがちな点がひとつ:「開発者が書いたファイルの方が優れている」わけではありません。研究では、どちらのタイプも成功率を確実には向上させないと分かりました。ただ、指示は守られるのに概要は守られないため、実践的な結論は明快です。概要の水増しを削り、実行可能な指示を残す。ファイルは小さく、成功率は同じ、コストは低く。

パラドックス——エージェントは熱心に従いすぎる

興味深いのは、エージェントが指示を無視するのではなく、少々熱心に従いすぎる点です。テストに触れれば、より多くのテストを実行します。ツールに触れれば、より多くのツールを使います。リポジトリ固有のワークフローに触れれば、より多く探索します。

問題は、そうした指示の多くがタスクをより速く解決する助けにならず、ただタスクを重くするだけだという点です。あなたが1行追加するごとに、エージェントが「実行しなければ」と感じる行が1つ増えます。だからこそ、肥大化したファイルはトークンを浪費し、より良い結果も出さないままタスクを長引かせるのです。

つまり AGENTS.md が悪いのではなく、書き方が悪い

教訓は「コンテキストファイルを捨てろ」ではありません。それは:バグを直すたびにエージェントが読み直す2,000語のハンドブックに、AGENTS.md を仕立て上げるな。ということです。

実行可能な部分を残しましょう:

• テストコマンド、ビルドコマンド、実行コマンド。
• 壊してはいけないルール(公開 API を変えない、ディレクトリ X に触れない…)。
• 重要なパス/ディレクトリ。

あとはエージェントに残りを考えさせましょう。ありていに言えば、エージェントを自分たちの知識に縛りつけすぎると、彼らは結局……私たちと同じくらい愚かになります。少し飛ぶ余地を与え、そのうえで実際の要件へと引き戻せばいいのです。

「プログレッシブ・ディスクロージャー」方式で書く(SKILL.md のように)

前述のとおり、SKILL.md はオンデマンドで読み込まれます——同じ発想を AGENTS.md にも適用しましょう。小さなファイルに分割して遅延読み込みするのです:「A をするなら、ファイル X を読む」。不要なときはエージェントがそれをスキップし、コンテキストを一切消費しません。

CLAUDE.md では、これを @path/to/file のインポート構文で行います(ツールは変化が速いので、最新の構文を確認してください)。ルートファイルには常に真であるコアだけを残し、作業の種類ごとの詳細は別ファイルに置いて、関連するときに引き込みます。これは Claude Code skills がコンテキストに応じて指示を読み込むのと同じ仕組みです。作り方はカスタムスキルの作成方法をご覧ください。コンテキスト全体の予算についてはコンテキストとメモリの管理をご覧ください。

1ファイル?それとも2ファイル?(シンボリックリンクの裏技)

ファイルを1つだけ残すなら、最も多くのツールに読まれる AGENTS.md にしましょう。Claude Code をメインのエージェントにしつつ、あらゆるツールでも動かしたい場合の定番の裏技は、単一の信頼できる情報源にすることです:AGENTS.md を書き、CLAUDE.md をそこへシンボリックリンクするのです。

mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

これでコンテンツを1か所にまとめつつ、すべてのツールに対応できます。トレードオフは、CLAUDE.md の階層的な読み込みとインポートを失うこと——なので @path インポートに大きく依存しているなら、CLAUDE.md をシンボリックリンクではなく実ファイルのまま残すことを検討してください。

ビフォー/アフター:長いハンドブックから約十数行へ

初期から今まで Claude Code のキットを使ってきた人なら気づくでしょう。1つの長い CLAUDE.md から、私はほんの十数行にまで圧縮しました。なぜなら、このファイルはプロジェクト固有であるべきだから——このプロジェクトに必要な追加ルールだけを保持し、何もかも溜め込む汎用の寄せ集めにはしないのです。

削り込みのルール:どの行も「これはエージェントの判断をどこで変えるのか?」に答えられなければなりません。答えられないなら、それは概要の水増し——削るか、遅延読み込みのファイルへ押し出しましょう。コピーして使えるリーンな CLAUDE.md テンプレートはCLAUDE.md ガイドにあります。

残す/削るチェックリスト

リーンなコンテキストを標準搭載したキット(AgentKit)

自分でチューニングしたくないなら、AgentKit のようなキット(agentkit.best、ak CLI——OpenAI AgentKit とは別物)は、リーンな CLAUDE.md 規約に加えてプログレッシブ・ディスクロージャー方式で書かれたスキル群を同梱しているので、肥大化したハンドブックを自作せずに済みます。概要はAgentKit レビューを読むか、AgentKit(リンク経由で20%オフ)をご覧ください。

よくある質問(FAQ)

AGENTS.md と CLAUDE.md は同じですか?

発想は同じで、ツールごとに名前が違うだけです。CLAUDE.md は Claude Code の規約で、AGENTS.md は多くのツール(Codex、Copilot CLI、Gemini CLI、Cursor、Claude Code)に読まれるクロスツール標準です。CLAUDE.md には、階層的な読み込みやインポートといった追加機能がいくつか残っています。

Claude Code は AGENTS.md を読みますか?

現状では、Claude Code は CLAUDE.md と並んで AGENTS.md も読み込めます——ただしこの領域は変化が速いので、最新の公式ドキュメントで確認してください。@path インポートや階層的な読み込みに依存しているなら、CLAUDE.md はやはり残しておく価値のあるルートファイルです。

コンテキストファイルは本当にエージェントの役に立ちますか?

2026年のある研究によれば、コンテキストファイルはタスク成功率を確実には向上させず(LLM 生成のものも開発者が書いたものも)、コストを20%以上引き上げます。特にリポジトリの概要は役に立たず、一方で具体的な指示は守られました。教訓:実行可能な指示は残し、概要は削る。

CLAUDE.md はどのくらいの長さにすべきですか?

できる限りリーンに——常に真であるコアだけを残し、詳細は @path インポートで遅延読み込みのファイルへ押し出しましょう。どの行もエージェントの判断を変えるものであるべきで、そうでないなら削ります。

CLAUDE.md における「プログレッシブ・ディスクロージャー」とは何ですか?

内容を小さなファイルに分割し、オンデマンドで読み込むことです:「A をするなら、ファイル X を読む」。関連しないときはエージェントがそれをスキップし、コンテキストを消費しません——スキルがコンテキストの一致時に指示を読み込むのと同じやり方です。

AGENTS.md では何を残し、何を削るべきですか?

残すもの:テスト/ビルド/実行コマンド、壊してはいけないルール、重要なパス、必要時に詳細を読むインポート。削るもの:リポジトリの概要、長い文章、めったに使わないワークフロー、エージェントがすでに持っている一般知識。

SKILL.md は AGENTS.md とどう違いますか?

SKILL.md は、タスクが一致したときにのみオンデマンドで読み込まれる再利用可能な機能です。一方、AGENTS.md は常時読み込まれる恒久的なコンテキストです。スキルの作成とインストールの手順一式は、Codex Skills の仕組みをご覧ください。

まとめ

コンテキストファイルは機能します——リーンで、プログレッシブ・ディスクロージャー方式で書かれていれば。長く書くのは自滅行為です:コストは20%以上増え、結果は良くなりません。概要を削り、実行可能な指示を残し、残りは遅延読み込みに。テンプレートはCLAUDE.md ガイドをご覧ください。自律実行もしているなら、/goal を効率的に使う方法と組み合わせましょう。