AGENTS.mdとは

AGENTS.mdは、対応するAIエージェントにプロジェクトの前提や作業ルールを伝えるMarkdownファイルです。書く内容は、技術スタック、ディレクトリ構成、開発コマンド、コーディング規約、作業ルールなどです。毎回プロンプトで同じ前提を伝える手間を省き、エージェントの振る舞いを安定させる目的で使います。

読み込み方法や配置場所は、AIクライアントによって異なります。リポジトリのルートや個人のホームディレクトリに置いて自動で読まれるツールもあれば、専用ファイルからimportする形で使うツールもあります。

なぜAGENTS.mdが必要か

AIコーディングエージェントは強力ですが、プロジェクトの文脈は持っていません。何のフレームワークを使っているか、テストはどう走らせるか、どんな規約があるかは、毎回伝えなければ知る方法がありません。プロンプトで伝え続けるのは非効率で、伝え忘れも起きます。

AGENTS.mdを置いておくと、エージェントはこの情報を毎回読み取って作業します。結果として、説明の手間が減り、出力のばらつきも小さくなります。

AGENTS.mdは、AIエージェント向け指示を共通化しやすくするオープンなMarkdown形式です。ただし、対応状況や読み込み方はAIクライアントによって異なります。次の章で、主要エージェントの対応状況を整理します。

主要AIコーディングエージェントの対応状況

AGENTS.mdへの対応はAIクライアントごとに異なります。以下はエージェント毎の対応状況です。

AGENTS.mdをそのまま全クライアントで共有するのは、現時点では難しい状況です。複数のクライアントを使う場合は、次のいずれかの運用が現実的です。

• AGENTS.mdをマスターとし、各クライアントの専用ファイルからimportや参照で読み込ませる
• AGENTS.mdの内容を各専用ファイルに複製する

ここから、主要なクライアントについて具体的な併用方法を整理します。

Claude Codeでの併用方法

Claude CodeはCLAUDE.mdしか読み込みません。AGENTS.mdの内容も活かしたい場合は、importかシンボリックリンクのいずれかで運用します。

方法1 importで読み込ませる

CLAUDE.md内に @AGENTS.md と書くと、AGENTS.mdの内容を読み込めます(import記法は別ファイルの内容を読み込む書き方です)。Claude Code固有の指示を併記したい場合に向いています。

# プロジェクト共通指示

@AGENTS.md

## Claude Code固有の指示

(ここにClaude Code特有の指示を書く)

方法2 シンボリックリンクで一本化する

CLAUDE.mdをAGENTS.mdへのシンボリックリンク(1つのファイルを別の名前でも参照できる仕組み)にすると、ファイルの実体は1つになります。内容がAGENTS.mdと完全に同じで良い場合に向いています。

ln -s AGENTS.md CLAUDE.md

二重管理を避けたい場合はこちらが簡単です。ただし、Claude Code固有の指示を分けて書きたい場合は方法1を選びます。

Cursorでの併用方法

CursorはAGENTS.mdをそのまま読み込みます。細かい適用条件(特定のファイルパターンだけに適用するルールなど)は .cursor/rules/ ディレクトリ内のRulesで管理し、シンプルな共通指示はAGENTS.mdに書く形が基本です。

Gemini CLIでの併用方法

Gemini CLIは既定でGEMINI.mdを読みます。AGENTS.mdを使いたい場合は、.gemini/settings.json で読み込むファイル名を指定します。

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

GitHub Copilotでの併用方法

