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

AGENTS.mdとは何か

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

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

なぜ標準化が必要なのか

理由は、コーディングエージェントが乱立し、指示が分散するからです。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は、ツール横断の共通指示として提唱されているオープンな取り組みです。

なお、Claude Codeのドキュメントでは、CLAUDE.mdは永続的な指示、auto memoryはエージェントが学習したメモとして整理されています。この記事で扱うのは前者です。

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

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

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

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

• 書く: ビルド/テスト/起動の正規コマンド、編集してよい範囲と禁止パス、命名や依存追加の規約、リント/フォーマッタの方針、過去に踏んだ落とし穴
• 書かない: コードから読めるディレクトリ構造、一般的なフレームワークの使い方、抽象的な品質論や精神論、気分や価値観だけの文章、すでに守られている当然のルール、たまにしか使わない手順、古いコマンド、例外だらけの禁止リスト、特定の会話でしか必要ない背景(人間向けの背景説明はREADMEへ)

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

Claude Codeのドキュメントでも、具体的で簡潔な指示ほど従われやすいと説明されています。多段の手順や一部のディレクトリだけに関係するルールは、1枚に詰め込まず、path-scoped ruleやskillに分けるほうが運用しやすくなります。

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

ツールごとに読み込みの仕様は異なります。「すべてのツールが必ず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側に集約し、専用ファイルは固有事項だけに絞るのが現実的です。

最小テンプレート

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

# Agent Instructions

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

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

## Boundaries
- `src/generated/` は自動生成。`dist/` `node_modules/` とあわせて手で編集しない
- `.env` と CSV はコミットしない
- 公開・デプロイ・外部への送信は、明示の承認なしに行わない
- シークレット、トークン、Cookie、顧客の個人データを出力しない

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

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

作業の進め方まで決めておきたい場合は、## Workflowを1つ足し、「編集前に関連ファイルを読む」「依頼された範囲に変更を絞る」「完了報告の前に、いちばん狭い有効な検証を回す」程度に留めます。この程度でも、毎回のやり取りはかなり安定します。

肥大化をどう防ぐか

放置すると指示ファイルは必ず太ります。防ぐコツは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はいつ更新すればよいですか?

エージェントが同じミスを2回した、レビューで「知っているべきだった」指摘が出た、毎回同じ確認コマンドを教えている、といった実際の出来事をきっかけに1行ずつ足します。先回りで書いたルールは守られているか確認できず、溜まるだけになりがちです。

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

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

関連記事

• AGENTS.mdとCLAUDE.mdの違いと同期方法
• 仕様駆動でAIエージェントに実装させる — SPEC.md・依頼テンプレート・よくある失敗5つ
• Claude Code導入ガイド: Windows/macOS/WSLと初期設定
• Codex CLI セットアップガイド