Claude CodeのAGENTS.md対応：CLAUDE.mdとの使い方と活用方法

Claude Code は v2.1.277 で AGENTS.md のサポートを導入しました。CLAUDE.md が存在しないプロジェクトでは、Claude Code が AGENTS.md をプロジェクトの指示書として読み込むようになりました。import もシンボリックリンクも設定も不要です。リポジトリに両方のファイルがある場合、Claude Code は CLAUDE.md のみを読み取ります。/config の Project instructions 設定を切り替えて両方を読み込ませることもできます。

チームで複数のコーディングエージェントを使っているなら、Codex や Cursor がすでに読み込んでいるのと同じ AGENTS.md が、Claude Code も従うようになります。このガイドでは、優先順位、移行手順、そして Apidog CLI でどんなエージェントにも API テストを教えるための AGENTS.md を解説します。

Claude Code における AGENTS.md とは？

AGENTS.md は、コーディングエージェント向けの指示を記述したプレーンな Markdown ファイルです。ビルドコマンド、テストコマンド、コードスタイル、プロジェクトルールなどを記載します。v2.1.277 以降、Claude Code は組み込みプラグインを通じてこのファイルを読み込むため、他のエージェント向けに整備されたリポジトリでも、追加ファイルなしで Claude Code が動作します。必須フィールドや特別な構文は必要ありません。

このフォーマット自体はオープンです。AGENTS.md の公式サイトでは、「コーディングエージェントを導くためのシンプルでオープンなフォーマット」と説明されており、6 万以上のオープンソースプロジェクトで利用され、現在は Linux Foundation 配下の Agentic AI Foundation によって管理されています。OpenAI Codex と Cursor はどちらも AGENTS.md サポートをドキュメント化しており、今回のリリースまで Claude Code が唯一の未対応だった存在でした。

このフォーマットが初めてという方は、まず API 開発チームのための AGENTS.md ファイルの書き方から始めてください。

Claude Code の公式変更履歴によるリリースの経緯は以下の通りです：

これらの機能に頼る前に、必ず claude --version を実行して確認してください。2.1.277 より古いバージョンでは、Claude Code は CLAUDE.md ファイルのみを読み込みます。

CLAUDE.md vs AGENTS.md：どちらが優先される？

デフォルトでは CLAUDE.md が優先されます。Claude Code は、作業ディレクトリおよびその上位ディレクトリに CLAUDE.md が存在しない場合にのみ AGENTS.md を読み込みます。Claude Code のメモリドキュメントでは、次の 3 つのケースが説明されています：

この判定ですべてのファイルが対象になるわけではありません。次の 3 つが AGENTS.md の読み込みをブロックします：

• 作業ディレクトリまたはその上位にある CLAUDE.md
• 作業ディレクトリまたはその上位にある .claude/CLAUDE.md
• 作業ディレクトリまたはその上位にある CLAUDE.local.md

一方、以下はブロックせず、AGENTS.md と並行して読み込まれ続けます：~/.claude/CLAUDE.md のユーザーファイル、組織の管理対象 CLAUDE.md、そして .claude/rules/ 配下のファイルです。

CLAUDE.local.md の罠に注意してください：コミットしないメモ用に個人の CLAUDE.local.md を追加すると、Claude はチームの AGENTS.md を読まなくなります。

Claude Code が読み込むものとタイミング

何もブロックされていない場合、Claude Code は以下を読み込みます：

1. セッション開始時：作業ディレクトリおよびその上位ディレクトリにあるすべての AGENTS.md と .claude/AGENTS.md。対話セッションでは no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md のような行が表示されます。
2. サブディレクトリ内：サブディレクトリの AGENTS.md は、Claude が Read ツールでそのフォルダ内のファイルを開き、そのフォルダに自前の CLAUDE.md がない場合に読み込まれます。
3. import：AGENTS.md 内の @path import は展開され、claudeMdExcludes パターンも適用されます。

Claude Code は AGENTS.local.md、AGENTS.override.md、.agents/ 配下のファイルは読み込みません。AGENTS.override.md をドキュメント化している Codex とリポジトリを共有する場合は、この点に注意してください。

Claude Code が読み込む指示ファイルを変更する方法

セッション内で /config を入力し、Project instructions を次の 4 つの値のいずれかに設定します：

多くの混在チームにとって、claude-md-and-agents-md が望ましい設定です。個人の CLAUDE.local.md を保持しつつ、共有の AGENTS.md も読み込めます。

設定ファイルで指定することもできます。Claude Code はこのエントリを ~/.claude/settings.json、--settings ファイル、または管理対象設定から読み取り、プロジェクト設定やローカル設定ファイル内では無視します：

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

v2.1.285 より前のプラグイン ID は agents-md@builtin でした。2.1.285 以降のバージョンはどちらの ID も読み取るため、古いインストールと設定ファイルを共有している場合は古い ID を使ってください。変更は次のメッセージから適用されます。

/config に Project instructions が表示されない場合、そのセッションは AGENTS.md を読み込めません。理由は、バージョンが 2.1.277 未満であるか、/plugin で組み込みプラグインを無効化しているか、アップグレード後の最初のセッションである（次のセッションから動作する）ためです。

従来の AGENTS.md 対応策からの移行方法

このリリース以前、多くのチームは AGENTS.md を手動で Claude Code に組み込んでいました。ドキュメントでは以下を推奨しています：

チームに 2.1.277 未満のバージョンを使っているメンバーがいる場合は、@AGENTS.md の import を残しておいてください。すべてのバージョンで機能する唯一のセットアップです。

import かシンボリックリンクか？

共有ファイルに加えて Claude 固有のルールが必要な場合は、import を使いましょう。Claude は import されたファイルを先に読み、その後残りを読みます：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude 固有の設定が不要なら、シンボリックリンクでも動作します：

