AGENTS.mdは、AIエージェントにプロジェクトの概要、作業ルール、ビルドやテスト手順、注意点を伝えるためのMarkdown形式の指示ファイルです。
OpenAI CodexなどのAIコーディング環境では、プロジェクトごとのルールを読み込ませる用途で使われます。
まず押さえたいポイント
- AIに毎回伝えたいプロジェクト前提を書くファイル
- 拡張子
.mdのMarkdownファイルとして書く - ビルド、テスト、デプロイ、禁止事項を書くと効果が出やすい
- 人間向けREADMEとは役割が近いが、AIが作業で迷いやすい点をより具体的に書く
どんな場面で使うか
AIにコード変更、記事作成、テスト修正、リファクタリングなどを依頼するとき、プロジェクト固有の前提を毎回チャットで説明するのは大変です。
AGENTS.mdに「このリポジトリは何か」「どのコマンドで確認するか」「本番反映前に何を見るか」を書いておくと、AIが同じ前提で作業しやすくなります。
たとえば、Laravelプロジェクトなら、記事データの場所、テストコマンド、Seederの実行手順、触ってはいけない設定ファイルなどを書くと実務で効きます。
よくある誤解
AGENTS.mdは、AIを完全に縛る強制設定ではありません。
あくまでAIに渡すコンテキストなので、重要な作業ではチャットでも「AGENTS.mdを読んでから進めて」と明示した方が安全です。
また、長くすればするほど良いわけでもありません。
古い情報や関係ない説明が増えると、AIが大事な指示を見落としやすくなります。短く、具体的で、検証可能な指示の方が使いやすいです。
実務で見るポイント
AGENTS.mdには、秘密情報を書かないことが重要です。
APIキー、パスワード、本番DB接続情報、クライアントの機密情報は含めず、必要なら環境変数名や確認手順だけを書くようにします。
AI向けmdファイル全体の使い分けは、AIコーディングで使うmdファイルとは？AGENTS.md・CLAUDE.md・指示書の役割を整理 で詳しく整理しています。