GitHub Copilotは、cloud agent、VS CodeのCopilot Chat、Copilot CLIなど一部環境でAGENTS.mdを読みます。リポジトリ単位の指示は .github/copilot-instructions.md、特定の用途に絞った指示は .github/instructions/*.instructions.md に書き分ける運用も可能です。

全体設定とプロジェクト別設定の使い分け

AGENTS.mdは、配置場所によって役割が変わります。全体設定とプロジェクト設定の2層に分けて運用するのが基本です。

2層構成の概要

全体設定とプロジェクト設定の扱いは、AIクライアントごとに異なります。階層を順に読み込んで内容を連結するクライアントもあれば、ルール種別ごとに統合するクライアントもあります。詳しい挙動は各クライアントの公式ドキュメントを参照してください。

ただし、考え方は共通です。全体設定には対話方針や安全方針を書き、プロジェクト設定には技術スタック、コマンド、ディレクトリ構成、禁止事項を書きます。

全体設定に書くこと

すべての作業に共通する個人ルールを書きます。

• 対話言語(日本語で答えてほしい等)
• 応答スタイル(結論から書く、推測せず確認するなど)
• 情報の扱い方(公式情報を優先、出典の明示など)
• 出力してはいけない情報(秘密情報、認証情報など)

プロジェクトを問わず適用したい、自分の好みやコミュニケーション方針を中心に書きます。コードやコミットの書き方など、開発プロジェクトに限った話は入れません。

プロジェクト設定に書くこと

そのプロジェクト固有の事実とルールを書きます。

• プロジェクト概要、技術スタック
• ディレクトリ構成、主要モジュールの役割
• 開発コマンド(セットアップ、テスト、Lint、ビルド)
• コーディング規約、コミット規約
• 作業ルール(最小差分、検証、事前確認が必要な操作)
• 触ってはいけないファイル
• 既知の落とし穴

プロジェクトを開いた人が、ファイル冒頭から読むだけで作業を始められる粒度を目指します。

使い分けの判断基準

全体設定とプロジェクト設定で迷ったら、以下を基準に判断します。

• そのルールは別のプロジェクトでも有効か。有効なら全体設定
• そのルールはこのプロジェクト特有の事情に基づくか。そうならプロジェクト設定

両方に同じ内容を書くと、メンテナンスが二重になります。全体設定で十分なものは、プロジェクト設定に書かないようにします。

AIクライアント別の全体設定の配置場所

全体設定の配置場所はAIクライアントによって異なります。

プロジェクト設定は、いずれもリポジトリルートに置きます。

AGENTS.mdの書き方のコツ

何を書くかと同じくらい、どう書くかも結果を左右します。エージェントに指示が伝わりやすくなる書き方のコツを整理します。

1ルール1行を基本にする

長い説明文より、短い命令形の方が指示として残りやすくなります。「〜してください」と敬体で書くより、「〜する」「〜しない」の体言止めや命令形の方が、文字数も少なく、解釈も安定します。

# 悪い例
- 変更を加える際は、なるべく必要な箇所にとどめ、関係のないファイルやコードに手を入れないようにしてください

# 良い例
- 変更は最小差分にする
- 無関係なファイルや設定を変更しない

AGENTS.mdはエージェントが毎回読み込むファイルです。冗長な表現はトークンを消費するだけでなく、重要なルールを薄める原因になります。

抽象的な表現を避ける

「丁寧に」「慎重に」「しっかりと」のような抽象的な指示は、エージェントの動作にほぼ反映されません。検証可能な具体的な指示に置き換えます。

# 悪い例
- コードは丁寧に書く

# 良い例
- 公開関数には引数と戻り値を説明するコメントを書く
- エラーは握りつぶさず、ログまたは上位への返却を行う

「このルールは具体的にどんな行動を求めているか」を考え、その行動を直接書きます。

「なぜ」を必要に応じて添える

ルールの背景を書くと、エージェントは似た状況での判断に応用できます。ただし、すべてのルールに理由を書くと冗長になるので、応用が効きやすい重要なルールに絞ります。

ファイルを長くしすぎない

AGENTS.mdは長く書くほど従ってくれるわけではありません。ファイルが肥大化すると、重要なルールが埋もれてエージェントが読み飛ばす傾向が強くなります。

目安として、最初は10〜30行で始めます。長くても100行以内に収めることを意識し、増えたら分割または削除します。Claude Code公式もCLAUDE.mdを200行未満に保つことを目標にしており、Cursor公式もRulesを500行未満に保つことを推奨しています。

長くなりそうなら、以下を検討します。

• Lint(コードの問題を自動チェックするツール)などで自動チェックできるものはAGENTS.mdから外し、設定ファイル側に寄せる
• 似た意図のルールを1つにまとめる
• 使われていないルールを削除する

よく使うコマンドや重要な禁止事項は早い位置に置く

よく使うコマンドや、絶対に守ってほしい禁止事項は、ファイルの早い位置に置きます。エージェントが作業中に参照しやすくなり、読者にも管理しやすくなります。

コードブロックでパス・コマンド・設定例を示す

ファイルパス、コマンド、設定キーなどは、コードブロックで囲むと識別が確実になります。本文中にインラインで書く場合も、バッククォートで囲みます。

# 悪い例
- 環境変数は.env.exampleに書く

# 良い例
- 環境変数は `.env.example` に追記する

例とアンチパターンを使い分ける

「こう書く」だけでなく「こう書かない」も示すと、解釈のブレが減ります。ただし、例を多く書くとファイルが膨らむので、誤解されやすいポイントに絞って使います。

AGENTS.mdのオススメテンプレート

ここまでの内容を踏まえた、コピペで使えるテンプレートを2種類用意しました。

• 全体設定: すべての作業に共通の個人設定
• プロジェクト設定: 開発プロジェクト用、複数言語汎用

そのまま使い始めて、運用しながらプロジェクト固有の事情を足していくのが現実的です。テンプレートはあくまで出発点なので、不要な項目は削り、足りない項目は追加してください。

全体設定テンプレート

配置場所は使っているAIクライアントに合わせて変えます(例: ~/.codex/AGENTS.md、~/.claude/CLAUDE.md)。

# グローバル設定
このファイルは、すべての作業に共通で適用される個人設定です。
プロジェクト固有のルールは、各リポジトリのAGENTS.mdを優先する。

## 対話と出力
- 対話、作業説明、完了報告はすべて日本語で行う

## 応答スタイル
- 回答は結論から書く
- 作業前に方針を短く示す
- 不明点は推測せず、根拠と未確認点を明示する
- ユーザーに迎合せず、事実と根拠にもとづいて回答する

## 情報の扱い
- 最新性が必要な情報は、日付を確認し、公式情報を優先する
- 公式ドキュメントへのURLがあれば添える

## 出力してはいけない情報
- 秘密情報、認証情報、個人情報を出力しない

プロジェクト設定テンプレート(複数言語汎用)

リポジトリルートに AGENTS.md として配置します。Claude Codeで使う場合は、シンボリックリンク(ln -s AGENTS.md CLAUDE.md)またはimport(@AGENTS.md)で読み込ませます。

# プロジェクト概要
例: 顧客管理用のWebアプリケーション。バックエンドはGoでREST APIを提供し、フロントエンドはTypeScript + Reactで実装。

## 技術スタック
- 言語: 例: Go 1.22 / TypeScript 5.4 / Python 3.12
- フレームワーク: 例: Echo / Next.js 14 / FastAPI
- データベース: 例: PostgreSQL 16
- パッケージマネージャ: 例: go mod / pnpm / uv
- テスト: 例: go test / vitest / pytest

## ディレクトリ構成
- `api/`: バックエンド(Go)
- `web/`: フロントエンド(TypeScript)
- `scripts/`: 開発・運用スクリプト
- `docs/`: 設計ドキュメント

## 開発コマンド
- セットアップ: `make setup`
- API開発: `make api-dev`
- Web開発: `make web-dev`
- テスト: `make test`
- Lint: `make lint`
- フォーマット: `make fmt`

## コード・コミットの言語ルール
- コード内のコメント、コミットメッセージ、PR本文は日本語
- 識別子(変数名、関数名、型名、ファイル名)は英語

## 作業ルール
- 変更は最小差分にし、既存の設計とスタイルを優先する
- 無関係なファイルや設定を変更しない
- 非自明な作業は、計画、実行、検証、報告の順で進める。前提が崩れたら停止して方針を再確認する

## 検証
- 変更後は可能な範囲でlint、test、buildを実行する
- 検証できない場合は、理由と未確認点を明記する

## 事前確認が必要な作業
- 新しい依存関係の追加
- データ削除やマイグレーション
- 権限、認証、公開範囲の変更
- 本番環境や外部APIに影響する変更

## 触らないもの
- `.env`、秘密鍵、認証情報ファイル
- 自動生成ファイル
- ビルド成果物
- この作業と無関係な設定ファイル

## AGENTS.mdの更新ルール
- 以下のいずれかに該当する場合、AGENTS.mdの更新を提案する
  - 技術スタック、ディレクトリ構成、開発コマンドが変化した
  - プロジェクトの独自ルールが見つかった
  - 同じような指示を繰り返し受けた
  - 関連箇所と揃えるべきルールが見つかった
  - つまずきやエラーになった箇所の対処法が得られた
- 既存セクションへの追記を基本とし、似た意図のルールは統合する
- 古くなった情報、解決済みや恒久対応された内容は削除する
- 追記、統合、削除はユーザーの承認を得てから行う

AGENTS.mdが効かなくなる失敗パターン

AGENTS.mdは書いて終わりではなく、運用の中で精度が落ちていきます。ファイルがあるのにエージェントが指示に従わなくなる典型的な失敗と、その対策を紹介します。

ファイルが長くなりすぎて重要なルールが埋もれる

原因

AGENTS.mdは長く書けば従ってくれるわけではありません。ファイルが肥大化すると、エージェントは「ルールがある」ことは認識しても、個別のルールを読み飛ばす傾向が強くなります。あらゆる好みや過去の反省を詰め込んだ結果、本当に守ってほしい数件が薄まってしまうのが典型的な失敗です。

対策

• 最初は10〜30行で始め、長くても100行以内を目安にする
• 守らせたい優先順位の高いルールほど上に置く
• 1ルール1行を基本にし、説明を長く書きすぎない
• Lintや設定ファイル側で吸収できるものはAGENTS.mdから外す

使っていないルールが残り続けて矛盾を生む

原因

過去のプロジェクトで使っていたルールや、当時のつまずきから追加したルールが、現在の状況に合わなくなっているケースです。古いルールと新しいルールがエージェントの中で衝突すると、解釈が安定しなくなります。「以前は意味があったが、今は誰も気にしていない」というルールが残り続けると、ファイル全体の信頼度が下がります。

対策

• 定期的に見直す。月1回など期間を決めて棚卸しする
• 解決済みの問題を防ぐためのルールは削除する
• 「なぜこのルールがあるのか」を即答できないルールは消す
• プロジェクトの方針が変わったタイミングで、関連するルールを更新する

テンプレートをコピペしただけで放置している

原因

公開されているテンプレートをそのまま貼り付け、自プロジェクト固有の事情を反映していないケースです。汎用ルールは万能ではありません。そのプロジェクトでしか起きない落とし穴、独自の規約、外部サービスとの連携時の注意点などは、テンプレートには書かれていません。コピペで終わると、エージェントは「一般的な振る舞い」しかしてくれなくなります。

対策

• テンプレートはあくまで出発点として扱う
• プロジェクト固有の情報を追記する。技術スタック、ディレクトリ構成、コマンド、独自の規約
• 実運用で発生したつまずきを記録し、AGENTS.mdに反映する仕組みを作る
• 全体設定とプロジェクト設定の役割を分けて書く

まとめ

AGENTS.mdは、AIコーディングエージェントの振る舞いを安定させるための指示書です。プロジェクトの文脈をファイルに書いておくことで、毎回プロンプトで伝える手間が減り、出力のばらつきも小さくなります。

この記事で押さえたポイントは以下です。

• AGENTS.mdはオープンなMarkdown形式だが、対応や読み込み方はAIクライアントごとに異なる
• 全体設定とプロジェクト設定の2層に分けて運用する
• 全体設定には個人ルール、プロジェクト設定には固有の事実とルールを書く
• 命令形・体言止めで簡潔に書く。抽象表現は避ける
• 長く書くほど従ってくれるわけではない。10〜30行で始め、100行以内を目安にする
• テンプレートは出発点として使い、運用しながら自プロジェクトに合わせて育てる

最後に1つ、AGENTS.mdを書いた後に意識してほしいことがあります。それは「書いて終わりではなく、運用しながら見直す」ということです。

プロジェクトは時間とともに変化します。技術スタックが変わり、メンバーが入れ替わり、規約が更新されていきます。AGENTS.mdもそれに合わせて更新しないと、すぐに陳腐化します。

今日できる最初の一歩として、この記事のテンプレートをコピペして、自プロジェクトのリポジトリルートに AGENTS.md を作成してください。そして、技術スタックとディレクトリ構成だけでも、実際のプロジェクトの内容に書き換えてみてください。それだけで、明日からのエージェントとの作業が変わります。