Set up Claude Code in a monorepo or large codebase

一行要約

大規模コードベースでの目的は「タスクが触れる部分に Claude をスコープする」ことであり、最初に決めるべきはどこで claude を起動するか — それによってロードされる CLAUDE.md も、適用される設定ファイルも変わる。

要点

as the codebase grows, the defaults tuned for smaller projects can fill the context window with instructions and file reads unrelated to the task, costing tokens and degrading Claude’s performance. コードベースが大きくなるにつれ、小規模なプロジェクト向けに調整された既定値は、タスクと無関係な指示やファイル読み込みで context window を埋めてしまい、トークンを浪費して Claude の性能を落としうる。

設定の一覧（やりたいこと → 手段）

やりたいこと	手段
触っているコードの規約だけをロードする	ディレクトリごとの CLAUDE.md
触らないパッケージの CLAUDE.md を除外する	`claudeMdExcludes`
ビルド成果物・生成コード・vendored 依存を開かせない	`permissions.deny` の `Read` ルール
ファイル走査ではなく language server でシンボルを引く	code intelligence プラグイン
worktree で必要なディレクトリだけ checkout する	`worktree.sparsePaths`
兄弟パッケージや別リポジトリを同じセッションから触る	`--add-dir` / `additionalDirectories`
特定領域の手順を、関連するときだけロードする	ディレクトリごとの skill
多数の CLAUDE.md を1つの規約セットに置き換える	内部マーケットプレースの plugin

最初の判断 — どこで起動するか

起動場所	ファイルアクセス	起動時にロードされる CLAUDE.md	使うとき
リポジトリルート	全ファイル	ルートのみ。サブディレクトリのものは読んだときにオンデマンド	タスクが複数パッケージにまたがる
サブディレクトリ	そのサブツリーのみ（追加で許可するまで）	そのディレクトリと全祖先	作業が1パッケージに閉じている

Project settings in .claude/settings.json load only from your starting directory and are not inherited from parent directories the way CLAUDE.md files are. .claude/settings.json のプロジェクト設定は起動したディレクトリからのみロードされ、CLAUDE.md のように親ディレクトリから継承されることはない。

これが最も間違えやすい点。 CLAUDE.md は階層的に継承されるが、.claude/settings.json は継承されない。

CLAUDE.md を階層化する

2階層の分割が定番:

ルート CLAUDE.md — どこでも適用される規約、コミット規約、リポジトリ構成
サブディレクトリごとの CLAUDE.md — その領域のスタック固有の規約

現状維持のための3つの習慣:

pull request でレビューする — CLAUDE.md の編集も文書変更として扱う
大きなモデルリリースの後に見直す

instructions that worked around an older model’s limitation may become overhead once a newer model handles the case on its own. For example, a rule that forces single-file refactors can be deleted once the limitation is gone 古いモデルの限界を回避するために書いた指示は、新しいモデルがその状況を自力で扱えるようになると単なるオーバーヘッドになる。たとえば「リファクタリングは1ファイルずつ」と強制するルールは、その制約が消えれば削除できる。

Stop hook で更新を提案させる — hook はセッション transcript のパスを受け取るので、露呈したギャップが新鮮なうちに CLAUDE.md の更新を提案できる

ディレクトリ別 CLAUDE.md と path-scoped rule の使い分け

方式	ファイルの場所	ロードされるとき	使うとき
ディレクトリ別 `CLAUDE.md`	そのディレクトリ内、コードと並んで	そこから起動したとき、またはそこのファイルを読んだとき	ディレクトリのオーナーが自分の規約を保守する。指示がコードと一緒にバージョン管理される
`.claude/rules/` の path-scoped rule	リポジトリルートの中央の `.claude/`	rule の `paths:` glob にマッチするファイルを扱うとき	規約を1箇所にまとめたい、または同じルールが散在する多数のパスに適用される

読む量を減らす

.gitignore は既定で尊重されるので node_modules/、dist/、build/ は追加設定なしに検索結果から外れる。checked-in された生成コードや vendored SDK には Read deny ルールを使う。

