メインコンテンツへスキップ
見出し画像

【2026年7月版】CLAUDE.mdとAGENTS.mdの違いとは?Claude Code・Codexでの使い分けを解説

    はじめに

    こんにちは、kazuです。

    Claude CodeとCodexを毎日併用して仕事をしています。私の会社リポジトリにはCLAUDE.mdとAGENTS.mdの両方が置いてあり、AI社員の運用憲章として毎日実際に読み込ませています。

    その立場から、この2つのファイルの違いを整理しました。

    「AGENTS.mdはCodex専用でしょ?」
    「Claude CodeもAGENTS.mdを読むんでしょ?」

    といったよくある誤解も、公式仕様を根拠に訂正していきます。

    なお本記事は、Anthropic公式ドキュメント、OpenAIのCodexガイド、AGENTS.md公式サイトなどの一次情報のみを根拠にしています。
    参照元は記事内に都度明記します。

    30秒でわかる結論

    まず結論です。

    CLAUDE.mdは、Claude Codeがネイティブに読み込む、Anthropic固有の指示・プロジェクト記憶ファイルです。

    AGENTS.mdは、Codexを起点に広がり、現在は複数のコーディングエージェントで共有できるオープン形式です。

    どちらも、ビルドコマンド、テスト方法、コーディング規約、プロジェクト構成などをAIに伝えるためのMarkdownファイルという点は同じです。
    違うのは、対応ツール、読み込み範囲、優先順位、ローカル設定、ファイル分割の方法です。

    そして重要な事実として、Anthropic公式ドキュメントは「Claude CodeはCLAUDE.mdを読み、AGENTS.mdは直接読まない」と明記しています。

    参照: How Claude remembers your project(Anthropic公式)

    主な違いの一覧

    以下、違いを整理します。

    画像

    位置付け
    ・CLAUDE.md: Claude Code専用の永続指示・プロジェクト記憶
    ・AGENTS.md: 複数のコーディングエージェント向けの共通指示

    ネイティブ対応ツール
    ・CLAUDE.md: Claude Code
    ・AGENTS.md: Codexの標準指示ファイル。Gemini CLIでは設定により読み込み可能。Google Antigravityでは小文字のagents.mdをエージェント定義に利用するなど、複数ツールで関連形式が採用されている

    ※ただし、ツールごとにファイル名、用途、探索場所、読み込み順序は異なります。たとえば、Antigravityの公式資料では小文字のagents.mdがAIペルソナやチーム構成の定義に使われています。Gemini CLIの標準はGEMINI.mdであり、AGENTS.mdは設定によって読み込み対象に追加できます。そのため、これらをCodexのAGENTS.mdと完全に同一の仕様として扱うのは正確ではありません。

    管理主体
    ・CLAUDE.md: Anthropic
    ・AGENTS.md: Agentic AI Foundation(Linux Foundation傘下)

    ユーザー共通設定の置き場所
    ・CLAUDE.md: ~/.claude/CLAUDE.md
    ・AGENTS.md: Codexでは~/.codex/AGENTS.md

    個人用のプロジェクト設定
    ・CLAUDE.md: CLAUDE.local.md(Gitにコミットしない個人用)
    ・AGENTS.md: CodexではAGENTS.override.mdが利用可能

    ファイルのインポート
    ・CLAUDE.md: @AGENTS.mdのようなインポート構文に対応
    ・AGENTS.md: Codex標準では同等の構文は示されていない

    推奨サイズ
    ・CLAUDE.md: 1ファイル200行未満が目安
    ・AGENTS.md: Codexでは合計32KiBが初期上限

    CLAUDE.mdとは

    CLAUDE.mdは、Claude Codeに対してセッションをまたいで同じ説明を繰り返さないための指示ファイルです。

    Claude Codeは各セッションを新しいコンテキストで開始します。CLAUDE.mdを読み込むことで、ビルドコマンド、コーディング規約、プロジェクト構成、アーキテクチャ上の決定といったプロジェクト固有の前提を、セッションをまたいで維持します。

    配置場所は用途に応じて複数あります。

    ・~/.claude/CLAUDE.md: 全プロジェクトに適用する個人設定
    ・project/CLAUDE.md: チームで共有するプロジェクト設定
    ・project/.claude/CLAUDE.md: 同じくプロジェクト設定
    ・project/CLAUDE.local.md: Gitにコミットしない個人用設定

    読み込みの仕組みも特徴的です。
    作業ディレクトリより上の階層にあるCLAUDE.mdを順に読み込み、基本的にはすべて連結してコンテキストに追加します。作業場所に近いファイルほど後ろに追加されますが、矛盾する指示がある場合にどちらが優先されるかは保証されません。Anthropicは、Claudeがどちらかを任意に選ぶ可能性があると説明しています。

    もう1つの固有機能が、@によるファイルインポートです。

    CLAUDE.mdの中に@AGENTS.mdや@docs/architecture.mdと書くと、そのファイルの内容を読み込ませることができます。再帰的なインポートは最大4階層までです。この機能が、後述する「両ファイル併用」の鍵になります。

    AGENTS.mdとは

    AGENTS.md公式サイトは、AGENTS.mdを「README for agents」と表現しています。README.mdが人間向けの概要を扱うのに対して、AGENTS.mdはAIエージェント向けに、ビルド方法、テスト、規約、セキュリティ上の注意点などを伝えるファイルです。

    参照: AGENTS.md公式サイト

    ここで最初の大きな誤解を訂正します。AGENTS.mdは、もうCodex専用ファイルではありません。

    もともとはCodexがプロジェクト固有の指示を安定して見つけるための仕組みとして始まりました。
    しかし2025年12月、OpenAIはAGENTS.mdをAgentic AI Foundationへ提供し、現在はLinux Foundation傘下で管理されるオープン形式になっています。OpenAIによると、公開後6万件以上のオープンソースプロジェクトで採用されています。

    参照: OpenAI「Agentic AI Foundation」発表

    公式サイトに掲載されている対応ツールには、Codexのほか、Google Jules、Gemini CLI、GitHub Copilot Coding Agent、VS Code、Cursor、Windsurf、Aider、Zed、JetBrains Junie、Devinなどが並んでいます。

    また、AGENTS.mdにはJSONやYAMLのような必須スキーマがありません。普通のMarkdownとして、プロジェクト概要、セットアップコマンド、ビルドとテスト、コードスタイル、テスト手順、セキュリティ上の注意、といった見出しを自由に立てて書きます。

    CodexはAGENTS.mdをどう読むか

    「AGENTS.mdという形式の一般仕様」と「Codexが実際にどう読むか」は分けて理解する必要があります。

    Codexは起動時、まずグローバル設定として~/.codex/AGENTS.override.mdを探し、なければ~/.codex/AGENTS.mdを使います。

    プロジェクト側は、Gitルートから現在の作業ディレクトリまでを探索し、各ディレクトリで最大1ファイル(AGENTS.override.md、AGENTS.mdの順で最初に見つかったもの)を読み込みます。ルート側から順に連結され、作業ディレクトリに近い指示ほど後ろに置かれます。OpenAIは、後ろに追加された具体的な指示が先の一般的な指示を上書きすると説明しています。

    読み込み上限は初期設定で合計32KiBです。~/.codex/config.tomlのproject_doc_max_bytesで変更でき、project_doc_fallback_filenamesで別名ファイル(たとえばCLAUDE.md)を読ませることもできます。

    参照: Custom instructions with AGENTS.md(OpenAI公式)

    最大の違いは子ディレクトリの読み方

    実務で一番効いてくる違いがここです。

    Claude Codeは、作業中に子ディレクトリのファイルへアクセスした時、そのディレクトリのCLAUDE.mdをオンデマンドで追加読み込みします。大きなリポジトリでも、触った場所のルールが後から効いてくる仕組みです。

    一方、現在のCodex公式ガイドでは、起動時にプロジェクトルートから現在の作業ディレクトリまでを読み、そこで探索を止めるとされています。
    リポジトリのルートでCodexを起動したまま下層のディレクトリを編集しても、下層のAGENTS.mdが自動で読み込まれるとは限りません。OpenAI公式ガイドも、下層の指示を使う例としてcodex --cd services/paymentsのように作業ディレクトリ自体を指定する方法を示しています。

    AGENTS.mdの一般仕様サイトには「編集対象ファイルに最も近いAGENTS.mdが優先される」と書かれていますが、探索アルゴリズムの細部まで全ツールで統一されているわけではないと理解しておくのが安全です。

    どちらも強制力はない

    もう1つ、実務で誤解しやすいポイントです。

    CLAUDE.mdやAGENTS.mdに「本番データベースを変更しないこと」と書いても、操作がブロックされるわけではありません。
    Anthropicは、CLAUDE.mdを強制設定ではなくコンテキストだと明記しています。
    Codexでも、AGENTS.mdはプロンプト内のユーザー指示として追加される位置付けです。

    参照: Unrolling the Codex agent loop(OpenAI公式)

    これは私自身、AI社員を毎日運用していて骨身に染みている点です。指示ファイルに禁止事項を書いても、AIは文脈次第でそれを踏み越えることがあります。私の会社リポジトリでは、ファイル削除の禁止やシークレット表示の禁止を指示ファイルに書いたうえで、それとは別にhook(ツール実行前に走るチェックスクリプト)で物理的にブロックしています。実際、指示だけでは防げなかった操作をhookが止めた場面を何度も見ています。

    つまり使い分けはこうなります。

    指示ファイルに書くべきもの
    ・行動方針、コーディング規約、テスト手順、作業フロー、レビュー観点

    指示ファイル以外(hooks、権限設定、CI、サンドボックス)で強制すべきもの
    ・秘密情報へのアクセス禁止、本番環境への接続禁止、特定コマンドの実行禁止

    併用する場合の推奨構成

    Claude CodeとCodexを両方使うなら、AGENTS.mdを共通ルールの正本にして、CLAUDE.mdからインポートする構成が管理しやすいです。これはAnthropic公式ドキュメントでも紹介されている方法です。

    AGENTS.mdに、インストール、テスト、lintのコマンドやコードスタイルなどの共通ルールを書きます。

    CLAUDE.mdは次のようにします。

    @AGENTS.md

    の1行で共通ルールを取り込み、その下にClaude Code固有の指示(プランモードの使い方、サブエージェントの使い分け、.claude/rules/の参照など)だけを書き足します。

    これでCodexや他の対応エージェントはAGENTS.mdを読み、Claude CodeはCLAUDE.md経由で同じ共通ルールを読みます。ルールの重複と更新漏れを減らせます。

    モノレポの場合は注意が1つあります。
    ルートのCLAUDE.mdがルートのAGENTS.mdをインポートしても、Claude Codeが子ディレクトリのAGENTS.mdまで読むようになるわけではありません。
    Claude CodeはAGENTS.mdをネイティブでは読まないため、子ディレクトリごとに@AGENTS.mdと書いた橋渡し用のCLAUDE.mdを置くか、Claude固有の.claude/rules/へ集約する必要があります。

    私の実運用から

    私のAIカンパニーリポジトリ(複数のAI社員を運用しているリポジトリ)では、次の構成で回しています。

    ・CLAUDE.md:
    会社の運用憲章。組織図、承認フロー、安全ルールの要点を書き、詳細は別ファイルへの索引にする
    ・.claude/rules/:
    ファイルパス別のルール。顧客対応ファイルを触った時だけ顧客対応ルールが自動で効く
    ・AGENTS.md: Codex用に同じ内容をCodex向けの文言で調整したもの

    運用して実感しているのは、Anthropicが推奨する「1ファイル200行未満」の意味です。
    以前、CLAUDE.mdに何でも書き足して肥大化させたところ、AIが指示を守る率が体感で下がりました。
    本文を要点だけに圧縮し、詳細をポリシーファイル群に逃して索引で参照させる形に直してから、挙動が安定しました。長く書くほど守ってくれるわけではない、というのは公式の推奨どおりでした。

    よくある誤解のまとめ

    誤解1: AGENTS.mdはCodex専用でしょ?
    違います。Google Antigravityでも利用します。ちなみに、 AGENTS.mdはLinux Foundation傘下のオープン形式で、多数のツールで利用されます。

    誤解2: Claude CodeもAGENTS.mdを自動で読む?
    読みません。CLAUDE.mdから@AGENTS.mdでインポートするか、シンボリックリンクを作る必要があります。

    誤解3: 下位のCLAUDE.mdが上位を完全に上書きするよね?
    基本は連結です。近いファイルが後ろに足されますが、矛盾時の厳密な上書きは保証されません。

    誤解4: 指示は長いほど正確になる?
    逆です。CLAUDE.mdは1ファイル200行未満が推奨で、Codexにも合計32KiBの初期上限があります。

    誤解5: 指示ファイルに書けば操作を禁止できる?
    できません。重要な禁止事項は、権限設定、hooks、CI、サンドボックスで技術的に強制する必要があります。

    まとめ

    CLAUDE.mdはClaude Code向けの高機能な専用指示ファイル、AGENTS.mdは複数エージェントで共有するためのオープンな共通指示ファイルです。

    両方使うなら、共通ルールの正本をAGENTS.mdに置き、CLAUDE.mdには@AGENTS.mdでのインポートとClaude固有の差分だけを書く。
    この形にすると、ツール間のルール重複と更新漏れを減らせます。

    そして、どちらのファイルもあくまでプロンプト上の指示です。守らせたいルールは指示ファイルに、破らせたくないルールはhooksや権限設定に。
    この線引きが、AIエージェントを安心して走らせるコツだと感じています。

    FAQ(よくある質問)

    Q. CLAUDE.mdとAGENTS.md、まずどちらから書き始めればいいですか?
    A.使っているツールが1つならそのツールのファイル(Claude CodeならCLAUDE.md、CodexならAGENTS.md)だけで十分です。複数ツールを使う予定があるなら、最初からAGENTS.mdを正本にしておくと後がラクです。

    Q. CLAUDE.mdとAGENTS.mdに同じ内容をコピペして二重管理してもいいですか?
    A.動きはしますが、更新漏れの温床になります。CLAUDE.mdに@AGENTS.mdと書いてインポートする方式なら、共通ルールの修正が1箇所で済みます。

    Q. 何を書けばいいか分かりません。
    A.最低限、プロジェクトの概要、ビルドとテストのコマンド、コードスタイル、やってほしくないこと、の4点があれば機能します。AIに「このリポジトリを読んで指示ファイルのたたき台を作って」と頼むのも有効です。

    Q. 書いたのにAIが指示を守ってくれません。
    A. まずファイルが長すぎないかを疑ってください。要点だけに圧縮すると追従率が上がります。それでも破られて困るルールは、指示ではなくhooksや権限設定で技術的にブロックする対象です。

    生成AIやDifyについて動画で学びたい方はこちら

    私が講師を務める生成AIコースでは、生成AIやDifyを用いたアプリの作り方も解説しています。

    生成AIコース(基礎)
    生成AIコース(実践)
    AI人材コース(機械学習・深層学習の基礎からPythonでAIエージェント開発まで)

    案件のご相談はこちら

    Difyやn8nをはじめとしたAIを活用した業務効率化エージェントの構築を支援しています。初回は無料相談も受け付けていますので、社内でAIエージェントを構築したい法人様はぜひお気軽に下記よりお問い合わせください。

    お問い合わせはこちらから

    X(旧Twitter)からでもお問い合わせいただけます。

    また、継続的にAI活用を伴走支援するAI顧問サービス(個人・法人向け、3ヶ月間のマンツーマンサポート)も提供しています。まずは30分の無料ヒアリングから可能です。AI顧問サービスの詳細はこちら

    この記事が参考になったら、ぜひ「スキ」をお願いします!🙇

    ワンコインメンバーシップのご紹介

    ChatGPT・Dify等の技術検証ログや、すぐに使える「設定ファイル(YAML)・プロンプト」等の素材を月1回以上お届けします。ワンコインで参加できますので、ぜひご参加ください!

    #生成AI #AI #Claude #ClaudeCode #Codex #AIエージェント #業務効率化 #LLM #プロンプト #自動化

     
     
    AIと働く仕組みを構築/Claude Code・Codex・最新AIについて共有/権限と承認、AIエージェント時代のAIセキュリティも発信/2016年AI Academy創業→売却→AI顧問/生成AI×教育 #AIエージェント #AIセキュリティ #EdTech

    あなたへのおすすめ