.claude/rulesのシンボリックリンクが読み込まれない原因と対処 — Claude Code
Claude Codeの.claude/rulesはシンボリックリンクに対応しますが、プロジェクト外を指すリンクは外部importと同じ承認ゲートで止まります。原因と回避策をまとめます。
Claude Codeの公式ドキュメントは、.claude/rules/がシンボリックリンクに対応すると説明しています。ところがプロジェクト外を指すシンボリックリンクは、@pathの外部importと同じ承認フラグでゲートされ、未承認のままでは読み込まれません。GitHub issue #88405は2026年8月20日に報告され、9月18日の最新コメントでもオープンのままです。
.claude/rules/のシンボリックリンクで何が起きるか
症状はシンプルです。.claude/rules/の中にプロジェクト外のファイルを指すシンボリックリンクを置いても、セッション開始時に読み込まれません。readlinkで解決先を確認しても中身は正しく、OS側では何も壊れていません。
issue #88405のOPは、同じ場所に置いた通常ファイル(シンボリックリンクでない)は正常に読み込まれることを確認済みです。差が出るのはシンボリックリンクかどうかだけで、.claude/rules/の読み込み機構全体が壊れているわけではありません。
影響を受けるのは、複数プロジェクトで共通ルールを共有している開発者です。OPは「シンボリックリンクはOSレベルでは正しく見えるため、何も壊れていないように見える」点が厄介だと指摘しています。Seledrex氏は社内で公式docsどおりの手順を使って共有ルールを配布していたところこの不具合に遭遇したと報告し、dspiegs氏は100人超のワークフローに影響したと述べています。
読み込まれたかどうかは、セッション内で/contextを実行し、Memory filesの一覧に対象のファイルが出るかで確認できます。
/contextissue提出時(Claude Code 2.1.238)に引用された旧版のdocsは、「.claude/rules/ディレクトリはシンボリックリンクをサポートし、通常どおり解決・読み込みされる」と説明していました。いまcode.claude.com/docs/en/memoryで読める現行のdocsは、この文言をすでに差し替えています。
現行のdocsは「シンボリックリンクの参照先が作業ディレクトリの外にある場合、Claude Codeはそれを外部importと同じ扱いにする」と明記し、承認するまでリンク先のルールは読み込まれないと説明しています。issueのタイトルは今も「contradicts docs」のままですが、現行のdocsを読む限りこの記述はすでに観測された挙動と一致しています。
なぜ読み込まれないのか — 外部importと同じ承認ゲート
ゲートの正体は、~/.claude.jsonの各プロジェクトエントリが持つhasClaudeMdExternalIncludesApprovedというフラグです。issueのコメント欄でnicholasshirley氏がバンドルされたコードを読んで特定し、複数人が独立に再現・検証しています。
このフラグがfalseのままだと、.claude/rules/がlstatでシンボリックリンクと判定され、解決先が作業ディレクトリの外にある場合はそのエントリを何も読み込まずスキップします。フラグがtrueになるのは、プロジェクトのメモリファイルが@pathで作業ディレクトリ外のファイルをインポートし、その承認ダイアログを受け入れたときだけです。ルールディレクトリのシンボリックリンク単体では、この承認ダイアログは一度も表示されません。
一方、~/.claude/rules/(ユーザースコープ)のシンボリックリンクはこのゲートの対象外です。ユーザースコープの読み込みは外部importの扱いを無条件で許可するため、プロジェクト外を指すリンクでも通常どおり読み込まれます。
ただしCoworkのデスクトップセッションは例外です。現行のdocsによると、作業ディレクトリの外を指す~/.claude/rules/のシンボリックリンクは、Coworkセッションではユーザースコープであってもスキップされます。~/.claude/CLAUDE.md自体がシンボリックリンクやハードリンクである場合も同様です。
| 配置 | paths指定なし | paths指定あり |
|---|---|---|
.claude/rules/(プロジェクト外へのリンク・未承認) | paths指定なし読み込まれない | paths指定あり読み込まれない |
.claude/rules/(プロジェクト外へのリンク・承認済み) | paths指定なし読み込まれる | paths指定あり承認後も読み込まれない |
~/.claude/rules/(ユーザースコープのリンク) | paths指定なし読み込まれる | paths指定あり読み込まれる |
.claude/rules/(通常ファイル、リンクでない) | paths指定なし読み込まれる | paths指定あり読み込まれる |
現行のdocsも「承認後に読み込まれるのはpathsフィールドを持たないものだけ」と明記しており、表右列の挙動は現在の仕様として扱われています。
いま試せる2つの回避策
回避策は2通り報告されています。どちらもhasClaudeMdExternalIncludesApprovedをtrueにする点は同じで、経路が違うだけです。
1つ目は、承認ダイアログを一度通す方法です。プロジェクトのCLAUDE.mdに一時的な@pathインポートを1行追加し、セッションを開始して承認ダイアログを受け入れ、その後に行を削除します。lcristin氏がこの手順を確認しています。
# CLAUDE.mdに一時的な外部importを追加
echo '@/absolute/path/outside/project.md' >> CLAUDE.md
# セッションを開始し、表示される承認ダイアログを受け入れる
claude
# 承認が終わったら、追加した行を削除する2つ目は、~/.claude.jsonのフラグを直接書き換える方法です。ダイアログを経由せずに済みます。
{
"projects": {
"/absolute/path/to/project": {
"hasClaudeMdExternalIncludesApproved": true
}
}
}csemrau氏はWindows版2.1.251で、この直接書き換えだけでリンク済みのルールが読み込まれることを確認しています。どちらの方法でも、paths指定のルールは承認後も読み込まれません。共有ルールにpathsフロントマターを付けている場合、承認フラグを設定しても読み込みは解決しません。
承認しても気づけない3つの落とし穴
承認フラグを設定しても見落としやすい落とし穴が3つあります。いずれもコミュニティの検証で確認されました。
- ワークツリーは親チェックアウトの承認を引き継ぐ。
git worktreeで作成したワークツリー自身のプロジェクトエントリがfalseでも、元になったリポジトリが承認済みなら外部シンボリックリンクを読み込みます。csemrau氏はこれを「修正されたように見えるだけの罠」と表現し、git rev-parse --git-common-dirで元リポジトリの承認状態を確認するよう勧めています。 - フラグは新しいプロジェクトパスごとにリセットされる。フレッシュクローンや新規ワークツリーは、パスが変わるたびにfalseから始まります。csemrau氏は、Windowsでは
C:\dev\...とC:/dev/...のようにパスの綴りが2通り記録され、両方に設定が必要になったケースも報告しています。 - 失敗が完全にサイレント。ルールがスキップされても
/contextのMemory files一覧に載らないだけで、エラーも警告も出ません。yashaka氏の検証では、/memoryにもInstructionsLoadedフックのログにも痕跡が残りませんでした。判定するには、ルールファイルにマーカー文字列を仕込み、モデルに実際に出力させて確かめる以外に方法がありません。
ユーザースコープにも潜む別の罠(VS Code拡張)
~/.claude/rules/は前述の承認ゲートを受けませんが、josesuntw氏はVS Code拡張(2.1.273)で別の不具合を2026年9月18日に報告しています。
既存の3つのシンボリックリンクルールは問題なく読み込まれる一方、セッションの最初の列挙より後に追加した4つ目のルールは、新規会話・ウィンドウの再読み込み・VS Codeの完全再起動・シンボリックリンクの再作成・ファイル名の変更のいずれを試しても読み込まれませんでした。
報告者はこの現象を「ユーザースコープの列挙が一度きりのスナップショットとしてキャッシュされている」可能性として説明していますが、Anthropicによる確認はまだありません。1件の報告であり、再現性は確定していません。
影響バージョンのタイムライン
退行は2026年8月13日リリースのv2.1.232で始まり、9月17日の最新確認でも解消していません。
| バージョン | 公式リリース日 | 状況 |
|---|---|---|
| v2.1.223 | 公式リリース日— | 状況コミュニティの遡及テストで最後に正常動作したと報告されたバージョン |
| v2.1.231 | 公式リリース日2026-08-13 | 状況複数人が正常動作を確認 |
| v2.1.232 | 公式リリース日2026-08-13 | 状況ARivottiC氏のbisectionで退行の起点と特定 |
| v2.1.238 | 公式リリース日2026-08-20 | 状況issue #88405提出時のバージョン |
| v2.1.239 | 公式リリース日2026-08-21 | 状況claudeMdExcludesのシンボリックリンク一致パターンを修正(読み込みゲート自体は対象外) |
| v2.1.251 | 公式リリース日2026-08-28 | 状況承認フラグの回避策が機能すると複数人が確認。paths指定ルールは承認後も読み込まれず |
| v2.1.257 | 公式リリース日2026-09-01 | 状況再現継続を確認 |
| v2.1.272〜274 | 公式リリース日2026-09-15〜17 | 状況再現継続。ワークツリーの承認継承という見誤りやすい罠が判明 |
| issue #88405 | 公式リリース日最終コメント2026-09-18 | 状況bug / has reproラベルのままオープン |
changelogを2.1.278まで確認しても、この承認ゲート自体を変更した記載は見当たりません。2.1.239のclaudeMdExcludes修正が、シンボリックリンクに触れる唯一のエントリです。
よくある質問
CLAUDE.mdをAGENTS.mdへシンボリックリンクする場合も同じ制限を受けますか
受けません。CLAUDE.mdをAGENTS.mdへのシンボリックリンクにする使い方は、同じディレクトリ内でファイルを指すだけで、作業ディレクトリの外を参照しません。外部import扱いになるのは解決先が作業ディレクトリの外にある場合だけなので、この用途はゲートの対象外です。
hasClaudeMdExternalIncludesApprovedをtrueにする際の注意点は
このフラグは、コミットされたシンボリックリンクが作業ディレクトリ外の任意のファイルを読み込めるようになることへの同意にあたります。信頼できないリポジトリで安易にtrueへ書き換えると、意図しない外部ファイルもまとめて読み込み対象になるため、自分で用意した共有ルールのプロジェクトに限定するのが妥当です。
まとめ
プロジェクト外を指す.claude/rules/のシンボリックリンクは、@pathの外部importと同じ承認フラグでゲートされています。未承認なら読み込まれず、承認してもpaths指定ルールは読み込まれません。
共有ルールをチームで運用する場合は、claudeMdExcludesでの除外設定と同様に、/contextのMemory files一覧を都度確認する習慣が要ります。除外設定の詳しい挙動はclaudeMdExcludesの設定手順で扱っています。
モノレポで複数チームのルールを整理する設計はClaude Codeモノレポ設計、CLAUDE.mdと自動メモリの役割分担はClaude Code memoryの三層構造を参照してください。この挙動が今後の更新で変わっていないかは、Claude Code v2.1.278のようなリリースノートで確認できます。