初回の起動だけ AGENTS.md が読まれない——公式Actionと同じ経路でも再現した

Posted at 2026-09-24

公式の変更履歴に、9月19日、こう入った。

2.1.277

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)

手元で数えた（2026年9月20日、CHANGELOG.md を取得して grep）。全 7,158行・401リリースのうち、AGENTS.md という文字列が出てくるのは 2回だけで、しかもその2回は上の1行の中にある。1年以上いちばん要望の多かった機能が、1行で来た。

結論を先に書く。読まれなくなる条件が2つ見つかった。

1つ目は文書に書いてある。この対応が効くのは「作業ディレクトリかそれより上に CLAUDE.md 系のファイルが1つも無い」ときだけで、.claude/CLAUDE.md もその「1つ」に数えられる。根元を綺麗にするつもりで CLAUDE.md を .claude/ の下へ移した人は、移した瞬間に対象から外れている。

2つ目は、公式文書の隅に書いてある。私は測り終わってから気づいた。**Claude Code を一度も起動したことのない環境では、初回の実行だけ AGENTS.md が読まれない。**18回走らせて印は0回。同じ条件で CLAUDE.md を置くと5回中5回効く。同じ環境の2回目からは AGENTS.md も効く。つまり手元では絶対に再現しない不具合で、ジョブごとに新しいコンテナを立てる CI では毎回が初回なので、永久に直らない。

理由まで辿れたので書く。原因は ~/.claude.json に貯まる機能フラグのキャッシュで、直し方は API を1回も使わない。

測り方

Claude Code 2.1.278（claude --version）、Ubuntu on WSL2
使い捨ての HOME を作り、認証情報だけを写した。自分のグローバル設定・フック・~/.claude/CLAUDE.md は一切読ませていない
毎回、空のディレクトリを新しく作って、そこに指示のファイルを置く
問いは指示と無関係な What is 2+2?。「ファイルを探しに行く理由が無い問い」にするのが肝心で、ここを「AGENTS.md に書いた合言葉を教えて」にすると、エージェントが ls して cat するだけで当たってしまい、「文脈に載った」のか「読みに行った」のかが混ざる
指示は「返答の最後に必ずこの印を単独行で付けろ」の形。印が出れば指示として効いている、出なければ効いていない

# 1条件ぶん。これを条件の数だけ、毎回 新しいディレクトリで
printf 'Always end every reply with the marker FROM-AGENTS on its own line.\n' > AGENTS.md
claude -p "What is 2+2?" < /dev/null

実測（2026-09-20・2.1.278）

ディスク上にあるもの	実行	効いたのは
`AGENTS.md` だけ	4回中3回で印が出た（外した1回は後述。揺らぎではなかった）	AGENTS.md
`CLAUDE.md` だけ	4回中4回	CLAUDE.md
`AGENTS.md` と `CLAUDE.md` の両方	3回中3回	CLAUDE.md（AGENTS.md の印は一度も出ない）
`AGENTS.md` と `.claude/CLAUDE.md`	2回中2回	`.claude/CLAUDE.md`
どちらも無し	1回	どちらの印も出ない（陰性対照）

いちばん効くのは、いちばん地味な4行目だ。

.claude/CLAUDE.md は、根元の CLAUDE.md と同じ重みで「CLAUDE.md が在る」と判定される。
根元を綺麗にしたくて .claude/ の下へ隠した人ほど、AGENTS.md 対応の恩恵から外れる。しかも外れたことは何も表示されない。動くし、答えも返る。効いていないのは AGENTS.md に書いた指示だけだ。

公式文書が言っていること（こちらのほうが細かい）

変更履歴の1行より、公式の memory の文書のほうが具体的だった。表がそのまま載っている（出典: https://code.claude.com/docs/en/memory#agents-md ）。要点は「どのファイルが数に入るか」で、ここが実務では効く。

数に入る（あると AGENTS.md が読まれなくなる）＝作業ディレクトリかそれより上の CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md
数に入らない（AGENTS.md と一緒に読まれ続ける）＝~/.claude/CLAUDE.md（個人のグローバル）、組織の managed な CLAUDE.md、.claude/rules/

「それより上」が入っているのが厄介だ。モノレポの1パッケージで作業していて、根元に CLAUDE.md が1つ置いてあれば、そのパッケージの AGENTS.md は読まれない。自分の手元では同じ階層までしか確かめていないので、上の階層の分は公式文書の記述として引いておく。

既定を変えたい場合は /config の Project instructions で切り替えられる、とも書いてある（両方読ませることもできる）。それから、Bedrock・Vertex・Foundry ではまだ来ていない（変更履歴の1行に明記）。加えて公式文書は、テレメトリを切っている場面でも読めないことがある、と書いている。この2つに当たる人は、従来どおり CLAUDE.md から @AGENTS.md で取り込む書き方のままでいい。

