AGENTS.md

Description:

AIコーディングエージェントへの指示やコンテキストを標準化する、プロジェクトのためのREADMEフォーマット

URL: https://agents.md/

GitHub:

https://github.com/agentsmd/agents.md

Tags:

Explore:

Qiita Zenn note Hatena

概要

AGENTS.md は、AIコーディングエージェント（Cursor, Aider, Claude Code, GitHub Copilotなど）に対して、プロジェクト固有の指示やコンテキストを伝えるためのシンプルかつオープンな設定フォーマットです。

「人間が得るための情報は README.md に、AIエージェントが必要とする詳細な技術コンテキストやコーディング規則は AGENTS.md に」という役割分担を提案しています。2026年現在、GitHub上の6万以上のプロジェクトで採用されており、AI時代のオープンソースプロジェクトにおける「第2のREADME」としての地位を確立しています。

なぜ AGENTS.md が必要なのか？

従来の README.md は、プロジェクトの目的、ライセンス、主要な依存関係など、人間がプロジェクトを理解し貢献を開始するための情報を主眼に置いています。しかし、AIエージェントが「自律的に」コードを修正したりテストを実行したりするには、人間には暗黙知となっている以下のような詳細な技術コンテキストが必要になります。

AIが必要とする情報の例

厳密なビルドステップ: npm install だけでなく、特定の環境変数が必要か、特定のプリビルドスクリプトが必要かといった詳細。
暗黙のコーディングルール: 「特定のライブラリの使用を避ける」「このディレクトリ配下のファイルは自動生成されるため直接編集禁止」といったプロジェクト独自の制約。
デバッグの指針: エラーが発生した際、どのログを確認すべきか、どのツールを使って診断すべきかという「手順」。

これらを AGENTS.md という標準的な名前でプロジェクトのルートに配置することで、エージェントは読み込み時に自動的にこの情報を吸収し、人間の監督がなくてもプロジェクトの「お作法」に従った行動が可能になります。

フォーマットの背景と管理

AGENTS.md は、OpenAI (Codex), Anthropic, Google (Jules), Cursor などのAI開発をリードする企業群による共同の取り組みから生まれました。

現在、この規格は Linux Foundation 傘下の Agentic AI Foundation (AAIF) によって管理されています。特定の企業が独占するのではなく、オープンな標準として進化を続けている点が特徴です。

特徴とメリット

特徴	詳細
人間とAIの関心の分離	`README.md` をビジネス要件や概要に集中させ、`AGENTS.md` に実装詳細を詰め込むことで、ドキュメントの肥大化を防ぎます。
エコシステム間のユニバーサル対応	1つの `AGENTS.md` を用意するだけで、Cursor, Aider, Claude Codeなど、利用するエージェントに関わらず同様の品質が得られます。
低コストな導入	JSONやYAMLのような厳格なスキーマは不要で、プレーンなMarkdownとして今すぐ書き始めることができます。
手戻りの削減	規約を文書化しておくことで、AIが誤ったスタイルでコードを作成する「ハルシネーション」的挙動を大幅に抑えられます。

他の設定フォーマットとの比較

AIエージェント向けの指示ファイルにはいくつか種類がありますが、AGENTS.md はその中でも「オープンな標準」という位置付けです。

フォーマット	対象範囲	特徴
AGENTS.md	プロジェクト全体	オープン標準であり、すべてのエージェントが読み込むことを想定。
.cursorrules	プロジェクト全体	Cursor専用。エディタの挙動や特定のプロンプト設定に特化。
SKILL.md	特定の機能・ワークフロー	Agent Skills規格。汎用的な「技術（スキル）」をパッケージ化して再利用。
.clauderc	セッション単位	Claude CLI等での個人設定。

導入方法と推奨構成

プロジェクトのルートディレクトリに AGENTS.md を作成します。構成に厳密な決まりはありませんが、一般的に以下のセクションに分けて記述することが推奨されています。

1. Setup & Environment

エージェントがタスクを開始する前に実行すべきコマンド。

- `npm install` を使用。
- `npm run dev` で開発サーバー起動（ポート 3000）。
- `.env.example` から `.env` を作成し、必要なキーを設定すること。

2. Coding Standards

AIに守らせたい具体的な実装スタイル。

- TypeScript を必須とし、`any` の使用は避ける。
- 非同期処理には `async/await` を使用し、Promiseチェーンは避ける。
- コンポーネントは `src/components/` に配置し、PascalCase で命名。

3. Architecture Context

プロジェクト固有の構造の解説。

- `src/core/` はドメインロジック。UIには依存せず、テストのカバレッジを高く保つ。
- `dist/` 配下は自動生成物。絶対に手動で編集しないでください。

4. Testing Guidance

テストの実行方法と品質基準。

- `npm test` で Jest によるテストを実行。
- 新機能を追加する際は、必ず対応する `.spec.ts` ファイルを作成してください。

発展的な活用：エージェントとの「対話」を記録する

高度な活用方法として、AGENTS.md に「過去にエージェントがハマった点」を追記していく手法があります。

「以前、このモジュールのリファクタリングで循環参照が発生した。今後同様の変更を行う際は util/resolver.ts を経由すること」

このように記載しておけば、別のエージェント（あるいは将来の自分）が同じミスを繰り返すことを防ぐことができます。まさに、プロジェクト専用の「AIのためのメンター資料」として機能します。

対応している主なエコシステム (2026年最新)

IDE / Editor: Cursor, Zed, Windsurf, Warp, VS Code (Copilot Enterprise)
CLI Tools: Aider, goose, opencode, Gemini CLI, Claude Code
Service: GitHub Copilot Workspace, Devin, Pluto, Factory
Frameworks: LangChain, CrewAI, AutoGen (各オーケストレーターでの自動読み込みをサポート)