組織のAI活用をAIポータルと伴走支援で加速

AGENTS.mdとは。Claude Code・Codex・Cursorで共通に使える指示ファイルの書き方

AGENTS.mdとは。Claude Code・Codex・Cursorで共通に使える指示ファイルの書き方

執筆:寺田昇平

AI Portalize株式会社 代表取締役/AI Digital Community 代表理事

仕組みとコンサルティング伴走支援の両面で、組織のAI活用の加速を支援。

AGENTS.mdは、AIのコーディングエージェントに、プロジェクトの決まりを伝えるMarkdownのファイルです。
リポジトリの一番上に置くと、Codex・Cursor・Claude Codeのどれで開いても、同じ指示が読まれます。
ただしClaude Codeは、同じ場所にCLAUDE.mdがあると、そちらだけを読みます。
そろえるなら、CLAUDE.mdからAGENTS.mdを読み込む形にしておきます。

AGENTS.mdをリポジトリの一番上に置いたとき、Codex・Cursor・Claude Codeがそれぞれどう読むかと、ほかに指示を書く場所を比べ、Claude CodeはCLAUDE.mdがあるとそちらだけを読むことを強調した図

仕様と読み込み方は、2026年11月11日に公式サイトと各道具の公式ドキュメントで確かめた内容です。
道具の更新で変わることがあるので、社内に案内する前に一度見直してください。

AGENTS.mdの書き方と置く場所

書き始める前に、「決まった項目や書式はあるの?」と気になるかもしれません。
公式サイトのよくある質問では、ふつうのMarkdownで、必ず書く項目はないと答えています。

公式サイトの案内をもとに、書いて置くまでの流れを、例として並べます。

AGENTS.mdを書いてリポジトリに置くまでの流れの例として、一番上のフォルダにファイルを作る、概要とコマンドを書く、コードの決まりを書く、触らないものと終える前の確認を足す、Gitにコミットして共有する、の5つを順に並べた図

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の公式ドキュメントでも、フォルダの構成のようにコードから分かる内容は削るよう、すすめています。

AGENTS.mdに書く中身の例として、リポジトリの説明、動かし方とテストのコマンド、コードの決まり、触らないもの、作業を終える前の確認を並べ、フォルダの構成のようにコードから分かる内容は書かないことを示した図

また、指示は守れたかを確かめられるくらい、具体的に書きます。
同じドキュメントには、「コードを適切に整える」ではなく「インデントは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の公式ドキュメントでは、初期設定で読むファイルを、組み合わせごとに示しています。

Claude Codeが初期設定で読むファイルを、AGENTS.mdだけがある場合はAGENTS.md、AGENTS.mdとCLAUDE.mdがある場合はCLAUDE.mdだけ、CLAUDE.mdで@AGENTS.mdと読み込んでいる場合は両方、の3つの組み合わせで示した図

  • 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だけに書くのが当社の目安です。
道具ごとに読むファイルが違うので、共通の指示をほかのファイルに分けると、どこかで読まれなくなります。

全員に守ってほしい指示はAGENTS.mdだけに書き、Claude Codeだけの指示はCLAUDE.mdの@AGENTS.mdの下に、Cursorだけの指示は.cursor/rulesに書くことを示した図

例えば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をそろえるときの置き場所として、リポジトリに置くAGENTS.mdと、一人ひとりのパソコンや会社全体で使う指示の場所(~/.codex/AGENTS.md、~/.claude/CLAUDE.md、CursorのUser Rules、Claude Codeの管理用のCLAUDE.md、CursorのTeam Rules)を左右に並べた図

  • リポジトリ: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活用の加速を支援。

keyboard_backspace

お知らせ・組織AI推進ノウハウ一覧

無料 自社に当てはめて知りたい方へ

読んだ内容を、

御社の数字

で確かめませんか。

利用データから、御社のAI活用がいまどこにいるのかを判定します。
同業他社との比較と、次にやることをお渡しします。

組織のAI活用力診断のメインビジュアル(ノートPCの利用データと結果表)

Related

関連記事

Service

サービス一覧

AI Portalizeの管理画面イメージ:AI活用数・効率化時間の見える化とチームへの広がり

AIツールが見つかる。社内に広がる。使われ方が見える。

組織のAIポータル「AI Portalize」

  • check_circle

    やりたいことで検索すると、業務アプリ300以上とナレッジ250本以上から見つかる

    check_circle

    社内で作ったツールやナレッジが共有され、よく使われるものが上に並ぶ

    check_circle

    誰が何をどれだけ使っているかが、集計の手間なしで分かる

デジタル系企業特化のAIコンサルティング&伴走支援のイメージイラスト

実務に組み込むまで伴走

組織のAI活用を加速「AIコンサル&伴走支援」

  • check_circle

    従業員が安心して使うためのガイドライン策定

    check_circle

    ドメイン知識が豊富なコンサルタント

    check_circle

    業務分解からAIワークフロー作成

    check_circle

    研修から実務への組み込みまで

法人向けAI研修のイメージ:受講者が自分の業務でAIを使いながら学ぶ研修の様子

自社の業務で、使える知識に

実務で使える知識を「法人向けAI研修」

  • check_circle

    いま使っているAIと受講者の業務を伺って、誰に・どのAIで・どの業務を題材にするかを提案

    check_circle

    Gemini・Claude・AIエージェントなど、8つの研修例と230以上のテーマ例

    check_circle

    基本はオンライン。研修の資料と録画もお渡し

デジタル系企業特化のAIコンサルティング&伴走支援のイメージイラスト

豊富な新規事業立ち上げ実績

AIを活用した
新規事業の立ち上げ支援

  • check_circle

    検討からサービス構築まで

    check_circle

    豊富な新規事業構築実績

    check_circle

    すでにあるAIボットなどを活用も可能

AI活用支援のビフォーアフター:迷っている状態からGemini等を使いこなす状態への変化

経営者・役員・AI担当向け

AIパーソナル
トレーニング

  • check_circle

    まだAI活用できていない状態でも大丈夫

    check_circle

    1回2時間のみからご利用いただけます

    check_circle

    実務で使える「今のAI活用」を学ぶ

    check_circle

    トップ層こそAIに詳しく

AIガイドライン作成+定着研修の紹介バナー:御社に合ったルールづくりから社内への定着まで

生成AIの社内ルールを一緒に作る

AIガイドライン作成+
定着研修

  • check_circle

    御社の現状をヒアリングしながら一緒に作成

    check_circle

    AIツールごとの仕組みや契約の違いを踏まえて線を引く

    check_circle

    従業員の方への定着研修までご支援

AIガイドライン作成+定着研修の紹介バナー:御社に合ったルールづくりから社内への定着まで

AIの答えに、自社の名前を

LLMO・GEO・AIO
対策

  • check_circle

    御社の現状をヒアリングしながら一緒に作成

    check_circle

    AIツールごとの仕組みや契約の違いを踏まえて線を引く

    check_circle

    従業員の方への定着研修までご支援

まずは、いまのAI活用の
状況をお聞かせください。

何から始めるか決まっていなくても、ご相談いただけます。

無料相談・お問い合わせ