結論：モノレポでClaude Codeを使うコツは「全部読ませない」こと。複数パッケージが同居するリポジトリでは、まず構成と依存関係を説明させ、変更の影響範囲を把握し、作業対象パッケージのディレクトリからClaude Codeを起動して読ませる範囲を絞り、ビルド/テストも対象だけに限定し、各パッケージのCLAUDE.mdに規約を書く——この5ステップでコンテキストの肥大とトークン浪費を防げます（2026年6月時点）。
- 要点1：モノレポは「1リポジトリ＝1コンテキスト」ではない。読ませる範囲を意図的に絞るほど精度もコストも改善する
- 要点2：あるパッケージの変更が他にどう波及するかは、AIに推測させず「依存元を列挙して」と実コードで検証させる
- 要点3：パッケージごとのCLAUDE.mdとビルド/テストのスコープ指定が、モノレポ運用の効きどころ
対象読者：npm/pnpm workspaces・Turborepo・Nxなどで複数パッケージを1リポジトリにまとめている開発者・テックリード。今日やること：作業対象パッケージのディレクトリからClaude Codeを起動し、そのパッケージ用のCLAUDE.mdを1枚書く。
正直、モノレポでClaude Codeを使い始めた頃は「リポジトリ全部を一度に把握してくれるんでしょ」と期待して、リポジトリのルートから雑に「このアプリ直して」と投げていました。結果、`packages/web`を直したいだけなのに`packages/api`や`packages/shared`のファイルまで読み込まれてコンテキストが膨らみ、トークンを食う割に的外れな変更を提案される——という状態に。モノレポは「広いから速い」ではなく「広いから絞る」が正解だと、痛い目を見て学びました。この記事では、複数パッケージのモノレポをClaude Codeで効率よく扱う実践ワークフローを、指示例（プロンプト）とコード例付きで5ステップに分けて解説します。
そもそもモノレポでClaude Codeが詰まる理由
Claude Codeは小規模プロジェクト向けにチューニングされたデフォルト設定で動きます。Anthropicの公式ドキュメント「Set up Claude Code in a monorepo or large codebase」でも、コードベースが大きくなるとデフォルトのままでは「タスクと無関係な命令やファイル読み込みでコンテキストウィンドウが埋まり、トークンを消費しClaudeのパフォーマンスを下げる」と明記されています。
モノレポ特有の事情を整理すると、詰まりどころは大きく3つです。
- パッケージ間の依存が見えにくい：`packages/web`が`packages/shared`に依存している、といった関係はファイルを横断しないと分からない
- 変更の波及範囲が広い：共有パッケージを1行直すと、それを使う複数アプリに影響が出る
- ビルド/テストが重い：リポジトリ全体をビルド・テストすると時間がかかり、AIの確認ループも遅くなる
本記事は、既存の「大規模コードベースを理解する」記事が扱う”1つの巨大ツリーをどう読み解くか”とは別軸で、「複数パッケージ・依存関係・影響範囲・ビルド/テストの絞り込み」というモノレポ固有の論点に絞って書きます。公式ドキュメントも「数百万行の単一リポジトリ」と「多数のパッケージを持つモノレポ」を両方”大規模コードベース”として扱っており、設定の考え方は共通しつつ、モノレポではパッケージ境界という明確な区切りを活かせるのが特徴です。
ステップ1：モノレポの全体像をClaude Codeに説明させる
最初にやるのは、自分が把握するためではなく「Claude Codeに今のリポジトリ構成を言語化させて、認識のズレを潰す」ことです。AIが構成を誤解したまま作業すると、依存関係の取り違えにつながります。
まずはパッケージ構成と依存関係を説明させるプロンプトから。
このリポジトリはモノレポです。以下を整理して教えてください。
1. ルート直下のワークスペース設定（package.json の workspaces / pnpm-workspace.yaml / turbo.json / nx.json のどれを使っているか）
2. packages/ 配下にどんなパッケージがあり、それぞれの役割は何か
3. 各パッケージの依存関係（どのパッケージがどのパッケージを import しているか）
推測は避け、実際のファイル（package.json の dependencies、import 文）を根拠に答えてください。
根拠にしたファイルパスも併記してください。ここで重要なのは「推測を避け、実ファイルを根拠に」と明示することです。AIは聞かれると依存関係をそれっぽく”創作”してしまうことがあるので、`package.json`の`dependencies`や実際の`import`文を読ませて答えさせます。返ってきた依存グラフは、必ず自分でも`package.json`を開いて突き合わせてください——AIの理解は実コードで検証する、が鉄則です。
参考までに、Anthropic公式ドキュメントが例に使うモノレポ構成はこうなっています。
monorepo/
packages/
api/ # Node.js + Express + TypeScript + PostgreSQL の REST API
web/ # React + Vite + TypeScript + TailwindCSS のフロント
shared/ # api と web の両方が使う共通 TypeScript ユーティリティこの`shared`のような「複数パッケージから参照される共通パッケージ」が、後述する影響範囲把握のキモになります。npm/pnpmのworkspaces、Turborepo、Nxはいずれも「複数パッケージを1リポジトリで管理し、依存を解決してビルドを最適化する」点で目的は共通です。ツール固有の細かい挙動はバージョンで変わるので断定せず、公式ドキュメントで確認するのが安全です。
ステップ2：変更の影響範囲（波及）を把握する
モノレポで一番怖いのが「共有パッケージを直したら、知らないアプリが壊れた」というやつです。だから変更前に「この変更はどこに波及するか」をClaude Codeに洗い出させます。
影響範囲を把握する手順は次のとおりです。
- 変更したい対象（関数・型・コンポーネント）を1つに特定する
- その対象が「どのパッケージから・どこで使われているか」をClaude Codeに列挙させる
- 列挙された参照箇所が、変更によって壊れないか1つずつ確認させる
- 波及先のパッケージのテストも実行対象に含める（ステップ4で絞り込む）
影響範囲を列挙させるプロンプト例です。
packages/shared の formatCurrency 関数のシグネチャを変更したいです。
この変更の影響範囲を把握したいので、以下を実コードベースで調べてください。
1. formatCurrency を import しているファイルを全パッケージ横断で列挙
2. それぞれの呼び出し箇所で、引数・戻り値の使われ方を要約
3. シグネチャ変更で壊れる可能性がある箇所に印をつける
grep / 検索結果のファイルパスと行を根拠として示してください。ポイントは「全パッケージ横断で」と「実コードベースで」を必ず付けること。AIが「たぶんここで使われています」と推測で答えると見落としが出ます。返ってきた参照リストは、可能なら`grep -rn “formatCurrency”`を自分でも回して件数を突き合わせると安心です。共有パッケージの変更ほど、AIの列挙を鵜呑みにせず実コードで二重チェックする価値があります。
❌ 悪い例：「formatCurrencyを直して」とだけ伝え、AIが触ったパッケージしかテストしない
⭕ 良い例：先に影響範囲を列挙させ、波及する全パッケージをテスト対象に含めてから変更する
ステップ3：該当パッケージに絞って作業させる（コンテキスト管理）
ここがモノレポ運用で一番効く一手です。公式ドキュメントは「作業がそのパッケージに閉じているなら、リポジトリのルートではなくそのパッケージのディレクトリからClaude Codeを起動する」ことを推奨しています。
起動ディレクトリによって読み込まれる範囲が変わります。公式ドキュメントの整理では次のとおりです。
- リポジトリのルートから起動：ルート直下のCLAUDE.mdを読み、サブディレクトリのCLAUDE.mdは「そのディレクトリのファイルを読んだとき」に随時ロード。タスクが複数パッケージにまたがるときに向く
- サブディレクトリ（パッケージ）から起動：そのサブツリーと、その親ディレクトリのCLAUDE.mdだけが対象。作業が1パッケージに閉じているときに向く
たとえば`packages/api`の修正だけなら、こう起動します。
# 悪い例：リポジトリ全体が視野に入りコンテキストが膨らむ
cd monorepo
claude
# 良い例：作業対象パッケージから起動して範囲を絞る
cd monorepo/packages/api
claude`packages/api`から起動すると、Claude Codeは`packages/api/CLAUDE.md`とルートの`CLAUDE.md`を読み込み、`packages/web`の命令はコンテキストに入りません。これだけでトークン消費が下がり、無関係なパッケージへの誤変更も起きにくくなります。コンテキスト管理の基本はコスト・トークン最適化ガイドでも触れていますが、モノレポでは「起動ディレクトリ＝読ませる範囲」という形で特に効きます。
どうしても別パッケージや別リポジトリも同時に触りたい場合は、`–add-dir`オプション（または設定の`additionalDirectories`）で明示的に対象ディレクトリを足せます。「デフォルトは狭く、必要なときだけ広げる」という運用が、モノレポでは安定します。
# api を主軸にしつつ、shared も読み書き対象に加える
cd monorepo/packages/api
claude --add-dir ../sharedなお、他チームのパッケージなど「自分が一切触らないディレクトリ」のCLAUDE.mdは、`claudeMdExcludes`設定でロード対象から外せます。グロブパターンで指定でき、自分だけに効かせたいなら`.claude/settings.local.json`（gitignore対象）に書きます。ただし公式が注意するとおり、これは静的な除外リストであってタスク単位のスイッチではないので、「今日はapi、明日はweb」という切り替えは除外を編集するのではなく、そのパッケージのディレクトリから起動する方法で行うのが筋です。
ステップ4：ビルド/テストの対象を絞る
モノレポ全体をビルド・テストすると遅く、Claude Codeの「変更→テスト→修正」ループも間延びします。だから対象パッケージだけをビルド/テストするコマンドをAIに使わせます。
絞り込みの基本は、ワークスペースツールのフィルタ機能を使うことです（ツールによってオプション名は異なるので、お使いのツールの公式ドキュメントで確認してください）。
# pnpm workspaces の例：api パッケージだけテスト
pnpm --filter api test
# npm workspaces の例：web パッケージだけビルド
npm run build --workspace=packages/web
# Turborepo の例：api にスコープを絞る
turbo run test --filter=api
# Nx の例：web プロジェクトだけテスト
nx test webそのうえで、Claude Codeにテストの実行範囲を明示します。
packages/api の変更を検証したいです。
リポジトリ全体ではなく、api パッケージとその依存先（shared）のテストだけを実行してください。
コマンドは pnpm --filter を使い、実行前にどのコマンドを叩くか宣言してから実行してください。
失敗したテストがあれば、ファイルと行を示して原因を説明してください。「実行前にコマンドを宣言してから」と書くのがコツで、AIが全体テストを暗黙に走らせるのを防げます。テスト自動化そのものの設計は実践テクニック完全ガイドに詳しいですが、モノレポでは「対象＋依存先だけ」に絞るのが時短の決め手です。ステップ2で洗い出した波及先のパッケージは、必ずこのテスト対象に含めるのを忘れずに。
ステップ5：CLAUDE.mdにモノレポ規約を書く
最後は、ここまでのルールを毎回口頭で伝えなくて済むようCLAUDE.mdに規約として書き込むステップです。公式ドキュメントが推奨するのは「ルートに1枚」ではなく「ルート＋パッケージごと」の2層構成です。
- ルートのCLAUDE.md：リポジトリ全体に効く規約（ワークスペース構成、共通の命名規則、「コマンドはパッケージディレクトリから叩く」等）
- 各パッケージのCLAUDE.md（例：`packages/api/CLAUDE.md`）：そのパッケージ固有のスタック・規約
`packages/api`から起動すると、Claude Codeは`packages/api/CLAUDE.md`とルートの`CLAUDE.md`の両方を読み、`packages/web`の命令は読みません。これにより「全体規約＋作業中パッケージの規約だけ」がコンテキストに乗ります。ルートCLAUDE.mdの例はこんな感じです。
# Monorepo Conventions
このリポジトリは pnpm workspaces のモノレポです。packages/ 配下に api / web / shared があります。
## ワークスペース構成
- packages/api: Express + TypeScript の REST API
- packages/web: React + Vite のフロント
- packages/shared: api/web 共通のユーティリティ（変更時は両方への影響を確認）
## ルール
- コマンドはリポジトリのルートではなく、対象パッケージのディレクトリから実行する
- shared を変更したら、必ず api と web の両方をテストする
- パッケージ間の依存は shared → api/web の一方向のみ。逆方向 import は禁止
- ビルド/テストは pnpm --filter で対象パッケージに絞る
詳細は @README.md と各パッケージの package.json を参照末尾の`@README.md`のように、CLAUDE.mdは`@path/to/file`構文で他ファイルを読み込めます。公式ドキュメントには「`@README`でプロジェクト概要、`@package.json`で利用可能なnpmコマンドを参照する」という使い方が示されており、モノレポではルートや各パッケージの`package.json`を`@`参照させると、利用可能なスクリプトをAIが把握しやすくなります。
CLAUDE.mdの設計・運用の基本はCLAUDE.md設計・運用ガイドにまとめていますが、モノレポで特に意識したいのは次の3点です。
- 1ファイル200行以内：公式は「CLAUDE.mdは200行を目安に、長いと文脈を食い遵守率も下がる」とし、肥大化するならpath-scoped rules（`.claude/rules/`）への分割を勧めている
- 命名・依存ルールを明文化：「shared→api/webの一方向依存」のような規約を書いておくと、AIが逆方向importを提案するのを防げる
- 矛盾を放置しない：ルートと各パッケージのCLAUDE.mdで規約が食い違うと、AIはどちらかを任意に選ぶ。定期的に見直す
なお`.claude/settings.json`はCLAUDE.mdと違って親ディレクトリから継承されません。リポジトリのルートに置いた`settings.json`は「ルートから起動したとき」だけ効くので、パッケージから起動する運用なら設定の置き場所にも注意してください。
つまずきやすいポイントと回避策
実際にやってみて引っかかった点を、❌⭕形式で残しておきます。
- ❌ リポジトリのルートから全部やろうとする → ⭕ 作業が1パッケージに閉じるなら、そのパッケージのディレクトリから起動する
- ❌ 依存関係をAIの記憶（推測）で判断 → ⭕ 「実ファイル（package.json・import文）を根拠に」と明示し、自分でもgrepで突き合わせる
- ❌ 共有パッケージを直してそのパッケージだけテスト → ⭕ 先に影響範囲を列挙させ、波及する全パッケージをテスト対象に含める
- ❌ ルートCLAUDE.mdに全パッケージの規約を詰め込む → ⭕ ルート＋パッケージごとの2層に分け、各200行以内に保つ
もう1つ、`git worktree`を併用して複数パッケージを並行で進める手もあります。worktreeごとにgitignoreされた`CLAUDE.local.md`は作成したworktreeにしか存在しないため、共通の個人設定はホームディレクトリのファイルを`@~/.claude/…`でimportして共有する、という公式の作法を覚えておくと事故が減ります。並行開発の詳細はgit worktree並列開発ガイドを参照してください。
まとめ：モノレポは「絞る」で速くなる
モノレポでClaude Codeを効率よく使う鍵は、繰り返しになりますが「全部読ませない・対象だけ絞る」の一点に尽きます。①構成と依存を実コードで説明させ、②変更の波及範囲を列挙させ、③作業対象パッケージのディレクトリから起動して読ませる範囲を絞り、④ビルド/テストも対象＋依存先だけに限定し、⑤ルート＋パッケージごとのCLAUDE.mdに規約を書く。この5ステップで、コンテキストの肥大もトークン浪費も、無関係なパッケージへの誤変更も同時に抑えられます。
今日できる最小の一歩は、作業対象パッケージのディレクトリからClaude Codeを起動して、そのパッケージ用のCLAUDE.mdを1枚書くこと。まずは一番よく触るパッケージで試して、効きを実感してみてください。次回は、モノレポでサブエージェントを使ってパッケージ単位で並行作業を回す応用編を予定しています。
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援を手がける。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載7回執筆。
参考・出典
- Set up Claude Code in a monorepo or large codebase — Claude Code Docs（Anthropic公式）
- Manage Claude’s memory（CLAUDE.md / claudeMdExcludes / @import / .claude/rules）— Claude Code Docs（Anthropic公式）
- Common workflows — Claude Code Docs（Anthropic公式）
- Workspaces — pnpm 公式ドキュメント
- workspaces — npm Docs（公式）
- Turborepo Documentation（公式）