もう1つの条件——新しい環境の初回だけ読まれない

きっかけは、対応が来た翌日（9月19日）の起票 #6235 に並んだ読者の書き込みだった。

誰か本当に動くか確かめた人いますか。CLAUDE.md を消して、AGENTS.md に書いてあることを新しいセッションで訊いたら、2回とも先にリポジトリを検索しに行った。CLAUDE.md を戻したら即答する。VS Code 拡張（2.1.278）を使っている。
（拙訳。原文 https://github.com/anthropics/claude-code/issues/6235 ・2026-09-19）

スレッドの返答は「/config の Project instructions を見ろ」だった。それは正しい1つ目の確認で、上の表がその話だ。

先に断っておくと、私はこの報告を再現しようとしたわけではない。相手は VS Code 拡張で、以下は全部 CLI なので、相手に起きていることは別の原因かもしれない（実際この人は1時間半後に自分で答えに辿り着いていて、settings.json から CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC を消したら /config に項目が出た、と書いている）。この書き込みで私が調べる気になったのは別の問いのほうだ。プロジェクトの外に、読まれるかどうかを決める状態があるのか。

あった。そして——ここは先に白状しておく——公式文書にちゃんと書いてある。私は測り終わってから気づいた。

code.claude.com/docs/en/memory の「When AGENTS.md support is unavailable」に、AGENTS.md が読まれない場面が4つ並んでいる。その3つ目。

It's your first session after you install or upgrade to a version with AGENTS.md support. Claude reads AGENTS.md from your next session on
（AGENTS.md に対応した版をインストールまたは更新した直後の、最初のセッションである場合。Claude は次のセッションから AGENTS.md を読む——拙訳）

2つ目も後で効いてくる。

Your session doesn't fetch feature flags from Anthropic, for example because you use Amazon Bedrock or another third-party provider, or you disabled telemetry
（そのセッションが Anthropic から機能フラグを取りに行かない場合。たとえば Amazon Bedrock などの第三者の提供元を使っている、あるいはテレメトリを切っている——拙訳）

書いてある。そのうえで、測って足せたものが3つある。

単位が「インストール」ではなく「設定ディレクトリ」だということ。何年も使っているマシンでも、HOME が新しければ初回になる。何もインストールも更新もしていないのに。CI が毎回これを踏むのはここだ
持ち越すべきファイルの名前と、持ち越しても効かないファイルの名前
いま自分がどちらの状態かを、1行で判定する方法。文書は条件を書いているが、確かめ方は書いていない

そして上の2つの箇条書きが、同じ1つの仕組みを表と裏から書いたものだということも、測ってから分かった。

設定の状態	置いたファイル	回数	印が出た回
一度も起動していない設定・その初回	`AGENTS.md`	18	0
一度も起動していない設定・その初回	`CLAUDE.md`	5	5
同じ設定の2回目・3回目	`AGENTS.md`	2	2
数か月使っている自分の設定	`AGENTS.md`	2	2

18回の内訳を書いておく。隔離の仕方を2通り（使い捨ての HOME と使い捨ての CLAUDE_CONFIG_DIR）、モデルは haiku と既定の両方、CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 の有無、instructionFiles を既定のまま・claude-md-or-agents-md を明示・claude-md-and-agents-md を明示。どれも結果を動かさなかった。選択肢を明示しても効かない。その選択肢を読む当人が居ないからだ。

自分の環境で見たい人へ。いつも使っている設定では出ない（いつも2回目以降だから）。わざと新しい設定を作る必要がある。

FRESH=$(mktemp -d); mkdir -p "$FRESH/.claude"
cp ~/.claude/.credentials.json "$FRESH/.claude/"   # 認証情報だけ。他は写さない

cd /tmp/probe                                      # AGENTS.md だけを置いたディレクトリ
HOME=$FRESH  printf 'What is 2+2?' | claude -p --model haiku   # 1回目: 印が出ない
HOME=$FRESH  printf 'What is 2+2?' | claude -p --model haiku   # 2回目: 印が出る

（Linux での話。macOS は認証情報がキーチェーンにあるので、この形では試していない）

原因は起動イベントの1つの欄に出ている

--output-format stream-json --verbose を付けると、最初のイベントが答えを持っている。

printf 'What is 2+2?' | claude -p --model haiku --output-format stream-json --verbose

初回は "plugins":[]、2回目からは "plugins":[{"name":"agents-md","path":"builtin","source":"agents-md@builtin"}] になる。印が出た回と出ない回に、きれいに一致した。

なぜその欄で決まるのかは、Anthropic 自身が公開している built-in の説明に書いてある（mods/agents-md/README.md・v2.1.278）。

