ホーム / チュートリアル / Claude Code をモノレポ・大規模コードベースで使う設定

Claude Code をモノレポ・大規模コードベースで使う設定

Claude Code エンジニアリング 7分で読めます

Claude Code はどんな規模のリポジトリでも動きますが、コードベースが大きくなると、小さなプロジェクト向けの既定の動きのままでは、作業と関係のない指示やファイルの読み込みでコンテキストウィンドウが埋まり、トークンを消費して性能も落ちます。この記事では、公式ドキュメント「Set up Claude Code in a monorepo or large codebase」に沿って、パッケージが多いモノレポや数百万行の単一リポジトリで、Claude が触る範囲を作業中のコードに絞る設定を順に説明します。各設定は独立しているので、自分のリポジトリに合うものだけを組み合わせて使えます。

以降の例は、公式ドキュメントと同じく3つのパッケージを持つモノレポを前提にします。単一の大きなリポジトリなら、packages/api/ を src/backend/ のような自分のサブシステムのディレクトリに読み替えてください。

monorepo/
  CLAUDE.md                     # リポジトリ全体の指示
  packages/
    api/
      CLAUDE.md                 # API 固有の指示
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # フロントエンド固有の指示
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # 共有ライブラリの指示
      src/

起動ディレクトリと CLAUDE.md の階層化

どこで claude を起動するか

claude を起動する場所によって、追加の許可なしに読み書きできるファイル、起動時に読み込まれる CLAUDE.md、適用されるプロジェクト設定が決まります。ほかの設定ファイルの置き場所もこれで変わるので、最初に決めておきます。

起動する場所ファイルへのアクセス起動時に読み込まれる CLAUDE.md向いている場面
リポジトリのルートすべてのファイルルートのみ。サブディレクトリの分は必要になった時点で読み込む作業が複数のパッケージにまたがる
サブディレクトリそのサブツリーだけ（追加で許可するまで）そのディレクトリと、すべての祖先ディレクトリの分作業が1つのパッケージに収まる

注意点として、.claude/settings.json のプロジェクト設定は CLAUDE.md と違って親ディレクトリから継承されません。

CLAUDE.md をディレクトリごとに分ける

ルートに CLAUDE.md を1つだけ置くと、全サブシステムの規約を抱えて肥大化するか、汎用的すぎて役に立たないかのどちらかになりがちです。公式がよくある分け方として挙げるのは次の2階層です。

たとえばルートには「パッケージのスクリプトはモノレポのルートではなくパッケージのディレクトリで実行する」「コミットの件名にパッケージ名を付ける」、packages/api/CLAUDE.md には「マージ済みのマイグレーションは編集せず新しく追加する」といった API 固有の規約を書きます。packages/api/ から起動すると、ルートと packages/api/CLAUDE.md の両方が読み込まれ、packages/web/ の指示はコンテキストに入りません。どのファイルが読み込まれたかは /context を実行し、Memory files の一覧で確認できます。CLAUDE.md の読み込み順そのものはCLAUDE.md の記事で詳しく説明しています。

これらのファイルはリポジトリにコミットしてチームで共有し、各ディレクトリの担当者が保守するのが一般的です。公式は、プルリクエストでほかのドキュメントと同じようにレビューすること、大きなモデルのリリース後に古いモデル向けの回避策を見直すことを勧めています。

ディレクトリ別 CLAUDE.md とパス指定ルールの違い

方法置き場所読み込まれるタイミング向いている場面
ディレクトリ別 CLAUDE.mdそのディレクトリ内（コードと同じ場所）そこから起動したとき、または必要になった時点ディレクトリの担当者が自分の規約を保守する
.claude/rules/ のパス指定ルールリポジトリのルートの .claude/paths: のグロブに一致するファイルを扱うとき規約を1か所にまとめたい、同じルールを散らばったパスに適用したい

関係ない CLAUDE.md を除外する（claudeMdExcludes）

ルートから起動すると、作業中に触れたサブディレクトリの CLAUDE.md が読み込まれていきます。他チームのパッケージやレガシーコードなど、自分が作業しない場所の CLAUDE.md は claudeMdExcludes 設定でパスやグロブを指定して読み込ませないようにできます。自分だけに適用するなら .claude/settings.local.json に書きます（手で作る場合は自分で gitignore に追加します）。

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

