Claude Media
claudeMdExcludesの設定手順 — モノレポで他チームのCLAUDE.mdを除外する
Claude Codeチュートリアル

claudeMdExcludesの設定手順 — モノレポで他チームのCLAUDE.mdを除外する

claudeMdExcludesはグロブパターンでCLAUDE.mdの自動読み込みを止める設定です。書ける場所ごとの効果範囲、除外できない対象、パターンが効かないときの原因を扱います。

読了目安 約11分

claudeMdExcludesは、settings.jsonに書く配列設定で、CLAUDE.mdの自動読み込みをファイル単位で止めます。数百のパッケージを抱えるモノレポでは、リポジトリルートから起動しただけで自分が触らないディレクトリのCLAUDE.mdまで次々に読み込まれ、コンテキストを消費します。対象のパスをこの設定に書けば、そのファイルは読み込み候補から外れます。

claudeMdExcludesとは何を除外する設定か

claudeMdExcludesは文字列配列の設定で、値はグロブパターンまたは絶対パスです。ここに書いたパターンに一致するCLAUDE.mdは、Claude Codeがメモリを読み込む段階でそもそも候補から外れます。

既定値は未設定で、この状態ではClaude Codeが見つけたすべてのCLAUDE.mdを読み込みます。除外の対象になるのはユーザー・プロジェクト・ローカルの各設定が管理するCLAUDE.mdだけです。組織がclaudeMd設定で配布するポリシー文字列は対象外で、管理者ポリシーとして注入された指示はclaudeMdExcludesをどう書いても必ず読み込まれます。

設定を書ける4つの場所と効果範囲

claudeMdExcludesはsettings.jsonの4つのファイルすべてに書けます。どこに書くかで、効果が及ぶ範囲がそのまま変わります。

設定ファイル効果が及ぶ範囲Git管理
~/.claude/settings.json(ユーザー)効果が及ぶ範囲自分の全プロジェクトで自分だけに適用Git管理されない
.claude/settings.json(プロジェクト)効果が及ぶ範囲リポジトリを開く全員に適用Git管理される(コミット対象)
.claude/settings.local.json(ローカル)効果が及ぶ範囲自分がこのリポジトリで作業するときだけGit管理されない
管理者設定(managed settings)効果が及ぶ範囲組織全体に強制配布Git管理IT管理者が配布

Claude Codeの設定は本来、同じキーが複数のファイルにあると上位のスコープの値だけが使われ、下位の値は消えます。優先順位は管理者設定・コマンドライン引数・プロジェクトローカル・共有プロジェクト・ユーザーの順です。ただし配列を値に持つキーはこの上書きルールの対象外で、claudeMdExcludesを含む多くの配列設定は上書きではなく合算されます。プロジェクト設定に書いた除外パターンが、ユーザー設定やローカル設定に書いた別のパターンで消えることはありません。この性質のおかげで、プロジェクト設定にチーム共通の除外パターンをコミットし、個々のメンバーがローカル設定に自分だけの除外を追加する、という運用が成立します。

自分専用に留めたい除外は.claude/settings.local.jsonに書きます。Claude Codeがこのファイルへ初めて設定を保存すると、そのファイルは自動でグローバルなgitignoreに追加されます。手書きで新規作成する場合は、自分でgitignoreへの追加が必要です。

モノレポで他チームのCLAUDE.mdを除外する設定手順

