Claude CodeのAGENTS.md設定と移行: 4つの読み込みモードとCLAUDE.mdとの違い

Name

Soren Atelier

更新日 2026/9/21

要点: Claude Code v2.1.277(2026 年 9 月 18 日)以降、AGENTS.md があり、パス上のどこにも CLAUDE.md がないリポジトリでは、AGENTS.md から自動的に指示を読み込みます。インストールも、import 行も、シンボリックリンクも不要です。作業ディレクトリまたはその親ディレクトリに CLAUDE.md か CLAUDE.local.md があれば、Claude Code は引き続きそちらを読み、AGENTS.md を無視します。これを変えるには、/config の Project instructions 設定を切り替えます。

確認は 10 秒で済みます。AGENTS.md だけがある repo で新しいセッションを開始し、会話の先頭付近に次の行が出るか見てください。

no CLAUDE.md found; AGENTS.md loaded: /path/to/repo/AGENTS.md

この行が出ない場合、原因は次の 4 つのどれかで、いずれも本記事で扱います。古いバージョンを使っている、親ディレクトリに CLAUDE.md か CLAUDE.local.md が隠れている、アップグレード後の最初のセッションである、あるいはセッションの種類が AGENTS.md をそもそも読めない(Bedrock、Vertex、Foundry、テレメトリ無効)のいずれかです。

以下で 実測 と記した項目は、2026 年 9 月 21 日に macOS 上の Claude Code 2.1.278 で、新規の検証用リポジトリと claude -p を使って確認したものです。それ以外は公式のメモリに関するドキュメント (opens in a new tab)と changelog (opens in a new tab) に基づいています。

何が変わったのか

2.1.277 の changelog エントリは 1 文だけです。

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config (not yet on Bedrock, Vertex or Foundry)

(要約: CLAUDE.md のないプロジェクトでは代わりに AGENTS.md を読む。/config の「Project instructions」で変更できる。Bedrock、Vertex、Foundry ではまだ未対応。)

このリリース以前は、Codex、OpenCode、Cursor などのために AGENTS.md (opens in a new tab) に統一していたチームも、その横に CLAUDE.md を置き続ける必要がありました。中身は複製、@AGENTS.md の import、またはシンボリックリンクのいずれかです。このリリースに関する Hacker News のスレッド (opens in a new tab)(725 ポイント、273 コメント)は、ほとんどがこうした回避策のどれを維持してきたかを語る内容です。

このリリースで AGENTS.md が CLAUDE.md と同等になったわけではありません。追加されたのは、切り替えスイッチ付きのフォールバックです。本ガイドの残りは、そのフォールバックがどこで止まり、スイッチがどこで効くかについてです。

どのファイルが優先されるか: 判定テーブル

これはデフォルトの動作、つまりモード claude-md-or-agents-md の場合です。「CLAUDE.md が存在する」の判定対象は、作業ディレクトリとそのすべての上位ディレクトリにある CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md です。個人用の ~/.claude/CLAUDE.md、組織の managed CLAUDE.md、.claude/rules/ 配下のファイルは判定に含まれず、AGENTS.md と一緒に読み込まれ続けます。

3 行目が、多くの人が最初にはまる落とし穴です。CLAUDE.local.md は、コミットしない個人用の指示を置く場所としてドキュメントに記載されています。AGENTS.md に依存しているプロジェクトにこれを 1 つ追加するだけで、Claude は何も言わずに AGENTS.md を無視する挙動に戻ります。対処は設定 1 つで済み、次のセクションで扱います。

検証方法

検証用 repo の各 AGENTS.md と CLAUDE.md には、指示を 1 つだけ書きました。すべての返答を [AGENTS_MD_LOADED] のような固定マーカーで始める、というものです。その上で次を実行します。

mkdir agentsmd-test && cd agentsmd-test && git init -q
printf '# AGENTS.md\n\nAlways begin your reply with the exact token [AGENTS_MD_LOADED].\n' > AGENTS.md
claude -p "What is 2+2? Answer in five words or fewer." < /dev/null

返答が [AGENTS_MD_LOADED] で始まればファイルは読み込まれています。素の 4. なら読み込まれていません。/context より粗い方法ですが、/context と /memory は直接読み込まれた AGENTS.md を一覧に出しません(後述の相違点テーブルを参照)。そのため、両方のファイルに使えるのはこのマーカー方式です。

Project instructions の 4 つのモード

