複数のAIエージェントが参照する共通フォーマット AGENTS.md。ただ置くだけでは効かず、書き方で成果が変わります。エージェントに効く規約ファイルの設計 を整理します。
AGENTS.md とは
ツール非依存の規約ファイルで、Codex・Cursor・Copilot など複数のエージェントが参照します。「このプロジェクトの歩き方」をエージェントに渡すためのものです。
効くAGENTS.mdの4要素
1. コマンド — 何をどう実行するか
## コマンド
- 依存インストール: uv sync
- テスト: pytest -q
- 型チェック: mypy src/
- 起動: python manage.py runserver
エージェントは「どのコマンドで検証するか」を知らないと自己修正できません。最優先で書くべき項目 です。
2. プロジェクト構造 — どこに何があるか
## 構造
- src/api/ … エンドポイント
- src/core/ … ドメインロジック
- tests/ … テスト（src と同じ構造）
3. 規約 — 守ってほしいこと
## 規約
- 新しい依存を足す前に理由をコメントで残す
- ログは structlog を使う（print 禁止）
- 公開関数には型ヒントを付ける
4. 禁止事項 — やってほしくないこと
## してはいけないこと
- migrations/ を手で書き換えない
- .env をコミットしない
- main へ直接 push しない
書き方のコツ
- 具体例を1つ添える — 「規約に従う」より「こう書く」の例が効く
- 短く保つ — 長大な規約は読み飛ばされる。要点を箇条書きで
- 禁止事項を明示 — 「やっていいこと」より「やってはいけないこと」の方が事故を防ぐ
階層で使い分ける
モノレポなら、ルートに全体規約、各パッケージに個別規約を置けます。近い階層のファイルが優先されるので、共通ルールはルート、固有ルールはサブに分けます。
まとめ
AGENTS.md は「コマンド・構造・規約・禁止」の4点を、具体例つき・短く 書くのが要点です。口頭で毎回説明していた前提を1ファイルに落とすと、既存コードに馴染む実装が安定して返ってきます。
相談・お仕事のご依頼
こうした設計・実装・診断の実務は snowcode.jp で承っています。
- お仕事のご依頼・料金目安: snowcode.jp/work
- 技術ブログ: snowcode.jp/blog
- X: @SNOWCODE_JP
雪符しき / SNOW CODE — プログラム × 音楽 × カクテルを愛する雪猫エンジニア