Claude Code reads AGENTS.md only when telemetryに見るtool use設計

description: Claude Codeがtelemetry有効時のみAGENTS.mdを読み込む挙動を起点に、AIエージェントのtool use設計・権限制御・ログ設計の実装論点を整理します。

meta description: Claude CodeのAGENTS.md読み込み条件とtelemetryの関係を技術的に解説。tool use設計・権限制御・fallback設計の実装判断に使える情報をまとめています。

何が出たのか

2026年9月前後のHacker NewsおよびRedditのr/ClaudeAIスレッドで、Claude Codeの挙動に関する興味深い報告が複数上がりました。内容を要約すると、Claude CodeはAGENTS.md（エージェントの動作指示を記述するMarkdownファイル）を、telemetry（テレメトリ：動作ログや計測データの収集機能）が有効になっている場合にのみ読み込むという動作が確認された、というものです。

AGENTS.mdはOpenAIのCodexが採用したフォーマットで、リポジトリのルートや特定ディレクトリに置くことでエージェントの振る舞いを宣言的に制御できます。Claude Codeも同フォーマットへの対応を進めており、CLAUDE.mdと並んで設定ファイルとして機能することが期待されていました。

ところが、telemetryをオフにした環境ではAGENTS.mdが無視されるという報告が相次ぎ、Anthropicの公式リポジトリのIssueトラッカーにも同様の指摘が登録されています（2026年9月時点）。Anthropic側からの公式コメントはまだ限定的ですが、内部的にAGENTS.mdの読み込みをtelemetryフラグと連動させている実装が存在することは、コードベースの断片的な公開情報からも裏付けられています。

エンジニアにとって直接的な影響は、プライバシー要件やセキュリティポリシーでtelemetryを無効化している環境では、AGENTS.mdによる動作制御が効かない可能性があるという点です。CI/CDパイプラインやオンプレミス環境でClaude Codeを使っている場合は特に注意が必要です。

技術的に面白い点

この挙動が技術的に興味深いのは、ファイル読み込みという低レベルの操作が、テレメトリという観測系の設定に依存しているという設計上の結合（カップリング）が存在する点です。

通常、設定ファイルの読み込みとログ収集は独立したレイヤーで扱われます。しかしClaude Codeの場合、AGENTS.mdの読み込みがtelemetryフラグの状態を前提条件として持っているとすれば、次のような設計意図が考えられます。

1. 観測可能性（Observability）を担保するための意図的な制約

AGENTS.mdにはツール呼び出しの許可リスト、禁止操作、外部APIへのアクセス可否などが記述できます。これらの指示がどのように解釈・実行されたかを追跡できない状態でエージェントを動かすことを、Anthropicが意図的に制限している可能性があります。言い換えると、「観測できないエージェント動作は許可しない」という設計ポリシーの表れとも読めます。

2. tool useの監査ログとの連動

Claude CodeはMCP（Model Context Protocol：モデルとツールを接続するための標準プロトコル）を通じて外部ツールを呼び出します。tool useの呼び出し履歴はtelemetryデータとして記録されますが、telemetryがオフの場合はこの記録が存在しません。AGENTS.mdで定義したツール制限が実際に機能したかどうかを検証する手段がなくなるため、読み込み自体を止めるという判断は、安全側に倒した設計として一定の合理性があります。

3. フラグ管理の実装パターンとしての問題

一方で、この実装は「機能フラグ（feature flag）の依存関係が不透明」という批判も受けています。telemetryフラグはプライバシー設定として扱われることが多く、エンジニアが「ログを切る」という操作をしたときに、まさかエージェントの設定ファイルが無効化されるとは想定しにくいです。副作用が直感に反する形で現れるため、デバッグが難しくなります。

既存の流れとの違い

AGENTS.mdというフォーマット自体はOpenAI Codexが先行して採用しており、GitHub Copilot WorkspaceやDevinなど複数のコーディングエージェントが類似の仕組みを持っています。これらのツールでは、設定ファイルの読み込みはtelemetryとは独立しており、オフライン環境やプライバシーモードでも動作します。

Claude CodeのCLAUDE.mdも同様で、telemetryの状態に関わらず読み込まれます。今回の挙動はAGENTS.mdに固有の問題であり、Claude Code固有の設定ファイル（CLAUDE.md）と、他エージェントとの互換フォーマット（AGENTS.md）で読み込み条件が異なるという非対称性が生じています。

この差分は実装上の重要な判断ポイントになります。

CLAUDE.mdtelemetry依存なし、Claude Code専用、安定して読み込まれる
AGENTS.mdtelemetry有効時のみ読み込まれる可能性あり、他エージェントとの共通フォーマット

マルチエージェント構成やCI環境でClaude CodeとCodexを並列運用しているチームは、AGENTS.mdを共通設定として使いたいというニーズがあります。しかし現状では、Claude Code側でtelemetryを有効にしなければAGENTS.mdが機能しないため、ポータビリティを期待して採用したフォーマットが、環境設定によって無効化されるリスクがあります。

MCP周辺のエコシステムでも、tool useの権限定義をどのファイルに書くかという議論が続いています。AGENTS.mdがその標準的な置き場所になりつつある流れの中で、今回の挙動は設計上の摩擦として認識されています。

エージェント実装で詰まりやすい点

実際にClaude Codeをプロダクトや業務システムに組み込む際に、この挙動が引き起こす具体的な問題を整理します。

