AGENTS.mdとは？AIエージェント専用READMEの役割と使い方
AIコーディングエージェントをプロジェクトに導入する際、まず課題になるのが「どうやってエージェントに正しいルールや手順を理解させるか」です。
その解決策が AGENTS.md。人間が読むREADMEとは別に、AI専用のREADMEとしてセットアップ手順やコード規約、開発ワークフローをまとめておくことで、エージェントは迷わず作業を進められます。
本記事では、開発者がすぐに導入できるように、AGENTS.mdの基本構成・運用ポイント・READMEとの違いをわかりやすく解説します。
OpenAIは2025年8月20日に、AIコーディングエージェントへの指示するためのシンプルなフォーマット「AGENTS.md」公開しました。
AGENTS.md とは
OpenAI Codexのほか、Amp、GoogleのJules、Cursor、Factory、Roo Codeといったエージェントやツールの開発チームと協力して作られました。
OpenAI Codexチームは、他のAIエージェントでも採用しやすい形で「AGENTS.md」という名前を作成しました。
AGENTS.mdは、AIコーディングエージェントがプロジェクト内で作業するためのコンテキストや指示を記述する、オープンな形式のMarkdownファイルです。
人間向けには、README.md があるようにAIコーディングエージェントでは AGENTS.md が効率・性格に作業するための情報になります。
各AIコーディングエージェントが順次対応を行っている状況です。
Devinも AGENTS.md に対応しています。
- Devin は AGENTS.md というファイルをサポート。
- AGENTS.md は AI エージェント用の簡易マニュアル（README のようなもの）。
- プロジェクトに必要なコンテキストや指示を記述して、Devin が作業前に読み取れる。
複数のエージェント間で機能する
サイトが公開時には、Devinはありませんでした。
徐々に他のエージェント間でも対応できるように取り組んでいるようです。
README と AGENTS の違いは？
人間向けドキュメントとの分離
AI向けの技術的な指示をAGENTS.mdに集約することで、README.mdが乱雑になるのを防ぎ、人間にとっての可読性を維持します。
2025年8月にOpenAIが仕様を公開し、多くのオープンソースプロジェクトで採用が進んでいます。
| 項目 | AGENTS.md | README |
|---|---|---|
| 対象 | AIエージェント | 人間の開発者 |
| 内容 | セットアップ手順、コードスタイル、テストガイドライン、プロジェクト構造、開発ワークフロー | プロジェクト概要、インストール方法、使用方法など |
| 参照 | AIエージェント が自動参照 | 人間が読むための説明書 |
| 目的 | AIエージェント が正確に作業できるようにする | 開発者がプロジェクトを理解・利用できるようにする |
AGENTS.md の設置
AGENTS.md を置くことで、AIエージェントが自動で AGENTS.md を参照して作業するために読み込みを行います。
- プロジェクトルートや任意の場所に AGENTS.md を置く。
- エージェント は作業開始前にこのファイルを自動で参照。
- 記載内容によって、コーディングスタイルや開発手順、テスト手順などを理解できる
AGENTS.md の基本構成例
AGENTS.md は、AIエージェントが開発環境やルールを読み込むためのファイルです。
基本構成は、開発環境やコードのスタイル・テストといった流れを箇条書きに書くことで指示を明確にすることがポイントになります。
ドメインやプロジェクト固有のルールもAGENTS.mdに書くことをオススメします。
# AGENTS.md
## 1. 目的
このファイルは AI エージェント（Devin）専用の指示書です。
Devin が作業を始める前に参照し、正確に作業できるようにプロジェクトのコンテキストやルールを提供します。
## 2. セットアップコマンド
- 依存関係のインストール: `npm install`
- 開発サーバー起動: `npm run dev`
- テスト実行: `npm test`
- 本番ビルド: `npm run build`
## 3. コードスタイル
- TypeScript strict モードを使用
- React は関数コンポーネント優先
- ESLint と Prettier の設定に従う
- コミットメッセージは Conventional Commit 形式
## 4. テストガイドライン
- 新規関数にはユニットテストを作成
- テストフレームワークは Jest
- カバレッジ >80% を目標
- コミット前に必ずテストを実行
## 5. プロジェクト構造
- `/src` - メインアプリコード
- `/tests` - テストコード
- `/docs` - ドキュメント
- `/public` - 静的アセット
- README.md は人間向けで、Devin は自動参照しない
## 6. 開発ワークフロー
- `main` ブランチから機能ブランチを作成
- プルリクエストでコードレビュー
- マージ前にコミットを squash
- 新規機能にはドキュメントを更新
## 7. プルリクエストのルール
- タイトル形式: [<project_name>] <タイトル>
- **必須** レビュワーからのコメントは、依頼者に確認して指示があるまで作業しないこと
- 必ずDraft PRで作成すること
- Assigneesは、実装依頼をした人を設定する
## 8. 注意事項
- PRにコメントがあっても、指示があるまで作業しないこと
- AGENTS.md は Devin 専用の指示書としてコーディング前に必ず参照
- `.rules`、`.mdc`、`.cursorrules`、`.windsurf` なども自動参照される
- 可能な限り詳細で明確な指示を記載することで、Devin の作業効率が向上
個人のプロジェクトで以下のような AGENTS.md を作成してみました。
まだ検証はしていませんが、仕様駆動駆動も以下のように作っておくと動作するのかは試してみたいと思っています。
オンボーディングのポイント
AIエージェントが適切にプロダクトコードを把握するためのオンボーディングとして活用できます。
また、AGENTS.mdを知らないチームメンバーにも伝えておきます。
役割を理解することで、メンバーがAIエージェントを使って改善していくことができます。
- AGENTS.md は Devin 専用の操作マニュアル
- README は人間向けの説明書
- AGENTS.md に詳細で明確な指示を記載するほど、AIエージェント の作業精度と効率が向上する
AGENTS.md ファイル作成・運用ポイント
-
AGENTS.md を整備する
- AIエージェント が作業に必要な環境やルールを理解できるようにする。
-
開発環境のセットアップ情報を記載
- 依存関係、ビルド、テストコマンドなど。
-
コードスタイル・テスト・ワークフローのルールを明確化
- AIエージェント がプロジェクトの標準に従って作業できる。
-
プロジェクト構造やドキュメント参照先も提示
- 必要に応じてファイルやディレクトリのパスを具体的に書く。
-
更新と改善
- 新しいルールや変更があれば、AGENTS.md を随時更新。
CLAUDE.mdやGEMINI.md：ほかのフォーマットについて
Claude Code や Gemini CLIといったツールでは、CLAUDE.mdやGEMINI.mdを利用していることが多いと思います。
あくまでも自分の考えでは、 AGENTS.md を起点にしておきたいと感じました。
理由としては、メンバーによってはClaude Codeを使ってる人・使っていない人がいることを考慮すると AGENTS.md に寄せておくほうがDevinやCodexには都合良いです。
AGENTS.mdを配置して、必ずCLAUDE.md を読み込むことと注意書きすることで、Devinが実装する際にはCLAUDE.mdを自動で読み込まれる動きが取れます。
いままのフォーマットを維持しつつ、AGENTS.mdを配置することで複数エージェントでの起点になります。
まとめ
AGENTS.mdは、サイトが公開されてから日が浅いです。
これから導入するプロダクトは多いと思います。運用を重ねてみて使い分けだったりを精査して精度を高めるようなドキュメントを作っていきたいと感じました。
Devinで実装を依頼する中で、設置したガードレールを無視したりするといった失敗談を繰り返すなかで共通で使えるAGENTS.mdは魅力に感じています。
これから複数のエージェント間で使えるツールが増えていくことを考慮して、プロダクトへの検討してみるのはいいかもしれません。
参考記事
Discussion