セッション内で /config を開いて Project instructions を設定するか、~/.claude/settings.json の組み込み agents-md プラグインの項目に同じ値を書きます。Claude Code はプロジェクト単位およびローカルの設定ファイルではこのキーを無視するため、repo にコミットして共有することはできません。ユーザー単位または managed の設定です。

設定ファイルでの書き方:

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

実測: 両方のファイルがある repo でこの JSON を --settings both.json で渡すと、返答は [CLAUDE_MD_LOADED] [AGENTS_MD_LOADED] の順で始まりました。AGENTS.md だけの repo で "instructionFiles": "claude-md" を渡すと素の 4. が返り、ドキュメント通りファイルは無視されました。

アップグレード直後の最初のセッションで動かない理由

これで検証を 2 回無駄にしました。ドキュメントには、「インストールまたはアップグレード後の最初のセッション」では利用できず、「次のセッション以降」で AGENTS.md を読む、と書かれています。

実測: インストールしたばかりの 2.1.278 と AGENTS.md だけの repo では、1 回目の claude -p はファイルを無視しました。2 回目も同様です。3 回目で読み込まれました。非対話の -p 実行は短時間で終わるため、AGENTS.md 対応を制御する feature flag が 2 回目の開始時点でまだ取得できていなかった可能性があります。実務上のルールはこうです。アップグレード後は使い捨てのセッションを 1 つ開いて閉じ、そのあとで AGENTS.md が読まれているかを判断してください。

ドキュメントによると、AGENTS.md をそもそも読めないセッションは次の通りです。

• Amazon Bedrock、Google Vertex AI、Microsoft Foundry
• テレメトリ無効(feature flag を取得できないため)
• disableAllHooks または allowManagedHooksOnly が設定されている、または /plugin で組み込みの agents-md プラグインが無効化されている
• 上記の通り、インストールまたはアップグレード後の最初のセッション

これらのいずれでも、/config に Project instructions 自体が表示されません。これが最も手早い見分け方です。こうしたセッションでの代替手段は、次のセクションで説明する import です。

直接読み込まれた AGENTS.md と CLAUDE.md の違い

設定経由で読み込まれた AGENTS.md は、CLAUDE.md の完全な代替ではありません。ドキュメントに記載された目に見える違いは 3 つです。

サブディレクトリの AGENTS.md は、Claude が Read ツールでそのディレクトリ内のファイルを開いたときに、そのディレクトリに固有の CLAUDE.md がなければオンデマンドで読み込まれます。AGENTS.md 内の @path import は展開され、claudeMdExcludes のパターンも適用されます。

移行: 既存の回避策をどうするか

2.1.277 より前に AGENTS.md を読ませる仕組みを作っていた場合、構成ごとのドキュメントの指針と、いつ動くべきかについての私の見解は次の通りです。

• @AGENTS.md だけを含む CLAUDE.md: 使用するすべてのセッションが新しい挙動に対応しているなら削除できます。チームの誰かが Bedrock、Vertex、Foundry 経由で作業しているなら残してください。それらではまだ import が必要です。残しておいても二重読み込みにはなりません。
• 散文で「AGENTS.md を読んで」と書いた CLAUDE.md: その文を @AGENTS.md に置き換えるか、ファイルを削除します。散文は Claude がファイルを開くと判断した場合にしか効きませんが、import は確定的です。
• AGENTS.md へのシンボリックリンクにした CLAUDE.md: どちらでも動きますが、Edit ツールと Write ツールはシンボリックリンク越しの書き込みを拒否し、リンク先にリダイレクトします。Windows では、core.symlinks が有効でない限りコミットされたシンボリックリンクは 1 行のテキストファイルとしてチェックアウトされるため、そこでは import を優先してください。
• AGENTS.md を出力する SessionStart フック: 削除してください。Claude が AGENTS.md を直接読むようになると、フックがコンテキストに 2 つ目のコピーを注入します。
• 内容の異なる両ファイル: Claude 固有の部分が別ファイルに値するかを決めます。値するなら、共通ルールは AGENTS.md に、Claude 専用ルールは短い CLAUDE.md に残し、両方が読み込まれるよう claude-md-and-agents-md を設定します。値しないなら、AGENTS.md にマージして CLAUDE.md を削除します。

ドキュメントでは、CLAUDE.md を残さざるを得ない repo 向けに次の共有パターンも提案されています。

@AGENTS.md
 
# Claude-specific
- Use the `Bash` tool for git; do not call the GitHub MCP for pushes.

Claude はまず import を読み、次に Claude 専用の行を読みます。

他のツールが読むもの