telemetryの有効・無効を環境変数で切り替えている場合の挙動差

開発環境ではtelemetryをオンにしていても、本番環境やステージング環境ではオフにしているケースがあります。この場合、開発時にはAGENTS.mdが読み込まれてエージェントが期待通りに動作するのに、本番デプロイ後に動作が変わるという問題が発生します。環境差異によるバグは原因特定が遅れやすく、特にエージェントの動作は非決定的な要素が多いため、再現性の確認も難しくなります。

権限制御の抜け穴リスク

AGENTS.mdにはツール呼び出しの制限を記述できます。たとえば「ファイル削除ツールは呼び出し禁止」といった制約です。telemetryがオフの環境でこのファイルが読み込まれない場合、制約が存在しない状態でエージェントが動作することになります。セキュリティ要件として権限制御をAGENTS.mdに依存している設計は、この挙動によって無効化される可能性があります。

fallback設計の必要性

AGENTS.mdが読み込まれないことを前提に、CLAUDE.mdへの記述を冗長に持つか、システムプロンプト側で権限制御を行うかという判断が必要になります。現時点では、AGENTS.mdに書いた制約はCLAUDE.mdまたはシステムプロンプトにも重複して記述するというfallback設計が現実的な対応です。

ログとデバッグの非対称性

telemetryをオフにした状態でエージェントが意図しない動作をした場合、tool useの呼び出し履歴が残りません。問題の再現と原因特定のために、アプリケーション側で独自のログ機構を持つことが必要です。MCPのサーバーサイドでtool呼び出しをインターセプトしてログを取る実装や、LangSmith・Langfuseなどの外部オブザーバビリティツールとの連携が選択肢になります。

AGENTS.mdの読み込み確認手段の不足

現状、AGENTS.mdが実際に読み込まれたかどうかをClaude Code側から確認する公式な方法が明確ではありません。デバッグ時には、AGENTS.mdに意図的なダミー指示（例：特定のフレーズを応答に含める）を入れて動作確認するという手動検証が有効です。

Spectralの見解

1. 技術的な読み

今回の挙動は、Anthropicがエージェントの観測可能性を機能の前提条件として設計に組み込んでいるという姿勢の表れとして読めます。「ログが取れない状態で高権限の操作をエージェントに許可しない」という考え方は、エンタープライズ向けのリスク管理として理にかなっています。一方で、その制約がtelemetryという別レイヤーの設定に暗黙的に依存している点は、実装の透明性という観点で改善の余地があります。AGENTS.mdとCLAUDE.mdの読み込み条件の非対称性は、今後のアップデートで解消される可能性が高いですが、2026年9月時点では実装上のリスクとして扱うべきです。

2. PoCで確認すべき点

Claude Codeを業務システムやプロダクトに組み込むPoCでは、以下を早期に検証することを推奨します。まず、対象環境のtelemetry設定を確認し、AGENTS.mdが実際に読み込まれているかをダミー指示で検証します。次に、権限制御をAGENTS.mdのみに依存している箇所がないかを洗い出し、CLAUDE.mdまたはシステムプロンプトへの二重記述が必要かを判断します。また、telemetryオフ環境でのtool use履歴の取得方法を確認し、代替ログ基盤の設計が必要かどうかを評価します。

3. 業務・プロダクト実装に移す時のリスク

最も注意すべきリスクは、権限制御の設計がtelemetryの設定に暗黙的に依存してしまうことです。セキュリティ要件として「このツールは呼び出し禁止」という制約をAGENTS.mdに書いた場合、telemetryがオフになった瞬間にその制約が消えます。プロダクション環境では、権限制御はシステムプロンプトかMCPサーバーサイドのガードレールで担保し、AGENTS.mdはあくまで補助的な設定として扱う設計が安全です。意思決定者の視点では、「エージェントに何をさせるか」の制御が環境設定の変更で無効化されるリスクがある、という点を実装前に認識しておくことが重要です。

まとめ

Claude CodeがAGENTS.mdをtelemetry有効時のみ読み込むという挙動は、観測可能性とエージェント動作の結合という設計上の判断を反映しています。この挙動自体の是非はともかく、実装者として押さえておくべき論点は明確です。

AGENTS.mdとCLAUDE.mdで読み込み条件が異なる非対称性がある
telemetryをオフにする環境では権限制御がAGENTS.mdから機能しない可能性がある
fallbackとして、CLAUDE.mdまたはシステムプロンプトへの重複記述が現実的な対応
tool useの監査ログはアプリケーション側またはMCPサーバーサイドで独自に取得する設計が必要

マルチエージェント構成やCI/CD環境でClaude Codeを使う場合は、AGENTS.mdの読み込み状態を環境ごとに明示的に検証するステップをデプロイフローに組み込むことを検討してください。エージェントの動作制御を設定ファイルに依存する設計は便利ですが、その設定ファイルが読み込まれているかどうかを確認する仕組みを持つことが、安定した運用の前提になります。

関連論点として Claude Code as a Daily Driver Claudemd, Skills,: AIエージェント実装の詰まりどころもあわせて読むと、この技術動向の背景を追いやすくなります。

Spectralでは、技術調査からPoC設計、プロダクト実装まで支援しています。実現性の確認や事業活用の相談はサービス詳細とお問い合わせをご覧ください。