無料相談する

カテゴリー / 連携・活用

CLAUDE.md の import（@）の仕様と確認方法｜相対パス・コードブロック・外部参照の扱い

NO WAVE公開 読了目安 8分

この記事の目次

CLAUDE.md の @ による取り込み（import）は、別ファイルの内容を CLAUDE.md から読み込ませる仕組みです。Claude Code は Anthropic の生成AIをターミナルなどで使うためのツールで、CLAUDE.md はそこで毎回読み込まれる指示ファイルです。この記事では、相対パスの基準、コードブロック内の扱い、連鎖、読み込みの確認と作業ディレクトリ外の参照という4点に範囲を絞ります。見出しの書き方などファイル全体の設計は CLAUDE.md の書き方ガイド に任せ、ここでは @ 行だけを扱います。

各挙動には、次の3区分のどれかを付けます。

  • 公式で確認：公式の memory 資料に記載がある
  • 公式に記載なし：公式の memory 資料に記載がない
  • 未実測：筆者が実機で結果を確かめていない。記載の有無とは別の軸で、この記事の実測はどの項目でも未実施

試すときは、本番の CLAUDE.md ではなく、検証専用の作業ディレクトリを新しく作ってください。

CLAUDE.md の @import の書き方と取り込まれる条件

@ の直後にファイルのパスを書くと、そのファイルの内容が CLAUDE.md と一緒に起動時に読み込まれます。

# プロジェクト概要
@docs/overview.md

# コーディング規約
@docs/style.md

相対パスの基準は @ を書いたファイルの位置

相対パスの基準は、作業ディレクトリではなく、@ を書いたファイルがある場所です。

次のツリーで考えます。

project/
├── CLAUDE.md        ← @docs/rules.md と書く
└── docs/
    ├── rules.md     ← @style.md と書く
    └── style.md

CLAUDE.md に書いた @docs/rules.md は、project/docs/rules.md を指します。一方、docs/rules.md の中に書いた @style.md は、基準が docs/ になるので project/docs/style.md を指します。@docs/style.md と書くと、project/docs/docs/style.md を探すことになります。

次の2つは、公式に記載を確認できていない項目です。

  • 上位のディレクトリを指す @../ が解決されるかどうか
  • .claude/ 配下のファイルやサブディレクトリの CLAUDE.md から書いた場合の基準

どちらも作業用のツリーで再現し、読み込みの確認手順（後述）で結果を見てください。

コードブロック内の @ が展開されない条件

コードフェンス（```で囲んだ範囲）とコードスパン（バッククォート1組で囲んだ範囲）の中の @ は、取り込みの対象になりません。パスを文章中で言及しただけの行が誤って展開されないための仕様と読めます。

書き分けると次のようになります。

目的 書き方 結果
ファイルを取り込みたい フェンスの外に @docs/style.md と素の文字で書く 取り込まれる
パスを説明として載せたい バッククォートで囲む 展開されない

記述例として CLAUDE.md の一部をフェンスで囲み、その中に @AGENTS.md のような行を置いた場合、その行は展開されません。このとき画面にエラーや警告が出るかどうかは、未実測です。取り込んだつもりのファイルが効いていないときは、該当の @ 行がフェンスやバッククォートの内側に入っていないかを見ます。

import の連鎖（再帰）と深さの上限

取り込んだファイルが、さらに別のファイルを取り込む連鎖は可能です。深さの上限は版によって記載が変わる可能性があるため、自分の版の公式 memory 資料で、数字と数え方（CLAUDE.md から最初のファイルまでを1段と数えるかなど）を確認してください。上限を超えた先がどう見えるかは、公式に記載のない項目です。

自分で確かめるなら、作業用ディレクトリに a.md から順に次のファイルを取り込む短い連鎖を作ります。段数を少しずつ増やし、どの段のファイルまで読み込まれるかを見ます。各ファイルの先頭に識別用の一行を書いておくと、見分けやすくなります。

import したファイルが読み込まれたかの確認手順

確認には、/memory と /context を役割を分けて使います。公式memory資料では、/memory は編集対象のメモリファイルの場所を一覧にし、まだ存在しないファイルの場所も表示すると説明されています。一覧に出るだけで読み込み成功とは判断できません。現在のセッションで読み込まれたCLAUDE.mdやルールは、/context の Memory files を確認します。

  1. 作業用ディレクトリで、CLAUDE.md に @ 行を1本だけ書きます。
  2. 新しいセッションで Claude Code を起動します（編集後に再起動が必要かどうかは未実測です）。
  3. /memory を実行し、編集対象のCLAUDE.mdの場所を確認します。
  4. /context の Memory files を見て、現在のセッションで読み込まれた指示ファイルを確認します。
  5. import先の表示方法はこの記事では未実測です。読み込みを確認できなければ、後述の逆引き表から原因の節へ戻ります。

確認した日付と claude --version の出力を自分用のメモに残しておくと、後日の再検証に使えます。

作業ディレクトリの外を指す import と承認

作業ディレクトリの外に解決される import は、プロジェクトで初めて見つかったときに承認が求められます。拒否した場合、その import は無効のままになります。

他人から受け取った CLAUDE.md や、コミット前、レビュー前の CLAUDE.md では、外部を指す @ 行がないかを見ます。見るのは @ 行と、その行が実際に指す解決先で、解決先が作業ディレクトリの外にあたるかどうかを確認します。

次の項目は、この記事では断定できません。

  • 拒否したあとの表示や、承認ダイアログが再び出るかどうか（未実測）
  • ユーザー階層のファイル（~/.claude/CLAUDE.md など）に承認が出るかどうか（この記事の対象外）

情報の扱いの判断は 運用ルールのガイド に、設定キーの話は settings.json のガイド にまとまっています。

うまく動かないときの逆引き表

症状から原因の節へ戻るには、次の表を使います。

症状 疑う原因（戻り先） 根拠区分 読者の検証方法
取り込んだはずの指示を /context で確認できない フェンス・コードスパン内に書いている（コードブロックの節） 展開されない点は公式で確認 該当行がコードブロックの外にあるか見る
別ディレクトリのファイルから書いたら解決されない 基準パスの取り違え（相対パスの節） 公式で確認 書いたファイルの位置から見た相対パスになっているか確認する
@../ で上位を指すと解決されない 上位参照の扱いが不明（相対パスの節） 公式に記載なし・未実測 作業用ツリーで再現し、/context で読み込みを確認する
深い階層の先のファイルだけ出ない 連鎖の上限（連鎖の節） 数字は要確認、超過時の挙動は未実測 段数を段階的に増やして、一覧に出る範囲を見る
作業ディレクトリ外のファイルが出ない 承認が未了、または拒否した（外部参照の節） 承認の存在は公式で確認、拒否後の見え方は未実測 解決先が作業ディレクトリの外かを確認し、公式の手順を見る

まとめ：@ 行を1本選んで確認する

まずは自分の CLAUDE.md から @ 行を1本選び、/context で現在のセッションに読み込まれた指示ファイルを確認してください。この記事の手順は、基準パス、コードブロック内の判定、読み込み確認を試すときの例として使えます。

この記事のように @ 行の挙動を自分で確かめる習慣を身につけたい方には、月額1,980円からの学習コミュニティ「AI駆動ラボ」があります。自分で使いこなすために学ぶ場として、活用してください。

参照資料

確認日：2026年10月3日。公式の記載と手元のバージョンの表示が一致するかは、読者自身の環境で確かめてください。

CONTINUE THE SESSION

関連記事