
AGENTS.mdとは。Claude Code・Codex・Cursorで共通に使える指示ファイルの書き方
2026/11/15
執筆:寺田昇平
AI Portalize株式会社 代表取締役/AI Digital Community 代表理事
仕組みとコンサルティング伴走支援の両面で、組織のAI活用の加速を支援。
AGENTS.mdは、AIのコーディングエージェントに、プロジェクトの決まりを伝えるMarkdownのファイルです。
リポジトリの一番上に置くと、Codex・Cursor・Claude Codeのどれで開いても、同じ指示が読まれます。
ただしClaude Codeは、同じ場所にCLAUDE.mdがあると、そちらだけを読みます。
そろえるなら、CLAUDE.mdからAGENTS.mdを読み込む形にしておきます。

仕様と読み込み方は、2026年11月11日に公式サイトと各道具の公式ドキュメントで確かめた内容です。
道具の更新で変わることがあるので、社内に案内する前に一度見直してください。
AGENTS.mdの書き方と置く場所
書き始める前に、「決まった項目や書式はあるの?」と気になるかもしれません。
公式サイトのよくある質問では、ふつうのMarkdownで、必ず書く項目はないと答えています。
公式サイトの案内をもとに、書いて置くまでの流れを、例として並べます。

1. リポジトリの一番上のフォルダに「AGENTS.md」を作る
2. プロジェクトの概要と、動かすコマンド・テストのコマンドを書く
3. コードの書き方の決まりと、プルリクエストの出し方を書く
4. 触ってはいけないファイルと、終える前に確かめる項目を足す
5. Gitにコミットして、同じリポジトリを使う人と共有する
フォルダごとに担当のチームが違うなら、それぞれのフォルダにもAGENTS.mdを置けます。
公式サイトでは、編集するファイルにいちばん近いAGENTS.mdが優先されるとしています。
チャットで直接伝えた指示は、それよりもさらに優先されます。
AGENTS.mdの書き方の例
例えば、社内のお知らせを表示するWebページのリポジトリなら、次のように書けます。
中身は説明のための例なので、実際のプロジェクトに合わせて書き換えます。
# このリポジトリについて
社内のお知らせを表示するWebページのコード。
説明とコメントは日本語で書く。
# 動かし方とテスト
- 準備:npm install
- テスト:npm test(コミットの前に必ず通す)
# コードの決まり
- TypeScriptで書き、インデントは2スペース
# 触らないもの
- config/production/ の中は変更しない
- 本番のデータベースにつながるコマンドは実行しない
# 作業を終える前に
- npm test と npm run lint が通ることを確かめる
- 変えたファイルと理由を短く書く
書く中身は、AIがコードを読んでも分からない決まりに絞るのが、当社の目安です。
Claude Codeの公式ドキュメントでも、フォルダの構成のようにコードから分かる内容は削るよう、すすめています。

また、指示は守れたかを確かめられるくらい、具体的に書きます。
同じドキュメントには、「コードを適切に整える」ではなく「インデントは2スペース」と書く例があります。
AGENTS.mdの仕様の出どころと、読み込む道具
AGENTS.mdは、特定の製品の機能ではなく、公開された形式です。
Linux Foundationの発表によると、OpenAIが2025年8月に公開しました。
2025年12月には、設立が発表されたAgentic AI Foundationに、OpenAIから提供されています。
仕様のリポジトリはGitHubにあり、MITライセンスで公開されています。
公式サイトには、CodexやCursor、Gemini CLIなど、AGENTS.mdを読む道具が並んでいます。
ただ、読み込み方は道具ごとに少しずつ違います。
道具 | AGENTS.mdの読み方 | ほかに指示を書く場所 |
|---|---|---|
Codex | 一番上から作業中のフォルダまで順に読み、近いフォルダが優先 | 個人用の ~/.codex/AGENTS.md |
Cursor | 下のフォルダの指示を、上の指示と合わせて使う | .cursor/rules のプロジェクトルール |
Claude Code | CLAUDE.mdがないときに、代わりに読む | CLAUDE.md |
Codexは、同じフォルダに「AGENTS.override.md」があると、AGENTS.mdの代わりにそちらを読みます。
読む指示の合計は、初期設定では32KiBまでです。
Cursorでは、細かい設定が要らないプロジェクトに向いた形として、AGENTS.mdが案内されています。
CLAUDE.mdとAGENTS.mdの関係
社内でよく聞かれるのが、「AGENTS.mdとCLAUDE.md、どちらに書けばいいの?」という問いです。
Claude Codeの公式ドキュメントでは、初期設定で読むファイルを、組み合わせごとに示しています。

