AGENTS.md – コーディングエージェントを指導するためのオープンフォーマット

2025年8月20日原文(agents.md)

概要

AGENTS.md は、 README.md を補完する形でエージェント向けの詳細な指示やコンテキストを管理するためのファイル。 人間向け のREADMEを簡潔に保ちつつ、エージェントには必要な情報を提供。 ビルド手順やテスト、コーディング規約 など、READMEには不要な技術的詳細を記載。 プロジェクト全体やサブプロジェクト ごとにAGENTS.mdを配置可能。 標準的なMarkdown形式 で、エージェントにも人間にも分かりやすいドキュメント管理を実現。

AGENTS.mdとは何か・README.mdとの違い

README.md は人間向けの概要、クイックスタート、貢献ガイドラインなどを記載
AGENTS.md はエージェント向けの詳細なコンテキストや手順、規約の保存場所
README.md では冗長になる情報や、エージェントのみが必要とする内容の管理
ファイルを分離 することで、人間向けREADMEの簡潔さを維持
エージェントが参照しやすい 明確な場所の提供

AGENTS.mdの導入目的

エージェント向け指示の一元管理
README.mdの簡潔化 と人間中心設計の維持
既存のREADMEやドキュメント を補完する、正確なエージェント向けガイダンスの提供
プロプライエタリな形式を避け、誰でも使える汎用的なファイル名とフォーマットを採用
AIコーディングエージェントのエコシステム 全体で活用可能

AGENTS.mdのサンプル内容

開発環境Tips
- pnpm dlx turbo run where <project_name>で目的パッケージへジャンプ
- pnpm install --filter <project_name>でパッケージをワークスペースに追加しVite, ESLint, TypeScriptで認識
- pnpm create vite@latest <project_name> -- --template react-tsでReact+ViteのTypeScript対応パッケージ作成
- 各パッケージのpackage.json内のnameフィールドで名称確認
テスト手順
- .github/workflowsフォルダでCIプラン確認
- pnpm turbo run test --filter <project_name>でパッケージごとの全チェック実行
- パッケージルートからpnpm testでテスト可能、マージ前に全テスト合格必須
- pnpm vitest run -t "<test name>"で特定テストのみ実行
- テストや型エラーは全て修正し、スイートがグリーンになるまで対応
- ファイル移動やimport変更後はpnpm lint --filter <project_name>でESLint, TypeScriptルール確認
- 変更コードには必ずテスト追加や更新
PRガイドライン
- タイトル形式：[<project_name>] <Title>
- コミット前に必ずpnpm lintとpnpm testを実行

AGENTS.mdの使い方

1. AGENTS.mdの新規作成
- リポジトリのルートにAGENTS.mdを配置、エージェントによる自動生成も可能
2. 必要事項の記載
- エージェントがプロジェクトで作業しやすくなる項目をセクションごとに記載
  - プロジェクト概要
  - ビルド・テストコマンド
  - コードスタイル
  - テスト手順
  - セキュリティ考慮点
3. 追加指示の記載
- コミットメッセージやPRガイドライン、セキュリティ注意点、大規模データセット、デプロイ手順など
4. 大規模モノレポでの活用
- サブプロジェクトごとにAGENTS.mdを配置可能
- エージェントはディレクトリツリー上で最も近いAGENTS.mdを自動参照
- OpenAIのメインリポジトリでは88個のAGENTS.mdを運用中（2024年6月時点）

AGENTS.mdの背景とコミュニティ

OpenAI Codex、Amp、Google Jules、Cursor、Factory などAI開発エコシステム全体での協働から誕生
オープンフォーマット として進化・維持をコミット
どのコーディングエージェントでも活用可能、開発者コミュニティ全体の利便性向上

FAQ

必須フィールドはなし
- 標準Markdownのみで構成、任意の見出しを利用可能
指示が競合した場合
- 編集対象ファイルに最も近いAGENTS.mdが優先、明示的なユーザーチャット指示があればそれが最優先
エージェントはAGENTS.md内のテストコマンド等を自動実行するか
- コマンドが記載されていれば、エージェントは関連チェックを実行し、失敗時は修正を試みる
後から内容を更新可能か
- AGENTS.mdは 生きたドキュメント として随時更新推奨
既存ドキュメントの移行方法
- 既存ファイルをAGENTS.mdへリネームし、シンボリックリンクで互換性維持
  - コマンド例：mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Hackerたちの意見

README.mdとAGENTS.mdを分けるのがいいアイデアだとはまだ納得できてないな。

└

この時点で、README.mdは「マーケティング/ランディングページのマークダウン」になって、AGENTS.mdやCLAUDE.mdは実際のコードやアーキテクチャ、使い方の概要を得るために訪れるものになるね。

