🦁

AGENTS.mdとは？ ─ プロジェクト品質管理にも通じる実践ガイド

に公開
AI
開発環境
品質管理
zennfes2025ai
idea

AGENTS.mdとは？ ─ プロジェクト品質管理にも通じる実践ガイド

サムネイル

最近、Github CopilotやOpenAIのCodexなどAIコーディングエージェントをチーム開発に活用する動きが広がっています。これらのAIツールとプロジェクトを円滑に連携させるために、新たなドキュメント形式として 「AGENTS.md」 が注目されています。これは、上述のようなエージェント向けの設定ファイルフォーマットのことであり、目的としては、エージェントにプロジェクトの内容やルールを分かりやすく説明することが挙げられます。

一方で、この仕組みは単にAIを便利に使うためだけではありません。プロジェクトのルールや開発手順を文書として体系的に残し、品質を安定させる という効果も大きなポイントです。よく課題として挙げられる「プロジェクトのルールを逐一AIに説明するのが大変」「AIが構造を理解できず二度手間になる」といった問題に対処するだけでなく、結果的に人間の開発者同士にとっても再現性のある品質管理につながります。
開発にAIを使う／使わないを問わず、プロジェクト品質を支えるのはドキュメント整備という普遍的な営み です。その意味で、AIを使わない方にとってもAGENTS.mdは一読の価値があるでしょう。

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

AGENTS.md とはプロジェクトリポジトリに追加するMarkdown形式のファイルで、AIコーディングエージェント向けの README のようなものです。人間の開発者向けのREADME.mdがプロジェクトの概要や使い方を簡潔にまとめているのに対し、AGENTS.mdはAIエージェントに特化した詳細な指示書の役割を果たします。
https://agents.md/
例えばビルドやテストの正確なコマンド、コードのスタイル規約、プロジェクト独自のルールなど、人間向けREADMEには書かれないような“機械向け”情報をまとめておくのです。

これによって、人間向けのREADMEはシンプルさを保ちつつ、AIエージェントには別途必要な情報を網羅した明確なガイドを提供することが可能になります。AGENTS.mdはAIにとって予測可能な場所に配置された一貫した情報源であり、AIエージェントがプロジェクトを理解し行動するための専用の説明書となります。

なぜ今、AGENTS.mdが必要とされているのか?

最も大きな要因としては、AIコーディングエージェントが開発現場で担う役割が増えてきたことが挙げられます。現場によって、浸透具合はさまざまですが、現在のAIは、開発環境のセットアップからテストの実行、コード整形（フォーマット）や品質検査・レビューまで、様々なルーチンタスクを自動化・支援することが可能であるとされています。
一方で、従来のREADME.mdは基本的に人間向けに記述された書式であるために、実際にAIが必要とする細かな手順やプロジェクト固有のルールが省略されがちです。その結果、AIエージェントはプロジェクトごとに構成やコマンドを一から探索し学習する必要が生じ、毎回余計な時間やリソースを浪費してしまうという問題が指摘されています。

この非効率を解消し人間とAIの協調をスムーズにすることがAGENTS.mdの目的です。AGENTS.mdにあらかじめ環境構築やテスト方法、コーディング規約などを記載しておけば、エージェントは最初からプロジェクトのルールに沿って動くことができます。「一度書いておけば、毎回プロンプトで同じ説明を繰り返す必要がなくなる」というわけです。
さらにAGENTS.mdはオープンな標準形式として提案されており、複数のAI開発支援ツール間で共通に使える点も重要です。実際、OpenAI CodexやGoogleのJules、Cursorなど多くのAIコーディング支援ツールがAGENTS.mdをサポートしています。各ツールごとに個別の設定ファイル（例1）を用意する代わりに、AGENTS.mdひとつでプロジェクトのルールを一元管理できるため注目を集めているのです。

例1. 各ツールごとに個別の設定ファイルを用意した場合。
CLAUDE.md,GEMINI.mdなどが入り乱れていることが分かります。