パターンは絶対パスに対するグロブとして照合されるため、相対的に書きたい場合は **/ から始めます。この例では packages/web/ 配下の CLAUDE.md とルールファイルがすべて読み込まれなくなります。ほかにも "**/packages/*/CLAUDE.md"（ルートは残して各パッケージの分だけ除外）のような書き方ができます。組織の管理ポリシーの CLAUDE.md は除外できません。この設定はユーザー・プロジェクト・ローカル・管理のどのスコープにも書け、配列はスコープ間でマージされます。除外リストは固定のもので、作業ごとの切り替えには向きません。日によって対象のパッケージが変わるなら、そのパッケージのディレクトリから起動する方が適しています。

Claude が読む範囲を減らす

生成コードやベンダーコードの読み込みを禁止する

Claude の内容検索は既定で .gitignore を尊重するので、node_modules/・dist/・build/ のように gitignore 済みのパスは検索結果に出てきません。一方、ベンダリングした SDK やコミット済みの生成コードのようにリポジトリに含まれているパスは、permissions.deny に Read の deny ルールを書いて開けないようにします。

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

ディレクトリのパターンを /** ではなく /**/* で終えているのは、ディレクトリの中身だけを対象にしてディレクトリ自体は対象外にするためです。こうすると Claude は ls dist や cd build のような一覧表示や移動はできます。

ルールを書くファイルで適用範囲が変わります。

deny ルールが効くのは Claude の組み込みファイルツールと、Bash で Claude Code が認識するファイル操作コマンド（cat・head・grep・find など）の引数やリダイレクト先に禁止パスが現れた場合です。ただし grep -r や find で禁止ファイルを含むディレクトリ全体を検索すると、その出力には含まれます。また、ファイルを自分で開くサブプロセスには効きません。ルールの書式は設定と権限の記事も参考になります。

コードインテリジェンスでファイルの読み込みを減らす

大きなコードベースでは、シンボルの定義や呼び出し元を探すだけで多数のファイル読み込みや grep が発生します。コードインテリジェンスのプラグインは Claude を言語サーバーにつなぎ、ツリーを走査する代わりに定義へのジャンプ、参照の検索、型エラーの表示を直接行えるようにします。公式マーケットプレイスには TypeScript・Python・Go・Rust などのプラグインがあり、ターミナルでは Claude Code のプロンプトで次のように入力してインストールします。

/plugin install typescript-lsp@claude-plugins-official

Marketplace "claude-plugins-official" not found と出た場合は /plugin marketplace add anthropics/claude-plugins-official でマーケットプレイスを追加してから再実行します。リポジトリの全員に有効にしたい場合は、プロジェクト設定の enabledPlugins に追加します。各開発者のマシンにその言語の言語サーバー本体が必要な点に注意してください。

worktree とディレクトリのアクセスを絞る

必要なディレクトリだけをチェックアウトする（sparsePaths）

--worktree フラグを付けるとセッションが新しい git worktree で始まり、変更がメインのチェックアウトから分離されます（worktree の記事参照）。既定ではリポジトリ全体がチェックアウトされますが、worktree.sparsePaths を設定すると git の sparse-checkout を使って、指定したディレクトリとルート直下のファイルだけをディスクに書き出します。worktree の作成が速くなり、容量も節約できます。

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

この設定はサブエージェントを worktree で分離して動かすときに特に効きます。1つのセッション内の worktree はすべて同じ sparsePaths を共有するので、サブエージェントごとに必要なパッケージが違う場合は両方を列挙します。なお、これらの設定は worktree を作る前に起動したディレクトリから読まれ、作成後のセッションの作業ディレクトリは worktree のルートになります。worktree 内で必要な権限ルールやフックは、リポジトリのルートの .claude/settings.json に置いてください。

ほかのパッケージやリポジトリへのアクセスを許可する

packages/api/ から起動した Claude は、そのディレクトリ内しか読み書きできません。共有の型を変えて api と web の両方を直すような作業では、兄弟ディレクトリへのアクセスを許可します。方法は設定ファイルの additionalDirectories か、起動時の --add-dir フラグです。

{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}
claude --add-dir ../shared

相対パスは起動したディレクトリを基準に解決されます。どちらの方法でもファイルの読み書きはできますが、追加したディレクトリの CLAUDE.md やスキルが読み込まれるかは方法によって違います。

