Claude Code のいちばん多い要望は、意外と知られていない

GitHub の anthropics/claude-code の起票を、反応の数の多い順に並べてみてください。先頭に来るのは、副の作業者の沈黙の停止でも、6月15日の課金分離でもありません。

起票 #6235、累計 5,500 を超える reactions（2026年6月25日に確認した時点で5,518件、なお増加中）。「AGENTS.md に対応してほしい」という機能の要望です。2025年8月21日に立てられて、9ヶ月以上たったいまも公式の対応はなく、コミュニティでは「2位の要望の約4倍で、いちばん求められている機能」と整理されています。単一の起票としては過去最大で、2位の717の7倍以上です。

それなのに、この話を日本語でまとめた記事はほとんど見かけません。本記事では、この痛みの正体と、対応を待つあいだに利用者の側で取れる回避策を、実際に運用したものだけ書きます。

痛みの正体——同じ指示を別々の場所に書き分ける

いま、AI コーディングの道具は1つではありません。Claude Code を主に使いながら、Cursor や Codex を併用する人が増えています。

問題は、それぞれが読む指示書の場所が違うことです。

Claude Code は CLAUDE.md を読む
Cursor は .cursorrules を読む
Codex は AGENTS.md を読む

同じ codebase の規約や制約を、3つの別々の名前で別々の場所に書き分けることになります。1つを更新したら、残りも手で揃える。この同期の手間が、毎週じわじわ積み重なります。

痛みの出方は、使い方で3つに分かれます。

個人で複数の道具を使う。1人で道具を切り替えるたびに、指示書のずれを確認する
チームで作業する。各人の好みの道具が混ざり、同期の責務がチームの管理者に集中する
複数の道具を同時並行で使う。1人で複数の窓を開き、切り替えるたびにずれを確認する

私自身は3番目です。並行で使っていると、1日に何度も道具の窓を行き来します。指示書のずれの確認だけで、ざっくり年に100時間以上が消えていました。

なぜ起きるのか

AGENTS.md は、coding agent が codebase を理解するための共通の Markdown 書類として、業界で収束しつつある標準です（公式は https://agents.md/ ）。

2026年6月の時点で、AGENTS.md の採用は6万を超えるリポジトリに広がり、OpenAI と Anthropic は AGENTS.md と MCP を Linux Foundation 傘下の Agentic AI Foundation へ寄贈しました。主要な道具の対応状況はこうです（2026年6月時点）。

道具	提供元	AGENTS.md の対応
Codex	OpenAI	ネイティブ対応
GitHub Copilot	GitHub	ネイティブ対応
Cursor	Cursor	ネイティブ対応（旧 `.cursorrules` から移行）
Windsurf	Codeium	ルートの `AGENTS.md` が常時有効
Amp	Sourcegraph	ネイティブ対応
Claude Code	Anthropic	未対応（`CLAUDE.md` の独自経路）

主要な道具がこぞって AGENTS.md をそのまま読むようになり、Claude Code だけが独自の経路を続けています。だから、Claude Code を使う人が他の道具と並行すると、指示書の書き分けが発生するわけです。標準が固まるほど、この1つだけの例外が目立ちます。

今すぐできる回避策

公式の対応を待つあいだ、利用者の側で取れる手当てがあります。まず公式の手引きが第一に勧める方法から、手軽な順に並べます。

1. CLAUDE.md に AGENTS.md を取り込む（公式が第一に勧める）

公式の Claude Code の手引きが最初に挙げる方法です。Claude Code は AGENTS.md ではなく CLAUDE.md を読みますが、CLAUDE.md を「AGENTS.md を1行で取り込むだけ」の内容にすれば、実体のファイルを増やさずに済みます。

@AGENTS.md

## Claude Code 固有の追記
（Claude Code だけに効かせたい指示があれば、この下に足す）

セッションの開始時に AGENTS.md を読み込み、その下に書いた追記を後ろに足します。実体のファイルは AGENTS.md の1つだけなので、食い違いが起きません。シンボリックリンクと違って特別な権限が要らず、公式も Windows ではこの取り込みを勧めています（Windows のシンボリックリンクは管理者権限か開発者モードが必要）。すでに AGENTS.md があるリポジトリで /init を実行すると、その中身を読んで CLAUDE.md に取り込んでくれます。

2. シンボリックリンクで参照を共通化する

実体を1つのファイルにして、2つの名前で参照します。

ln -s CLAUDE.md AGENTS.md

最初に約2分かければ、それで済みます。維持の手間はほぼゼロです。ただし Windows と一部の WSL では管理者権限か開発者モードが要り、clone の経路によってはリンクが実体のコピーに化けることがあるので、ちゃんとリンクとして解決できているかは確認してください。Claude Code 固有の追記が要らず、OS の制約がないなら手軽です。