root/
├─ README.md
├─ AGENT.md
├─ CLAUDE.md      
├─ GEMINI.md
├─ .clinerules/
│  └─ rules/
│     ├─ base.mdc
│     └─ testing.mdc
├─ .rouroules/
│  └─ general.mmcd
├─ packages/
│  ├─ README.md
│  ├─ AGENTS.md
│  └─ .cursor/rules/ui.mdc
├─ api/
│  ├─ README.md
│  └─ CLAUDE.md
├─ worker/
│  └─ GEMINI.md
└─ tools/
   └─ scripts/

例2. AGENTS.mdにより統合した場合

root/
├─ README.md
├─ AGENTS.md
├─ packages/
│  ├─ README.md
│  └─ AGENTS.md
├─ api/
│  ├─ README.md
│  └─ AGENTS.md
├─ worker/
│  └─ AGENTS.md
└─ tools/
   └─ scripts/

AGENTS.mdは人間とAIの橋渡し役を担ってくれます。共通フォーマットにプロジェクト情報をまとめることで、「AIに何をしてほしいか」 を明確に伝え、開発ワークフローにおける人間とAI間の摩擦を減らす狙いがあります。これは、README.mdがオープンソース初期に果たした役割（プロジェクトの統一的な案内役）にも通じており、今後AGENTS.mdもそれに匹敵する存在になる可能性があると言われています。

実践 - AGENTS.mdに記載すべき内容

では、具体的なプロジェクトを例にAGENTS.mdの内容を検討してみましょう。今回例に挙げるのは、Python/Djangoを用いたプロジェクトです。
基本的な考え方は「新人メンバー向けに渡す詳細な開発ガイドの作成」というイメージになります。
以下のような内容を含むと良いでしょう。

  • プロジェクト概要・アーキテクチャ: プロジェクトの全体像や技術構成のメモ。主要なフレームワークやライブラリ、データベースなどを箇条書きします。
    例: 「本プロジェクトはPython 3.12上で構築されたDjangoアプリケーションです。ユーザー認証にdjango-allauthを使用し、フロントエンドは標準のDjangoテンプレート＋HTMX/Alpine.jsで動的UIを実現しています…」

  • 開発環境のセットアップ手順: ローカル開発環境を構築するための具体的な手順です。使用Pythonのバージョン、仮想環境の作成方法、依存パッケージのインストールコマンド、開発サーバーの起動方法などを明示します。
    例: 「Python 3.x系で動作確認しています」「仮想環境を作成しrequirements.txtから依存関係をインストールしてください (pip install -r requirements.txt)」「ローカルサーバーはpython manage.py runserverで起動します」など。

  • テストの実行方法: 自動テストの手順やコマンドを示します。Django標準のテストやpytestの利用有無、カバレッジ計測方法などもここに含めます。
    例: 「ユニットテストは python manage.py test で実行できます。pytestを使用している場合は pytest コマンドを利用してください。テストはすべて成功している状態でプルリクエストを提出してください」

  • コードスタイル: コーディング規約やコードフォーマットのルールです。PEP8に準拠しているか、使用しているフォーマッタ（例えばflake8など）等を明記します。
    例: 「本プロジェクトではPEP8スタイルガイドに従っています。コード整形にはFlake8を使用してください。コミット前にflake8を実行し、コードスタイルを検証してください」

  • セキュリティに関する方針: プロジェクト独自のセキュリティ上の注意事項や、AIエージェントに守ってほしいルールです。例えば 「機密情報をコード上にベタ書きしない」 とか 「環境変数ファイル（.env）から認証情報を読み込む」 といったガイドライン、データの取扱いポリシー などを含めます。Djangoならではの例として「デバッグモードは本番環境で無効にする」「重要な設定項目（SECRET_KEYなど）は環境変数で注入する」といった点も書けます。加えて、エージェントがコード生成する際にセキュリティ上考慮すべき事項（例えば「ユーザー入力はDjangoのフォームやバリデーションを使って必ず検証する」等）も伝えられるでしょう。

  • その他の開発ルール: 上記以外にも、プロジェクト特有のルールやベストプラクティスがあれば記載します。例えばコミットメッセージやプルリクエストの書き方（フォーマットや含めるべき情報）を示すチェックリスト、Gitフローやブランチ戦略の簡単な説明、CI/CDの実行手順、デプロイ手順、使用している外部サービス(APIキーの管理方法など)に関する注意など、新しく参加したエンジニアに伝えたい事柄は何でも含めてOKです。AIエージェントに対しても、これらのルールを教えておくことで、例えば「プルリクエストのタイトルはfeat: ...の形式にする」「テストがすべてグリーンになっていることを確認してから提案を完了する」といった動作を促すことができます。

