CLAUDE.mdが記憶なら、AGENTS.mdは行動マニュアルです。AIコーディングエージェントがプロジェクトに投入される際に「ここではこうやって動いて」と伝える、たった一つのファイル。それなのに、6万以上のオープンソースプロジェクトがすでに使っているこのファイルを、まだ作っていないとしたら？ 今が始めるタイミングですよ。
これは何?
AGENTS.mdはプロジェクトのルートに置くMarkdownファイルです。AIコーディングエージェント向けのREADMEと考えれば分かりやすいです。 人がREADME.mdを見てプロジェクトを理解するように、AIエージェントはAGENTS.mdを見て「ここではどう動けばいいか」を把握します。
2025年8月にOpenAI Codexチームが最初に提案し、現在はLinux Foundation傘下のAgentic AI Foundationが管理するオープン標準になっています。 核心は一つのファイルですべてのAIツールをカバーするという点です。以前は.cursorrules、.builderrulesといったツール別の設定ファイルがプロジェクトを散らかしていましたが、AGENTS.md一つで整理できます。
CLAUDE.mdとの違いは?
CLAUDE.mdはAnthropicのClaude製品専用です。AGENTS.mdはツールに関係なく動く汎用標準です。両方使いたい場合は？CLAUDE.mdにStrictly follow the rules in./AGENTS.mdと一行書くか、シンボリックリンクで連携すればOKです。
対応ツールのリストはすでに膨大です。GitHub Copilot、Cursor、Windsurf、Codex、VS Code、Gemini CLI、Devin、Junie(JetBrains)、Amp、Aider、Zed、goose、Roo Code... 主要なAIコーディングツールはほぼ網羅されています。
何が変わるのか?
AGENTS.mdがないと、AIエージェントは毎回探検家になってしまいます。プロジェクト構造を探索し、ビルドコマンドを推測し、コーディングスタイルを把握するために時間とトークンを消費します。そして高い確率で間違えます。
Builder.ioのSteve Sewellが直接実験した結果は印象的です。AGENTS.mdなしでFigmaのデザインをコードに変換してみたところ — MUIのバージョンを誤参照してスタイルが崩れ、内部の状態管理ライブラリ(mobx)の代わりにuseStateを使い、ダークモードのトークンを省いてしまいました。AGENTS.mdを追加した後は？同じプロンプトでUI精度、トークン使用量、コードスタイルいずれも目に見えて改善しました。
| AGENTS.mdなし | AGENTS.mdあり | |
|---|---|---|
| プロジェクト把握 | 毎セッション構造探索を繰り返す | 核心ファイルの場所を即座に参照 |
| ビルド/テスト | フルビルド実行(数分かかる) | ファイル単位のコマンドで数秒で検証 |
| コーディングスタイル | バージョンエラー、ライブラリ選択ミス | 正確なバージョンとパターンを初回から適用 |
| 安全性 | 予告なくパッケージインストール、ファイル削除 | 許可/禁止アクションが明確に定義済み |
| 一貫性 | ツールごとに異なる結果 | どのツールを使っても同じルールが適用される |
GitHubのMatt Nighは2,500件以上のAGENTS.mdファイルを分析して成功パターンを見つけました。 結論は明快でした — うまくいくAGENTS.mdには6つの領域が必ず含まれていました: 実行コマンド、テスト、プロジェクト構造、コードスタイル、Gitワークフロー、そして境界(Boundaries)。
一方、失敗するファイルの共通点も明確でした。「You are a helpful coding assistant」のような曖昧な指示、技術スタックをすべて列挙する冗長さ、具体的なコマンドなしに抽象的な説明だけがある場合。 Ben Tossellも興味深いデータを共有しています — 技術スタック、核心ファイル、アーキテクチャを詳細に書いたAGENTS.mdが、むしろパフォーマンスを低下させてコストを20%高めたという研究結果があるそうです。 エージェントはそういったことは自分で把握できるからです。
"AGENTS.md should be pretty empty. It should be your preferences and nudges to correct agent behaviour."
— Ben Tossell, Ben's Bites
ポイント整理: 良いAGENTS.mdの書き方
- Do/Don'tリストから始めましょう
最も効果的な出発点です。AIエージェントに作業を任せてみて、気に入らない点が出てきたら一行ずつ追加していけばOKです。 「MUI v3互換のコードを書くこと」「カラー値をハードコーディングしないこと」といった形で。抽象的な説明ではなく、具体的な指示が肝心です。 - ファイル単位のコマンドを入れましょう
フルビルドの代わりに、ファイル一つを素早く検証できるコマンドを提供すると、エージェントが数分ではなく数秒でフィードバックループを回せます。 たとえばnpm run tsc --noEmit path/to/file.tsxのように。速くてコストも低いので、「常に実行せよ」と指示できます。 - 境界(Boundaries)を3段階で定義しましょう
GitHubの分析で最も効果的だったパターンです。 許可(Always do)、確認してから進める(Ask first)、絶対禁止(Never do)の3段階に分けましょう。「絶対にシークレットをコミットするな」が最も多く登場した制約でした。 - 良いサンプルファイルを指定しましょう
説明を三段落書くより実際のコードサンプルを一つ示す方が有効——これが2,500件分析の結論です。 「フォームはapp/components/DashForm.tsxを参照すること」「レガシーのAdmin.tsxのクラスコンポーネントパターンは真似しないこと」——このように良いファイルと悪いファイルをピンポイントで指定しましょう。 - 繰り返すミスが見えたら一行追加しましょう
AGENTS.mdは完成品ではなく、生きたドキュメントです。 エージェントが同じミスを二度したら、そのタイミングでルールを追加すればいいんです。最初から完璧に書こうとしないでください。アップフロントの計画よりイテレーションの方が効果的というのが実践からの教訓です。
よくあるミス: 書きすぎること
技術スタック、アーキテクチャ、ファイル一覧をすべて書くと逆効果です。 AIエージェントはプロジェクトを探索してそういったことは自分で把握できます。エージェントが間違えそうなことだけ書きましょう — 好みのライブラリ、コーディングの規約、絶対に触ってはいけない領域などです。
モノレポを使っているなら、もう一つポイントがあります。サブディレクトリごとにAGENTS.mdをネストできます。 エージェントは作業中のファイルから最も近いAGENTS.mdを優先して適用します。OpenAI CodexのリポジトリにはAGENTS.mdが88個あります。 ルートには共通ルール、サブパッケージには該当パッケージ専用のルールを入れればいいんです。