ln -s AGENTS.md CLAUDE.md

注意点が 2 つあります。Claude の Edit ツールと Write ツールはシンボリックリンクを通じて書き込めないこと、そして Windows の Git では core.symlinks が有効でない限り、コミットされたシンボリックリンクが 1 行のテキストファイルとしてチェックアウトされることです。チームに Windows ユーザーがいるなら、import を選びましょう。

どちらの場合でも、次のセッションで /context all を実行し、Memory files の下に CLAUDE.md が表示されることを確認してください。

Codex・Cursor・Claude Code で 1 つの AGENTS.md を共有する

メリットは、単一の情報源が持てることです。ビルドコマンド、テストコマンド、規約をリポジトリのルートにある AGENTS.md にまとめれば、Codex、Cursor、Claude Code のすべてがそれを読み込みます。

実践で通用するレイアウト：

• ルートの AGENTS.md：すべてのエージェントが必要とする内容すべて。コマンド、フォルダ構成、スタイルルール、触ってはいけない箇所。
• 大きなサブフォルダ内の AGENTS.md：そこにのみ適用されるルール。例：services/payments/AGENTS.md。Claude Code はそのフォルダ内のファイルを読んだ際に、必要に応じてこれらを読み込みます。
• 任意の CLAUDE.md：plan モードやフックなど、Claude 固有の挙動が必要な場合のみ。冒頭に @AGENTS.md を記載します。

注意点：設定を通じて読み込まれた AGENTS.md は InstructionsLoaded フックを発火させず、--add-dir ディレクトリからは読み込まれません。いずれかに依存している場合は、@AGENTS.md の import を使ってください。

AGENTS.md で、エージェントに Apidog CLI による API テストを教える

API テストのルールを一度書けば、どのエージェントがリポジトリを開いても同じ方法でテストを実行します。Apidog CLI は、エージェントが読める構造化された JSON 出力を提供するため、ループ全体をターミナル内で完結できます。

マシンごとに一度だけセットアップします：

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

ショートカットとして、エージェントに「https://apidog.com/apidog-cli-installation-guide.md を読んで Apidog CLI をセットアップして」と指示する方法もあります。このガイドはエージェント向けに書かれており、インストール、ログイン、スキルについて網羅しています。

次に、AGENTS.md に以下のようなセクションを追加します：

## API testing (Apidog CLI)

- Apidog project ID: 123456. Staging environment ID: 7890.
- Never build Apidog JSON payloads from memory. Run
  `apidog cli-schema get <key>` first, then
  `apidog cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apidog endpoint list --project 123456` and its cases with
  `apidog test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apidog test-case create --project 123456 --file case.json`.
- Run cases with
  `apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apidog unless the task asks for it.

これで、Claude Code、Codex、Cursor のいずれでも、1 つのプロンプトで作業が完了します：

I changed POST /orders to require a currency field. Update the Apidog test
case for it and run it against staging, following AGENTS.md.

エージェントはあなたのルールに従い、次のようなコマンドを実行します：

apidog endpoint list --project 123456
apidog test-case list --project 123456 --endpoint <endpointId>
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json

上記のすべてのフラグは、Apidog CLI 2.2.12 の apidog <cmd> --help に基づいています。同じ apidog run のコマンドに -r junit を付けると CI にそのまま組み込め、--upload-report を付けると実行概要がアプリに送信され、チームで確認できます。Claude Code 側の詳細は Claude Code での Apidog CLI の使い方を、Codex ユーザーは Codex での Apidog CLI を参照してください。Apidog Free は最大 4 ユーザーまで利用できるので、小規模チームでも今日から試せます。

トラブルシューティング：AGENTS.md が読み込まれない

1. パス上に CLAUDE.md がないか確認。作業ディレクトリまたはその上位にある CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md はデフォルトで優先されます。あなたの ~/.claude/CLAUDE.md は該当しません。
2. バージョンを確認。claude --version を実行してください。2.1.277 以降が必要で、Bedrock、Vertex AI、Foundry、ゲートウェイ、またはテレメトリ無効の場合は 2.1.281 以降が必要です。
3. 設定を確認。/config を開き、Project instructions が claude-md や managed-only になっていないことを確認してください。
4. 読み込まれたか確認。/memory を実行し、リストに AGENTS.md のパスがあるか確認してください。

FAQ

Claude Code は AGENTS.md を読み込むようになったのか？ はい、v2.1.277 からです。作業ディレクトリおよびその上位に CLAUDE.md がない場合、Claude Code は AGENTS.md をプロジェクトの指示書として自動的に読み込みます。

CLAUDE.md と AGENTS.md の両方がある場合、どちらが使われる？ デフォルトでは CLAUDE.md のみです。両方を読み込むには、/config で Project instructions を claude-md-and-agents-md に設定してください。CLAUDE.md が先に読み込まれます。

@AGENTS.md を import している CLAUDE.md は削除すべき？ 削除する必要はありません。この import で AGENTS.md が二重に読み込まれることはなく、2.1.277 未満のバージョンを使っているチームメンバーにとっても引き続き機能します。内容がそれ以外に何もなく、全員がアップグレード済みの場合にのみ削除してください。

Claude Code は Codex のように AGENTS.override.md を読むのか？ いいえ。Claude Code は AGENTS.override.md、AGENTS.local.md、.agents/ 配下のファイルは無視します。

AGENTS.md は Amazon Bedrock や Google Vertex AI でも動作する？ はい、v2.1.281 から動作します。それ以前のバージョンでは、Bedrock、Vertex AI、Foundry、ゲートウェイ、またはテレメトリ無効の環境では CLAUDE.md のみを読み込むため、そこでは @AGENTS.md の import を使ってください。