AGENTS.mdにはプロジェクト運営上の「約束事リスト」 を網羅して記載します。特にDjangoプロジェクトでは、開発手順（環境構築やサーバー起動、マイグレーション適用など）やテスト/デプロイ手順、コーディング規約（Pythonのスタイルガイド、Djangoのベストプラクティス）などを明文化しておくと、AIエージェントがそれらを踏まえて作業してくれやすくなります。

AGENTS.mdのテンプレート例

参考までに、簡単なAGENTS.mdのひな型例を示します。Djangoプロジェクトを題材に、どんな内容を盛り込めるかイメージしてみましょう。

# AGENTS.md

## プロジェクト概要 / Overview
- **フレームワーク**: Django 4.x （Python 3.10）
- **データベース**: PostgreSQL (本番), SQLite (開発)
- **主要ライブラリ**: Django REST Framework (API構築用), Celery + Redis（タスクキュー）
- **環境設定**: 環境変数は `.env` ファイルで管理（機密情報はコードに直書きしない）

## 開発環境セットアップ / Development Setup
- Python 3.10 を使用してください（推奨: virtualenvで仮想環境を構築）
- リポジトリをクローン後、仮想環境を作成しアクティベートする:  
  `python3 -m venv venv && source venv/bin/activate`
- 依存パッケージをインストール:  
  `pip install -r requirements.txt`
- データベースを準備:  
  `python manage.py migrate` でスキーマを適用
- 開発サーバーを起動:  
  `python manage.py runserver` （デフォルトで http://127.0.0.1:8000/ で起動）

## テストの実行方法 / Testing
- ユニットテストを実行: `python manage.py test`  
  （またはpytest使用時: `pytest`）
- 新機能を追加した際は必ず対応するテストコードを追加してください
- テストが全てパスすることを確認してから変更を確定します

## コードスタイル / Code Style
- コーディング規約: **PEP8**に準拠 (スタイルガイドの遵守)
- フォーマッター: **Black** を使用（`black .` でソースコードを整形）
- リンター: **Flake8** を使用（`flake8` で静的解析チェック）
- インポート順の整理: **isort** を使用（`isort .` でインポート並び替え）
- これらのフォーマットチェックはコミット前に必ず実行し、指摘がない状態にしてください

## セキュリティ方針 / Security
- **秘密情報は厳重に管理**: APIキーやパスワードなど秘密情報は`.env`や環境変数から読み込み、絶対にGitに含めないでください
- **ユーザ入力の検証**: フォームやAPIで受け取る入力はDjangoのバリデーション機構で適切に検証してください
- **デバッグ設定**: 開発中以外では`DEBUG = False`に設定し、エラーページや機密情報が漏洩しないようにします
- **依存パッケージ**: 新しいパッケージを導入する際はセキュリティ面を確認し、必要に応じてチームの承認を得てください

## プルリクエストガイドライン / PR Guidelines
- **タイトル形式**: `feat: 機能概要` のように、プレフィックスと簡潔な説明を書いてください
- **事前チェック**: コードを提出する前に `flake8` や `pytest` を実行し、エラーやテスト失敗がないことを確認しましょう
- **差分の範囲**: 1つのPRは関連する変更に留め、小さくまとまった変更を心がけてください（大規模な変更は分割を検討）
- **説明コメント**: PRの説明欄には変更内容と目的、動作確認の方法を簡潔に記述してください

上記はあくまで一例です。プロジェクトの性質に合わせてセクションを増減したり内容を調整したりします。AGENTS.mdに定まったスキーマはなく、Markdownで自由に書けるとされています。見出しや項目名もプロジェクトに合ったものに変えて問題ありません。重要なのは、AIエージェントに伝えたい情報が過不足なく整理されていることです。

