「AIコーディングエージェントに指示してるのに、なんか意図通りに動いてくれない…」そんな経験、ありませんか？ 🤔
実はその悩み、AGENTS.mdというたった1つのファイルで一気に解決できるかもしれません！
今回は、AGENTS.mdをゼロからステップごとに作り上げながら、AIエージェントが実際にどう変わるかを確認していきましょう。
🤖 AGENTS.mdって何者？
AGENTS.mdとは、プロジェクトのルートに置く1枚のMarkdownファイルです。イメージとしては、「AIエージェントへの取扱説明書」みたいなもの、と思ってもらえると分かりやすいです。
AIエージェントはこのファイルを読んで、
- ✅ どのコマンドでテストを実行するか
- ✅ コーディング規約は何か
- ✅ どのディレクトリに何があるか
- ✅ やってはいけないことは何か
…といったプロジェクト固有のコンテキストを把握できるようになります。
AGENTS.mdがないと、エージェントは毎回「なんとなく推測」で動くしかありません。でもAGENTS.mdがあれば、プロジェクトの事情を知ったチームメンバーとして動いてくれます。
🛠️ AGENTS.mdをステップごとに作ってみよう
ざっくりとした流れがつかめるよう、実際のファイル構築を一緒に見ていきましょう。
STEP 1: プロジェクト概要セクション
まず「このプロジェクトは何をするものか」をエージェントに伝えます。ここが土台です。
# AGENTS.md
## プロジェクト概要
このリポジトリはFastAPIベースのタスク管理APIです。
Python 3.11 / FastAPI / SQLAlchemy / PostgreSQL を使用しています。
STEP 2: セットアップ・実行コマンドセクション
次に、よく使うコマンドを明記します。エージェントがテストを走らせたり環境構築するときに参照する、超重要なセクションです。
## セットアップ & コマンド
# 依存パッケージのインストール
pip install -r requirements.txt
# 開発サーバー起動
uvicorn app.main:app --reload
# テスト実行（必ずこのコマンドを使うこと）
pytest tests/ -v
# リント & フォーマット
ruff check . && black .
ポイントをまとめるとこんな感じです👇
- コマンドは実際に動くものを書く（古くなったらすぐ更新）
- 「必ずこのコマンドを使うこと」など制約をコメントで明記する
- 複数の選択肢があるときは優先順位も書いておくと親切
STEP 3: コーディング規約セクション
「型ヒントを必ず書いて」「docstringはGoogle形式で」といったチームのルールを伝えます。これがないと、エージェントが独自スタイルのコードを生成してしまうんですよね。
## コーディング規約
- 型ヒント（Type Hints）は必須
- docstringはGoogle形式を使用
- 1ファイル200行を超えたらモジュール分割を検討
- `app/models/` に新しいモデルを追加する場合は必ず migration ファイルも作成すること
STEP 4: やってはいけないことセクション
これ、地味に大事です。「エージェントが勝手にやりがちなNG行動」を明示しておきましょう。
## ⚠️ 禁止事項
- `main` ブランチへの直接コミット禁止
- `.env` ファイルの編集・コミット禁止
- テストを削除してカバレッジを上げることは禁止
📁 最終的なファイル構成イメージ
4つのセクションをまとめると、こんな構成になります。
- 📄 プロジェクト概要：何を作っているか
- ⚙️ セットアップ & コマンド：環境構築・テスト・リントの手順
- 📝 コーディング規約：スタイル・命名規則・アーキテクチャルール
- 🚫 禁止事項：やってはいけないこと
これだけで、AIエージェントの動きがガラッと変わります。「なんか微妙にズレたコードが来る…」という悩みが、かなり減るはずです。
まとめ
AGENTS.mdは、AIエージェントにプロジェクトの「文脈」を渡すための取扱説明書です。プロジェクト概要・コマンド・規約・禁止事項の4セクションをそろえるだけで、エージェントの動きが一段と使いやすくなります 🎉
難しいことはありません。まずは今のプロジェクトにAGENTS.mdを1つ作ってみることから始めてみてください。ぜひ試してみてください！
こちらも読まれています
📚 関連商品・おすすめ書籍
※本記事にはアフィリエイトリンクが含まれます。
PR