AGENTS.md に統一する意味は、1 つのファイルがすべてのエージェントに使えることにあります。各ツールが実際にどう扱うかを、現在のドキュメントからまとめます。

共有ファイルにとっての帰結は 2 つあります。

1. Codex は CLAUDE.md をまったく読みません。 そこにしかない内容は Codex には見えません。同じ repo で Codex と Claude Code を 2 つのファイルで使っていたなら、両方が見るのは AGENTS.md だけです。
2. OpenCode が CLAUDE.md を読むのは AGENTS.md がないときだけで、Claude Code のデフォルトとちょうど鏡写しです。両方のファイルがある repo では、Claude Code は CLAUDE.md を、OpenCode は AGENTS.md を読みます。2 つのファイルの内容が食い違っていると、2 つのエージェントはどちらも何も告げずに別々のルールに従います。

したがって、複数ツールで使う repo の安全な最終形はこうです。共通ルールを書いた AGENTS.md を 1 つ置き、Claude 専用ルールがなければ CLAUDE.md は置かない。あるなら、@AGENTS.md で始まる CLAUDE.md を置く。

状況別のおすすめ構成

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

上から順に確認してください。いずれも上で再現したか、ドキュメントに原因として明記されているものです。

1. claude --version を実行します。 2.1.277 以降が必要です。古ければ claude update で更新してください。
2. すべての親ディレクトリで CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md を探します:

d="$PWD"; while [ "$d" != "/" ]; do for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do [ -f "$d/$f" ] && echo "blocks AGENTS.md: $d/$f"; done; d=$(dirname "$d"); done

~/.claude/CLAUDE.md 以外がヒットしたら、claude-md-and-agents-md に切り替えない限り Claude はそのファイルを読みます。

3. アップグレード直後なら 2 つ目のセッションを開始します。 私の検証では 3 回目の実行で初めて読み込まれました。
4. /config を開き、Project instructions が claude-md や managed-only になっていないことを確認します。設定自体が表示されない場合、そのセッションの種類では AGENTS.md を読めません。@AGENTS.md の import を使ってください。
5. 確認に /memory や /context を頼らないでください。 直接読み込まれた AGENTS.md はそこには表示されません。AGENTS.md loaded の行を探すか、プロジェクト指示を引用するよう Claude に頼んでください。

FAQ

Claude Code はデフォルトで AGENTS.md を読みますか?

はい、v2.1.277 以降は読みます。ただし、作業ディレクトリとそのすべての親ディレクトリに CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md がない場合に限ります。いずれかが存在すれば Claude Code はそちらを読み、Project instructions を claude-md-and-agents-md に設定しない限り AGENTS.md を無視します。

CLAUDE.md と AGENTS.md の両方を読ませることはできますか?

できます。/config で Project instructions を claude-md-and-agents-md に設定するか、~/.claude/settings.json の pluginConfigs → agents-md@builtin → options.instructionFiles に同じ値を書きます。各ディレクトリの CLAUDE.md が先に、次にその AGENTS.md が読み込まれます。CLAUDE.md から import 済みのファイルは二重には読まれません。

Claude Code を更新した直後に AGENTS.md が読み込まれないのはなぜですか?

インストールまたはアップグレード後の最初のセッションでは AGENTS.md を読めず、対応はそれ以降のセッションから始まります。claude -p での検証では、3 回目の実行で初めて読み込まれました。使い捨てのセッションを開始して閉じてから、もう一度確認してください。

すでに AGENTS.md があるなら CLAUDE.md は削除すべきですか?

CLAUDE.md の中身が @AGENTS.md だけで、チームに Bedrock、Vertex、Foundry のユーザーがいなければ削除できます。Claude 固有のルールが書かれているなら残し、1 行目に @AGENTS.md を置いて、どの環境でも両方が読み込まれるようにしてください。

Codex は CLAUDE.md を読みますか?

読みません。Codex は repo ルートから作業ディレクトリまで、ディレクトリごとに AGENTS.override.md または AGENTS.md を読み、さらに ~/.codex/AGENTS.md も読みます。フォールバックのファイル名は config.toml で設定できます。CLAUDE.md にしかない内容は Codex には見えません。

関連ガイド

• Codexの使い方ガイド: 始め方、5つのTips、Best Practicesまで
• OpenCodeの使い方ガイド: 始め方、実践Tips、Oh My OpenCodeとの使い分け
• Claude Code DesktopでBypass permissionsを有効にする方法
• Claude Code Routinesとは？AIエージェントの定期実行と自動化を理解する
• DeepSeek Harness の使い方：インストール、初期設定、最初のエージェント実行まで