AGENTS.md作成時のポイントと今後の活用アイデア

最後に、AGENTS.mdを作成・運用する上での注意点や工夫についていくつか紹介します。

  • 小さく始めて継続的に改善する: 最初から完璧なAGENTS.mdを用意する必要はありません。まずは重要な項目から書き始め、AIエージェントの提案や動作を試しながら足りない情報を追記・修正していくと良いでしょう。実際に「AIが望ましくないコードを生成したら、その都度ルールをAGENTS.mdに追加し、再実行させて徐々にプロジェクトに合わせ込んでいる」という開発者の声もあります。
    https://forum.djangoproject.com/t/ai-agent-rules/40929/2
    このように試行錯誤を通じてAGENTS.mdを育てていく姿勢が大切です。

  • 内容は常に最新に保つ: AGENTS.mdは一度書いたら終わりではなく、README.md同様に生きたドキュメントとして扱います。プロジェクトに変更（使用ツールのアップデートや新ルールの追加など）があれば、その都度AGENTS.mdも更新しましょう。AIエージェントは最新の情報を頼りに動作するため、ドキュメントの陳腐化を防ぐことが重要です。

  • 人間のレビューと併用する: AGENTS.mdが充実すればAIエージェントはかなり賢く立ち回れるようになるとされていますが、それでも最終的な判断は人間が行う必要があります。ビジネスロジックの意図やプロジェクトの本質的な目的まではAGENTS.mdだけで伝えきれない場合もありますし、あくまでAIエージェントは人間の補助的な役割にすぎません。必ず人間のレビューやテストを経て受け入れるようにしましょう。また、AGENTS.mdに記載しきれない高度な設計判断やチームの暗黙知については、引き続き開発者間での共有・議論が必要だと思います。

  • 複数のAIツールで活用する: 現時点で主要なAIコーディング支援ツールはAGENTS.mdに対応しつつありますが、もし特定のツールが独自の設定ファイルを要求する場合でも心配ありません。単一のAGENTS.mdを他の設定ファイルから参照させることで実質的に一本化できます。例えば「CLAUDE.md」などツール固有名のファイルを用意し、中に「./AGENTS.mdを遵守せよ」と記述することで、全エージェントが同じルールを参照するようにできます。
    将来的な流れはまだまだ予測しにくい側面がありますが、現段階ではプロジェクト内で工夫しつつ運用するのが良いと思います。

  • 新たなメンバーや将来の自分への財産: AGENTS.mdはAIエージェントのためだけでなく、人間の新人開発者にとっても有用です。README.mdより詳細な開発手引きとして機能するため、新しくプロジェクトに参加したメンバーが環境構築や開発ルールを理解する助けになります。チーム全員でAGENTS.mdをメンテナンスし、プロジェクトの知見を蓄積する場として活用していくと良いでしょう。

おわりに

いかがでしたか？実際、AIとの協業という大それたことを言いつつも、実は「ドキュメントをしっかり残しましょう」というプロジェクト全体の開発品質を支える文脈に過ぎない ことがよく分かると思います。

ドキュメントの整備はAIの有無に関わらず、ソフトウェア開発の品質を左右する重要な要素です。コード規約やテスト手順、環境構築方法を明文化しておけば、開発者が誰であっても同じ水準の成果を出しやすくなります。逆にこれらが曖昧なままでは、ヒューマンエラーや認識齟齬が積み重なり、品質のばらつきや不具合につながりやすくなります。

AGENTS.md はその延長線上にあるものです。AIを活用する際に役立つだけでなく、プロジェクト内のルールや知見を一箇所に集約する「品質基準書」として機能します。結果として、開発体制の安定化や新規メンバーのスムーズなオンボーディングにもつながるでしょう。

AI時代だからこそ注目されていますが、本質は普遍的です。「プロジェクトの品質は、コードだけでなくドキュメントの品質によっても大きく左右される」 ──その当たり前を改めて実践するきっかけとして、AGENTS.md を活用していくことが大切だと思います。

Discussion