AGENTS.md ガイド: コーディングエージェント (AI エージェント) 用のオープンソースの「プロジェクト記述」形式。 AGENTS.md は、「AIコーディングエージェント」のオープンソースの命令形式です。 これは README の「エージェント バージョン」のようなもので、ビルド、テスト、コード仕様、考慮事項などの重要な情報をエージェントに提供し、エージェントがコードベースでタスクをより確実に実行できるようにします。 同サイトによると、多くのオープンソースプロジェクトがこの形式を採用しているという。 その設計目標は、複数のエージェントとツールで共通であり、チームやオープンソースリポジトリが迅速に実装するのに適しています。
1. AGENTS.md とは1
) ポジショニング: README の機能補足である AI コーディング エージェントのドキュメント ドキュメント。
2) 目標: エージェントに固定された予測可能な入り口を与えて、コンテキストと指示を一元化して「エージェントを効率的に作業させる」ようにします。
3) フォーム: 純粋なマークダウン、強制フィールドなし。 オンデマンドで書き込み、長期的なメンテナンスとバージョン管理を行います。
2. なぜ AGENTS.md が必要なのか(READMEとの関係)
1) READMEは人間の読者を対象としており、製品の説明、クイックスタート、投稿ガイドに重点を置いています。
2) AGENTS.md エージェント指向で、ビルド/テスト コマンド、コード スタイル、CI 要件、セキュリティ ポイントに重点を置きます。
3) 分離の利点: README を簡潔に保ちながら、エージェントに「これを見るだけで仕事をできる」という専用のドキュメントを提供します。
3. コア設計と生態学的互換性
1) オープン形式: 任意のサブセクションのタイトルとコンテンツ構造を使用し、テキストによるプロキシ解析を使用し、独自の構文は使用しません。
2) マルチエージェントの互換性: 複数のエージェント/ツール (Codex、Amp、Jules、Cursor、Factory、RooCode など) の適応方向の公式リスト。
3) 優先順位ルール: 命令の競合が発生した場合、ターゲット ファイルに最も近い AGENTS.md が有効になります。 明示的なユーザー ダイアログの指示は、一般的な命令よりも優先されます。
4) モノレポフレンドリー: サブパックに「近く」の AGENTS.md 配置をサポートします。 大規模な倉庫では、さまざまなサブプロジェクトのエージェントの説明をレイヤーで管理できます。
4. 採用方法 (4 つのステップ)
1) ファイルを追加する: コードベースのルート ディレクトリに AGENTS.md を作成します。 必要に応じて、サブパックにコピーを入れます。
2) カバレッジの焦点: プロジェクトの概要、ビルドとテストのコマンド、コードスタイル、テスト仕様、セキュリティとコンプライアンスのポイント。
3) 補足ルール: 提出情報と PR 仕様、データとモデル リソースのダウンロード、展開手順と一般的な落とし穴。
4) 反復メンテナンス: これを「生きたドキュメント」として扱い、CI/依存関係/ディレクトリ構造が更新されるにつれて更新します。
5. 利用可能な最小限のテンプレート
# AGENTS.md ## プロジェクト概要 - モノレポ+PNPMワークスペース。 主な言語はTypeScriptです。 ## セットアップ &; ビルド - インストール: pnpm install - 開発: pnpm dev - テスト:pnpmテスト - 糸くず: pnpm lint ## コードスタイル - TSストリクトモード。 単一引用符、セミコロンなし。 関数式が優先されます。 ## テスト - .github/workflows の CI。 コミットする前に、すべてのユースケースをローカルに渡す必要があります。 ## PRルール - タイトル: [<pkg>] <タイトル>; コミットする前に lint を実行してテストする必要があります。 ## セキュリティ - .env を送信しないでください。 キーは、ウェアハウスシークレットまたはローカルインジェクションを使用して挿入されます。
6. 代表的な使用例1
) オープンソースリポジトリ: それに接触したエージェントに「すぐにテスト」させ、ビルド/シングルテスト/静的チェックを自動的に実行します。
2) チームコラボレーション: エージェントと人の間の摩擦を減らすための明示的な「暗黙の規則」(コーディング スタイル、送信プロセス)。
3) 大規模な倉庫ガバナンス: サブプロジェクトごとに AGENTS.md を分割して、近くの指示と差別化されたプロセスを実現します。
4)セキュリティとコンプライアンス:「アップロード不可のデータ/モデル」とセキュリティのレッドラインを明確に書き、自動化された運用のリスクを軽減します。
7. 実装の提案とリスク警告1
) 「最小限のテンプレート」から始めて、ビルド、テスト、スタイル、PR ルールのみを行い、徐々に改良します。
2) CI との整合性: CI から AGENTS.md へのキー コマンドを同期して、「エージェントは実行されるが CI は実行できない」ことを回避します。
3)明示的な競合処理:ファイルの先頭に「ユーザー指示と競合がある場合は、ユーザー指示が優先する」と書く。
4) 不確実な記述: 「採用されたプロジェクトの数」などの指標に関しては、データの誤読を避けるために「サイトの自己声明に従って」とマークすることをお勧めします。
Q&A よくある質問Q
: AGENTS.md に必須のフィールドや標準テンプレートはありますか?
A: いいえ。 これは、プロジェクトの実際のニーズに応じて章を編成することを奨励する一般的な Markdown 命令です。
Q: README で作業をどのように分割していますか?
A: READMEは人向けです。 AGENTS.md エージェント指向。 前者は「何を/どのように開始するか」について話し、後者は「エージェントがビルド/テスト/仕様をどのように実行するか」について話します。
Q: Monorepoは複数の AGENTS.md をどのように整理しているのですか?
A: 一般的な説明をルートディレクトリに配置し、最も近い説明をサブパッケージに配置します。 エージェントは通常、ターゲット ファイルの最も近いコピーの読み取りを優先します。
Q: 複数のプロキシ ツールをサポートしていますか?
A:プロジェクトページによると、複数のエージェントやツールに対応して設計されており、原則として「1つのドキュメント、複数のエージェントが利用可能」です。
