0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@d_murata(大輔 村田)

Claude CodeがAGENTS.md対応、CLAUDE.mdとの優先関係を検証した

0
Posted at

Claude CodeがAGENTS.md対応、CLAUDE.mdとの優先関係を検証した

はじめに

Claude Codeのv2.1.277で、「AGENTS.md」への対応が始まりました。リリースノートによると、プロジェクトにCLAUDE.mdが存在しない場合、Claude Codeが代わりにAGENTS.mdを読み込むようになったとのことです(リリースノート)。

AGENTS.mdは、Claude Code以外にもCursorやCodexなど複数のAIコーディングツールで使われている、プロジェクト指示ファイルの業界共通フォーマットです。私は普段EC-CUBEを中心にEC構築・保守の仕事をしていますが、複数のAIコーディングツールを併用する開発チームでは「ツールごとに別々の指示ファイルを書く」という無駄が地味に負担になります。この対応が実際にどう動くのか、特にCLAUDE.mdとAGENTS.mdが両方あった場合にどちらが優先されるのかは、指示ファイルの運用設計に直結するので手元で確認しました。

検証環境

  • OS: Ubuntu 24.04.4 LTS
  • claude CLI: 2.1.283
  • Python: 3.11.15(検証スクリプト実行用)
  • モデル: claude -pのデフォルトモデル(プロンプト内で自己申告: claude-sonnet-5)
  • 実行日時: 2026-09-28 03:40 UTC

やってみた

検証は、3種類のディレクトリを用意し、それぞれでclaude -p "自己紹介を一文でしてください"を実行するだけのシンプルなものです。AGENTS.mdとCLAUDE.mdには、それぞれ「回答の先頭に決まったプレフィックスを付けること」という指示だけを書き、実際の出力にその指示が反映されるかを見ています。

AGENTS_MD_CONTENT = """# Instructions

You are operating under a test instruction file. This is AGENTS.md, not CLAUDE.md.

IMPORTANT: Your answer MUST always begin with the exact prefix "【AGENTS.mdテスト】" (this exact Japanese bracketed string), followed by your normal answer. Do not omit this prefix under any circumstances.
"""

CLAUDE_MD_CONTENT = """# Instructions

You are operating under a test instruction file. This is CLAUDE.md, not AGENTS.md.

IMPORTANT: Your answer MUST always begin with the exact prefix "【CLAUDE.mdテスト】" (this exact Japanese bracketed string), followed by your normal answer. Do not omit this prefix under any circumstances.
"""

PROMPT = "自己紹介を一文でしてください"

3つのケースを用意しました。

  1. test0_control: CLAUDE.mdもAGENTS.mdも置かない(コントロール)
  2. test1_agents_only: AGENTS.mdのみ配置
  3. test2_both: AGENTS.mdとCLAUDE.mdの両方を配置

実行結果は次の通りです(logs/run.logより抜粋)。

===== TEST CASE: test0_control (cwd=.../test0_control) =====
files in dir: []
$ claude -p 自己紹介を一文でしてください
--- STDOUT ---
私は、AI関連情報を検証しながらQiita記事の下書きを作成するお手伝いをする、Claude Codeのアシスタントです。

--- EXIT CODE: 0 ---

===== TEST CASE: test1_agents_only (cwd=.../test1_agents_only) =====
files in dir: ['AGENTS.md']
$ claude -p 自己紹介を一文でしてください
--- STDOUT ---
【AGENTS.mdテスト】私はソフトウェア開発全般を支援するAIアシスタントのClaude Codeです。

--- EXIT CODE: 0 ---

===== TEST CASE: test2_both (cwd=.../test2_both) =====
files in dir: ['AGENTS.md', 'CLAUDE.md']
$ claude -p 自己紹介を一文でしてください
--- STDOUT ---
【CLAUDE.mdテスト】私はAnthropicが開発したAIアシスタント「Claude」で、ソフトウェア開発や文章作成などのタスクをお手伝いするために、この環境ではClaude Codeとして動作しています。

--- EXIT CODE: 0 ---

