AGENTS.mdとは
AGENTS.mdは、AIコーディングエージェントにプロジェクトのルールを伝えるためのファイルです。
Claude CodeやOpenAI CodexのようなAIコーディングツールを使うとき、AIはコードを読んで作業してくれます。
ただし、プロジェクトごとのルールや方針までは、最初から完璧に分かるわけではありません。
そこで、AGENTS.mdに開発ルールを書いておくことで、AIに「このプロジェクトではこう動いてほしい」と伝えやすくなります。
なぜAGENTS.mdが必要なのか
AIにそのまま作業を依頼すると、コードは書けても、チームのルールに合わない修正になることがあります。
たとえば、次のようなズレが起きやすいです。
- 使ってほしくないライブラリを追加する
- 既存の設計と違う書き方をする
- テスト方法を間違える
- 勝手に大きなリファクタリングをする
- デプロイや環境ファイルを触ってしまう
AGENTS.mdを用意しておくと、AIが作業前に確認するルールとして使えます。
人間でいうと、新しくプロジェクトに参加したメンバー向けの「開発ガイド」に近いものです。
まず書くべき内容
最初から完璧なAGENTS.mdを作る必要はありません。
まずは、AIに守ってほしい最低限のルールを書くだけで十分です。
たとえば、次のような項目です。
- このプロジェクトの概要
- 使用している技術
- よく使うコマンド
- 編集してよいファイル、触ってはいけないファイル
- コーディングルール
- テストや確認方法
- コミットやPRのルール
- 秘密情報の扱い
AIに任せる作業が増えるほど、こうしたルールが効いてきます。
AIにAGENTS.mdを読ませて作業する
AGENTS.mdを置いたら、AIに作業を依頼するときに次のように伝えると使いやすいです。
AGENTS.mdのルールに従って、このバグを修正してください。
変更後はlintとtestを実行し、結果も教えてください。または、最初にこう聞くのもおすすめです。
このリポジトリのAGENTS.mdを読んで、作業前に守るべきルールを要約してください。こうすると、AIがプロジェクトの前提を理解しているか確認できます。
AGENTS.mdは育てていくもの
AGENTS.mdは、一度作って終わりではありません。
AIに作業を任せていると、「このルールも書いておけばよかった」と感じる場面が出てきます。
たとえば、AIが不要なファイルを触ったり、テストの実行方法を間違えたり、既存の設計と違う実装をした場合は、その内容をAGENTS.mdに追記していきます。
つまりAGENTS.mdは、AIと一緒に開発するためのプロジェクト運用メモです。
まとめ
Claude CodeやOpenAI CodexのようなAIコーディングエージェントを使うなら、まずAGENTS.mdを作るのがおすすめです。
AGENTS.mdがあると、AIにプロジェクトのルールや確認方法を伝えやすくなります。
最初は完璧でなくて大丈夫です。
プロジェクト概要、使用技術、作業ルール、確認方法だけでも書いておくと、AIとの開発がかなり進めやすくなります。
