Claude Code 2.1.277: AGENTS.md サポートとテレメトリ制限の問題と回避策

Claude Code 2.1.277 で AGENTS.md のサポートが発表されました。CLAUDE.md が存在しないプロジェクトでは AGENTS.md が代わりに読み込まれる予定でしたが、テレメトリをオフにしているシェル環境ではファイルが一切読み込まれませんでした。

本稿では、原因となる環境変数の挙動、計測結果、回避策、および改善要望について整理します。

1. ゲート（ブロック）の仕組み

ローダーは

agents-md

• isOnByDefault

  (W): デフォルトで

  false

  です。

• isAvailable

  (B): リモート機能フラグ

  tengu_agents_md_mod

  を照会します（デフォルト

  false

  ）。

var W = !1; // isOnByDefault = false
var B = () => Oa("tengu_agents_md_mod", W); // 遠隔フラグをチェック

• 問題点:
  • Claude Code がリモートフラグ (

    isAvailable

    ) を取得できない場合、プラグインは無効化されます。
  • プラグインが無効化されると、ローカル上のファイルは一切読み込まれません。
  • マークダウンファイルの読み込みにはネットワーク通信は不要ですが、サーバーサイドのスイッチに依存してしまいます。

2. テスト環境と手順

AGENTS.md のみを含む空のディレクトリを作成し、「カナリー」という単語を記述してテストを行いました。

• 手順:

  1. AGENTS.md

     に「PERIWINKLE」という単語を記述する。

  2. claude -p

     コマンドでモデルがその単語を確認できるか検証する。

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."

• 結果: 初回セッションではフラグ取得のみ、2 回目に実際の機能を使用されます。

3. 計測結果と環境変数の影響

テレメトリをオフにする設定が AGENTS.md の読み込みをブロックすることを確認しました。

ブロックされるケース

以下のいずれかの環境変数を設定した状態では、AGENTS.md は決して読み込まれません。両方をクリアする必要があります。

• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

• DISABLE_TELEMETRY=1

有効化できないケース

ブロックを解除する以下の試みも失敗しました（機能は維持されたまま）。

• 環境変数を

  0

  にしても効果なし。
  • ドキュメントには「いずれの値でも有効」と記載されていますが、機能をオンにする際にこれを見過ごしやすいです。
• プロジェクト内の

  .claude/settings.json

  で環境変数ブロッカーをクリアしても効果なし。
  • 単一のリポジトリに対してのみこの機能をオンにする手段はありません。

有効な回避策：セッションレベルのオーバーライド

二回目のセッション以降、セッション引数で両方の設定をクリアすることで正常に機能します。

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

警告メッセージの問題

• 警告は表示されません。
  • セッションは開始し、モデルは指示を無視して回答します。
  • ファイルがスキップされたことは示されず、ユーザーに何も教えてくれません。
• サードパーティ製ゲートウェイ (Bedrock, Vertex など) でも同様の問題が発生しており、フラグがそこで

  true

  に解決されないためです。

4. 回避策

CLAUDE.md は

@path

echo '@AGENTS.md' > CLAUDE.md

• 効果: テレメトリをオフ (

  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

  ) のままも「カナリー」という単語を取得できます。
• 代償: 各リポジトリに追加ファイル (CLAUDE.md) を作成する必要が発生します（これは AGENTS.md サポート導入で排除されるべきものです）。

5. なぜこの対応は受け入れられないか

意図的にテレメトリをオフにしたにもかかわらず、静かにローカルファイルの読み取り機能が犠牲にされています。

• 問題の本質:
  • サーバー通信機能であれば遠隔フラグの使用は理解できます。
  • しかし、入力データは既に作業ディレクトリ内に存在しているため、ネットワーク不要です。
• 影響範囲:
  • 診断情報を失うものの他何もないという期待が裏切られています。
  • Bedrock や Vertex を使用するチームや、慎重な情報選別を行うエージェント管理者にも影響します。
  • 彼らは「利用可能」と発表された機能を、実質的に受け取っていません。
• 静かな不具合:
  • カナリーテストやバイナリ検索など高度な調査を行わないユーザーは、モデルが指示を無視していると考えてしまいます。
  • プロンプト作成に時間を費やすことになりますが、原因は明確になりません。

改善の必要性

プライバシー設定において、無関係なローカル動作を静かにオフにするのは適切ではありません。 段階的な展開が必要な場合でも、以下のように目に見えるメッセージを表示すべきです。

1. AGENTS.md が存在してスキップされた場合、起動時に警告を表示する。
2. 何らがスキップされたか、その理由を示す。

6. 今後の要望と改善提案

以下の機能を追加または修正することを推奨します。

① ローカルファイルの読み込みはテレメトリに依存すべきではない

• 段階的な展開のためにゲートを維持する必要がある場合でも、AGENTS.md がスキップされた際に起動時に警告を表示すべきです。
  • これにより、開発者がカナリーテストなどに時間を費やす必要がなくなります。

② グローバルな AGENTS.md のサポート

• 現状のプラグインは

  プロジェクトディレクトリ/AGENTS.md

  と

  .claude/AGENTS.md

  のみを検索しています。
• ユーザーレベルのファイル（例：

  ~/.codex/AGENTS.md

  やユーザーの CLAUDE.md に隣接するもの）が認識されていません。
  • Codex は

    ~/.codex/AGENTS.md

    を読み込み、

    /import

    コマンドでコピー可能ですが、後の編集には追従しません。
• 複数エージェント向けの指示セットを個人レベルで維持する場合、共有ファイルを指す

  @import

  がユーザーの CLAUDE.md に必要な現状です。

③ 共有エージェントスキルに対するネイティブサポート

• Codex は

  .agents/skills

  を直接読み込みますが、Claude Code 2.1.280 では

  /import

  コマンド内でのみ認識され、スキルは

  .claude/skills

  にコピーされます。
  • ソースからずれるため、シンボリックリンク (

    .. /.agents/skills

    ) で補う必要があります。
• ナティブなサポートがあれば、ソースとの同期管理が容易になります。

現在の暫定対応策

• 指示: 一行の

  CLAUDE.md

  を使用（

  @AGENTS.md

  ）。
• スキル: シンボリックリンクを使用。