AGENTS.mdとは？書き方とテンプレート【2026年】

AIコーディングエージェントに毎回「このプロジェクトでは何のコマンドを使うのか」「どこまで変更してよいのか」を説明するのは非効率です。説明が抜ければ、存在しないコマンドを実行したり、変更してはいけない自動生成ファイルを編集したりするおそれもあります。

AGENTS.mdは、この問題をリポジトリ側から解決するためのMarkdownファイルです。人間向けのREADME.mdを補完し、AIエージェントが作業するときに必要な手順と制約をまとめます。

ただし、ファイル名が共通でも、読み込む範囲や優先順位まで全製品で同一ではありません。本記事では、AGENTS.mdの共通の考え方と、Codex、GitHub Copilot、Cursorの製品固有仕様を分けて解説します。コピーして使えるテンプレート、モノレポの配置例、読み込まれない場合の対処法も紹介します。

AGENTS.mdとは？AIエージェント向けのREADME

AGENTS.mdは、コーディングエージェントへリポジトリ固有の指示を渡す、シンプルでオープンな形式です。AGENTS.md公式サイトは「A simple, open format for guiding coding agents」と説明し、「README for agents」と位置づけています。

一般的なREADME.mdは、プロジェクトの概要、利用者向けのクイックスタート、ライセンスなど、人間が最初に読む情報を担います。一方、AGENTS.mdには、エージェントがコードを安全に変更するための詳細を書きます。

ファイル	主な読み手	向いている内容
README.md	開発者、利用者	概要、導入方法、利用例、公開情報
AGENTS.md	AIコーディングエージェント	構成、検証コマンド、規約、禁止事項、完了条件

AGENTS.mdはREADME.mdの代わりではありません。人間にもAIにも同じ情報が必要ならREADME.mdを正本にし、AGENTS.mdから「詳細はREADME.mdの該当節を参照」と案内できます。反対に、AIへだけ伝えたい実行順や変更禁止パスはAGENTS.mdへ分離します。

Markdownで自由に書ける

AGENTS.mdには、必須見出しや専用のJSONスキーマはありません。通常のMarkdownで、プロジェクトに必要な情報を書けます。公式の基本例では、開発環境、テスト、PRの指示などが示されています。

自由度が高いからこそ、抽象的な精神論より、再現できるコマンドを優先します。「品質を高く保つ」だけでは判断できません。「変更後はnpm run lintとnpm testを実行する」と書けば、エージェントは具体的に行動できます。

AGENTS.mdに書くべき7項目

効果的なAGENTS.mdは、長い文章ではなく、作業に必要な判断材料がそろっています。まずは次の7項目を検討してください。

1. プロジェクトの目的と技術構成

何を作るリポジトリか、主要な言語とフレームワークは何かを2〜5行で説明します。複数のアプリを含む場合は、apps/webはフロントエンド、apps/apiはAPIというように、ディレクトリの役割も記載します。

2. セットアップと依存関係

パッケージマネージャー、必要なランタイム、依存関係の導入コマンドを書きます。npmとpnpmを混在させず、実際に採用している方法を明記します。

3. ビルド、lint、型チェック、テスト

エージェントが変更後に実行すべきコマンドを、軽い順に並べます。全テストが重い場合は、変更箇所に対応する単体テストと、最終確認用の全体テストを分けます。

## Validation1. `pnpm lint`2. `pnpm typecheck`3. 変更箇所のテスト: `pnpm test -- path/to/file.test.ts`4. 提出前の全体テスト: `pnpm test`

4. コーディング規約

命名、型、エラーハンドリングなど、レビューで繰り返し指摘する事項を書きます。ESLint、Prettier、Ruffなどが正本なら、その設定に従わせます。

5. 変更してよい範囲と禁止事項

自動生成ファイル、マイグレーション、ロックファイル、インフラ設定など、誤変更の影響が大きい領域を明示します。

## Boundaries- `src/generated/`は直接編集しない- データベースマイグレーションは依頼がある場合のみ作成する- 新しい依存関係を追加する前に、既存ライブラリで代替できないか確認する- 依頼と無関係なリファクタリングを含めない

6. 完了条件とPRの要件

「何をもって完了とするか」を書きます。コード変更だけでなく、テスト更新、ドキュメント更新、互換性、変更内容の要約を含めると、提出品質が安定します。

7. セキュリティ上の注意

