.claude/rulesのシンボリックリンクが読み込まれない原因と対処 — Claude Code

プロジェクト外を指す.claude/rules/のシンボリックリンクは、@pathの外部importと同じ承認で止まります。v2.1.283までは承認を求めるプロンプトすら出ず、ルールが黙ってスキップされました。v2.1.284からは、リンクを置いただけで承認プロンプトが出ます。承認してもpathsフロントマター付きのルールが読み込まれない点は、今も変わっていません。

v2.1.284を境に何が変わったか

v2.1.284のchangelogには、次の項目が載っています。

Fixed rules symlinked into .claude/rules from outside the project being skipped without ever showing the external-imports approval prompt; a .claude directory symlinked from outside the project now asks for the same approval

この症状は、GitHub issue #88405で2026年8月20日に報告されました。issueは完了としてクローズされ、2.1.284での再テストでは、@importによる回避策が不要になったと報告されています。

一方でcode.claude.com/docs/en/memoryのシンボリックリンクの節は、承認を求めるのは@pathのときだけで、リンクだけでは求めないと書いたままです。changelogとmemoryページの記述が食い違っているので、手元の挙動はバージョンで判断することになります。

読み込まれないとき、どこから切り分けるか

/context

読み込みの記録を残したいときは、InstructionsLoadedフックが使えます。CLAUDE.mdと.claude/rules/のファイルが読み込まれるたびに、file_path・memory_type・load_reasonを含むJSONが標準入力に渡されます。次の例は、その3項目をjqでログに追記します。

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '[.load_reason, .memory_type, .file_path] | @tsv' >> /tmp/instructions-loaded.log"
          }
        ]
      }
    ]
  }
}

セッションを始めて、ログにリンクしたルールの行がなければ、そのルールは読み込まれていません。issueでは、このフックのログでバージョンごとの読み込みの有無が比べられていました。

なぜ読み込まれないのか — 外部importと同じ承認ゲート

memoryページは、リンク先が作業ディレクトリの外にあるシンボリックリンクを、外部importと同じ扱いにすると説明しています。承認するまでリンク先のルールは読み込まれず、承認後に読み込まれるのはpathsフィールドを持たないものだけです。

承認の状態は、~/.claude.jsonの各プロジェクトのエントリに、hasClaudeMdExternalIncludesApprovedというフラグで保存されます。issueのコメントでは、このフラグとhasClaudeMdExternalIncludesWarningShownをfalseにした状態でリンクが落ち、trueにすると読み込まれると報告されています。

memoryページが挙げる、リンクが読み込まれない場面は、ほかに2つあります。

• 解決先がUNC共有の\\server\shareや/net・/Network配下のネットワークパス。参照先のホストへ問い合わせる可能性があるため、リンクをたどらない
• Coworkのデスクトップセッションで、作業ディレクトリの外を指す~/.claude/rules/のリンク。ユーザースコープでもスキップされ、~/.claude/CLAUDE.md自体がシンボリックリンクやハードリンクの場合も同じ

ユーザースコープの~/.claude/rules/は、Cowork以外ではこの承認を受けません。ユーザーが自分で書いたファイルとして、外部importも確認なしで読み込まれるためです。memoryページは、承認なしで共有ルールを読み込みたいときの置き場所として~/.claude/rules/を挙げています。

承認プロンプトを経由せずに読み込ませる方法

v2.1.284以上なら、リンクを置いたプロジェクトでプロンプトが出たときに承認すれば済みます。v2.1.283以下では、次の2通りが報告されています。どちらもhasClaudeMdExternalIncludesApprovedをtrueにする点は同じです。

1つ目は、承認ダイアログを一度通す方法です。プロジェクトのCLAUDE.mdに一時的な@pathインポートを1行足し、セッションを始めて承認し、その後に行を消します。

# CLAUDE.mdに一時的な外部importを追加
echo '@/absolute/path/outside/project.md' >> CLAUDE.md
 
# セッションを開始し、表示される承認ダイアログを受け入れる
claude
 
# 承認が終わったら、追加した行を削除する

2つ目は、~/.claude.jsonのフラグを直接書き換える方法です。Windows版2.1.251で、この書き換えだけでリンク済みのルールが読み込まれたと報告されています。

{
  "projects": {
    "/absolute/path/to/project": {
      "hasClaudeMdExternalIncludesApproved": true
    }
  }
}

paths付きのルールは、リンクをやめると効く

