CLAUDE.md importの書き方｜相対パス・4ホップ・承認の確認手順

CLAUDE.md の import は、@ の直後にファイルパスを書くだけで使えます。相対パスは作業ディレクトリではなく「その @ を書いたファイル」が基準で、取り込んだ先からさらに取り込む再帰の上限は4ホップまでです。プロジェクトの CLAUDE.md から作業ディレクトリの外を指す import は、そのプロジェクトで初めて検出されたときに承認ダイアログが出ます（~/.claude/CLAUDE.md などユーザー階層のファイルは別扱い）。参照元の CLAUDE.md の読み込み確認を行う方法は /context の Memory files で、import の参照先を1件ずつ確かめるなら InstructionsLoaded フックの include で確認します。

CLAUDE.md に何を書くか（見出しの構成や指示の書き方）は CLAUDE.md の書き方ガイドで扱っています。この記事は @ 行の仕様だけに絞ります。

CLAUDE.md の import はどう書く？基本の構文

公式資料（How Claude remembers your project の Import additional files）によると、CLAUDE.md は @path/to/import の形で別ファイルを取り込めます。取り込んだファイルは展開され、参照元の CLAUDE.md と一緒に起動時にコンテキストへ読み込まれます。

@ は行頭である必要はなく、文中や箇条書きの中に書いても取り込まれます。公式の例は次のとおりです。

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

この例では README、package.json、docs/git-instructions.md の3つが取り込まれます。

import を使う前に知っておきたい点が2つあります。

コンテキストの消費は減らない。公式は、import は長いファイルの整理には役立つものの、取り込んだファイルも起動時に読み込まれるのでコンテキストのコストは下がらないと書いています。読み込み量を抑えたいなら、該当するファイルを扱うときだけ読み込まれる path-scoped rules が公式の案内です。
サイズの警告では別ファイルとして数える。CLAUDE.md、rules ファイル、@path import はそれぞれ1ファイルとして数えられ、1つずつは推奨の長さに収まっていても合計が上限を超えると起動時に警告が出ます。また 4 MiB を超えるファイルは読み込まれません。

相対パスはどこが基準になる？

相対パスは「import を書いたファイルの場所」が基準です。公式（Import additional files）は、作業ディレクトリ基準ではないと明記しています。相対パスのほか、ルートから書いたフルパスも使えます。

たとえば project/CLAUDE.md と、その下の project/docs/rules.md、project/docs/style.md があるとします。

`@` を書いたファイル	書いた内容	解決される先
`project/CLAUDE.md`	`@docs/rules.md`	`project/docs/rules.md`
`project/docs/rules.md`	`@style.md`	`project/docs/style.md`
`project/docs/rules.md`	`@docs/style.md`	`project/docs/docs/style.md`（意図した場所とは異なる）

3行目は基準を取り違えた例です。CLAUDE.md から見たパスを下位のファイルにそのままコピーすると、基準がずれます。

ホームディレクトリのファイルは ~ で指定できます。公式は、同じリポジトリの複数の git worktree で個人用の指示を共有したい場合の例として次を挙げています。gitignore した CLAUDE.local.md は作成した worktree にしか存在しないためです。

# Individual Preferences
- @~/.claude/my-project-instructions.md

この import は作業ディレクトリの外を指すため、後述の承認の対象になります。

空白を含むパスやコードブロック内の @ はどう扱われる？

パスに空白が含まれる場合は、空白エスケープとしてバックスラッシュを付けます。付けないと、その行に @ 行が1つしかなくても、最初の空白でパスが終わったものとして扱われます。引用符で囲んだパスは、バックスラッシュの有無にかかわらず取り込まれません。Design Docs フォルダのファイルを取り込む公式の例です（出典: Import additional files）。

- API conventions @Design\ Docs/api-conventions.md

もう1つ、Markdown のコードスパン（バッククォートで囲んだ部分）とフェンスドコードブロックの中は、import のパス解析では対象外です。パスを説明として書きたいだけで取り込みたくない場合は、バッククォートで囲みます。

