AGENTS.mdの書き方テンプレ｜copilot-instructions比較

AGENTS.mdとは、AIコーディングエージェント向けに「このリポジトリでの作業の仕方」を書いておく、ツール共通のMarkdownファイルです。 人間向けのREADMEとは別に、ビルド・テストのコマンド、コード規約、触ってはいけない場所などをまとめておくと、Copilot・Codex・Claude Code・Cursorなど複数のエージェントが同じ指示を読んで作業します。

この記事では、主要エージェントがどのファイルを読むかの対応表（各公式ドキュメントを2026年10月2日に確認）と、規模別にそのまま使えるテンプレート3種をまとめました。Copilot前提の解説やテンプレートのない比較記事では分かりにくい「copilot-instructions.md・CLAUDE.md・.cursor/rules とどう併用するか」「ネストしたときどれが優先されるか」「指示が食い違ったらどうなるか」まで、判断表で整理します。

AGENTS.mdと各ツールの指示ファイルの早見表

どのエージェントが何を読むか（2026年10月2日時点の各公式ドキュメントより）

結論：共通の内容は AGENTS.md に1本化し、ツール固有の機能（パス別ルール、Claude専用の指示など）だけを各ツールのファイルに書くのが、2026年10月時点で最も重複が少ない構成です。

AGENTS.mdとは：仕様と位置づけ

公式サイト（agents.md）では、AGENTS.mdを 「コーディングエージェントを導くための、シンプルでオープンなフォーマット」 と説明しています。押さえておきたい仕様は次のとおりです。

READMEとの違いは読み手です。 READMEは人間がプロダクトを理解するための文書、AGENTS.mdはエージェントが作業を正しく進めるための手順書です。READMEに書くと人間には細かすぎる「lintの正確なコマンド」「生成ファイルは編集しない」といった内容を、AGENTS.mdに分けて書きます。

copilot-instructions.md・CLAUDE.md・.cursor/rules との関係

flowchart TD
    A["AGENTS.md<br>ツール共通の作業ルール"] --> B["Copilot<br>直接読む"]
    A --> C["Codex<br>直接読む"]
    A --> D["Cursor<br>直接読む"]
    A --> E["Claude Code<br>CLAUDE.mdがなければ直接読む<br>あれば @AGENTS.md で取り込む"]
    A --> F["Gemini CLI<br>context.fileName で指定"]
    G[".github/copilot-instructions.md<br>.github/instructions/*.instructions.md"] --> B
    H[".cursor/rules/*.mdc"] --> D
    I["CLAUDE.md / .claude/rules/"] --> E

Copilot code review は AGENTS.md を読まないため、PRレビューで指摘してほしい観点は copilot-instructions.md にも書いておきます。

CLAUDE.md自体の書き方や置き場所は別記事「CLAUDE.mdの書き方｜何を書くか・置き場所・育て方【テンプレートつき】」で詳しく扱っています。本記事はAGENTS.mdを中心に、複数ツールで共有する視点に絞ります。

主要エージェントの読み込みルール（公式ドキュメントの要点）

以下は各公式ドキュメント（2026年10月2日確認）の要点です。各ツールは更新が速いため、導入時には公式ドキュメントで再確認してください。本記事では各エージェントの実際の読み込み動作は実行していません。

GitHub Copilot

• 読むファイル：.github/copilot-instructions.md（リポジトリ全体）、.github/instructions/NAME.instructions.md（frontmatterの applyTo でパス指定）、エージェント指示として AGENTS.md・CLAUDE.md・GEMINI.md。
• ネスト：「作業中は、ディレクトリツリーで最も近いAGENTS.mdが優先される」と記載。
• 優先：個人の指示 → リポジトリの指示 → 組織の指示の順。
• 環境差：Copilot CLI はリポジトリ全体・パス別・エージェント・個人のすべてに対応。code review はリポジトリ全体とパス別のみ。

---
applyTo: "src/api/**/*.ts"
---
# API のルール
- 入力は zod でバリデーションする
- エラーは `{ code, message }` 形式で返す

OpenAI Codex