3. コミット前に同期する（pre-commit hook）

git の hook で、コミットのたびに自動で揃えます。2つを別の実体のファイルとして保ちたいときに向きます。チームでシンボリックリンクの周知が難しいときにも使えます。

4. SessionStart hook で整合を確認する

セッションの開始のたびに、CLAUDE.md と AGENTS.md がずれていないかを確認します。私が配布している無料の hook 集（後述）に、この用途の agents-md-sync-checker が入っています。サイズの差が大きいときに警告し、シンボリックリンクを提案します。

5. direnv で環境変数を整える

ディレクトリに入ったときに環境変数を整える direnv を使う方法です。プロジェクトごとに指示書の扱いを変えたいときに向きます。

6. CI で差異を検出して警告する

CI で、指示書がずれていないかを検査して警告します。チームでの運用を補完する、最後の防波堤です。

どれを選ぶか

これから始めるなら、まず公式が勧める 1（取り込み）。実体が1つで食い違いが起きず、Windows でも権限が要りません
Claude Code 固有の追記が要らず、OS の制約もないなら 2（シンボリックリンク） も手軽
チームで使う → 3（pre-commit）+ 6（CI） で、各人の手元と共有の両方を押さえる

私自身は、取り込みが公式に整理される前から 2（シンボリックリンク）と 4（SessionStart hook） の組み合わせで運用してきました。最初の設定に12分ほどかかったきりで、それまで年に100時間以上かけていた確認が、ほぼゼロになりました。いまから始めるなら、まず1の取り込みが最短です。

無料の hook 集

4番目で触れた agents-md-sync-checker を含む、Claude Code の事故防止の hook 集を MIT ライセンスで配布しています。直近14日で約360名が使っています。

どの道が自分の環境で静かに壊れるか

ここまでの回避策は、多くの人にはそのまま効きます。ただ、手軽な道ほど特定の環境で静かに壊れます。

シンボリックリンク（2）は、Windows で静かに壊れます。管理者権限や開発者モードが無いと Git for Windows は既定（core.symlinks=false）でリンクをたどれず、リンク先のパスを1行書いただけの普通のテキストファイルとして clone されます。CLAUDE.md の中身が AGENTS.md という文字列だけになり、Claude Code はそれを指示書として読もうとして、指示が静かに無効化します。エラーは出ないので、チームの Windows の人だけ指示が効いていない、という事故になりがちです（WSL から Windows 側の道具がリンクを解決できない問題も併発します）。この壊れ方の実機での再現（core.symlinks=false で CLAUDE.md が9バイトのテキストになる様子）と、安全な移行の手順は、別記事「AGENTS.mdとCLAUDE.mdをsymlinkで統一したら、Windowsのメンバーだけ指示が消えていた」にまとめました
pre-commit hook（3）は、git clone では複製されないので、チームでは各人に配る別の手当てが要ります
公式が勧める取り込み（1）は制約が一番少ない一方、Claude Code 固有の追記の置き場所を間違えると共有側に漏れます

つまり、どれを選べば壊れないかは、使い方の型（個人で使い分ける／チーム／並行）と環境で変わります。自分の型に最短で効いて、しかも静かに壊れない道はどれか——その判断材料を、別の本にまとめています。

5つの道それぞれが、どの型・どの環境で壊れるかの一覧
3つの下位の問題（提供元の固定、.agents/skills/ の生態系、文書と実機の挙動の差）
Anthropic の公式の対応の追跡と、6月15日の課金分離との関係
CLAUDE.md から AGENTS.md への安全な移行の手順（巻き戻しの道つき）
回避策それぞれの、すぐ使えるテンプレート集

AGENTS.md と Claude Code の interop 運用の手引き（¥1,500、はじめにと第1章・第2章は無料で試し読みできます）

複数の道具を併用していて、指示書の書き分けに毎週時間を取られているなら、まずは本記事の回避策のどれかを今日試してみてください。公式が勧める取り込みなら、CLAUDE.md に1行 @AGENTS.md と書くだけで始められます。

Claude Code は毎月のように仕様が変わり、費用の膨らみ方も事故の新種も毎月出ます。「先月から何が変わったか・今すぐ直すべき設定や貼るべき hook はどれか」を毎月15日ごろ短く受け取りたい人には、Claude Code 事故まとめ(無料・月次)もあります（本は腰を据えて読む手引き、便りは毎月の鮮度で走らせる運用の線、という住み分けです）。

800時間の Claude Code 運用データから、トークン消費の削減・複数ベンダー(Claude / Codex / Gemini / Copilot)の並行運用・事故の検知と復旧・サブエージェントの沈黙の失敗対策など、主題別の手引きを公開しています。気になる人は著者の本の一覧から、価格と評価を見て選べます。