やりたいこと	書き方	結果
ファイルを取り込む	バッククォートの外に `@README` と書く	取り込まれる
パスに言及するだけ	バッククォートで囲む	文字のまま残る
空白入りのパスを取り込む	空白の前に `\` を付ける	取り込まれる
引用符を使う	パスを引用符で囲む（空白を `\` で処理していても同じ）	取り込まれない

import の再帰は何段まで？

取り込んだファイルが、さらに別のファイルを取り込むことはできます。公式（Import additional files）の記載は「最大深さは4ホップ」です。

4ホップをどこから数えるか（CLAUDE.md から最初の取り込み先までを1ホップとするか）と、上限を超えた先のファイルがどう表示されるかは、公式の memory ページに記載がないため、本稿では断定しません。上限ぎりぎりの連鎖は組まず、CLAUDE.md から直接取り込む浅い構成にしておくと、どのファイルが効いているかを追いやすくなります。

作業ディレクトリの外を import すると何が起きる？

プロジェクト階層のメモリファイルにある import のうち、作業ディレクトリの外に解決されるものは「外部 import」として扱われます。公式資料（Import additional files、Share rules across projects with symlinks）の記載をまとめると次のとおりです。

Claude Code がそのプロジェクトで初めて外部 import に出会ったとき、対象ファイルを一覧にした承認ダイアログを表示する
拒否すると、その import は無効のままになり、ダイアログは再び表示されない
このダイアログは、共有プロジェクトに他人がコミットしたファイルから利用者を守るためのもの
ユーザー階層のファイル（~/.claude/CLAUDE.md や ~/.claude/rules/）の import は、ダイアログなしで読み込まれる。例外はデスクトップの Cowork セッションで、ユーザー階層ファイル内の作業ディレクトリ外を指す import はスキップされ、ファイルの残りだけが読み込まれる
作業ディレクトリ外を指すシンボリックリンクの .claude/rules/ も外部 import と同じ扱いで、承認するまで読み込まれない。承認は対話セッションの開始時にプロジェクトごと1回求められ、ダイアログには外部の @path import と並んで表示される

拒否すると再表示されないため、ダイアログで一覧に出たファイルは、出どころを確認してから判断します。他人から受け取ったリポジトリでは、CLAUDE.md の @ 行のうち、~ やフルパス、上位ディレクトリを指すものを先に確認しておくと、ダイアログで迷わずに済みます。拒否したあとに承認し直す手順は、公式の memory ページに記載がないため、本稿では案内していません。

チームでどこまで外部ファイルを許すかといった運用の判断は Claude Code の運用ルールにまとめています。

AGENTS.md を CLAUDE.md から import するには？

他のコーディングエージェント向けに AGENTS.md を置いているリポジトリでは、CLAUDE.md から @AGENTS.md で取り込めば、1つのファイルを複数のツールで共有できます。公式（Share one file with other coding tools）は、プロジェクトに CLAUDE.md もある場合、Project instructions を claude-md に設定した場合、AGENTS.md を直接読めないセッションでこの方法を挙げています。

import の下に Claude Code 向けの指示を足すと、取り込んだ AGENTS.md が先に読まれ、そのあとに残りが読まれます。公式の例です。

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

この書き方について、公式資料には次の記載があります。

@AGENTS.md を含む CLAUDE.md は残してよく、Project instructions の設定値にかかわらず AGENTS.md が二重に読まれることはない
CLAUDE.md に「AGENTS.md を読んで」と文章で書いただけでは、Claude がそのファイルを開くと判断したときにしか内容を見ない。@AGENTS.md の import に置き換えるよう案内されている
リポジトリを Windows で扱う人がいる場合は、CLAUDE.md を AGENTS.md へのシンボリックリンクにするのではなく、@AGENTS.md の import を使う

Claude Code が AGENTS.md を直接読む場合（直接の読み込みは Claude Code v2.1.277 以降が必要）でも、AGENTS.md の中の @path import は展開されます。ただし Project instructions の設定で直接読む AGENTS.md では、作業ディレクトリ外を指す import は、そのプロジェクトで外部 import をすでに承認している場合にだけ読み込まれ、承認ダイアログは出ません。

import したファイルが読み込まれたか確認するには？

import は起動時に読み込まれるので、@ 行を足したり直したりしたら、新しいセッションを始めてから確認します。確認に使うコマンドは役割が違います（出典: Debug your configuration、/memory での閲覧と編集）。

コマンド	わかること	注意点
`/context`	現在のセッションのコンテキストの内訳。Memory files の一覧で、起動時に読み込まれた CLAUDE.md や rules を確認できる	一覧に無いファイルは Claude から見えていない
`/memory`	ユーザーとプロジェクトのメモリファイルの場所。まだ存在しない CLAUDE.md の項目も出る	一覧に出ても読み込み成功の証拠にはならない

手順は次のとおりです。

確認用に、CLAUDE.md に @ 行を1本だけ書く
新しいセッションで Claude Code を起動する
プロジェクト階層の外部 import をそのプロジェクトで初めて検出した場合は承認ダイアログが出るので、内容を見て判断する（拒否済みなら再表示されない）
/context を実行し、Memory files に参照元の CLAUDE.md が出ているか見る

公式が /context で確かめる対象として挙げているのは CLAUDE.md や rules で、import 先のファイルが Memory files に個別に表示されるかどうかは、memory と debug-your-config のページに記載がないため、本稿では断定しません。取り込みを1件ずつ確かめたい場合は、InstructionsLoaded フック（Hooks reference）を使います。このフックは CLAUDE.md や .claude/rules/*.md がコンテキストに読み込まれたときに発火し、入力の load_reason が読み込まれた理由を示します。import されたファイルは load_reason が include になり、parent_file_path に取り込み元のファイルのパスが入ります。matcher は load_reason に対して照合されるので、include に絞って import による読み込みだけを記録できます。このフックは読み込みを止めたり変えたりはできず、記録用です。なお、Project instructions の設定で AGENTS.md を直接読む場合は、このフックは発火しません（CLAUDE.md から import した AGENTS.md では発火します）。フックの設定方法は Claude Code hooks のガイドを参照してください。

読み込まれない・効かないときはどこを確認する？

症状ごとに確認する場所を並べます。

症状	確認すること
取り込んだはずの指示が効いていない	`@` 行がコードスパンやフェンスドコードブロックの中にないか。パスを引用符で囲んでいないか
下位のファイルに書いた import だけ解決されない	パスが「その `@` を書いたファイル」から見た相対パスになっているか
空白を含むフォルダのファイルが読み込まれない	空白の前にバックスラッシュがあるか
連鎖の深い先だけ読み込まれない	4ホップの上限に達していないか。構成を浅くできないか
ホームや別ディレクトリのファイルが読み込まれない	外部 import の承認ダイアログで拒否していないか。拒否するとダイアログは再表示されない
「Instruction file not loaded」と表示された	表示された理由を見る（下記）
`/context` で読み込みを確認できたのに従わない	読み込みではなく指示の書き方を見直す

「Instruction file not loaded」は、存在するメモリファイルが読み取り制限によって読み込まれなかったことを示す通知です（出典: Errors の Instruction file not loaded）。理由の例として公式は、Read の deny ルールがそのパスに一致している、permissions.blockReadsOutsideWorkingDirectories が有効で作業ディレクトリの外にある、リンクが自分自身を指すなどでリンク先を特定できない、の3つを挙げています。制限が意図したものなら何もしなくてよく、そのファイルの指示なしでセッションが続きます。Read の deny ルールが理由の場合、公式はルールを取り除くか狭めてから新しいセッションを始めるよう案内しています。Read の deny ルールは Read(./.env) や Read(./secrets/**) のように、Claude のファイルツールに読ませたくないファイルを止めるための設定です（出典: Permissions の Read and Edit）。取り除く・狭める前に、そのルールが秘密情報などのファイルを守っていないかを確かめます。守っている場合は、ルールを取り除くのではなく、読ませたいメモリファイルが外れる範囲にだけ狭めます。deny ルールなど settings.json の権限設定は settings.json のガイドで扱っています。

表の最後の行について、公式は、/context で読み込みを確認できたのに Claude が特定の指示に従わない場合は、読み込みではなく指示の書き方に原因がある可能性が高いと書いています。CLAUDE.md の内容はシステムプロンプトのあとにユーザーメッセージとして渡されるため、厳密に守られるとは限りません。コミット前など決まった時点で実行させたい処理は、フックで書くよう案内されています。

公式資料で確認できなかった点

次の項目は、本稿で照合した公式資料（memory・hooks・errors・debug-your-config の各ページ、2026年10月19日取得）に記載がなかったため、断定していません。

@../ のように上位ディレクトリを指す相対パスの個別の挙動（本稿では検証していない。確認できたのは「import を書いたファイルが基準」という一般規則のみ）
4ホップの数え方と、上限を超えた先のファイルの表示
存在しないファイルを import したときの表示
外部 import を拒否したあとに承認し直す手順
import 先のファイルが /context の Memory files に個別に表示されるかどうか