• 探索順：グローバル（~/.codex/AGENTS.override.md → ~/.codex/AGENTS.md）のあと、Gitルートから作業ディレクトリまで各階層で AGENTS.override.md → AGENTS.md → 代替ファイル名の順に探す。
• 結合：ルートから順に空行で連結。近いディレクトリのファイルほど後ろに来るので優先される。
• 上限：project_doc_max_bytes（既定 32KiB）に達すると以降のファイルは追加されない。空のファイルは読み飛ばす。
• 代替名：~/.codex/config.toml の project_doc_fallback_filenames で、AGENTS.md 以外のファイル名も読ませられる。

# ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md", "TEAM_GUIDE.md"]
project_doc_max_bytes = 65536

Claude Code

Claude Code は v2.1.277 以降、AGENTS.md を直接読めます。 既定の動作は次のとおりです。

• /config の Project instructions を claude-md-and-agents-md にすると両方を読みます（claude-md で CLAUDE.md のみ）。
• AGENTS.local.md、AGENTS.override.md、.agents/ 配下は読みません。
• 個人用に CLAUDE.local.md を置くと、既定では AGENTS.md が読まれなくなる点に注意します。

CLAUDE.md と AGENTS.md を併用するなら、CLAUDE.md の先頭でインポートするのが確実です（古いバージョンでも動きます）。

@AGENTS.md

## Claude Code
- 大きな変更はプランモードで計画してから進める

Cursor

• ルールの種類：Project Rules（.cursor/rules/*.mdc）、User Rules、Team Rules、AGENTS.md。
• .mdc の frontmatter：alwaysApply、description、globs の組み合わせで「常に適用」「ファイル一致で自動適用」「エージェントが判断」「手動で呼ぶ」が決まる。
• AGENTS.md はネスト配置に対応し、親と結合してより具体的な指示が優先。
• ルール間の優先：Team Rules → Project Rules → User Rules（先のものが優先）。

---
description: React コンポーネントを書くときの規約
globs: src/components/**/*.tsx
alwaysApply: false
---
- 関数コンポーネントと名前付きエクスポートを使う

Gemini CLI

既定は GEMINI.md ですが、設定でAGENTS.mdを読ませられます。