└

その通り。READMEは人間向け、AGENTSなどはLLM向けだよ。ツールの使い方やインストール方法はREADMEに書いて、コンパイルやテスト、アーキテクチャの決定、コーディングスタンダード、リポジトリの構造などはエージェントのドキュメントに書くべきだね。

└

この例を読んでて、同じことを思ったよ。AGENTS.mdの内容は、いいREADME.mdに全部入ってるべきだね。

└

たぶんね。クロードには好きなことをClaudeファイルに入れさせて、時々それがめちゃくちゃじゃないか確認してる。人間向けに書いた高品質なREADMEにはすごく気を使ってるから。Claudeファイルには人間には明らかなことが書いてあって、READMEに詰め込むのは変だけど、Claudeが正しく動くためには必要な情報が入ってるんだ。

└

考慮すべき理由の一つは、LLMとのコンテキストの使い方について。一般的に、少ない方が良いし、README.mdファイルはテキストが多すぎることがあって、その中には毎回のコンテキストウィンドウに入れたくないものもある。私のプロジェクトでは、AGENT.mdやそれに似たファイルが、テストやビルドコマンドなどのフィードバックループに関する簡潔で具体的なコマンドを含んでいる。確かに同じコマンドがREADME.mdにもあるけど、毎回LLMに送るコンテキストウィンドウに入れたくない余計なテキストが多いことがあるんだよね。

└

これについても議論してるんだ: https://technicalwriting.dev/ai/agents/#gotta-keep-em-separa... （その投稿から引用）エージェントを分けておくべき理由: * 書き方。エージェントのドキュメントでは、すべて大文字を使うのが特定の指示を強調するのに効果的かもしれない。でも、内部のエンジニアドキュメントでは、失礼に感じられたり、気が散るかもしれない。 * 簡潔さと完全性。エージェントのドキュメントでは、内容を厳選する必要がある。情報を詰め込みすぎると、APIのクォータをすぐに使い切っちゃって、LLMの出力品質が下がる可能性がある。内部のエンジニアドキュメントでは、理想的には100%の完全性を目指すんだ。つまり、重要な設計決定、APIリファレンス、ワークフローなどはどこかに文書化されているべきなんだ。 * 知識のニーズの違い。LLMが必要とする情報は、人間のエンジニアが必要とする情報とは違う。例えば、Gemini 2.5 ProはPigweedのC++スタイルガイドをかなりよく理解している。Gemini APIを使って「Pigweed C++ガイドを全部 recite して」と指示したら、完全には recite しなかったけど、すべてのポイントの詳細な要約をくれた。だから、Gemini 2.5 Pro APIはスタイルガイドでトレーニングされているか、必要に応じてスタイルガイドを取得できるんだ。だから、AGENTS.mdのコンテキストとしてフルスタイルガイドを含める必要はないよ。（このアイデアはKeir Mierleに感謝。）反対の理由: * 重複。概念的には、エージェントのドキュメントは内部エンジニアドキュメントのサブセットなんだ。基本的な目標は同じで、チームにとって重要なワークフローや知識を文書化している。でも、今はその情報を2つの異なるドキュメントセットで維持しなきゃいけないんだ。

└

私たちはこれが役立つと思ってる: * エージェントはまだまだ不十分だから、コンテキスト管理や足元をすくうのを避けるための助けが必要なんだ。例えば、< 500locのai/readme.mdを作って、必須事項や他のリンク、使い方のメタ情報を載せてる。 * IaaCと似ていて、私たちが読むのと同じように準備が整ってないものを分けるのが役立つし、多くのマークダウンは自然言語で書かれたスクリプトみたいなものだから、例えばplan.md.templateとか。

└

かなり前のことだけど、多くのプロジェクトにはREADMEとBUILD/README.build/DEVELOPMENTファイルがあったよね… AGENTS.mdはこの最後のファイルに近いと思う。

これがフォーマットや標準だって、どういうこと？ただの名前空間の中のマークダウンじゃん。

└

このページは「LLMエージェントがリポジトリの指示を見るためのファイル名はAGENTS.mdです。それだけが標準です」と言うだけで100語以内に収まるよ。本当に問題だよ！今、すべてのエージェントが変なファイル名を使ってる。デイビッド・クロウショーのsketch.devが大好きだけど、理解できない理由で「dear_llm.md」って名前を選んでるんだよね。

└

標準は、シンプルで広く採用されることでその価値が生まれるんだよね。例えば、.gitignoreやCONTRIBUTING.md、LICENSEファイルなんかは、みんながその場所と目的に同意してるから機能するんだ。

Hacker Newsで議論の続きを見る

ハクソク