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ガイドライン

  • タイトル形式：[] </li> <li>コミット前に必ず<code>pnpm lint</code>と<code>pnpm test</code>を実行</li> </ul> </li> </ul> <h3>AGENTS.mdの使い方</h3> <ul> <li><strong>1. AGENTS.mdの新規作成</strong><ul> <li>リポジトリのルートにAGENTS.mdを配置、エージェントによる自動生成も可能</li> </ul> </li> <li><strong>2. 必要事項の記載</strong><ul> <li>エージェントがプロジェクトで作業しやすくなる項目をセクションごとに記載<ul> <li>プロジェクト概要</li> <li>ビルド・テストコマンド</li> <li>コードスタイル</li> <li>テスト手順</li> <li>セキュリティ考慮点</li> </ul> </li> </ul> </li> <li><strong>3. 追加指示の記載</strong><ul> <li>コミットメッセージやPRガイドライン、セキュリティ注意点、大規模データセット、デプロイ手順など</li> </ul> </li> <li><strong>4. 大規模モノレポでの活用</strong><ul> <li>サブプロジェクトごとにAGENTS.mdを配置可能</li> <li>エージェントはディレクトリツリー上で最も近いAGENTS.mdを自動参照</li> <li>OpenAIのメインリポジトリでは88個のAGENTS.mdを運用中（2024年6月時点）</li> </ul> </li> </ul> <h3>AGENTS.mdの背景とコミュニティ</h3> <ul> <li><strong>OpenAI Codex、Amp、Google Jules、Cursor、Factory</strong> などAI開発エコシステム全体での協働から誕生</li> <li><strong>オープンフォーマット</strong> として進化・維持をコミット</li> <li><strong>どのコーディングエージェントでも活用可能</strong>、開発者コミュニティ全体の利便性向上</li> </ul> <h3>FAQ</h3> <ul> <li><strong>必須フィールドはなし</strong><ul> <li>標準Markdownのみで構成、任意の見出しを利用可能</li> </ul> </li> <li><strong>指示が競合した場合</strong><ul> <li>編集対象ファイルに最も近いAGENTS.mdが優先、明示的なユーザーチャット指示があればそれが最優先</li> </ul> </li> <li><strong>エージェントはAGENTS.md内のテストコマンド等を自動実行するか</strong><ul> <li>コマンドが記載されていれば、エージェントは関連チェックを実行し、失敗時は修正を試みる</li> </ul> </li> <li><strong>後から内容を更新可能か</strong><ul> <li>AGENTS.mdは <strong>生きたドキュメント</strong> として随時更新推奨</li> </ul> </li> <li><strong>既存ドキュメントの移行方法</strong><ul> <li>既存ファイルをAGENTS.mdへリネームし、シンボリックリンクで互換性維持<ul> <li>コマンド例：<code>mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md</code></li> </ul> </li> </ul> </li> </ul>