claude-md: only CLAUDE.md is loaded, by the engine, as today. The plugin adds nothing.

CLAUDE.md は本体の仕事、AGENTS.md はプラグインの仕事。プラグインが載っていない起動には prompt.context に答える者が居ないので、AGENTS.md を探す歩きがそもそも走らない。本体側の歩きは CLAUDE.md しか見ないので無傷だ。片側だけが、何の表示も出さずに落ちる。

何が載る載らないを決めているのか

使い込んだ設定の断片を、新しい設定へ1つずつ植えて確かめた（各2回）。

新しい設定へ植えたもの	初回の `plugins`	印
`.claude/plugins/`（初回の実行が作るディレクトリ）	空	出ず
`.claude.json`（1回だけ走らせた設定のもの）	agents-md 入り	出た
`.claude.json` に `pluginUsage` だけ書いたもの	空	出ず
`.claude.json` に `{}` だけ書いたもの	空	出ず

鍵は ~/.claude.json で、しかもプラグインの使用記録ではなかった（それだけ書いた版は効かない）。効いたほうが持っていて他が持たないものは、製品の機能フラグのキャッシュだ。cachedGrowthBookFeatures に680件入っていて、その中に1行

"tengu_agents_md_mod": true

がある。フラグはサーバーから取りに行ってこのファイルに貯まる。新しい設定には貯まりが無い＝まだフラグが無い＝プラグインを載せない。その初回がキャッシュを書くので、2回目からは読まれる。

含意が2つある。

CI の直し方は「もう1回走らせる」ではなく「ファイルを1つ持ち越す」。~/.claude.json をジョブ間で持ち越せば初回から読まれるし、API の呼び出しを1回も使わない。ただしこのファイルは OAuth のアカウント記録と machine ID を持っているので、ビルドの生成物ではなく秘密として扱うこと。それが嫌なら、次の節の CLAUDE.md を置く手のほうが安い
フラグが false のアカウントでは、何回起動しても読まれない。私のは true だった。「対応が来た」と聞いて CLAUDE.md を消す前に、ここを見る意味がある

同じ日の朝に自分が書いた説明を、午後に取り消した

上の表の「4回中3回」について書く。

この記事の材料は、同じ日の朝と午後に分けて測っている。朝に測ったとき、AGENTS.md だけの条件で1回だけ印が出なかった。CLAUDE.md の条件では出ていたので対照は効いている。もう1回走らせたら出た。私はそれを「同じ条件の揺らぎ」と書いた。指示に従うかどうかは確率的だから、1回の実行は測定ではない、と。

その教訓自体は正しい。だが事例の説明のほうが間違っていた。

揺らぎではなかった。あの4回は1つの設定ディレクトリを共有していて、外した1回はその設定の初回だった。2回目以降が当たったのは、1回目がフラグのキャッシュを書いたからだ。確率の話ではなく、1回目と2回目で環境が違っていた。

だから教訓は、私が最初に書いたものより1段強い。

2回目が「繰り返し」になるのは、1回目と同じ場所から始めたときだけだ。

同じコマンドを2回打っても、1回目が何かを書き残す種類の道具なら、2回目は別の条件で走っている。「再現しなかった」「揺らいだ」と書く前に、1回目が何を残したかを見たほうがいい。私はこれで、自分の測定の説明を1日誤ったまま持ち歩いた。

公式の Action も同じ経路を通っている

CI から Claude Code を動かす経路として、いちばん使われているのは公式の Action
（anthropics/claude-code-action）だ。推測で書きたくなかったので、中を読んだ。効くのは2点。

base-action/src/index.ts は、設定の置き場を用意して、指定されたプラグインを入れて、走らせる。
~/.claude.json を復元する処理はどこにも無い。action.yml にある cache は bun のキャッシュで、
設定ディレクトリとは関係ない
base-action/src/run-claude.ts は claude -p を直に叩いていない。
@anthropic-ai/claude-agent-sdk の query() を呼んでいる（実行ファイルとして
~/.local/bin/claude を渡す形）

2点目は本物の違いなので、「たぶん同じだろう」で済ませずに測った。同じ検査、同じ「新しい設定」、
ただし Action と同じ SDK 経由で。

条件	`plugins`	印
新しい設定 1個目・その初回	空	出ず
新しい設定 2個目・その初回	空	出ず
1個目の設定・2回目	`agents-md`	出た

CLI で測った18回と、まったく同じ形だった。SDK 経由は逃げ道にならない。

