AGENTS.md完全ガイド — Codex・Cursor・Clineで共通のエージェント指示を書く

結論

AGENTS.mdは、複数のコーディングエージェントが参照することを目指した共通の指示ファイルです。リポジトリ直下に置き、ビルド・テスト・規約・ハマりどころなど「コードからは推測できない情報」だけを短く書きます。Claude Code専用のCLAUDE.mdと役割は重なるので、両方使うなら正本を1つに決めて参照させると重複を防げます。要点は「ツールごとに別の指示を書かず、1枚に集約する」ことです。

AGENTS.mdとは何か

AGENTS.mdは、リポジトリ直下に置いて複数のコーディングエージェントに読ませる、共通の指示ファイルです。agents.mdはこれをオープンな取り組みとして提唱しており、特定ベンダーに閉じない形式を狙っています。中身は普通のMarkdownで、特別な構文はありません。

発想はシンプルです。エージェントを使うたびにチャットで「テストはnpm test」「src/legacy/は触らないで」と説明し直すのは無駄が多い。ならばその知識をリポジトリに書き、各ツールに読ませればよい、というものです。READMEが人間向けのオンボーディング文書であるのに対し、AGENTS.mdはエージェント向けの作業前提を圧縮したメモだと考えると整理しやすくなります。

なぜ標準化が必要なのか

理由は、コーディングエージェントが乱立し、指示が分散するからです。Claude Code、Codex、Cursor、Cline、GitHub Copilotと選択肢が増えるほど、ツールごとに別々の設定ファイルへ同じ前提を書き写すコストが膨らみます。

同じプロジェクトを複数人が別々のツールで触る場面では、これがさらに効きます。AさんはCursor、BさんはClaude Code、CIではCodex、という構成でも、作業前提が1枚に集約されていれば、誰がどのツールで入っても同じ規約・同じコマンドで動けます。逆に指示が各ツールの設定に散っていると、片方だけ更新されて挙動がずれ、原因追跡に時間を取られます。共通の正本を1つ持つこと自体が、保守性の改善になります。

AGENTS.mdとCLAUDE.mdは何が違うのか

役割は重なりますが、出自と読まれ方が違います。CLAUDE.mdはClaude Codeが毎回読み込む専用のメモリファイルで、Anthropicのメモリ機能の一部として定義されています。一方AGENTS.mdは、ツール横断の共通指示として提唱されているオープンな取り組みです。

AGENTS.md

CLAUDE.md

位置づけ

複数エージェント共通のオープンな取り組み

Claude Code専用のメモリファイル

読まれ方

対応するツールが広がりつつある

Claude Codeが起動時に毎回読み込む

書く内容

推測できない作業前提(コマンド・規約・落とし穴)

同左。Claude固有の運用も足せる

併用時

こちらを正本にして集約しやすい

正本を参照する形にすると重複を防げる

役割は重なる。両方使うなら、どちらを正本にするかを先に決める。

実務では、共通前提をAGENTS.mdに集約し、CLAUDE.mdからはClaude Code固有の運用(使うサブエージェントの方針など)だけを書いて、共通部分はAGENTS.mdを参照させる、という分担が扱いやすくなります。逆でも構いませんが、同じ内容を二重メンテすると必ず片方が腐るので、正本は必ず1つに決めてください。

何を書き、何を書かないか

書くのは「コードを読んでも分からないこと」だけです。これが最大の原則です。ディレクトリ構成やフレームワークはエージェントが自分で読めるので、わざわざ書く価値は低い。逆に、正規のビルド・テストコマンド、暗黙の規約、過去にハマった落とし穴は、書かないと毎回つまずきます。

具体的には次のような区別になります。

書く: ビルド/テスト/起動の正規コマンド、編集してよい範囲と禁止パス、命名や依存追加の規約、リント/フォーマッタの方針、過去に踏んだ落とし穴
書かない: コードから読めるディレクトリ構造、一般的なフレームワークの使い方、抽象的な品質論や精神論、すでに守られている当然のルール

長く書くほど良いわけではありません。指示が長文になると、文脈に埋もれて優先度の高い制約が薄まります。各行に「これを消したらエージェントがミスするか」を問い、ノーなら削る。これだけで質が安定します。