承認フラグを立てても、pathsフロントマター付きのルールはリンク経由では読み込まれません。2.1.284で再テストしたコメントでも、対象ファイルを読んだときにpath_glob_matchのInstructionsLoadedイベントが出ませんでした。同じ内容を実体のファイルとして置くと、同じ読み込みで一致したそうです。

使い分けは次のとおりです。

• pathsで適用範囲を絞りたいルール: リンクをやめ、プロジェクトの.claude/rules/に実体のファイルとして置く
• 全体に効かせてよいルール: pathsを外してリンクのまま使う
• 自分のマシンの全プロジェクトに効かせたいルール: ~/.claude/rules/に置く

承認の状態で見落としやすい2つの落とし穴

承認の状態が思ったとおりに働かないケースが2つあります。issueのコメントでは、v2.1.272〜274の時期の検証として報告されました。

1. ワークツリーは親チェックアウトの承認を引き継ぐ。git worktreeで作ったワークツリー自身のエントリがfalseでも、元のリポジトリが承認済みなら外部リンクが読み込まれます。報告者は、git rev-parse --git-common-dirで元のリポジトリの承認状態を確かめるよう勧めています。
2. 承認は新しいプロジェクトパスごとにやり直しになる。フレッシュクローンや新しいワークツリーは、パスが変わるたびにfalseから始まります。WindowsではC:\dev\...とC:/dev/...のようにパスの綴りが2通り記録され、両方に設定が必要になった例もあります。

ユーザースコープで起きた別の不具合(VS Code拡張)

~/.claude/rules/は承認ゲートの対象外ですが、VS Code拡張2.1.273では別の症状が2026年9月18日に報告されています。

報告者の環境では、paths付きのシンボリックリンクが4つ置かれていました。既存の3つは読み込まれましたが、セッションの最初の列挙より後に追加した4つ目は、新規会話・ウィンドウの再読み込み・VS Codeの再起動・リンクの再作成・ファイル名の変更のどれでも読み込まれませんでした。

報告者はこれを、ユーザースコープの列挙が一度だけ取られたスナップショットになっている可能性として説明しています。Anthropicからの確認はなく、1件の報告にとどまります。

修正の経過

v2.1.239の変更は、リンクをclaudeMdExcludesで除外するときの一致規則です。除外したいファイルがリンク経由のとき、ルールディレクトリ側のパスとリンク先のパスのどちらに書いても一致します。それ以前は、リンク先のパスに書いたパターンだけが効きました。除外の書き方はclaudeMdExcludesの設定手順にまとめています。v2.1.284のリリースノートでは、.claudeディレクトリそのものがリンクの場合に承認が必要になった点も読めます。

よくある質問

CLAUDE.mdをAGENTS.mdへシンボリックリンクする場合も同じ制限を受けますか

受けません。同じディレクトリ内のファイルを指すだけで、作業ディレクトリの外を参照しないからです。外部import扱いになるのは、解決先が作業ディレクトリの外にある場合だけです。ただし別の制約があります。

• EditツールとWriteツールはシンボリックリンクを通した書き込みを拒否し、リンク先のAGENTS.mdを編集するよう案内します
• Windowsでリンクを作るには管理者権限か開発者モードが要ります
• Gitは、core.symlinksが有効でない限り、コミット済みのリンクをプレーンテキストのファイルとしてチェックアウトします

WindowsでCLAUDE.mdをリンクにすると、クローンした側には1行だけのCLAUDE.mdが残ります。Windowsの利用者が1人でもいるリポジトリなら、memoryページは@AGENTS.mdのimportを勧めています。

フラグをtrueにする前に、何を確かめますか

外部importの承認ダイアログは、共有プロジェクトに他人がコミットしたファイルからユーザーを守るために出ます。フラグを書き換えると、このダイアログを通さずに同じ許可を与えることになります。リンク先のファイルを自分で用意しているプロジェクトかを確かめてから書き換えます。

まとめ

v2.1.283以下では、承認プロンプトが出ないままルールが落ちるため、まずバージョンを疑います。v2.1.284以上でpathsのないルールなら承認で足り、paths付きのルールだけは実体のファイルか~/.claude/rules/に置く選択になります。

モノレポで複数チームのルールを置き分ける設計はClaude Codeモノレポ設計、CLAUDE.mdと自動メモリの役割分担はClaude Code memoryの三層構造で扱っています。