// ~/.gemini/settings.json または .gemini/settings.json
{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

読み込まれた内容は /memory show で、再読み込みは /memory refresh で確認できます。

規模別コピペ用テンプレート3種

共通の方針：「エージェントがコードを読んでも分からないこと」だけを、短く・検証できる形で書きます。 ディレクトリ一覧や依存関係の列挙のように、コードから読み取れる内容は最小限にします。

テンプレート1：小さなライブラリ（約40行）

# AGENTS.md

## 概要
日付文字列を解析する TypeScript ライブラリ。npm で公開している。
公開 API は `src/index.ts` から export しているものだけ。

## コマンド
- 依存のインストール: `pnpm install`
- テスト: `pnpm test`（Vitest）
- 型チェック: `pnpm typecheck`
- lint と整形: `pnpm lint --fix`
- 変更後は **typecheck → lint → test** の順にすべて通してから完了とする

## コード規約
- TypeScript strict。`any` は使わず `unknown` と型ガードで扱う
- 外部ランタイム依存は追加しない（devDependencies は可）
- 公開関数には JSDoc と `@example` を書く

## テスト
- テストは `src/**/*.test.ts` に置く
- 新しい書式に対応したら、正常系と異常系のテストを1つずつ追加する
- スナップショットテストは使わない

## 変更してはいけないもの
- `dist/` は生成物なので編集しない
- `CHANGELOG.md` は changesets が生成するので直接編集しない（`pnpm changeset` を使う）

## コミット・PR
- Conventional Commits（`feat:` `fix:` `docs:` など）
- 公開 API を変える場合は PR 説明に「破壊的変更」と明記する

テンプレート2：Webアプリ（約70行）

# AGENTS.md

## 概要
備品の貸し出しを管理する社内向け Web アプリ。
Next.js（App Router）+ PostgreSQL + Prisma。認証は Auth.js。

## セットアップとコマンド
- 起動: `docker compose up -d db && pnpm dev`（http://localhost:3000）
- テスト: `pnpm test`（ユニット）、`pnpm test:e2e`（Playwright、`pnpm dev` 起動中に実行）
- 型チェック・lint: `pnpm typecheck && pnpm lint`
- DB マイグレーション作成: `pnpm prisma migrate dev --name <内容>`
- 作業の完了条件: typecheck・lint・test がすべて通ること

## 構成で知っておくこと
- サーバー処理は Server Actions（`src/app/**/actions.ts`）に置く。API Route は外部連携用のみ
- DB アクセスは `src/server/repositories/` 経由。コンポーネントから Prisma を直接呼ばない
- 日時は DB に UTC で保存し、表示時に `Asia/Tokyo` に変換する

## コード規約
- UI は `src/components/ui/` の既存コンポーネントを再利用する。新規作成の前に既存を探す
- フォームのバリデーションは zod スキーマを `src/schemas/` に置き、クライアントとサーバーで共有する
- エラーメッセージは日本語、ログは英語

## テスト
- Server Action を変えたら対応する `*.test.ts` を更新する
- E2E は主要な操作（貸し出し・返却・検索）のみ。細かい分岐はユニットテストで書く

## セキュリティ
- 秘密情報は `.env.local` に置き、コミットしない。サンプルは `.env.example` に追記する
- ユーザー入力を SQL に連結しない（Prisma の API か `$queryRaw` のタグ付きテンプレートを使う）
- 権限チェックは `requireRole()` を必ず通す

## 変更してはいけないもの
- `prisma/migrations/` の既存ファイルは編集しない（新しいマイグレーションを追加する）
- `src/generated/` は自動生成

## コミット・PR
- ブランチ名: `feat/<内容>`、`fix/<内容>`
- PR には変更点、確認手順、画面変更があればスクリーンショットを書く

テンプレート3：モノレポ（ルート＋パッケージ別）

モノレポでは、ルートには全体共通のルールだけを書き、パッケージ固有の内容は各パッケージのAGENTS.mdに分けます。

repo/
├── AGENTS.md                 ← 全体共通（ツール、コミット規約、パッケージ間の決まり）
├── apps/
│   ├── web/AGENTS.md         ← Next.js 固有
│   └── api/AGENTS.md         ← API サーバー固有
└── packages/
    └── ui/AGENTS.md          ← 共有 UI ライブラリ固有

# AGENTS.md（ルート）

## 概要
pnpm workspaces + Turborepo のモノレポ。
- `apps/web`: 会員向け Web（Next.js）
- `apps/api`: API サーバー（Hono）
- `packages/ui`: 共有 UI コンポーネント
各パッケージの詳細はそれぞれの AGENTS.md を参照。

## 共通コマンド（ルートで実行）
- 全体のビルド: `pnpm turbo build`
- 変更したパッケージだけテスト: `pnpm turbo test --filter=...[origin/main]`
- 特定パッケージで実行: `pnpm --filter @repo/web <script>`

## パッケージ間のルール
- アプリ間で直接 import しない。共有するコードは `packages/` に置く
- `packages/ui` の公開 API を変えたら、`apps/web` の型チェックも通す
- 依存の追加は対象パッケージの package.json に行う（ルートには追加しない）

## コミット・PR
- Conventional Commits。scope にパッケージ名を入れる（例: `feat(web): ...`）
- 1つの PR で複数パッケージを変える場合は、理由を PR 説明に書く

# AGENTS.md（apps/api）

## このパッケージについて
Hono + Drizzle ORM の API サーバー。Node.js 22。

## コマンド（このディレクトリで実行）
- 起動: `pnpm dev`（http://localhost:8787）
- テスト: `pnpm test`
- マイグレーション生成: `pnpm drizzle-kit generate`

## ルール
- ルートの AGENTS.md の共通ルールに加えて以下に従う
- ハンドラは `src/routes/<リソース>.ts` に1リソース1ファイル
- レスポンスの型は `@repo/schemas` から import し、ここで再定義しない
- `src/db/migrations/` の既存ファイルは編集しない

テンプレートの行数とサイズは次のとおりです（wc -l -c で計測）。どれも Codex の既定上限 32KiB に対して十分小さく収まります。

ネスト配置でどれが優先されるか

apps/api/src/routes/tasks.ts を編集するときの読み込みを、各公式ドキュメントの記載から整理すると次のようになります。

どのツールでも「近いファイルが優先されやすい」一方、結合のされ方はツールごとに違います。 確実に動かすには、子のファイルでは親と矛盾する指示を書かず、「追加」だけを書くのが安全です。例外を作る場合は「ルートの〇〇は、このパッケージでは△△とする」と明示します。

書くべき項目・書かない方がよい項目

書くべき項目チェックリスト

ポイントは「検証できる具体的な書き方」です。「きれいなコードを書く」より「2スペースインデント」「pnpm lint を通す」のほうが、守られたかどうかを確認できます。

書かない方がよい項目

長さの目安： Claude Code の公式ドキュメントは CLAUDE.md を「1ファイル200行未満」を目安にしており、長いほど文脈を使い遵守率が下がると説明しています。Codex は既定32KiBで読み込みを打ち切ります。AGENTS.mdも100〜200行程度に収め、詳細は別ファイルへのリンクにすると、どのツールでも扱いやすくなります。

指示が食い違ったときの扱い

食い違いを作らない一番の方法は、同じ内容を2か所に書かないことです。 CLAUDE.mdは @AGENTS.md で取り込み、copilot-instructions.md にはレビュー観点などCopilot固有の内容だけを書きます。

運用：更新のタイミングとレビュー

更新するタイミング

レビューのしかた

• AGENTS.mdの変更もPRでレビューします。 コードと同じく、チームの合意が必要な「ルール」だからです。
• 四半期に1回など定期的に、古いコマンドや矛盾を探します。 Claude Code では /doctor prompt-audit（v2.1.283以降）で、CLAUDE.md・AGENTS.md の古い記述や矛盾を洗い出せると公式ドキュメントに記載があります。
• コマンドが今も動くかをCIで確かめると、記述が古くなるのを防げます。例えばAGENTS.mdに書いたコマンドと同じものをCIで実行しておきます。
• 削除も大切です。効果が見えない指示、もう起きない間違いへの注意は消して短く保ちます。

よくある質問

Q. copilot-instructions.md と AGENTS.md はどちらに書けばよいですか？ A. Copilot以外のエージェントも使うなら、共通の内容はAGENTS.mdに書きます。 Copilot code review はAGENTS.mdを読まないので、レビューで見てほしい観点は copilot-instructions.md に書き、パス別の細かいルールは .github/instructions/*.instructions.md に分けます。

Q. Claude Code を使うなら CLAUDE.md は不要ですか？ A. Claude Code v2.1.277以降は、CLAUDE.mdがなければAGENTS.mdを直接読みます。Claude専用の指示があるなら、CLAUDE.mdの先頭に @AGENTS.md を書いてその下に追記すると、両方の内容が確実に読まれます。

Q. AGENTS.mdは英語で書くべきですか？ A. 仕様上の決まりはありません。チームが読みやすい言語で書いて問題ありません。 コマンド、ファイル名、識別子はコードと同じ表記にすると、エージェントがそのまま使えます。

Q. モノレポで子のAGENTS.mdが読まれていないようです。 A. ツールによって読み込むタイミングが違います。Claude Code はそのディレクトリのファイルを読んだときに追加で読み込み、Codex は起動した作業ディレクトリまでの階層を読みます。パッケージのディレクトリで起動する、または対象ファイルを開いてから指示すると確実です。

まとめ

• AGENTS.mdはツール共通の「エージェント向けREADME」。必須項目はなく、普通のMarkdownで書けます。
• Copilot・Codex・Cursorは直接読み、Claude Codeは v2.1.277以降CLAUDE.mdがなければ読み、Gemini CLIは設定で読みます（2026年10月時点）。
• 共通内容はAGENTS.mdに1本化し、ツール固有の内容だけを専用ファイルに書くと重複と矛盾を防げます。
• 書くのは「正確なコマンド・完了条件・コードから分からない決まり・編集しないファイル」。秘密情報や長い手順書は入れません。
• ネストでは近いファイルが優先されやすいので、子には「追加」と「明示した例外」だけを書きます。
• AGENTS.mdもPRでレビューし、同じ間違いが2回起きたら1行足す運用で育てます。

株式会社RJCでは、AIエージェントと一緒に開発するための知識を仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。