AGENTS.md と CLAUDE.md を1つにまとめたい、という需要は大きいです。GitHub の Claude Code への最大の要望の1つ（#6235、5,200 を超える reactions）も、ここにあります。
手軽な定番が symlink です。CLAUDE.md を AGENTS.md へのシンボリックリンクにすれば、1つのファイルを両方の道具が読みます。多くの解説がこれを勧めています。
でも、チームに Windows の人がいると、その人だけ指示が静かに消えます。エラーは1つも出ません。気づくのは、AI が「守ります」と書いたルールを破り始めてからです。
何が起きるか（手元で再現できます）
元のリポジトリでは、CLAUDE.md は symlink です。git ls-files --stage で mode が 120000 と出ます。
$ git ls-files --stage
100644 c0a9443... 0 AGENTS.md
120000 47dc3e3... 0 CLAUDE.md
これを、Windows の既定の設定（core.symlinks=false）で clone してみます。
$ git -c core.symlinks=false clone <repo> cloned
すると、clone した側の CLAUDE.md は symlink になりません。中身を見ると、こうなっています。
$ cat cloned/CLAUDE.md
AGENTS.md
$ wc -c cloned/CLAUDE.md
9
CLAUDE.md の中身が AGENTS.md という9バイトの文字列だけ。本来の指示（# プロジェクトの指示 から始まる全文）は1文字も入っていません。
Claude Code は、この9バイトのファイルを指示書として読みます。つまり、指示が丸ごと消えた状態で動きます。それでも CLAUDE.md は存在するので、読み込みには成功し、警告も出ません。
なぜこうなるか
Git は symlink を「リンク先のパスを中身とするファイル」として保存します。checkout のときに本物の symlink を作り直すかどうかは、core.symlinks の設定で決まります。
Git for Windows の既定では、管理者権限か開発者モードが無いと symlink を作れないため、core.symlinks が false になります。すると Git は、リンク先のパスを書いただけの普通のテキストファイルとして checkout します。CLAUDE.md の中身が AGENTS.md になるのは、これが理由です。
同じリポジトリを core.symlinks=true で clone した側は、ちゃんと symbolic link になり、中身も正しく読めます。違いはこの設定1つだけです。
自分の環境で確認する方法
clone した後、CLAUDE.md の中身とサイズを見るだけです。
file CLAUDE.md # "ASCII text" ならテキスト化しています
cat CLAUDE.md # 中身が "AGENTS.md" だけなら壊れています
wc -c CLAUDE.md # 数バイトしかないなら壊れています
正常なら、CLAUDE.md の中身は本来の指示の全文です。チームで symlink を使っているなら、Windows のメンバーに一度この3行を走らせてもらうのが、一番早い切り分けです。
どうすればいいか
公式が勧めるのは、symlink ではなく取り込みです。CLAUDE.md の冒頭に1行、
@AGENTS.md
と書くだけ。CLAUDE.md は実体のあるファイルなので、Windows でもテキスト化しません。Claude Code はこの CLAUDE.md を読み、@AGENTS.md の行で AGENTS.md の中身を取り込みます。Claude Code 固有の指示は、その下に足せます。
どうしても symlink を続けたいなら、チーム全員が git config core.symlinks true を設定し、Windows のメンバーは OS の開発者モードを有効にする必要があります。1人でも漏れると、その人だけ静かに壊れます。だからこそ、公式は Windows では取り込みを勧めています。
他の回避策にも、それぞれの壊れ方がある
symlink のこの罠は、両立の5つの道のうちの1つです。pre-commit hook で同期する道は、git clone では複製されないので各人への配布が別に要ります。CI で同期する道は手元には効きません。公式の取り込みは一番制約が少ない一方、Claude Code 固有の追記の置き場所を間違えると共有側に漏れます。
消えるのが「安全の指示」だったとき——手間が事故に変わる
ここまでは「指示が静かに消える」を、不便さの問題として書いてきました。けれど、この罠の本当に怖いところは、消えるのがどの指示かを選べないことです。
CLAUDE.md には、書式の好みだけでなく、安全の歯止めも書きます。「本番のデータベースには触らない」「確認なしに削除しない」「main に直接 push しない」——こうした一行が、symlink の罠で Windows のメンバーだけ静かに消えていたら、どうなるか。そのメンバーの環境では、あなたがチームのために決めた歯止めが、その作業のあいだ存在しないのと同じになります。
しかも、何も警告は出ません。エージェントは「歯止めに引っかかって止まった」のではなく、「歯止めが読み込まれていない状態で動いた」だけだからです。気づくのは、たいてい何かが起きた後です。だから、CLAUDE.md と AGENTS.md のずれは、見た目は同期の手間でも、中身は安全の問題を含みます。指示書を1か所に集約してどの道具からも同じに効かせることは、手間を減らすためだけでなく、自分が決めた歯止めを確実に効かせるための作業でもあります。
どの道が、自分の使い方（個人で使い分ける／チーム／並行）と、どの環境で静かに壊れるか。その一覧と、CLAUDE.md から AGENTS.md への巻き戻しつきの移行の手順を、別の本にまとめています。
- 5つの道それぞれが、どの型・どの環境で壊れるかの一覧
- Anthropic の公式の対応の追跡と、6月15日の課金分離との関係
- 回避策それぞれの、すぐ使えるテンプレート集
AGENTS.md と Claude Code の interop 運用の手引き（¥1,500、はじめにと第1章・第2章は無料で試し読みできます）
破壊的コマンドや認証情報の流出を予防する hook は、cc-safe-setup（MIT、無料）で約800件公開しています。
800時間の Claude Code 運用データから、トークン消費の削減・複数ベンダー(Claude / Codex / Gemini / Copilot)の並行運用・事故の検知と復旧・サブエージェントの沈黙の失敗対策など、主題別の手引きを公開しています。気になる人は著者の本の一覧から、価格と評価を見て選べます。