追加の方法CLAUDE.md とルールスキル
additionalDirectories 設定読み込まない読み込まない
--add-dir フラグ / /add-dir コマンド環境変数を設定したときだけ読み込む

--add-dir で追加したディレクトリの CLAUDE.md も読み込みたい場合は、CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared のように環境変数を付けて起動します。この環境変数は additionalDirectories 設定には効きません。

ディレクトリ別スキルと集約の考え方

パッケージごとにスキルを置く

サブディレクトリは、自分のスタック専用のスキルを .claude/skills/ に持てます。スキルは関係があると Claude が判断したときにだけ読み込まれるので、API 用のスキルがフロントエンドの作業中にコンテキストを使うことはありません。

mkdir -p packages/api/.claude/skills/api-testing

作成したディレクトリに SKILL.md を置き、frontmatter の description に「packages/api/ のテストを書く・直すときに使う」のような用途を書いて、本文にテストの配置・実行方法・ヘルパー・書き方の決まりをまとめます。packages/web/.claude/skills/component-patterns/ のように別のパッケージにも同じ形でスキルを置けば、それぞれのパッケージで作業するときに対応するスキルだけが読み込まれます。置き場所ではなくファイルのパターンで絞りたい場合は、スキルの paths frontmatter にグロブ（例: **/migrations/**）を指定します。

スキルを見つけやすく保つ

スキルが多くのディレクトリに散らばると、Claude が選ぶ候補の一覧が大きくなります。対象になるスキルは起動場所で変わります。

スキルが多いと一部のスキルは説明文が省かれ、判断の手がかりになるキーワードが失われることがあります。説明文は短くし、依頼に含まれそうな語を先頭に置くのが公式の勧めです。PR の規約やデプロイのチェックリストのように多くのディレクトリで使うスキルはルートの .claude/skills/ に置き、リポジトリをまたいで使う場合はプラグインにまとめます。プラグインのスキルは plugin-name:skill-name の名前空間を持つので、ディレクトリ別スキルと名前が衝突しません。

階層化で回らなくなったら集約する

ディレクトリ別の CLAUDE.md が増えると、規約のずれや更新漏れが起きやすくなります。公式は、常に読み込まれる CLAUDE.md から、必要なときだけ読み込まれる仕組みへ移すことを勧めています。

なじみのない領域で作業を始めた人に適切なプラグインを知らせるには、SessionStart フックが使えます。フックが標準出力に出したテキストは最初のプロンプトの前に Claude のコンテキストへ追加されるので、起動ディレクトリからプラグインを引く対応表を読み、おすすめを出力するスクリプトを登録しておく方法を公式は例に挙げています。

設定をまとめた例とパッケージ横断の変更

ここまでの設定を組み合わせた公式の例です。packages/api/ から起動する開発者全員が同じ設定を使えるよう、packages/api/.claude/settings.json にコミットします。サブディレクトリの設定ファイルはルートの設定を継承しないため、それ単体で完結させます。

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  },
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ],
    "deny": [
      "Read(./**/dist/**/*)",
      "Read(./**/build/**/*)"
    ]
  }
}

packages/api/ から起動すると兄弟パッケージの CLAUDE.md は最初から対象外なので、ここでは claudeMdExcludes は不要です。一方、この設定から作った worktree の中では作業ディレクトリが worktree のルートになりこのファイルは読まれないため、deny ルールの写しをリポジトリのルートの .claude/settings.json にも置きます。こうしておくと、packages/api/ から起動したセッションは次のように動きます。

複数パッケージにまたがる変更の進め方

共有の型とそれを使う全呼び出し箇所を一度に直すような変更では、作業の進め方も結果に影響します。公式が挙げるコツは2つです。

コードベースの規模がトークン使用量に与える影響はコスト管理の記事も参考になります。

本記事は Anthropic 公式ドキュメント「Set up Claude Code in a monorepo or large codebase」に基づく非公式の日本語解説で、設定名は「How Claude remembers your project」と設定リファレンスでも確認しています（確認日 2026-10-09）。仕様は更新される場合があるため、利用前にSet up Claude Code in a monorepo or large codebaseとHow Claude remembers your projectをご確認ください。

関連チュートリアル / 次に読む

CLAUDE.md で Claude Code にプロジェクトを記憶させる worktree で Claude Code を並列実行する Claude Codeの設定と権限を管理する スキルとは何か？ コストを効果的に管理する
← チュートリアル一覧へ戻る カテゴリで探す