AGENTS.md(エージェンツエムディー)とは
AGENTS.mdとは、Codexなどのコーディングエージェントに、プロジェクトごとの作業ルールや確認手順を伝えるMarkdownファイルです。人間向けのREADME.mdが概要や使い方をまとめるのに対し、AGENTS.mdはAIが作業前に読む「このリポジトリではこう動く」という指示書に近い存在と言えます。
英語表記:AGENTS.md
読み:エージェンツエムディー
何を書くファイルか
典型的には、テストコマンド、編集してよい範囲、コードスタイル、レビュー前の確認、触ってはいけないファイルを記す項目です。AIエージェントはリポジトリ内の情報を頼りに作業するため、暗黙知をそのままにすると、意図しない修正や確認漏れにつながります。
経営側の視点では、AGENTS.mdは「AIに仕事を頼むための社内手順書」です。属人的な口頭指示をファイル化することで、担当者が変わっても同じ基準で作業を始められます。ただし、APIキー、パスワード、顧客情報は書いてはいけません。エージェントが読める場所に秘密情報を置くと、流出や誤送信のリスクになります。
運用で失敗しない見方
AGENTS.mdは一度書いて終わりではありません。新しいテスト、禁止したい作業、レビューで頻発したミスがあれば、短く追記して改善する運用にします。長すぎる指示は読まれにくく、矛盾した指示は品質を落とすため、重要ルール、確認コマンド、停止条件を中心に整理しましょう。
特にWordPress、Shopify、社内CRMのように本番影響が大きい領域では、バックアップ、権限、公開前確認を明文化します。AGENTS.mdはAIエージェントを賢くする魔法ではなく、失敗しにくい作業環境を作るための入口と考えると扱いやすいでしょう。
Topic近い階層の指示ほど強くなる
OpenAIのAGENTS.mdガイドでは、Codexがグローバル設定から作業ディレクトリまで順に指示を読み、近い階層の内容が後から入ると説明されています。これは会社全体の規程と部門ごとの手順が重なる構造に似ています。
AGENTS.mdに関するよくある質問
- AGENTS.mdはREADME.mdの代わりですか？
- 代わりではありません。README.mdは人間向けの概要、AGENTS.mdはAIに守らせたい作業条件を置く場所として分けます。
- AGENTS.mdに秘密情報を書いてもよいですか？
- 書いてはいけません。認証情報は環境変数や安全な管理場所で扱い、AGENTS.mdには参照手順や禁止事項だけを書きます。
- どのくらい詳しく書くべきですか？
- 最初は短くて十分です。テスト方法、編集禁止範囲、公開前チェック、停止条件を優先し、レビューで見つかった問題を追加します。
