最近、AIコーディングエージェントの活用が急速に広がっていますが、「思った通りに動いてくれない」という悩みを持つ方も多いのではないでしょうか。そこで注目されているのが「AGENTS.md」というアプローチです。プロジェクトのルートディレクトリに設定ファイルを置くだけで、AIエージェントの振る舞いを制御できる仕組みについて調べてみました。
AGENTS.mdとは何か
AGENTS.mdは、AIコーディングエージェントに対してプロジェクト固有のルールやコンテキストを伝えるためのマークダウンファイルです。READMEがプロジェクトの概要を人間に伝えるものだとすれば、AGENTS.mdはプロジェクトの約束事をAIに伝えるものという位置づけですね。
もともとはAnthropicのClaude Codeが採用した仕組みで、その後GitHub CopilotやCursorなど他のAIコーディングツールでも類似のアプローチが広がっています。ファイル名は「AGENTS.md」「CLAUDE.md」「CURSOR_RULES.md」などツールによって異なりますが、基本的な考え方は同じです。
AGENTS.mdに書くべき内容
効果的なAGENTS.mdを書くために、押さえておきたいポイントがいくつかあります。実際に運用してみて特に重要だと感じた項目を紹介します。
コーディング規約とスタイルガイド
プロジェクトで使っている言語のコーディング規約を明記しておくと、AIが生成するコードの品質が格段に上がります。たとえば「TypeScriptではインターフェース名にIプレフィックスを付けない」「関数はアロー関数で統一する」といった具体的なルールが効果的です。曖昧な指示よりも、具体例を添えた方がAIの理解度が高まりますね。
プロジェクト構成の説明
ディレクトリ構成やモジュール間の依存関係を記述しておくことも大切です。「srcディレクトリ以下にドメインロジック、apiディレクトリにルーティング」のようにアーキテクチャの概要を伝えると、AIが適切な場所にコードを配置してくれるようになります。
禁止事項と制約
「やってほしくないこと」を明記するのも重要なポイントです。「console.logをコミットしない」「any型を使わない」「外部APIの呼び出しにはラッパー関数を経由する」など、プロジェクト特有の制約をリストアップしておきます。AIスロップ問題の対策としても、こうした明確な制約が役立ちます。
AGENTS.mdの効果はあるのか
Hacker Newsでも「AGENTS.mdは本当に役に立つのか」という議論が活発に行われています。結論から言うと、効果はあるものの万能ではないというのが現時点での評価です。
具体的なルール（「テストはVitestを使う」「エラーハンドリングにはResult型を使う」など）は高い確率で遵守されます。一方で、「コードを美しく書く」のような抽象的な指示はほとんど効果がないようです。AIエージェントハーネスの設計パターンと組み合わせることで、より精度の高い制御が可能になると考えられています。
AGENTS.mdの実践的な書き方
実際にAGENTS.mdを書く際のテンプレートを紹介します。以下の構成が使いやすいと感じました。
# AGENTS.md
## プロジェクト概要
- 言語: TypeScript
- フレームワーク: Next.js 15 (App Router)
- テスト: Vitest + Testing Library
- パッケージマネージャ: pnpm
## コーディング規約
- 関数はアロー関数で統一
- 型定義にはinterfaceよりtypeを優先
- エラーハンドリングはResult型パターン
- コンポーネントはnamed exportのみ
## 禁止事項
- any型の使用
- console.logのコミット
- 直接的なDOM操作
- グローバルステートの乱用
## テストルール
- 全ての公開関数にユニットテスト
- モックは最小限に
- テストファイルは対象ファイルと同階層の__tests__ディレクトリに配置
AGENTS.mdを使う際の注意点
いくつか気をつけておきたいポイントがあります。まず、ファイルが長すぎるとAIが重要な部分を見落とす可能性があるため、500行以内に収めるのが理想的です。また、矛盾するルールがあるとAIが混乱するので、定期的な見直しも必要ですね。
さらに、AGENTS.mdはバージョン管理に含めてチーム全体で共有することをおすすめします。個人の開発環境でだけ使っていると、チームメンバー間でAIの出力に差が出てしまいます。MCPサーバー開発のようなAIツール連携の文脈でも、統一的な設定ファイルの重要性は高まっています。
まとめ
AGENTS.mdは、AIコーディングエージェントを効果的に制御するためのシンプルかつ強力なアプローチです。完璧ではありませんが、具体的なルールを明記することでコード品質の底上げが期待できます。まだ導入していないプロジェクトがあれば、まずは基本的な規約だけでも書いてみると良いかもしれません。