APIトークン、秘密鍵、パスワード、個人情報、接続文字列をAGENTS.mdに書いてはいけません。多くの場合、ファイルはGitで共有されます。秘密情報は環境変数やシークレット管理サービスで扱い、AGENTS.mdには変数名や安全な参照手順だけを書きます。

AGENTS.mdの作り方を4ステップで解説

最初から完璧である必要はありません。リポジトリを基準に作って検証します。

Step 1. 正しいコマンドを確認する

package.json、pyproject.toml、Makefile、CI設定、既存README.mdを確認します。過去の記憶ではなく、現在のリポジトリで成功するコマンドを採用してください。

依存関係の導入、開発サーバー、lint、型チェック、テスト、ビルドの順に候補を洗い出します。

Step 2. ルートに最小版を作る

まずはリポジトリ直下にAGENTS.mdを作ります。次のテンプレートは、Node.jsプロジェクト向けの最小例です。

# AGENTS.md## Project overviewTypeScriptで構築したWebアプリケーションです。パッケージマネージャーはnpmを使用します。## Setup```bashnpm ci```## Validation変更後は次の順に実行します。```bashnpm run lintnpm run typechecknpm test```## Code style- 既存のESLintとPrettier設定に従う- 公開APIの挙動を変更した場合はテストも更新する- 依頼と無関係なファイルを変更しない## Pull requests- 変更理由、実装内容、検証結果を要約する- 自動生成ファイルを手作業で編集しない

Pythonプロジェクトなら、検証部分を次のように置き換えられます。

## Setup- Python 3.12を使用する- 依存関係は`uv sync --frozen`で導入する## Validation1. `uv run ruff check .`2. `uv run ruff format --check .`3. `uv run mypy src`4. `uv run pytest`## Code style- 公開関数には型注釈を付ける- バグ修正には再現テストを追加する- 既存例外を握りつぶさない

Step 3. 読み取り結果を説明させる

対応エージェントを対象リポジトリで起動し、いきなり編集させる前に確認します。

この作業ディレクトリに適用される指示ファイルを確認し、1. 実行すべき検証コマンド2. 編集してはいけない領域3. 完了条件をファイルパス付きで説明してください。まだ編集はしないでください。

回答がAGENTS.mdと一致しない場合は、配置場所、ファイル名、エージェントの対応状況、現在の作業ディレクトリを確認します。

Step 4. 実タスクで検証して更新する

小さな修正を依頼し、エージェントが手順どおりにテストするかを確認します。抜けが見つかったらAGENTS.mdを更新します。ファイル自体もコードレビューの対象にし、特定の担当者だけが暗黙知を追加し続ける状態を避けます。

Codexの導入と基本操作は、Codex CLIの使い方ガイドで詳しく解説しています。GitHub Copilotを使う場合は、GitHub Copilotの使い方と安全運用も参考にしてください。

AIコーディングエージェントの導入や、社内ルールの設計にお困りですか？NexaのAI顧問サービスでは、業務選定、導入設計、セキュリティ、定着まで一貫して支援します。

配置場所とモノレポの階層設計

小規模なリポジトリでは、ルートのAGENTS.mdだけで十分です。モノレポや複数言語のプロジェクトでは、ルートに全体ルールを置き、サブディレクトリに領域固有のファイルを追加します。

repository/├── AGENTS.md              # 全体の方針、共通コマンド├── apps/│   ├── web/│   │   └── AGENTS.md      # フロントエンド固有の規約│   └── api/│       └── AGENTS.md      # API固有の規約└── packages/    └── ui/        └── AGENTS.md      # UI部品とStorybookの規約

ルートには、次のような全体共通事項を書きます。

• モノレポ全体の構成
• パッケージマネージャー
• 共通のブランチ、コミット、PR方針
• 秘密情報と依存関係の扱い
• 全体テストの実行方法

apps/web/AGENTS.mdには、Reactコンポーネント、アクセシビリティ、ブラウザテストなど、フロントエンドだけに必要な事項を書きます。apps/api/AGENTS.mdには、API互換性、スキーマ、データベース、統合テストの規約を書きます。

ルールは重複させず、差分を書く

下位ファイルへルートと同じ文章をコピーすると、更新漏れが起きます。下位ファイルには、その領域で追加または変更する指示だけを書くのが基本です。

ただし、「近いAGENTS.mdがルートを必ず上書きする」「すべてのAGENTS.mdが必ず連結される」と全製品共通の仕様として断定はできません。たとえばCodexはルートから作業ディレクトリまで指示を連結しますが、他製品の探索仕様は異なる場合があります。利用製品の公式情報を確認してください。

