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

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

起票 #6235、累計 5,200 を超える reactions。「AGENTS.md に対応してほしい」という機能の要望です。2025年8月21日に立てられて、9ヶ月以上たったいまも未対応のまま続いています。単一の起票としては過去最大で、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/ ）。

主要な道具の対応状況はこうです。

道具	提供元	AGENTS.md の対応
Codex	OpenAI	読み込み対応済
Amp	Sourcegraph	読み込み対応済
Cursor	Cursor	`.cursorrules` と並行で対応
Aider	open-source	対応の議論中
Claude Code	Anthropic	未対応（`CLAUDE.md` の独自経路）

4つ以上が対応済みか対応中で、Claude Code だけが独自の経路を続けています。だから、Claude Code を使う人が他の道具と並行すると、指示書の書き分けが発生するわけです。

今すぐできる回避策

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

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日で1,580名以上が使っています。

さらに深く知りたい人へ

本記事は、5,200 を超える reactions の痛みと、すぐ使える回避策の概要です。

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

これらは、別の本にまとめています。

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

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