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)の並行運用・事故の検知と復旧・サブエージェントの沈黙の失敗対策など、主題別の手引きを公開しています。気になる人は著者の本の一覧から、価格と評価を見て選べます。