AGENTS.md を共有したつもりが、Claude Code だけ古い指示を読んでいた

Last updated at 2026-08-19Posted at 2026-08-19

AGENTS.md は、Codex や Cursor など複数のコーディングエージェントが読む共通の指示ファイルです。

Claude Code はこれを読みません。 公式が案内している回避策は2つあります。

ln -s AGENTS.md CLAUDE.md   # ① シンボリックリンク
echo '@AGENTS.md' > CLAUDE.md   # ② インポート

Windows で ① を選ぶと、静かに壊れます。

コマンドは成功します。エラーも出ません。初回はちゃんと動きます。
それなのに AGENTS.md を更新しても、Claude Code だけが古い指示を読み続けます。

測った結果を順に書きます。

検証環境: Windows 10 Home 19045 / Claude Code 2.1.235 / Git Bash

まず結果

置いたもの	合言葉を答えられたか
`AGENTS.md` だけ	答えられない（「不明」）
`CLAUDE.md` に `@AGENTS.md` と書く	答えられる
`ln -s AGENTS.md CLAUDE.md`	答えられる。ただし後述の問題あり

検証方法: AGENTS.md に「合言葉は◯◯」と書いて claude -p で聞きました。
ファイル読み取りツールは禁止しているので、指示ファイルとして読まれたかだけが分かります。

AGENTS.md だけでは読まれない

まっさらなディレクトリに AGENTS.md を1つ置きました。

# Project Instructions

このプロジェクトの合言葉は「向日葵7391」です。

聞いてみます。

不明

読まれていません。 これは公式ドキュメントのとおりでした。

Claude Code reads CLAUDE.md, not AGENTS.md.
（Claude Code は CLAUDE.md を読む。AGENTS.md ではない）

「フォールバックで読んでくれる」という説を見かけますが、手元では読みませんでした。

「完了」の中身は、回避策のドキュメント化だった

では何が完了したのか。issue に残っていた回答がこれです。

you can share one file with other agents: create a CLAUDE.md containing just @AGENTS.md (an import), or symlink CLAUDE.md to AGENTS.md.
（他のエージェントと1つのファイルを共有できる。@AGENTS.md だけを書いた CLAUDE.md を作るか、CLAUDE.md を AGENTS.md へのシンボリックリンクにすればよい）

実装ではなく、回避策の案内でクローズされています。

クローズ翌日のコメントです。

even though it was "Closed #6235 as completed", the AGENTS.md support is still unavailable and not working in Claude Code
（「completed としてクローズ」されたにもかかわらず、AGENTS.md 対応は依然として利用できず、Claude Code で機能していない）

実測もそのとおりでした。

回避策1: `@AGENTS.md` インポート（推奨）

CLAUDE.md を作って、1行だけ書きます。

@AGENTS.md

## Claude Code

この節は Claude Code 専用です。

これで通りました。

向日葵7391

これは実ファイルへの参照です。 AGENTS.md を書き換えて試しました。

`AGENTS.md` を書き換え	Claude Code の回答
向日葵7391 → 椿5024	椿5024
椿5024 → 楓8846	楓8846

毎回そのまま反映されます。 二重管理になりません。

インポートの下に Claude 専用の指示を足せるので、共通は AGENTS.md、Claude だけの話は CLAUDE.md と分けられます。

回避策2: symlink — Windows では黙って壊れる

ここが本題です。

公式にはこう書いてあります。

ln -s AGENTS.md CLAUDE.md

Git Bash で実行しました。エラーは出ません。

ln -s: 成功

聞くと、ちゃんと答えます。

向日葵7391

一見、成功しています。 しかし ls -l が違いました。

-rw-r--r-- 1 ... 165 Aug 20 08:34 CLAUDE.md

-rw-r--r-- です。 シンボリックリンクなら lrwxrwxrwx になるはずです。確認しました。

inode比較: AGENTS.md=7036874418332751  CLAUDE.md=7881299348464765
readlink: **リンクではない**

別ファイルです。 Git Bash の ln -s はコピーを作っていました。

問題はここからです。AGENTS.md だけを書き換えます。

ファイル	中身
`AGENTS.md`（書き換えた）	椿5024
`CLAUDE.md`（コピー）	向日葵7391 のまま

Claude Code の回答も、こうなりました。

向日葵7391

古い指示を読み続けます。

エラーは出ません。動いて見えます。Claude Code だけ取り残されていることに気づく手がかりがありません。

なお公式ドキュメントにも、Windows についての注意はありました。

On Windows, creating a symlink requires Administrator privileges or Developer Mode, so use the @AGENTS.md import instead.
（Windows でシンボリックリンクを作るには管理者権限か開発者モードが必要なので、代わりに @AGENTS.md インポートを使うこと）

「使えない」とは書かれていますが、「成功したように見えてコピーになる」とは書かれていません。

どちらを使うか

環境	方法
Windows	`@AGENTS.md` インポート一択。 symlink は避ける
macOS / Linux	どちらでも。ただしインポートなら Claude 専用の指示を足せる
すでに `ln -s` した人	`ls -l` で `l` から始まるか確認する。 `-` なら同期していない

確認は1行です。

ls -l CLAUDE.md    # lrwxrwxrwx なら本物、-rw-r--r-- ならコピー

残る不便もあります。 サブディレクトリごとに AGENTS.md を置く構成では、
その数だけダミーの CLAUDE.md が要ります。

まとめ

Claude Code は AGENTS.md を読まない。 公式ドキュメントにも明記され、実測でも読まれなかった
issue #6235（リアクション5,983）は 2026-08-17 に completed で閉じられたが、
中身は回避策の案内で、実装ではない
@AGENTS.md インポートが推奨。 実ファイル参照なので、書き換えが毎回反映される
Windows の Git Bash で ln -s すると、リンクではなくコピーができる。 エラーも出ず初回は動くので気づきにくく、
AGENTS.md を更新しても反映されない。 確認は ls -l CLAUDE.md（l で始まらなければコピー）