すべて終了コード0で成功し、次の2点が確認できました。

  • AGENTS.mdのみを置いた場合、その指示(プレフィックス付与)がそのまま出力に反映される
  • CLAUDE.mdとAGENTS.mdの両方がある場合はCLAUDE.md側の指示が優先され、AGENTS.mdの指示は無視される

リリースノートに書かれていた「CLAUDE.mdが無ければAGENTS.mdを使う」という挙動と、手元の検証結果は一致しました。

ハマりどころ

今回の検証範囲では、想定外のエラーや失敗は起きませんでした。ただし、検証したのはあくまで「単一のAGENTS.mdをプロジェクト直下に置いた場合の、単純なプレフィックス指示」というシンプルなケースのみです。以下は今回確認できていない、実務では気になりそうな点です。

  • サブディレクトリにAGENTS.mdを置いた場合の扱いや、複数階層にまたがる優先順位
  • AGENTS.mdとCLAUDE.mdを部分的にマージするような挙動があるか(今回の結果を見る限り、マージではなくCLAUDE.mdが丸ごと優先されるように見えます)
  • 既存のCursorやCodex向けに書かれたAGENTS.mdをそのまま流用したときの互換性(記法や想定する読み手が異なる可能性)

これらは今回の検証では確認していないため、断定はできません。導入前に自分のプロジェクト構成で試すことをお勧めします。

EC-CUBEやWebアプリにどう組み込むか

EC-CUBEのプラグイン開発・保守やEC構築の現場では、複数のAIコーディングツールを開発者ごとに使い分けているケースが増えてきています。今回の検証結果を踏まえると、以下のような組み込み方が考えられます。

  • 指示ファイルの一本化: すでにCursorなどのためにAGENTS.mdを用意しているプロジェクトなら、Claude Code用に別途CLAUDE.mdを作らなくても、コーディング規約・DB接続時の注意・テスト実行コマンドといった基本的なプロジェクト情報をAGENTS.mdに集約できる可能性があります。EC-CUBEのプラグイン開発では「本体のバージョンごとの差異」「決済プラグインとの依存関係」など、AIに毎回説明するのが面倒な前提知識が多いので、一本化できればメンテナンスの手間が減ります。
  • Claude Code固有の指示はCLAUDE.mdに残す: 検証の通りCLAUDE.mdがある場合はそちらが優先されます。ツール共通の内容はAGENTS.md、Claude Code特有の運用ルール(たとえば「本番DBに接続するコマンドは実行しない」といった安全策)はCLAUDE.mdに書く、という役割分担が現実的だと思われます。
  • 運用上の注意: AGENTS.mdは他ツールとの共有ファイルになる分、機密性の高い情報(APIキーや本番環境の接続情報など)を書き込まないよう、レビュー体制を分けて管理する必要があります。指示ファイルの記述だけで安全性を担保するのではなく、実行権限やアクセス制御と組み合わせて運用するのが前提になります。
  • 移行時の見直し: すでにCLAUDE.mdとAGENTS.mdを両方運用しているプロジェクトがあれば、内容が重複・矛盾していないかを一度棚卸しするタイミングだと思います。今回の検証ではCLAUDE.mdが優先されるため、AGENTS.md側にだけ書いた指示が意図せず無視される可能性があります。

まとめ

Claude Code v2.1.277のAGENTS.md対応を、実際にコマンドを実行して確認しました。手元の検証では、AGENTS.md単体の指示は反映され、CLAUDE.mdと併存する場合はCLAUDE.mdが優先されることが分かりました。複数のAIコーディングツールを併用する開発チームにとっては指示ファイルを一本化できる可能性がある一方、優先順位やサブディレクトリでの挙動など未検証の部分も残っているため、導入時は自分たちのプロジェクト構成で一度試すことをお勧めします。

筆者について

株式会社エム・エー・ディー 取締役の村田です。エンジニア歴24年、ECを中心に開発してきました。
現在はEC構築の知見とAI駆動開発を組み合わせたDX支援に取り組んでいます。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?