Codex、GitHub Copilot、Cursorの対応を比較

2026年8月22日時点の公式情報を基に、主な違いを整理します。

ツール	AGENTS.md対応	複数階層	製品固有の指示形式	注意点
OpenAI Codex	公式対応	起動時の作業ディレクトリまで探索して連結	AGENTS.override.md、グローバル指示	プロジェクト指示チェーンの既定合計上限は32KiB
GitHub Copilot	対応機能で公式に案内	作業対象に最も近いAGENTS.mdを優先	.github/copilot-instructions.md、パス別instructions	Codexと同じ連結方式とは限らない
Cursor	公式対応	公式のAGENTS.mdページで階層利用を案内	.cursor/rules/*.mdc、User Rules、Team Rules	細かな適用条件はProject Rulesが向く

OpenAI Codexの探索順と上書き

OpenAI公式のAGENTS.md解説によると、Codexは開始時に指示チェーンを構築します。

グローバル指示では、通常~/.codex/AGENTS.override.mdを最初に探し、なければ~/.codex/AGENTS.mdを読みます。CODEX_HOMEを設定している場合は、そのディレクトリが基準です。

プロジェクト内では、開始時にプロジェクトルートからその時点の作業ディレクトリへ下り、各ディレクトリで次の順に候補を確認します。

1. AGENTS.override.md
2. AGENTS.md
3. project_doc_fallback_filenamesで設定した代替ファイル名

1つのディレクトリでは最大1ファイルを採用します。ルート側から順に連結され、現在の作業場所に近い指示が後に入るため、競合時にはより具体的な指示として優先されます。

Codexがプロジェクト内で連結する指示ファイルは、既定では合計32KiBまでです。上限を超える場合は、重複を削るか、対象ディレクトリにだけ適用される指示へ整理します。project_doc_max_bytesで変更できますが、設定例の数値と既定値を混同しないでください。

Codex全体の役割は、Codexとは何かを解説した記事も参照してください。

GitHub Copilotの3種類のリポジトリ指示

GitHub公式ドキュメントは、GitHub上のCopilotに対するリポジトリ指示として、主に次の形式を案内しています。

• .github/copilot-instructions.md: リポジトリ全体の指示
• .github/instructions/NAME.instructions.md: applyToグロブで対象パスを指定する指示
• AGENTS.md: リポジトリ内のエージェント向け指示

AGENTS.mdは複数箇所に配置でき、作業対象のファイルに最も近いものが優先されます。Codexと同じ連結方式とは限らないため、上位と下位が自動統合される前提では設計しません。使用するCopilot機能が両形式に対応する場合は、共通方針を.github/copilot-instructions.md、ディレクトリ別ルールをパス固有instructionsへ分けられます。

GitHub CopilotにはIDE、GitHub上のコーディングエージェント、コードレビューなど複数の機能があります。カスタム指示の対応範囲は変わる可能性があるため、使用機能の公式ページを確認してください。

CursorはAGENTS.mdとProject Rulesを選べる

Cursor公式のルールドキュメントは、Project Rules、User Rules、Team Rules、AGENTS.mdの4種類を案内しています。AGENTS.mdは、Markdown形式で書ける.cursor/rulesのシンプルな代替手段です。

一方、CursorのProject Rulesは.cursor/rules配下の.mdcファイルで管理し、frontmatterにより次のような適用方法を選べます。

• 常に適用する
• 説明に基づき関連するときに適用する
• 特定のファイルパターンへ適用する
• @メンションしたときだけ適用する

複数製品で共有したい基本指示にはAGENTS.md、Cursor内で細かな適用条件を設定したいルールにはProject Rulesが向いています。

README.md、CLAUDE.md、GEMINI.mdとの違い

指示ファイルが増えると、「どれが正本か」が分からなくなります。役割を分けて管理してください。

ファイル	主な対象	おすすめの役割
README.md	人間中心	プロジェクト概要、利用開始、公開情報
AGENTS.md	複数の対応エージェント	共通のビルド、テスト、規約、禁止事項
CLAUDE.md	Claude系ツール	Claude固有の機能やワークフロー
GEMINI.md	Gemini系ツール	Gemini固有の機能やワークフロー
.github/copilot-instructions.md	GitHub Copilot	Copilot向けのリポジトリ共通指示
.cursor/rules/*.mdc	Cursor	パス条件や適用方式を持つCursor固有ルール

複数ツールで同じ指示を使うなら、AGENTS.mdへ共通事項を集約します。ベンダー固有ファイルには、AGENTS.mdを読み直すよう促すか、固有の差分だけを書きます。同じ規約を複数ファイルへ手作業で複製すると、更新時に矛盾しやすくなります。

なお、GitHub Copilotの公式ページでは、ルートの単一CLAUDE.mdまたはGEMINI.mdもリポジトリ指示の選択肢として案内されています。ファイル名だけで対象製品を決めつけず、実際に使う機能の対応表を確認することが重要です。

AGENTS.mdが読み込まれない場合の確認事項

期待どおり動かない場合は、次の順で確認します。

1. 名前: AGENTS.mdであることを確認します。AGENT.mdやagents.md.txtは別名です。
2. 位置: エージェントを起動した場所と、変更対象の階層を確認します。ルートの検出方法と探索範囲は製品ごとに異なります。
3. 対応機能: IDE、CLI、クラウドエージェント、コードレビューで対応状況が異なる場合があります。
4. 矛盾: 上位でnpm、下位でpnpmを指定するような衝突をなくします。共通事項は上位、差分は下位へ寄せます。
5. 長さ: 重複と古い手順を削り、重要な命令を前半に置きます。Codexでは既定の合計サイズ上限も確認します。
6. 再現性: 存在しないスクリプトやローカル専用コマンドを避け、CIでも使うコマンドを優先します。

AGENTS.mdを企業で安全に運用する5原則

AGENTS.mdは判断を助ける文書であり、権限制御の代わりではありません。

1. Gitでレビューする: 変更履歴を残し、コードと同様に確認します。
2. 仕組みでも強制する: CI、ブランチ保護、最小権限、承認フローを併用します。
3. 秘密情報を書かない: トークン、秘密鍵、パスワード、個人情報、接続文字列を禁止します。
4. 正本を決める: コマンドはCI、規約はlint設定など、機械的に検証できる設定を正本にします。
5. 棚卸しする: ランタイムや構成が変わったら更新します。

本番認証情報を開発環境へ渡さず、破壊的操作には承認を要求します。外部リポジトリのAGENTS.mdも、危険なコマンドや外部送信を促す記述がないか、人が確認してから利用してください。

AGENTS.mdに関するよくある質問

AGENTS.mdは日本語で書けますか？

はい。通常のMarkdownと自然言語で記述できます。簡潔な文を使い、コマンドやファイル名は正確に書いてください。

複数のAGENTS.mdを配置できますか？

できます。ルートに全体ルール、下位に領域固有ルールを置けます。ただし、探索と競合解決は製品ごとに異なるため、公式仕様を確認してください。

AGENTS.mdに文字数上限はありますか？

共通の一律上限はありませんが、製品側に上限がある場合があります。Codexが探索・連結するプロジェクト指示ファイルは、現行公式ページで既定合計32KiBまでです。

AGENTS.mdを書けば指示は必ず守られますか？

保証はできません。テスト、lint、型チェック、CI、コードレビュー、最小権限を組み合わせてください。

まとめ：小さなAGENTS.mdから始めて検証する

AGENTS.mdは、AIコーディングエージェントにプロジェクト固有の作業方法を伝える、オープンなMarkdown形式です。README.mdを置き換えるのではなく、セットアップ、検証コマンド、規約、禁止事項、完了条件をエージェント向けに補います。

最初はルートに短いファイルを1つ作り、実際に成功するコマンドだけを書いてください。読み取り結果をエージェントに説明させ、小さなタスクで検証します。モノレポで情報量が増えたら、共通事項をルート、領域固有の差分を下位ディレクトリへ分けます。

そして、共通形式と製品固有仕様を混同しないことが重要です。Codexの探索順や上書き、GitHub Copilotのパス別指示、CursorのProject Rulesは、それぞれ公式ドキュメントで確認します。

AI活用を社内の標準業務へ落とし込みたい企業様へNexaのAI顧問サービスでは、AIコーディングエージェントの選定、ルール設計、ガバナンス、社内定着を支援します。

参考にした公式情報

• AGENTS.md公式サイト（2026年8月22日確認）
• AGENTS.md公式GitHubリポジトリ（2026年8月22日確認）
• OpenAI: Custom instructions with AGENTS.md（2026年8月22日確認）
• GitHub Docs: Adding repository custom instructions for GitHub Copilot（2026年8月22日確認）
• Cursor Docs: ルール（2026年8月22日確認）