クロードコードは、テレメトリがオンのときのみAGENTS.mdを読み取ります

概要

Claude Code 2.1.277以降、 AGENTS.md 対応が追加されたが、 CLAUDE.mdが無い場合のみ 読み込まれる仕様。 テレメトリ無効設定 ではAGENTS.mdが読み込まれず、警告も表示されない問題が存在。 環境変数 や session-level override による挙動の違いを検証。 ワークアラウンド としてCLAUDE.mdからAGENTS.mdをimportする方法が有効。 改善要望 として、ローカルファイルの読み込み仕様や警告表示の追加を提案。

Claude Code AGENTS.md プラグインの挙動と問題点

• Claude Code 2.1.277 で AGENTS.md サポート開始
• CLAUDE.md がプロジェクトに存在しない場合のみ AGENTS.md を自動で読み込む設計
• プラグイン名 は agents-md、2.1.280バンドルで確認
• isOnByDefault （W）はデフォルトで false
• isAvailable （B）はリモートのfeature flag（tengu_agents_md_mod）を参照、取得失敗時は false でプラグイン無効
• ローカルファイル読み込みにもネットワーク判定が必要 なため、サーバー側スイッチに依存

テスト方法と検証結果

• 空ディレクトリ に AGENTS.md を設置し、canary word（例：PERIWINKLE）で挙動を検証
• 2セッション で検証（1回目でflag取得、2回目で利用）
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 で機能ブロック
• DISABLE_TELEMETRY=1 でも同様にAGENTS.mdが読み込まれない
• どちらか一方でも有効 なら機能停止、両方クリアする必要あり
• 0をセット してもブロックは解除されず、環境変数の仕様上 任意の値で無効化
• .claude/settings.json で環境変数クリアしても効果なし、 リポジトリ単位での解除不可
• セッション単位のオーバーライド （--settingsでenvを空文字に）で2回目以降のみ有効
• 警告メッセージなし、ファイル未読でも通知されず、ユーザーは理由を把握しづらい
• BedrockやVertexなどのサードパーティゲートウェイ でも同様にflag解決不可で機能しない

ワークアラウンドと制限

• CLAUDE.mdの@pathインポート はflagに依存せず利用可能
  • 例: @AGENTS.md をCLAUDE.mdに1行追加で回避
• AGENTS.mdサポートの本来の意義 （ファイル数削減）が失われる

問題点の指摘

• 意図的にテレメトリを無効化 しているユーザーに対し、 ローカルファイル読み込み機能も黙って停止
• サーバー通信不要な機能 にもリモートflag必須は不合理
• AGENTS.mdを活用したいユーザー層 ほど、非通知で機能停止することで混乱を招く
• 警告や説明なし で機能が働かないため、ユーザーが原因特定に時間を浪費
• プライバシー設定がローカル挙動まで制限する設計 は不適切

改善要望

• ローカルファイル読み込み は テレメトリ設定に依存しない仕様 に変更希望
• 段階的ロールアウト が必要なら、 flag取得不可時は明示的な警告 や ドキュメント通りの挙動 に
• グローバルAGENTS.md対応
  • プロジェクト直下以外にも、ユーザーディレクトリや共通パスのサポート希望
  • Codexのように ~/.codex/AGENTS.md 参照や /import コマンドで同期可能が理想
• 共有エージェントスキルのネイティブ対応
  • Codexは .agents/skills や ~/.agents/skills を参照
  • Claude Code 2.1.280は /import のみ対応、 .claude/skills へのコピーが必要
  • シンボリックリンクで回避可能だが、 公式サポートを希望

暫定運用方法

• プロジェクトごとに1行のCLAUDE.md でAGENTS.mdをimport
• スキル共有 には .claude/skills を .agents/skills へシンボリックリンク

---

このまとめは、AGENTS.md機能の現状と課題、そしてユーザー視点での改善要望を整理したものです。