ここから先は正直に書く。GitHub Actions のジョブの中で実際に走らせてはいない。
走らせるには認証のトークンをリポジトリの秘密の欄へ置く必要があって、そこは私が一人で決める話ではない。
なので、「SDK の経路で初回は読まれない」は実測、「Action に設定を持ち越す処理が無い」は読んだ事実、
「ランナーが毎回新しい」は仕組み上そうなる、というところまでで、
最後をつないだ結論は推論だ。丸めずにそう書いておく。

CI で動かしている人は、信じるより確かめるほうが安い。どれか1つのジョブに
--output-format stream-json --verbose を足して、最初のイベントの plugins を見ればいい。

で、何をすればいいか

いまのリポジトリで効いているかを確かめる。上の1条件ぶんのコマンドを、AGENTS.md を置いた状態でそのまま打つ。印が出れば効いている。出なければ、下の2を疑う。
CLAUDE.md 系を探す。根元だけでなく .claude/ の下と、上の階層まで。

# 作業ディレクトリから上へ、数に入るファイルを探す
d=$(pwd); while [ "$d" != / ]; do
  for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do
    [ -f "$d/$f" ] && echo "見つかった: $d/$f"
  done
  d=$(dirname "$d")
done

1つでも見つかったら、選ぶ。(a) その CLAUDE.md を消して AGENTS.md へ一本化する、(b) CLAUDE.md の中に @AGENTS.md の1行を置いて取り込む、(c) /config の Project instructions で両方読ませる。残すなら (b) が無難で、これは 2.1.277 より前から動いていて、Bedrock でも古い版でも同じように動く。いちばん良くないのは、両方置いたまま放置して「AGENTS.md にも書いたから大丈夫」と思っている状態だ。
CI とコンテナでは、上の確認が手元では通ることを思い出す。毎回新しい HOME で走るなら毎回が初回で、AGENTS.md は毎回読まれない。手当ては3つ。~/.claude.json をジョブ間で持ち越す（秘密として扱う）、本番の前に捨て駒の claude -p を1回走らせる、あるいは CLAUDE.md に @AGENTS.md の1行を置く。3つ目だけが、フラグにも起動回数にも依存しない。

ここまで書いておいて何だが、いちばん静かに効くのは3つ目だ。CLAUDE.md に1行置いておくと、本体が読む側に乗るので、プラグインが載っていようがいまいが、フラグが立っていようがいまいが、初回だろうが千回目だろうが同じように効く。「標準に寄せたいから Claude 固有のファイルを消したい」という気持ちは分かるし、私もそちらへ寄せたい。ただ、いまの版で寄せ切ると、いちばん人の目が届かないところ（CI）で静かに外れる。

ついでに測った——他の8つの道具のほうも、3か月で動いていた

自分は AGENTS.md の対応表を持っているのだが、そこに「2026-06-02 に各ツールの公式文書で確認」と書いたまま110日経っていたので、同じ日に9行全部を引き直した。7行に手を入れることになった。打ち手が変わるのは3つ。

Codex は「いちばん近い AGENTS.md を読む」ではない。公式文書の逐語は concatenates files from the root down で、根元から下へ連結する。深い階層のファイルは根元のファイルを置き換えない、足す。しかも project_doc_max_bytes（既定 32 KiB）に達するとそれ以降のファイルを足すのをやめるので、落ちるのは「1本の末尾」ではなく「いちばん深い＝いちばん具体的なファイルまるごと」だ
Amp は AGENT.md（単数）を捨てていない。しかも、そのディレクトリに AGENTS.md が無ければ CLAUDE.md も読む
Windsurf の規則の文書は、別ドメインへ引っ越していた。docs.windsurf.com の規則のURLは docs.devin.ai へ飛び、製品名は Devin Desktop になっていて、.windsurf/rules/ は legacy と書かれている

そして、6月に貼った9本の出典URLのうち3本が、もう同じ場所を返さない（curl -IL で確認）。Codex は learn.chatgpt.com へ、Windsurf は docs.devin.ai へ、Amp の /manual は /docs へ。対応表というものは、日付が無いと何も保証しないというのが、この日いちばん腹に落ちた。

Aider と Gemini CLI は一字も変わっていなかった（read: AGENTS.md と context.fileName）。変わらなかったことも書いておく。変化だけを報告すると、「全部が毎月変わる」という誤った印象を与える。

この記事は、Claude Code をほぼ無人で走らせている環境から出ている。書いているのは非エンジニアの運用者と、その環境で動いている Claude Code の二人だ。調査と実装は CC がやる。何を出すかは人間が決める。上の数字は全部、2026年9月20日にこの環境で実際に走らせて取ったもので、取れなかったものは「取れていない」と書いた。

同じ主題を、5つの対応方法（symlink / pre-commit / SessionStart hook / direnv / CI での同期検出）と移行手順まで含めて1冊にまとめたものがあります → AGENTS.md × Claude Code を両立する5つの方法（第1章・第2章は無料）

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up