手順は3つです。

  1. 除外したいディレクトリを決める(自分が触らないパッケージ、レガシーコード、vendor配下など)
  2. 設定ファイルを選ぶ(チーム全員に適用するなら.claude/settings.json、自分だけなら.claude/settings.local.json)
  3. パターンを書いて保存する
{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

このパターンはpackages/web配下のCLAUDE.mdと.claude/rules/のルールファイルをまとめて除外します。ルートのCLAUDE.mdと、自分が作業するパッケージのCLAUDE.mdは影響を受けません。

書き方のバリエーションは次のとおりです。

除外したい対象パターン例
特定パッケージのCLAUDE.mdだけパターン例**/packages/web/**
全パッケージのCLAUDE.mdを除外しルートだけ残すパターン例**/packages/*/CLAUDE.md
名前が一致するパッケージ群パターン例**/packages/legacy-*/**
1ファイルだけ絶対パスで指定パターン例/home/user/monorepo/legacy/CLAUDE.md

どこに指示を書くかによって、除外パターンの当たり方が変わります。ディレクトリごとにCLAUDE.mdを置く方式は、Claude Codeがそのディレクトリを起動元にしたとき、またはそのディレクトリ内のファイルを読んだときに読み込まれ、ディレクトリの所有者が自分たちの規約をコードと一緒にバージョン管理したい場合に向きます。一方、.claude/rules/配下にまとめるpath-scopedルールはリポジトリルートの.claude/に集約され、ルールのpaths:グロブに一致するファイルをClaudeが扱うたびに読み込まれ、規約を1か所にまとめたい場合や、同じルールを散らばった複数のパスに適用したい場合に向きます。他チームの規約がこの2方式のどちらで管理されていても、除外パターンの書き方自体は変わりません。除外の対象はCLAUDE.mdだけでなく、.claude/rules/配下のルールファイルにも及びます。次の例は、上位フォルダのCLAUDE.mdと、他チームが管理するルールディレクトリをまとめて除外します。

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

.claude/rules/配下のファイルをシンボリックリンクでプロジェクト間に共有している場合は、リンクそのものが置かれたパスと、リンク先の実体パスのどちらにパターンを書いても除外できます。どちらか一方が一致すれば十分です。v2.1.239より前のバージョンでは、リンク先の実体パスに書いたパターンしか効きませんでした。

設定ファイルが読み込まれたかどうかは/statusで確認します。

/status

Setting sourcesの行に、そのセッションで読み込まれた設定ファイル(User settingsやProject local settingsなど)が一覧で出ます。ただし/statusが示すのは読み込まれたファイルの一覧までで、どのファイルがclaudeMdExcludesの値を決めたかまでは表示しません。JSONの構文が壊れていたり値がスキーマに合わないときはセッション開始時にダイアログか警告が出ますが、個別のキーだけが無効になっているケースを詳しく見たいときはclaude doctorを実行すると、Claude Codeが読み込みを拒否した設定の詳細を確認できます。

claudeMdExcludesにできないこと

claudeMdExcludesが止めるのは、Claudeが自動でファイルを読みにいったときのCLAUDE.mdの追加読み込みだけです。次の3つはできません。

除外リストは静的で、タスクごとの切り替えには向きません。今日はpackages/apiだけ見て明日はpackages/web、という日替わりの使い分けをしたいなら、除外設定を書き換えるより、そのディレクトリからclaudeを起動するほうが単純です。起動場所を含めた全体設計はClaude Codeのコンテキスト管理で扱っています。

もう1つは、claudeMdExcludesとファイルの読み取り禁止は別の仕組みだという点です。claudeMdExcludesが制御するのは、Claude Codeが自動で行うCLAUDE.mdの読み込みだけです。ファイルの読み取りそのものを禁止したい場合は、permissions.denyにReadルールを別途追加します。

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/vendor/**/*)"
    ]
  }
}

permissions.denyのRead拒否ルールは、Claude組み込みのRead・Grep・Globツールを対象にします。Bash経由でも、cat・grep・findのように該当パスを引数に取るコマンドや、< fileのようなリダイレクトの対象になった場合は適用されます。ただしgrep -rやfindでディレクトリを再帰的に検索したときは、拒否対象のファイルが結果に含まれてしまうことがあり、Grep・Globツールについても除外はbest-effort(確実な保証ではない)止まりです。claudeMdExcludesで除外したCLAUDE.mdや.claude/rules/のパスをそのままpermissions.denyにも書けば、自動読み込みと明示的な読み取りの両方を止められます。このルールも.claude/settings.json(リポジトリを開く全員に適用)、.claude/settings.local.json(自分だけ)、管理者設定(組織全体に強制)のいずれに書くかで適用範囲が変わり、スコープの考え方はclaudeMdExcludesと共通です。claudeMdExcludesが扱うのはCLAUDE.mdと.claude/rules/のルールファイルだけですが、permissions.denyのRead拒否ルールはビルド生成物やvendor配下のコードそのものにも書けます。除外したいディレクトリにメモリファイルとコードの両方が含まれる場合は、この2つを組み合わせることで、自動読み込みとコード自体の読み取りの両方を1か所ずつ塞げます。

