はじめに
こんにちは、エンジニアのkeitaMaxです。
AGENTS.mdについて整理してみます。
AGENTS.mdとは
AGENTS.mdは、AIコーディングエージェント向けにプロジェクトの情報を記述する設定ファイルの規格です。Claude CodeのCLAUDE.mdと似た役割ですが、特定のツールに依存しないオープンな規格として広まりつつあります。
中身に書く内容は基本的にCLAUDE.mdと同じで、
- プロジェクトの構成
- コーディング規約
- よく使うコマンド（テスト実行、ビルドなど）
- ディレクトリ構成のルール
といった「エージェントに知っておいてほしい前提情報」をまとめます。
CLAUDE.mdとの違い
一番大きな違いは「対象ツールの広さ」です。
AGENTS.mdはOpenAI Codexが普及させた、複数のAIコーディングツールが共通で読み込めることを目指した規格です。Codex CLIやCursor、Gemini CLI、Devinなど多くのツールがネイティブに対応しています。Linux Foundation配下のAgentic AI Foundationにも寄贈されており、ツール非依存の「エージェント向けREADME」として広がりつつあります。
ここで注意が必要なのは、Claude CodeはAGENTS.mdを直接は読み込まないという点です。Claude Codeが自動で読み込むのはあくまでCLAUDE.mdで、AGENTS.mdを使いたい場合はCLAUDE.mdの中で
@AGENTS.md
のようにインポートする形を取ります。「Claude CodeもAGENTS.mdをそのまま読んでくれる」と思っていると、内容が反映されずハマるので注意が必要です。
併用する場合の考え方
複数のAIツールを使い分けている場合は、
-
AGENTS.md：ツール共通で使う基本情報（技術スタック、ディレクトリ構成、命名規則など） -
CLAUDE.md：Claude Code固有の細かい指示（@AGENTS.mdでの読み込み + Skillsの呼び出し方など）
のように役割を分けると整理しやすいです。Claude Codeしか使わないのであれば、無理にAGENTS.mdを導入せずCLAUDE.mdだけで十分です。Codex・Cursor・Gemini CLIなど複数ツールを併用する人にとって価値が出てくる規格だと思います。
書くときに気をつけていること
仕様書をAIに引き継ぐ運用をしていて感じるのは、「書きすぎても書かなすぎてもダメ」ということです。
- 書きすぎ：コンテキストを圧迫し、本当に重要な情報が埋もれる
- 書かなすぎ：毎回同じ説明をし直すことになる
なので、「セッションをまたぐたびに何度も説明している内容」だけを抜き出してAGENTS.mdに書く、というスタンスがいいのかなと思います。
おわりに
この記事での質問や、間違っている、もっといい方法があるといったご意見などありましたらご指摘していただけると幸いです。
最後まで読んでいただきありがとうございました！