AGENTS.mdとは？
AIエージェントにリポジトリを理解させるファイルの書き方

Claude CodeやOpenAI Codex、Cursorといった「AIコーディングエージェント」を使い始めると、多くの人が同じ壁にぶつかります。「毎回プロジェクトの説明をするのが面倒」「うちの規約を無視して勝手な書き方をする」「触ってほしくないファイルを編集される」──。これらをまとめて解決するのがAGENTS.mdです。本記事では、AGENTS.mdの役割、CLAUDE.mdとの違い、具体的な書き方とテンプレート、そしてやりがちな失敗まで、初心者向けに丁寧に解説します。

AGENTS.mdとは何か

AGENTS.mdは、AIコーディングエージェントがリポジトリ（ソースコードの保管場所）を操作する前に読む「AI向けの取扱説明書」です。人間向けのREADME.mdとよく似ていますが、想定読者がAIである点が決定的に違います。README.mdが「このソフトの使い方」を説明するのに対し、AGENTS.mdは「このコードベースでAIがどう振る舞うべきか」を指示します。

OpenAIがコーディングエージェント「Codex」で正式に採用したことをきっかけに広まり、2025〜2026年にかけて複数のツールが対応する事実上の標準になりつつあります。エージェントはコードを書く前にAGENTS.mdを読み込み、「技術スタックは何か」「どのファイルは触ってはいけないか」「テストはどう実行するか」を把握してから作業に入ります。

なぜ必要なのか──ない場合とある場合の違い

AGENTS.mdがないと、エージェントはプロジェクトの全体像を知らないまま作業を始めます。その結果、ファイルを片っ端から読んで推測したり（時間とコストの無駄）、プロジェクトの慣習に反するコードを書いたりします。具体的には次のような差が出ます。

場面	AGENTS.mdなし	AGENTS.mdあり
技術スタックの把握	毎回ファイルを探って推測	冒頭で即座に理解
コーディング規約	独自スタイルで書きがち	規約に沿って統一
自動生成ファイル	誤って直接編集する	禁止を認識して回避
テスト実行	コマンドが分からず確認しない	指定コマンドで自己検証

CLAUDE.md / Copilot Instructionsとの違い

似たファイルがいくつか存在するため混乱しがちですが、対応するエージェントが違うだけで役割は近いものです。

ファイル名	対応エージェント	用途
AGENTS.md	OpenAI Codex・汎用	プロジェクト全体の汎用ルール
CLAUDE.md	Claude Code（Anthropic）	Claude専用の設定・優先指示
.github/copilot-instructions.md	GitHub Copilot	Copilot専用のコーディング規約

これらは共存できます。おすすめの運用は、共通ルールをAGENTS.mdに集約し、各エージェント固有の細かい指示だけを専用ファイルに分けること。重複した内容を3ファイルに書くと保守が大変になるので、「汎用はAGENTS.md、固有は専用ファイル」と役割分担するのがコツです。

どこに置くか

基本はリポジトリのルートディレクトリに1つ置きます。さらにサブディレクトリにも置くことができ、その場合はそのフォルダ以下にだけ適用されます。エージェントはルートから順に読み込み、より深い階層の指示で上書きしていきます。たとえば大規模なモノレポ（複数プロジェクトを1つのリポジトリで管理）では、ルートに共通ルール、各パッケージのフォルダに個別ルール、という階層構成が有効です。

AGENTS.mdの書き方：最小テンプレート

難しく考える必要はありません。次のような構成で、まずはルートに1ファイル作るだけで効果が出ます。

# Project Overview
Next.js 14 + TypeScript + Prisma の Webアプリ。
ユーザー管理とダッシュボードが主機能。

# Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- DB: PostgreSQL via Prisma ORM
- Styling: Tailwind CSS

# Directory
- src/app/      ... 画面とAPIルート
- src/lib/      ... 共通ロジック
- src/generated/... 自動生成（編集禁止）

# Rules
- `src/generated/` は自動生成のため直接編集禁止
- コミット前に必ず `npm run test` を実行すること
- APIルートは `src/app/api/` 以下に置く
- 変数名は camelCase、コンポーネントは PascalCase

# Commands
npm run dev         # 開発サーバー
npm run test        # 単体テスト
npm run test:e2e    # E2Eテスト（Playwright）
npm run lint        # 静的解析

書くべき項目：優先度順

1. プロジェクト概要と技術スタック（必須）──まずこれだけでも効果絶大
2. ディレクトリ構成の説明──どこに何があるかを地図として示す
3. 禁止事項──自動生成ファイル・本番環境の直接操作など「やってはいけないこと」
4. テスト・ビルドコマンド──エージェントが自分で動作確認できるように
5. コーディング規約──命名規則・コメントスタイル・使用ライブラリの方針

よくある失敗3つ

1. 長すぎて読まれない：数千行の規約を貼ると、肝心の指示が埋もれる。要点を簡潔に。詳細は別ドキュメントへのリンクで補う。
2. 古くなったまま放置：技術スタックを変えたのにAGENTS.mdが古いと、エージェントが誤った前提で動く。コード変更時に一緒に更新する。
3. 禁止事項を書き忘れる：「触ってほしくないファイル」を明記しないと、自動生成ファイルや設定ファイルを壊される。禁止事項こそ最優先で書く。

まとめ

AIエージェントを使い始めたら、まずリポジトリのルートにAGENTS.mdを1つ作りましょう。完璧を目指す必要はありません。「このプロジェクトは何か（概要・技術スタック）」と「やってはいけないこと（禁止事項）」の2点があるだけで、エージェントの精度と安全性は劇的に変わります。チームで同じエージェントを共有する場合は、属人化を防ぐ共通ルールとしても機能します。まだ日本語の解説が少ない領域なので、今のうちに使いこなしておくと一歩リードできるはずです。

よくある質問

AGENTS.mdとCLAUDE.mdの違いは何ですか？

AGENTS.mdはOpenAIのCodexや複数のAIエージェントが参照する汎用仕様です。CLAUDE.mdはAnthropicのClaude Code専用の設定ファイルです。両方置いておくと、それぞれのエージェントが適切なファイルを読みます。共通ルールはAGENTS.mdに集約するのがおすすめです。

AGENTS.mdはどこに置けばよいですか？

リポジトリのルートディレクトリに置くのが基本です。サブディレクトリにも置け、そのフォルダ以下に適用されます。エージェントはルートから順に読み込み、深い階層の設定で上書きします。

AGENTS.mdに何を書けばよいですか？

プロジェクトの概要・技術スタック・ディレクトリ構成・コーディング規約・テストの実行方法・禁止事項を書きます。AIが迷わず正確に作業できる情報を優先してください。

← JOURNALに戻る ｜ AIツール一覧を見る →