Deny rules cover Claude’s built-in file tools and recognized Bash file commands, including cat, head, grep, and find, when a denied path is passed as an argument. They do not filter denied paths out of a recursive search’s output, and they do not cover arbitrary subprocesses that open files themselves. deny ルールは、拒否対象のパスが引数として渡されたとき、Claude の組み込みファイルツールと、cat、head、grep、find を含む、認識されている Bash のファイル操作コマンドに適用される。再帰的な検索の出力から拒否対象のパスを取り除くことはしないし、自分でファイルを開く任意のサブプロセスも対象外である。

deny ルールをどこに置くかで適用範囲が変わる:

リポジトリの全員 → .claude/settings.json にコミット（起動ディレクトリからしかロードされない点に注意）
自分だけ → リポジトリルートの .claude/settings.local.json（こちらは起動ディレクトリに関わらず、そのリポジトリ内の全 CLI セッションでロードされる）。ただし相対パターンは起動ディレクトリを基準にするので、サブディレクトリから起動するなら Read(//absolute/path/to/repo/vendor/**) のように // 絶対パスで書く
全員に強制 → managed settings

worktree のスパースチェックアウト

worktree.sparsePaths は git sparse-checkout で列挙したディレクトリ + ルート直下のファイルだけを書き出す。

パスは起動ディレクトリに関わらずリポジトリルートからの相対
ディレクトリを列挙する。個別ファイルは列挙しない
ルート直下のファイル（package.json、lock ファイルなど）は常に checkout される。ルート直下のディレクトリはされない → ルートの .claude/settings.json や .claude/skills/ を worktree 内で使いたいなら .claude をリストに入れる
subagent の worktree 隔離と特に相性が良い。セッション内の全 worktree が同じ sparsePaths を共有するので、1つが packages/api/ を、別のが packages/web/ を必要とするなら両方を列挙する
symlinkDirectories と併用して node_modules の重複を避ける

worktree 作成後、セッションの作業ディレクトリは worktree のルートになる。 したがって worktree 内の project settings は worktree ルートの .claude/settings.json からロードされる。worktree 内で必要な設定（permission ルール、hook など）はリポジトリルートの .claude/settings.json に置く。

追加ディレクトリと、何がロードされるか

追加方法	CLAUDE.md と rules	skills
`additionalDirectories` 設定	決してロードされない	決してロードされない
`--add-dir` / `/add-dir`	環境変数を設定したときのみ	ロードされる

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 で --add-dir 先の CLAUDE.md と rules をロードできる。additionalDirectories 設定にはこの環境変数は効かない。

skill を発見可能に保つ

どの skill がスコープに入るかは起動場所で決まる。

サブディレクトリから起動 — そのディレクトリ、全祖先、user、enterprise レベル
リポジトリルートから起動 — ルートの skill + セッション中に Claude が触れた全サブディレクトリの skill。数百に膨れうる
--add-dir で兄弟を追加 — その兄弟の skill もロードされる

Names always load, but descriptions are shortened when there are many, which can strip the keywords Claude uses to decide whether a skill applies. Keep descriptions short and lead with words a request would contain, like “writing or modifying tests in packages/api/”. 名前は常にロードされるが、数が多いと description は短縮される。そのため、Claude がその skill を使うかを判断する手がかりとなるキーワードが削られることがある。description は短く保ち、依頼に含まれそうな語を先頭に置け。たとえば「packages/api/ でテストを書く、または変更するとき」のように。

使われていない skill を見つける方法: OpenTelemetry の logs exporter を有効にし、OTEL_LOG_TOOL_DETAILS=1 を設定すると skill 名が redact されずに記録される。skill_activated イベントの skill.name が全呼び出しを記録し、invocation_trigger が「コマンド / Claude / 入れ子の skill のどれが呼んだか」を記録する。

階層化が破綻したら中央集権へ

Per-directory CLAUDE.md files can become hard to govern as the codebase grows. Conventions drift, files go stale, and no one owns the root. ディレクトリごとの CLAUDE.md は、コードベースが大きくなると統制が難しくなる。規約が食い違い、ファイルが古び、ルートを誰も持たなくなる。

常時ロードされる CLAUDE.md から、オンデマンドの機構へ移す — skills / plugins / MCP サーバ（既にコード検索や RAG インデックスを運用しているなら MCP ツールとして露出させ、ファイルを直接読ませない）。

SessionStart hook で適切な plugin を推薦する: 起動ディレクトリを hook 入力から読み、リポジトリにコミットした「パス → plugin」の対応表を引き、推薦を stdout に出す。stdout は最初のプロンプトの前に Claude の context へ入る。

パッケージをまたぐ変更

1セッションで変更全体を渡す — 共有の編集と全呼び出し箇所を一緒に渡すと、各編集の背後にある判断が一貫する
編集の前に計画をファイルに保存する — 長いセッションは途中で compaction されるが、保存した計画は会話履歴が消えても残る

そのまま使える具体例

例のモノレポ構成:

monorepo/
  CLAUDE.md                     # root instructions
  packages/
    api/
      CLAUDE.md                 # API-specific instructions
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # frontend-specific instructions
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # shared library instructions
      src/

ルートの CLAUDE.md（構成を教えることに徹する）:

This is a monorepo with three packages under packages/:
 
- packages/api: Node.js REST API with Express, TypeScript, and PostgreSQL
- packages/web: React frontend with Vite, TypeScript, and TailwindCSS
- packages/shared: shared TypeScript utilities used by both api and web
 
Run commands from the package directory, not the monorepo root.
Each package has its own tsconfig.json, package.json, and test suite.

パッケージの CLAUDE.md（コマンドと禁止事項を具体的に）:

This package is the REST API server.
 
- Run tests: `npm test` (uses Vitest)
- Run dev server: `npm run dev` (port 3001)
- Database migrations: `npm run migrate`
- Environment variables: copy `.env.example` to `.env`
 
API routes are in src/routes/. Each route file exports an Express router.
Database queries use Knex in src/db/. Never write raw SQL strings in route handlers.

他チームのパッケージを除外する（.claude/settings.local.json）:

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

よくあるパターン:

"**/packages/*/CLAUDE.md"        全パッケージの CLAUDE.md を除外し、ルートは残す
"**/packages/legacy-*/**"        glob にマッチする全パッケージを rules ごと除外
"/home/user/monorepo/legacy/CLAUDE.md"   絶対パスで1ファイルだけ除外

生成物と vendored コードを読ませない:

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

worktree のスパースチェックアウト + node_modules の symlink:

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

兄弟パッケージへのアクセス:

{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}

claude --add-dir ../shared
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared

パッケージ固有の skill:

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

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
---
 
## Test structure
 
Tests are in `src/__tests__/` mirroring the `src/` directory structure.
Each route file has a corresponding `.test.ts` file.
 
## Running tests
 
- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`
- Watch mode: `npm test -- --watch`
 
## Test utilities
 
- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()` for database tests
- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()` for authenticated endpoints
 
## Patterns
 
- Use `supertest` for HTTP assertions, not raw fetch
- Always wrap database tests in a transaction that rolls back
- Mock external services in `src/__tests__/mocks/`

code intelligence プラグインを入れる:

/plugin install typescript-lsp@claude-plugins-official
/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace update claude-plugins-official

すべてを組み合わせた最終形（packages/api/.claude/settings.json）:

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

worktree セッション用に、deny ルールをルートにも複製する（.claude/settings.json）:

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

原典で言及されている関連文書

memory — CLAUDE.md の階層とロード順、claudeMdExcludes
claude-code-best-practices — 調査を subagent に回して context を小さく保つ
skills — skill 一覧の文字数予算と description の切り詰め
costs — コードベース規模がトークン使用に与える影響
features-overview — CLAUDE.md / rules / skills の使い分け
context-window — compaction で何が生き残るか（計画をファイルに保存する理由）

未取得の派生リンク

https://code.claude.com/docs/en/worktrees — worktree と subagent の隔離
https://code.claude.com/docs/en/discover-plugins#code-intelligence — 言語別の code intelligence プラグイン
https://code.claude.com/docs/en/monitoring-usage#skill-activated-event — skill 利用の計測
https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start

ai-docs

エクスプローラー