ツール別にどう読まれるか

ツールごとに読み込みの仕様は異なります。「すべてのツールが必ずAGENTS.mdを読む」と断定はできませんが、対応や参照する設計は広がっています。正確な挙動は各ツールのドキュメントで確認するのが前提です。

Codex: AGENTS.mdをエージェントへの指示の置き場所として参照する設計が採られています。codex CLIの初期設定は別記事にまとめています。
Cursor / Cline: ルールファイルやプロジェクト指示の仕組みを持ち、リポジトリ内の指示を参照する設計が広がっています。具体のファイル名と優先順位は各ツールの設定を確認してください。
GitHub Copilot: リポジトリ単位の指示ファイルに対応しています。読み込み対象のファイル名はドキュメントに従ってください。
Claude Code: CLAUDE.mdを毎回読み込みます。AGENTS.mdを正本にする場合は、CLAUDE.mdから参照させる形が無難です。

# Claude Code への指示

共通の作業前提は AGENTS.md を正本とする(重複させない)。
@AGENTS.md

## Claude Code 固有
- 重い実装は codex サブエージェントに委譲してよい
- 本番反映は branch → PR → merge の手順を踏む

参照記法やインクルードの可否はツールで異なります。参照が効かないツールでは、共通前提をAGENTS.md側に集約し、専用ファイルは固有事項だけに絞るのが現実的です。

最小テンプレート

迷ったら次の骨格から始めてください。見出しは3つか4つで十分です。

# Agent Instructions

## Commands
- build: `npm run build`
- test: `npm test`
- dev: `npm run dev`(UI 変更時はブラウザで目視してから完了とする)

## Conventions
- TypeScript strict。新規依存の追加は事前に相談する
- 命名は既存ファイルのパターンに合わせる(独自規約を持ち込まない)

## Boundaries
- `src/generated/` は自動生成。手で編集しない
- `.env` と CSV はコミットしない

## Gotchas
- DB マイグレーションは `npm run migrate` を通すこと(直接 SQL を流さない)
- 本番反映は branch → PR → merge to main の順

ポイントは、コマンドを先頭に置くことと、禁止事項を「パス単位」で具体的に書くことです。「気をつける」ではなく「src/generated/は編集しない」と書く。エージェントは具体的な制約のほうが守れます。

肥大化をどう防ぐか

放置すると指示ファイルは必ず太ります。防ぐコツは2つです。

1つは、追記のタイミングを「同じミスを2回したとき」に固定すること。先回りであれこれ書くと、守られても確認できないルールが溜まります。実際に踏んだ落とし穴だけを1行ずつ足すほうが、密度が保てます。

もう1つは、定期的に各行へ「これを消したらエージェントがミスするか」を問うこと。ノーなら削る。すでに2回以上守られている当然のルールや、抽象的な品質論は削減候補です。指示ファイルは育てるものですが、同時に刈り込むものでもあります。1タスク1差分で更新すれば、レビューもしやすくなります。

よくある質問

AGENTS.mdとは何ですか?

複数のコーディングエージェントが参照することを目指した、リポジトリ直下に置く共通の指示ファイルです。ビルド・テスト・規約・ハマりどころなど、コードからは推測できない情報を1か所にまとめます。

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

CLAUDE.mdはClaude Codeが毎回読み込む専用のメモリファイルです。AGENTS.mdはツール横断の共通指示として提唱されているオープンな取り組みで、どちらも役割は重なります。併用する場合は片方を正本にし、もう片方から参照させると重複を防げます。

AGENTS.mdには何を書くべきですか?

コードを読めば分かることは書かず、推測できない情報だけを書きます。正規のビルドとテストのコマンド、編集してよい範囲、命名や依存追加の規約、過去にハマった落とし穴が中心です。

AGENTS.mdが長いと無視されるのは本当ですか?

長文の指示は文脈に埋もれ、優先度の高い制約が薄まりやすくなります。各行に「これを消したらエージェントがミスするか」を問い、ノーなら削るのが運用の基本です。

すべてのツールが必ずAGENTS.mdを読みますか?

必ず読むと断定はできません。対応するツールや参照する設計は広がっていますが、読み込みの有無や優先順位はツールごとに異なるため、各ツールのドキュメントで確認してください。