AGENTS.mdだけがある:AGENTS.mdを読む
AGENTS.mdとCLAUDE.mdがある:CLAUDE.mdだけを読む
CLAUDE.mdで「@AGENTS.md」と読み込んでいる:両方を読む
ここで数に入るCLAUDE.mdには、作業中のフォルダとその上にある「CLAUDE.local.md」も含まれます。
つまり、自分用のメモのつもりでCLAUDE.local.mdを置くだけで、AGENTS.mdが読まれなくなります。
一方、各自の ~/.claude/CLAUDE.md は数に入らず、AGENTS.mdと一緒に読まれます。
会社が配る管理用のCLAUDE.mdも同じです。
AGENTS.mdを直接読むには、Claude Code v2.1.277以降が必要です。
読むファイルは、「/config」の「Project instructions」で変えられます。
例えば「claude-md-and-agents-md」を選ぶと、両方を読みます。
当社がすすめるのは、CLAUDE.mdの1行目に「@AGENTS.md」と書く形です。
Claude Codeだけの指示は、その下に足します。
こうしておけば、CLAUDE.mdがあっても、AGENTS.mdの中身が読まれます。
シンボリックリンクでつなぐ方法もあります。
ただ、Windowsで作業する人がいるなら、読み込みの形を使うよう公式ドキュメントに書かれています。
読まれたかどうかは、「/memory」と打って、一覧にAGENTS.mdの場所が出るかで確かめます。
共通にする指示と、道具ごとに分ける指示
全員に守ってほしい指示は、AGENTS.mdだけに書くのが当社の目安です。
道具ごとに読むファイルが違うので、共通の指示をほかのファイルに分けると、どこかで読まれなくなります。

例えばClaude Codeは、「AGENTS.override.md」や「AGENTS.local.md」を読みません。
そこに共通の指示を書くと、「Codexでは守るのに、Claude Codeでは守らない」という差が出ます。
道具だけの指示は、それぞれの道具の場所に分けます。
Claude Codeだけの指示は、CLAUDE.mdの「@AGENTS.md」の下に書きます。
Cursorだけの指示は、.cursor/rules のプロジェクトルールに書きます。
とはいえ、AGENTS.mdもCLAUDE.mdも、AIが読んで従おうとする指示で、必ず守られる設定ではありません。
Claude Codeの公式ドキュメントも、確実に止めたい操作は、フックや禁止の設定で止めるよう案内しています。
禁止の設定との分け方は、Claude Codeを非エンジニアに配る。CLAUDE.mdと禁止設定の分担に書いています。
社内でAGENTS.mdをそろえるときの置き場所
開発の道具が人によって違う会社では、「この指示はどこに書くのか」を先に決めておくと、ばらばらになりません。
当社では、置き場所を次の3つに分けて考えています。

リポジトリ:AGENTS.md。そのリポジトリで作業する全員の決まり
一人ひとりのパソコン:~/.codex/AGENTS.md、~/.claude/CLAUDE.md、CursorのUser Rules
会社全体:Claude Codeの管理用のCLAUDE.md、CursorのTeam Rules(TeamとEnterpriseのプラン)
リポジトリのAGENTS.mdは、会社で1つひな形を作り、新しいリポジトリにはそこから写すと項目がそろいます。
直す担当をリポジトリごとに1人決め、AIが同じ間違いを2回したら書き足すのが、当社の目安です。
公式サイトも、AGENTS.mdは更新し続ける文書として扱うよう書いています。
開発の道具そのものの選び方は、AI開発ツールの選び方。Claude Code・GitHub Copilot・Cursorの違いと、社内で使うときの権限にまとめています。
作った指示やツールが部署の外に広がらないときは、AIツールやプロンプトが、社内で共有されないのページが参考になります。
Claudeを組織で使うときの考え方は、Claudeを業務で使う。Geminiとの使い分けと、組織に入れるときの考え方で扱っています。
AGENTS.mdのひな形を全社で探せるAI Portalize
リポジトリが増えると、よく書けたAGENTS.mdがどこにあるのか、作ったチームの外からは見つけにくくなります。
組織のAIポータル「AI Portalize」では、ナレッジ記事を登録して全社で探せるので、ひな形と書き方の決まりを1本の記事にまとめておけます。
Claudeのスキルや、Gem・Gemini Notebook・HTMLアプリ・GASアプリも、ツールとして同じ場所に登録できます。
AGENTS.mdは1つにまとめ、CLAUDE.mdから読み込む
AGENTS.mdは、Codex・Cursor・Claude Codeが共通に読める、AIへの指示のファイルです。
リポジトリの一番上に1つ置き、Claude Codeを使う人がいるなら、CLAUDE.mdから読み込みます。
道具だけの指示はそれぞれの場所に分け、AGENTS.mdには全員に守ってほしい決まりだけを残します。
参照した情報(2026年11月11日に確認)
すぐ使える業務アプリが300以上
開いてそのまま使えて、AIで自社用にも直せます。15の分野から、やりたい作業で探せます。業務アプリを見る
執筆:寺田昇平
AI Portalize株式会社 代表取締役/AI Digital Community 代表理事
仕組みとコンサルティング伴走支援の両面で、組織のAI活用の加速を支援。
お知らせ・組織AI推進ノウハウ一覧












