Claude Code関連の記事やリポジトリを見ていると、最近やたら AGENTS.md というファイルが出てきます。「CLAUDE.mdじゃなくて?」と思った人もいるはずです。私もそうでした。

この記事は、AGENTS.mdとは何か、CLAUDE.mdとどう違うか、Claude Codeでどう扱うかを整理したものです。

AGENTS.mdをよく見るようになった

きっかけは、知人のリポジトリを覗いた時でした。プロジェクト直下に AGENTS.md と CLAUDE.md の2つが並んでいて、それぞれ似たような内容が書いてある。なぜ重複しているのか、と聞いたところ、「AGENTS.mdに寄せていきたいから」という答えが返ってきました。

調べてみると、これはAI開発ツール業界の小さな潮流でした。

ツール横断の共通仕様として登場

AGENTS.mdは、AIコーディング支援ツールに「このプロジェクトの前提」を伝えるためのファイルです。特徴は、特定のツールに縛られていない開かれた仕様であること。

AGENTS.md 公式

agents.md

Cursor、Codex、Aider、Clineなど、複数のAIツールが対応を表明しています。各社がそれぞれ独自のファイル名を採用すると、開発者は同じ内容を何度も書くはめになる。それを避けるための共通仕様、という位置づけです。

つまりAGENTS.mdは、「どのAIツールから見ても、ここを読めば前提が分かる」というハブの役割を狙っています。

CLAUDE.mdとの違いと住み分け

ここが混乱しやすい点です。CLAUDE.mdは、Claude Code専用に作られたファイル。AGENTS.mdは、複数のツールが共通で読むファイル。

観点

CLAUDE.md

AGENTS.md

想定読者

Claude Code

複数のAIツール

仕様の主体

Anthropic

業界横断の開かれた仕様

書く内容

Claude Code固有の指示

どのツールでも通じる前提

書く中身の方針も少し変わります。CLAUDE.mdはClaude Codeの機能(MCPサーバーの設定、/コマンドの規約など)を前提に書ける。AGENTS.mdはツール非依存の言葉で書くのが筋。「Claudeに見せる」ではなく「AIエージェント全般に見せる」つもりで書く、という違いです。

CLAUDE.mdの書き方そのものは別記事に整理してあります。

CLAUDE.mdの書き方テンプレート

claudecodelab.jp

Claude Codeでの取り扱い方

Claude CodeはCLAUDE.mdを優先して読む作りですが、AGENTS.mdを取り込む手段も用意されています。

簡単なのは、CLAUDE.mdの中から @AGENTS.md のように書いてAGENTS.mdを取り込む方法。これでClaude CodeはCLAUDE.md → AGENTS.mdの順に情報をたどります。私はこの方式に落ち着きました。CLAUDE.mdにはClaude Code固有のクセだけ書いて、汎用的なプロジェクト前提はAGENTS.mdに寄せる、という分け方です。

実際、このメディアのリポジトリでもこの構成を採っています。CLAUDE.mdは8行くらいに圧縮して、本体はAGENTS.md側、というように。

自分の使い方

参考までに、私のいまの方針です。

AGENTS.mdに書くのは、プロジェクトの目的、技術スタック、避けるべき書き方、参照すべきドキュメントの場所。特定のAIツールの話は書かない。

CLAUDE.mdに書くのは、Claude Code固有の挙動への対応 — MCP設定、/コマンドの規約、サブエージェントの呼び出し方など。Claude Codeを別のツールに置き換えても残らない部分です。

この分け方にすると、別のAIツールを試したくなった時、AGENTS.mdをそのまま使えるので楽です。

移行を急ぐ必要はない

最後に、現実的なアドバイスを。

すでにCLAUDE.mdで運用が回っているなら、慌てて全部をAGENTS.mdに移す必要はありません。AGENTS.md対応はまだ広がっている途中で、ツール側の挙動も微妙に変わっていく時期です。

新しいプロジェクトで「最初からツール横断にしておきたい」時はAGENTS.md主体で。既存プロジェクトは、機会を見て少しずつ寄せていく、くらいのペースで十分です。

まとめ

  • AGENTS.mdはAIコーディングツール横断の共通仕様
  • CLAUDE.mdはClaude Code専用、AGENTS.mdは複数ツール向けで住み分ける
  • Claude CodeはCLAUDE.md内の @AGENTS.md でAGENTS.mdを取り込める
  • 汎用前提はAGENTS.md、Claude Code固有はCLAUDE.mdに分けると整理しやすい
  • 既存プロジェクトを急いで移す必要はなく、機会を見て寄せていけばよい