Claude Codeはテレメトリがオンの場合のみAGENTS.mdを読み込む

Claude Codeはテレメトリがオンの場合のみAGENTS.mdを読み込む

Claude Code 2.1.277でAGENTS.mdのサポートが発表されました。プロジェクトにCLAUDE.mdがない場合、代わりにAGENTS.mdが読み込まれるはずです。私はシェルでテレメトリをオフにしており、私のリポジトリではこのファイルはロードされませんでした。Issue #95690でその理由が説明されており、私はそれに独自の計測結果を追加しました。この記事ではそれらを一箇所にまとめます。

ゲートはどこにあるか

ローダーはagents-mdという組み込みプラグインとして提供されています。2.1.280バンドルでの登録は以下のようになっています。

var W = !1;
var B = () => Oa("tengu_agents_md_mod", W);
var H =
  "AGENTS.md as project instructions: by default loaded where the project has no CLAUDE.md; ...";

WはプラグインのisOnByDefault値で、falseです。BはisAvailableで、リモートのフィーチャーフラグtengu_agents_md_modを問い合わせており、フォールバック値はfalseです。Claude Codeがフラグを取得できない場合、プラグインは利用できず、ローカルファイルは決して読み込まれません。作業ディレクトリからマークダウンファイルを読み込むのにネットワークは全く必要ありませんが、ここではサーバーサイドのスイッチに依存しています。

テスト方法

カナリアワードを含むAGENTS.mdのみを持つ空のディレクトリを作成し、その単語についてclaude -pに尋ねました。各セットアップは2つのセッションで実行されました。なぜなら、新しい設定での最初のセッションはフラグを取得するだけで、2番目のセッションがそれを使用するからです。

echo 'The canary word is PERIWINKLE.' > AGENTS.md
claude -p 'What is the canary word from the project instructions? Answer NONE if you have none. Do not read files.'

計測結果

• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1は、Issueで述べられているように、機能をブロックします。
• DISABLE_TELEMETRY=1も同様にブロックします。どちらかの変数が設定されていると、AGENTS.mdはロードされなかったため、両方をクリアする必要がありました。
• いずれかの変数を0に設定しても助けにはなりません。ブロックはそのまま残ります。環境変数ドキュメントには、どのような値でもカウントされるとありますが、機能をオンにしようとする際には見落としやすい点です。
• プロジェクトの.claude/settings.jsonにあるenvブロックで両方の変数をクリアしても効果はありません。単一のリポジトリで機能をオンにする方法はありません。
• セッションレベルのオーバーライドは、2番目のセッションから有効になります。

claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'

これらのケースのいずれでも警告は表示されません。セッションは開始され、モデルはプロジェクトの指示なしで応答し、ファイルがスキップされたことを示すものは何もありません。Issueでは、サードパーティのゲートウェイであるBedrockやVertexでも同様の問題が発生していると指摘されています。なぜなら、これらの環境ではフラグがtrueに解決できないからです。

回避策

CLAUDE.mdは@pathインポートをサポートしており、これらはフラグに依存しません。AGENTS.mdの隣に1行のCLAUDE.mdを置くことで、テレメトリオフでもロードできます。

echo '@AGENTS.md' > CLAUDE.md

そのファイルが配置された状態で、同じカナリアテストはCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1が設定されたままでも単語を返します。コストはリポジトリごとに1つの追加ファイルですが、これはAGENTS.mdサポートが削除しようとしていたものです。

なぜこれが容認できないと考えるか

私は意図的にテレメトリをオフにしました。そして、その選択が診断情報の一部を失うだけで、それ以上のコストはかからないと期待していました。ここでは、私のディスクからファイルを読み込む機能が、静かにコストとして失われています。リモートフラグはサーバーと通信する機能には意味があるかもしれませんが、この機能が必要とする唯一の入力は既に作業ディレクトリにあります。

このゲートは、AGENTS.mdを最も気にする人々にも影響します。複数のエージェントに対して1つの指示ファイルを使用する人は、各ツールが何を送信するかについて通常は注意深く、BedrockやVertex、またはゲートウェイ上のチームはポリシーで不要なトラフィックを無効にしていることがよくあります。彼らは皆、利用可能と発表された機能が何も機能しないという状況に直面します。

沈黙が最悪の部分です。カナリアワードとバイナリの文字列検索で原因を確認しましたが、ほとんどの人はそこまでしません。彼らはモデルが指示を無視していると結論付け、ファイルがそもそもモデルに到達していないのに、プロンプトに時間を費やすことになります。

プライバシー設定は、関連性のないローカルの動作を静かにオフにすべきではありません。Anthropicが段階的なロールアウトを望むなら、取得できなかったフラグのフォールバックは、文書化された動作であるべきか、少なくとも何がスキップされ、なぜスキップされたのかを示す可視的なメッセージであるべきです。

見たいこと

• ローカルファイルの読み込みはテレメトリに依存すべきではありません。段階的なロールアウトのためにゲートを残す必要がある場合、AGENTS.mdが存在しスキップされた場合に起動時の警告があれば、私がカナリアテストに費やした時間を節約できるでしょう。
• グローバルなAGENTS.md。プラグインはプロジェクトディレクトリ内のAGENTS.mdと.claude/AGENTS.mdを探しますが、ユーザーのCLAUDE.mdの隣にユーザーレベルのファイルはありません。Codexはプロジェクト内の~/.codex/AGENTS.mdを読み込みますが、Claude Code 2.1.280は/importコマンドでのみこれらのパスを知っており、それはユーザーのCLAUDE.mdにコピーされますが、そのコピーは後続の編集を追跡しません。複数のエージェントに対して1つの個人指示セットを保持する場合でも、共有ファイルを参照するユーザーCLAUDE.mdに@インポートが必要です。
• 共有エージェントスキルのネイティブサポート。Codexはプロジェクト内の.agents/skillsとホームディレクトリ内の~/.agents/skillsからスキルを読み込みます。Claude Code 2.1.280は/importでのみこれらのパスを知っており、それは.claude/skillsにコピーされます。カナリアスキルを.agents/skillsに配置しましたが、Claude Codeはそれをリストしませんでしたが、同じリポジトリ内の.claude/skillsからの同じスキルはリストしました。コピーはソースから乖離するため、代わりに.claude/skillsを../.agents/skillsにリンクしており、Claude Codeはそのシンボリックリンクをたどります。

それまでは、指示には1行のCLAUDE.mdを、スキルにはシンボリックリンクを使用しています。