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

claudeMdExcludesは、settings.jsonに書く配列設定で、CLAUDE.mdの自動読み込みをファイル単位で止めます。数百のパッケージを抱えるモノレポでは、リポジトリルートから起動すると、Claudeが他チームのディレクトリのファイルを読むたびにそこのCLAUDE.mdが追加で読み込まれ、コンテキストを消費します。上位フォルダのCLAUDE.mdは起動時に読まれます。対象のパスをこの設定に書けば、そのファイルは読み込み候補から外れます。

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

claudeMdExcludesは文字列配列の設定で、値はグロブパターンまたは絶対パスです。ここに書いたパターンに一致するCLAUDE.mdは、Claude Codeがメモリを読み込む段階でそもそも候補から外れます。祖先ディレクトリの探索そのものが遅いときは、autofs環境での起動の遅さも確認してください。

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

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

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

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

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

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

{
  "claudeMdExcludes": [
    "**/packages/web/**"
  ]
}

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

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

他チームの規約が置かれ方のどちらでも、除外パターンの書き方は変わりません。

次の例は、上位フォルダのCLAUDE.mdと、他チームが管理するルールディレクトリをまとめて除外します。

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

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

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

/status

Setting sourcesの行に、そのセッションで読み込まれた設定ファイル(User settingsやProject local settingsなど)が一覧で出ます。ただし/statusが示すのは読み込まれたファイルの一覧までで、どのファイルがclaudeMdExcludesの値を決めたかまでは表示しません。

起動時に読まれる上位階層のファイルは、/contextのMemory filesの一覧で除外を確認できます。サブディレクトリのCLAUDE.mdは、Claudeがそこのファイルを読んだときに初めて読み込まれます。起動直後に一覧に無くても、除外が効いているとは限りません。除外したディレクトリ内のファイルをClaudeに読ませてから/contextを見る方法があります。

InstructionsLoadedフックを使うと、どのファイルがいつ、なぜ読み込まれたかをログに残せます。読み込みの理由にはsession_start、nested_traversal、path_glob_match、include、compactがあります。

claudeMdExcludesにできないこと

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

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

ファイルの読み取りそのものを禁止したい場合は、permissions.denyにReadルールを別途追加します。

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

Read拒否ルールは、Bash経由でもcat・head・tail・sed・teeのようにClaude Codeが認識するファイル系コマンドと、リダイレクトの対象になったパスに適用されます。grep -r pattern .のようにパスを名指ししない検索や、ファイルを自分で開くPython・Nodeのスクリプトには効きません。Grep・Globツールの除外もbest-effort(確実な保証ではない)止まりです。

メモリファイルとコードの両方を含むディレクトリは、2つを併用します。claudeMdExcludesの対象パスを、そのままpermissions.denyにも書きます。適用範囲は、書く設定ファイルで決まります。.claude/settings.jsonなら全員、.claude/settings.local.jsonなら自分だけ、管理者設定なら組織全体で、考え方はclaudeMdExcludesと共通です。

祖先フォルダのCLAUDE.mdをまとめて外せない

claudeMdExcludesのパターンは絶対パスに対するグロブとして照合されます。「起動したディレクトリより上のCLAUDE.mdを、場所を問わず全部外す」という指定は書けない、という報告があります。起動ディレクトリ自身のCLAUDE.mdまで巻き込まずに祖先だけを狙うパターンがない、というのが報告者の主張です。ユーザー設定に**/CLAUDE.mdと書くと、作業中のプロジェクトのCLAUDE.mdも対象になるとされています。

配列は設定スコープをまたいで合算されるので、ユーザー設定に書いた広いパターンを、特定のプロジェクトのローカル設定から取り消すこともできません。GitHubでは、この制約を理由に「起動ディレクトリで止める」設定を求める要望がissue #93858として出ています。

祖先のCLAUDE.mdは、起動ディレクトリを変えても起動時に読み込まれます。除外するなら、**/monorepo/CLAUDE.mdのように祖先ごとにパスを書きます。

兄弟パッケージのCLAUDE.mdを読み込み範囲から外すだけなら、大規模リポジトリ向けの公式ガイドが示すとおり、作業するパッケージのディレクトリからclaudeを起動すれば足ります。兄弟パッケージは最初から範囲に入らないため、claudeMdExcludesは不要です。ルートからも起動するなら、リポジトリルートの.claude/settings.local.jsonに書き足します。

v2.1.285以前には、ワークツリーを分離したサブエージェントがプロジェクトのCLAUDE.mdを二重に読み込む不具合があり、issue #98052の報告を受けてv2.1.286で修正されました。

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

CLAUDE.mdを読み込ませない方法はclaudeMdExcludesだけではありません。恒久的に除外するか一時的に疑うだけかで使い分けます。特定のサブエージェントだけに絞って止めたいときはomitClaudeMdでサブエージェントに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の構文エラーや配置場所の間違いで設定ファイルごと無視されていることがあります。Claude Codeが拒否した項目はclaude doctorで一覧できます。claudeMdExcludesに限らず設定が反映されない原因の探し方はClaude Code設定が反映されない原因の探し方にまとめています。

まとめ

触らないパッケージのCLAUDE.mdが重いと感じたら、除外リストを書く前に、作業するパッケージのディレクトリから起動できないかを見ます。除外パターンの出番は、起動場所を変えても読まれる祖先のCLAUDE.mdと、ルートから起動する運用のときです。

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