AGENTS.mdとCLAUDE.mdをsymlinkで統一したら、Windowsのメンバーだけ指示が消えていた——Git for Windowsの静かな罠

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 から AGENTS.md への巻き戻しつきの移行の手順を、別の本にまとめています。

• 5つの道それぞれが、どの型・どの環境で壊れるかの一覧
• Anthropic の公式の対応の追跡と、6月15日の課金分離との関係
• 回避策それぞれの、すぐ使えるテンプレート集

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

破壊的コマンドや認証情報の流出を予防する hook は、cc-safe-setup（MIT、無料）で約800件公開しています。