第51回：AGENTS.mdの目的・機能と導入による効果

はじめに

AGENTS.md は、AIコード支援エージェントのための「プロジェクト専用README」とも言えるMarkdownドキュメントです。 リポジトリ内に配置し、ビルド／テスト手順、コード規約、アーキテクチャ概要、セキュリティ上の注意、PR運用など、 エージェントが作業開始前に把握しておくべき情報を一箇所に集約します。README.mdを人間向けの簡潔な要約に保ちつつ、 AGENTS.mdにはエージェントに必要な詳細を過不足なく記述する——この役割分担によって、AIと人の協調開発を加速させます。

1. AGENTS.mdの役割と目的

• エージェント向けの詳細な指示集： 人間向けREADMEでは省きがちな具体手順や内部規約を、機械可読な形で提供。
• プロジェクト文脈の明示： 技術スタック、ディレクトリ構成、ドメイン固有用語、外部サービス連携、環境変数など。
• 標準化の核： ツールごとにバラついていた独自指示ファイルを統一（One AGENTS.md for many agents）。
• 人間の部族知の共有： 熟練者の暗黙知を、エージェントが行動できる粒度で明文化。

2. 典型的に記載する内容（テンプレ例）

• ビルド＆テスト：npm run build / pnpm test 等の具体コマンド、対象ランタイム、CIの前提。
• コードスタイル：言語別規約（例：TS 厳格モード、シングルクォート、セミコロン禁止等）、アーキテクチャパターン。
• アーキテクチャ概要：主要モジュール、データフローの1段落サマリー、フォルダ命名・配置ルール。
• セキュリティ＆外部サービス：APIキーの扱い、認証フロー、必要な環境変数名、機微データのガイド。
• Gitフロー／PR規約：ブランチ戦略、コミットメッセージ規則、PRに含めるべきチェック項目。

3. 設計・連携フローへの具体的な影響

多くのAIコーディングエージェントは、タスク開始時に作業ディレクトリで最も近い AGENTS.md を読み込み、 記載された手順や規約をプランニングへ直結させます。例えば「編集後にpnpm testを実行し、全テストを通す」 という一文があれば、エージェントは自動的にテスト実行→失敗時の修正→再実行を行程に組み込みます。
また、フォルダ構成・命名規約は新規ファイル作成や編集範囲の判断に、セキュリティの注意点や用語集は誤解・幻覚の低減に寄与します。

3-1. マルチエージェントでの効果

複数エージェントが協働する場合でも、共通の AGENTS.md を参照することで前提が揃い、タスク分担が滑らかになります。 大規模モノレポでは、サブプロジェクトごとに複数のAGENTS.mdを配置し「最も近いものを使う」階層ルールで適用範囲を切り分ける運用が有効です。

4. VS Code / GitHub Copilot との統合

• Copilotエージェント対応： リポジトリ直下（必要に応じてサブディレクトリ）にAGENTS.mdを置けば、エージェントが自動で読み込みます。
• 計画への自動反映： 記載のビルド／テスト手順を行動計画に取り込み、編集後の検証ループを自律的に実行。
• IDE体験： VS CodeではAGENTS.md中のパスやURLがリンクとして機能し、コード箇所へ素早く移動できます。
• 移行の容易さ： 既存の .github/copilot-instructions.md 等からの移行や併用も可能（優先度はAGENTS.md）。

5. 導入効果：生産性とコラボレーション

• 試行錯誤の削減： 正しいコマンド・規約を事前共有することで、無駄なビルド失敗や探索コストを抑制。
• 品質向上： 「テスト必須」「リンター順守」などが自動的に執行され、CI通過率が向上。後工程の手戻りが減少。
• オンボーディング高速化： 人・AIの新人が最初に読むべき「一本化ドキュメント」として機能。プロジェクト流儀が浸透。
• チーム文化の統一： 各メンバーが異なるAIツールを使っても、参照ルールが一つなので出力の方針と品質が揃う。

AGENTS.md は、AIにプロジェクトの「作法」を教えるためのナレッジレイヤー。
README.md と役割分担しつつ、エージェントが“理想の新人エンジニア”として動ける土台を作ります。

6. 他フォーマットとの関係（YAML/JSON 等）

AGENTS.mdはMarkdownであり、厳密なスキーマを持ちません。これは「特定ツールへのロックインを避け、誰でも書ける」ための選択です。 一方で、YAML/JSONのような厳密な構造化が必要な箇所は従来通りそれらを用い、AGENTS.mdから参照・説明します。 つまり、AGENTS.mdは設定の代替ではなく、AIに文脈を渡すための説明層として機能します。

7. 導入・運用のベストプラクティス

• 単一の情報源： ビルド手順や規約が変わったらAGENTS.mdを必ず更新。重複ドキュメントを作らない。
• セクション化： 「ビルド/テスト」「コード規約」「セキュリティ」「PRフロー」など見出しで整理。
• コマンドは具体的に： npm run build のようにコピー＆ペーストで実行できる形で記載。
• 階層配置： モノレポでは各サブディレクトリに必要な分だけAGENTS.mdを配置し、最近傍ルールで適用。
• CI連携： AGENTS.mdに記載の手順をCIで検証し、乖離を検知（変更漏れを防止）。

まとめ

AGENTS.mdは、AIエージェントと人間開発者の協調開発を前提にした、新しい「プロジェクトの作法書」です。 ベンダー中立のMarkdown一枚で、エージェントが守るべき文脈・手順・規約を共有し、開発のスピードと品質を両立させます。 まずはリポジトリ直下に最小限のAGENTS.mdを置くことから始め、プロジェクトに合わせて段階的に育てていくのが良いアプローチです。