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 と書くだけで始められます。