claudeMdExcludesと一時的な無効化手段の違い

CLAUDE.mdを読み込ませない方法はclaudeMdExcludesだけではありません。恒久的に除外するか一時的に疑うだけかで使い分けます。

方法効果適用範囲向いている場面
claudeMdExcludes効果指定したファイルだけを除外適用範囲設定した範囲で恒久的向いている場面他チームのパッケージなど、触らないディレクトリを継続的に無視する
CLAUDE_CODE_DISABLE_CLAUDE_MDS=1効果ユーザー・プロジェクト・自動メモリを含めCLAUDE.mdを一切読み込まない適用範囲環境変数を立てている間ずっと向いている場面CLAUDE.mdの影響を完全に排除して挙動を検証する
--bare効果CLAUDE.mdを含む自動検出全般をスキップ(高速化目的)適用範囲そのセッションだけ向いている場面スクリプトからの呼び出しを高速化する
--safe-mode効果管理者ポリシーのCLAUDE.mdも含めカスタマイズを丸ごと無効化適用範囲そのセッションだけ向いている場面CLAUDE.mdやフックが不具合の原因かを切り分ける

--safe-modeはclaudeMdExcludesと違い、管理者設定が配布したclaudeMdポリシーも読み込みません。認証・モデル選択・組み込みツール・パーミッションは通常どおり動くので、挙動がおかしいときに何が原因かを切り分ける用途に向きます。CLAUDE_CODE_DISABLE_CLAUDE_MDSはさらに絞り込んだ効果で、CLAUDE.md周りだけを丸ごと止めますが、スキルやフックはそのまま動きます。恒久的に特定ファイルだけ外したいならclaudeMdExcludes、CLAUDE.mdだけを疑うなら環境変数、それ以外のカスタマイズも含めて疑うなら--safe-modeという住み分けです。

よくあるつまずき — パターンを書いても除外されない

相対っぽいパターンが一致しないケースがあります。パターンは絶対パス全体に対して評価されます。packages/web/CLAUDE.mdのように、リポジトリからの相対パスのつもりで書くと、実際のパスの前方部分と一致せず素通りします。公式の例が**/packages/web/**のように必ず**/から始めているのはこのためです。相対的な書き方をするときは、先頭に**/を補います。

空配列や未設定のまま放置しているケースもあります。既定値は未設定で、この状態ではすべてのCLAUDE.mdが読み込まれます。除外リストを作ったつもりで設定ファイルにclaudeMdExcludesのキー自体を書き忘れていると、何も変わりません。保存後に設定ファイルを開き直し、キーとパターンが両方入っているかを確認します。

設定ファイル自体が読み込まれていないこともあります。パターンは正しくても、JSONの構文エラーや配置場所の間違いで設定ファイルごと無視されていることがあります。claudeMdExcludesに限らず設定が反映されない原因の探し方はClaude Code設定が反映されない原因の探し方にまとめています。

まとめ

claudeMdExcludesは、他チームのパッケージやレガシーコード、vendor配下など、自分が触らないディレクトリのCLAUDE.mdを自動読み込みの対象から外す設定です。書く場所によって効果範囲が変わり、プロジェクト設定とローカル設定を組み合わせれば、チーム共通のルールと個人の除外を両立できます。パターンが絶対パスに対して評価される点と、組織のポリシーやRead経由の読み取りまでは止められない点を踏まえておけば、設定でつまずく場面はほとんどなくなります。

CLAUDE.md自体の書き方はCLAUDE.mdを実用に引き上げる10のパターン、記憶の階層構造はClaude Code memoryの三層構造で扱っています。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →