複数のプロジェクトを一つのリポジトリで管理する「モノレポ」は、コードの共有や管理がしやすく非常に便利です。しかし、ターミナルで自律的に動くClaude Codeを導入した途端、最初の「Indexing…（インデックス作成中）」という表示から全く進まなくなり、頭を抱えてしまった方も多いのではないでしょうか。
この問題の多くは、AIが膨大なファイル数の波に飲み込まれていることが原因です。この記事では、なぜモノレポでスキャンが止まってしまうのか、その理由を解き明かし、わずか数秒で作業を開始できるようにするための設定や運用のコツを詳しく解説します。
なぜモノレポだとClaude Codeのインデックスは終わらないのか
モノレポ構成でClaude Codeを使い始めると、最初のインデックス作成がいつまで経っても終わらない現象に遭遇しがちです。これはAIがリポジトリ内の全ファイルを把握しようとして、数万を超えるファイル数の波に飲み込まれているのが主な要因です。本章では、スキャンが止まるメカニズムと、開発者が陥りやすい3つの罠を整理し、問題の根っこを明らかにします。
node_modulesの階層が深すぎてスキャンが迷子になる
モノレポでは、パッケージごとに独自の node_modules が存在することが多く、リポジトリ全体で見るとそのファイル数は膨大なものになります。Claude Codeは標準でこれらの中身まで把握しようと試みますが、ライブラリの海を一つひとつ探索していては、いつまで経っても終わりません。
特に依存関係が複雑に入り組んでいる場合、AIは「どのファイルが重要か」の判断がつかなくなり、スキャンのループから抜け出せなくなります。
本来、AIが知るべきなのは「あなたが書いたソースコード」であって、外部ライブラリの内部実装ではありません。
- パッケージごとの
node_modulesが重複している。 - ライブラリ内の深すぎるディレクトリ構造。
- 使っていない古いパッケージの残骸。
このように、整理されていない「重い」フォルダが複数あるだけで、インデックス作成の難易度は跳ね上がります。AIに自由を与えすぎず、まずは視界を狭めてあげることが不可欠です。
ビルド生成物やキャッシュが大量に紛れ込んでいる
開発を進める中で自動生成される dist や build、あるいは各種フレームワークのキャッシュ用フォルダも、スキャンを遅延させる大きな原因です。これらはテキストデータではあっても、人間が直接読み書きするものではないため、AIが学習する必要は全くありません。
モノレポではこれらのフォルダが各プロジェクトに点在しているため、意識的に除外しないとAIの処理コストを奪い続けます。
AIが機械的なコードの羅列（ビルド後のファイル）を読み込もうとすると、無駄なリソースを消費するだけでなく、回答の精度を下げる原因にもなりかねません。
例えば、以下のファイル群は真っ先に除外を検討すべきです。
| 除外すべき対象 | 理由 | スキャンへの影響 |
| ビルド生成物 | .next や dist はファイル数が多く、中身が複雑。 | 処理が数分単位で遅れる。 |
| キャッシュ | .turbo や eslintcache は頻繁に更新される。 | 差分検知の負荷が上がる。 |
| ログファイル | npm-debug.log などは解析に不要。 | 無駄なトークンを消費する。 |
依存関係のリンクを辿って無限ループに陥る
モノレポ特有の仕組みとして、パッケージ間でシンボリックリンク（ショートカットのようなもの）を多用することがあります。Claude Codeのスキャナーがこのリンクを辿り始めると、同じディレクトリを何度もぐるぐると回り続けてしまう「無限ループ」に陥るリスクがあります。
AIからすれば、リンクの先が新しい知識に見えてしまうため、終わりが見えない迷宮を歩き続けることになります。
特に pnpm や Yarn Berry を使っている環境では、このリンク構造が非常に複雑になるため、注意が必要です。
スキャンが終わらないのは、AIの能力不足ではなく、入り口と出口が繋がった迷路を渡してしまっているからです。
人間が先にリンクの「断絶」を指定してあげなければ、AIは永遠に「Indexing…」という看板を掲げ続けることになります。
解決の鍵を握る「.claudeignore」による除外設定
インデックス作成を爆速にする最も確実な方法は、AIに対して「見なくていい場所」をハッキリと伝えることです。そのために使うのが、Claude Code専用の設定ファイルである .claudeignore です。本章では、このファイルの基本的な作りかたと、Gitの除外設定との違いを解説します。これを導入するだけで、スキャン時間は分単位から秒単位へと劇的に短縮されるはずです。
.claudeignoreをルートディレクトリに用意する
まず、プロジェクトの最も上の階層（ルート）に .claudeignore という名前のテキストファイルを作成しましょう。使いかたは .gitignore とほぼ同じで、無視してほしいフォルダやファイルのパターンを一行ずつ書いていきます。
このファイルを作成した瞬間に、Claude Codeはスキャンのルールを読み込みます。
これまで無理に読み込もうとしていた巨大なディレクトリが視界から消えるため、AIは驚くほど軽快に動き始めます。
「とりあえず作成する」という一歩が、モノレポでのAI活用を成功させる最大の分かれ道です。
まずは空のファイルでも良いので作成し、後述する除外リストを書き込んでいく準備を整えてください。
Gitの除外設定とは別にAI専用のルールを作る
「すでに .gitignore があるから大丈夫だろう」と考えていませんか？
実は、Gitでは追跡したいけれど、AIには見せたくないというファイルは意外と多いものです。
例えば、プロジェクトの仕様書が詰まった巨大なPDFや、テスト用のダミーデータ（画像など）です。これらはGitで管理すべきですが、AIがインデックスに含めるとスキャンの重荷になります。
.claudeignore を使うメリットは、AIのためだけに最適化された「視界」を作れる点にあります。
開発の履歴管理（Git）と、AIの文脈理解（Claude Code）を切り分けて考えることで、よりスマートな開発環境が構築できます。
インデックスを劇的に軽くする記述のテンプレート
何を書けばいいか迷っている方のために、モノレポで効果を発揮する標準的な設定内容を紹介します。これをコピーして自分の環境に合わせて微調整するだけで、インデックス問題の大部分は解決します。
# 依存関係
**/node_modules
**/bower_components
# ビルド生成物
**/dist
**/build
**/.next
**/.turbo
# キャッシュとログ
**/.npm
**/.eslintcache
**/*.log
# バイナリとメディア
**/*.png
**/*.jpg
**/*.pdf
**/public/assets
この記述にある **/ という表現は、リポジトリ内のどの階層にあっても、その名前のフォルダを無視するという意味です。
モノレポでは各プロジェクトにこれらのフォルダが散らばっているため、この指定方法が非常に有効です。
まずはこの基本セットを導入し、AIがスムーズに起動することを確認してみましょう。
インデックス対象を絞り込む具体的な書きかた
設定ファイルを作ったら、次は内容をさらに絞り込みましょう。モノレポで特に「重い」とされる特定のディレクトリを狙い撃ちすることで、スキャン範囲を最小限までダイエットさせます。本章では、除外すべき優先順位の高い項目と、記述時の注意点を深掘りします。AIに見せる情報を「厳選」することが、最終的な回答の精度を上げることにも繋がります。
各パッケージ内のライブラリフォルダを隠す
モノレポ内の個別のパッケージ（ apps/web や packages/ui など）の下にある node_modules は、最も大きなノイズです。これらを一つずつ手動で除外するのは大変ですが、ワイルドカードを使えば一括で隠せます。
AIは「どのライブラリが使われているか」については package.json を読めば理解できます。
そのため、ライブラリの中身（ソースコードそのもの）を読み込ませる必要は、多くの場合ありません。
- ルートの
node_modules - 各パッケージ階層の
node_modules - ライブラリが生成する一時ファイル
これらを徹底的に排除することで、AIは「あなたが書いたコード」だけに集中できるようになります。
情報の密度が高まるため、AIからの提案もより的外れなものが少なくなります。
自動生成フォルダをすべて除外する
Next.jsやNuxt、Viteなどのモダンなツールを使っている場合、実行時に作られる .next や .nuxt などのディレクトリが巨大なファイル群を抱え込みます。これらはインデックス作成を停滞させる最大の「犯人」といっても過言ではありません。
これらのフォルダには、トランスパイル（変換）された後の読みづらいコードや、巨大なキャッシュデータが含まれています。
AIがここを読み込んでしまうと、処理が重くなるだけでなく、APIのトークン料金を無駄に消費することにも繋がります。
除外の徹底は、あなたのパソコンのメモリ消費を抑え、CPU負荷を軽減させる効果もあります。
AIに快適な作業場を提供するために、不要な自動生成フォルダは一つ残らず指定リストに加えましょう。
画像やログファイルなどのテキスト以外のデータを弾く
Claude Codeはテキストを解析するツールです。画像データ（png, jpg）やフォントファイル、音声データなどをいくら読み込ませても、AIは何の知見も得ることができません。
それどころか、これらのバイナリファイルはサイズが大きいため、インデックス作成の時間をいたずらに引き延ばします。
「publicフォルダ」や「assetsフォルダ」などは、中身がメディアファイル中心であれば丸ごと除外しても問題ありません。
以下の表は、除外設定を検討すべき拡張子の一覧です。
| カテゴリ | 対象となる拡張子 | 除外の推奨度 |
| 画像 | .png, .jpg, .svg, .gif | 高 |
| 動画 | .mp4, .mov, .webm | 最高 |
| 書類 | .pdf, .docx, .pptx | 中 |
| 圧縮 | .zip, .tar.gz, .rar | 最高 |
これらを .claudeignore に追記するだけで、インデックス作成の待ち時間はさらに短縮されます。
無駄な読み込みを削ることは、プロのエンジニアがAIを使いこなす上での基本技術です。
起動するディレクトリを工夫してスキャンを回避する
リポジトリのルート（一番上の階層）でClaude Codeを起動するのは、実はモノレポにおいては「最終手段」に近い行動です。作業する範囲が決まっているなら、あえて狭い範囲で起動することで、物理的にインデックスの対象を制限できます。本章では、起動場所を変えることによる運用メリットと、効率的なフォルダ移動の手順について解説します。
編集したいパッケージの階層まで移動してから起動する
モノレポ全体をAIに教えようとせず、今から修正するプロジェクトのフォルダまで cd コマンドで移動してから claude を起動しましょう。例えば、 apps/admin-web だけをいじりたいなら、その中で起動するのが最も賢明です。
こうすることで、他のプロジェクトのファイルは一切スキャン対象に入りません。
ファイル数が1/10になれば、インデックス作成も10倍速くなります。
AIの「記憶」を限定的に保つことは、AIの勘違い（別のプロジェクトのコードを参考にし始めるなど）を防ぐ効果もあります。
狭い範囲で深い推論をさせる。これが、大規模リポジトリにおけるAI運用の鉄則です。
ループを避けるために読み込み範囲を限定して指示する
もしルートで起動しなければならない場合でも、指示を出す際に範囲を限定することが可能です。Claude Codeに対して「このディレクトリの中だけを見て修正して」と明示的に伝えるのです。
例えば、「 packages/shared の中にあるユーティリティ関数を使って、 apps/api の修正をして」といった具合です。
最初から全スキャンを待つのではなく、必要なタイミングで必要な場所だけをAIに「見せる」感覚を持ちましょう。
範囲外のファイルが修正に必要になったらどうすればいいでしょうか？
その場合は、AIが自ら「あのファイルも読む必要があります」と提案してくれます。
最初から全てを渡すのではなく、必要に応じてAIに「鍵」を渡していくイメージで進めるのが、最も効率的で間違いのない方法です。
必要な時だけルートに戻って全体をスキャンさせる
基本は各パッケージ内で作業し、大規模なリファクタリングやプロジェクトを横断する検索が必要な時だけ、ルートディレクトリに戻りましょう。
全体スキャンの頻度を下げることで、開発のリズムが崩れるのを防げます。
インデックス作成は「一度やれば終わり」ではなく、ファイルが大幅に変わるたびに更新の負荷がかかるため、ルートでの滞在時間は最小限にするのがコツです。
- 日常のコーディング：各プロジェクトフォルダ内で。
- 全体検索・大規模修正：ルートディレクトリで。
- 環境構築・パッケージ管理：ルートディレクトリで。
このように役割を明確に分けるだけで、モノレポでの開発体験は劇的に向上します。
場所を選んでAIを呼び出す。この一工夫が、あなたの時間を守ってくれます。
プロジェクト構成を見直してAIの読み込みを助ける
設定や起動場所の工夫だけでなく、プロジェクトの「作りかた」そのものをAIフレンドリーに変えることも検討しましょう。AIが迷わない、読み込みやすい構造にすることは、実は他の開発メンバーにとっても読みやすいリポジトリを作ることと同じです。本章では、AIの読み込みを助けるための整理術と、保守性の高いディレクトリ管理について深掘りします。
ディレクトリ構造をシンプルに保つ
階層が深すぎるディレクトリ構造は、AIにとっても人間にとっても情報の把握を困難にします。特にモノレポでは、プロジェクトが重なり合うため、構造が複雑になりがちです。
AIは「パス（ファイルの住所）」を見て関連性を判断します。
あまりに深い入れ子構造は、AIの探索コストを上げ、最悪の場合は重要なファイルを見落とす原因になります。
できるだけフラットで、直感的な名前のディレクトリ管理を心がけましょう。
「どこに何があるか一目でわかる」状態は、AIのインデックス作成スピードを底上げします。
不要なサブディレクトリを減らし、役割ごとにファイルを整理することで、AIとの意思疎通はよりスムーズになります。
巨大なデータセットをリポジトリの外に置く
機械学習のモデルや巨大なCSV、JSONデータなどをリポジトリに含めていませんか？
これらはインデックスを最も重くする要因の一つです。
こうしたデータはAIがコードを書くための参考にはならないため、基本的にはリポジトリの外で管理するか、 .claudeignore で完全に除外すべきです。
もしコード上でそのデータを参照する必要があるなら、数行のサンプルデータだけを別ファイルで用意し、それをAIに見せるのが賢いやりかたです。
巨大な重荷を背負わせたまま「早く動け」と言うのは酷な話です。
AIには「考えるための素材（コード）」だけを与え、重い荷物（データ）は預けておきましょう。
依存関係の整理を徹底してスキャンエラーを防ぐ
使っていない古いパッケージや、各プロジェクトでバラバラに定義されたライブラリは、スキャン時の不整合を招きます。モノレポの健全性を保つことは、AIの動作を安定させることに直結します。
例えば、共有パッケージの workspace: 参照が壊れていたり、シンボリックリンクが正しく貼られていなかったりすると、AIはそのパスを解決できずにエラーを吐き出すことがあります。
- 定期的に
pnpm pruneなどで不要なライブラリを消す。 - 共有ライブラリのバージョンを統一する。
- 循環参照を避ける。
こうした「リポジトリの掃除」を怠らないようにしましょう。
清潔なリポジトリであれば、Claude Codeも迷うことなく最短ルートでインデックスを完了させることができます。
トークンコストも抑える！無駄なファイルを隠すコツ
インデックスの高速化は、作業効率だけでなく「お金（APIコスト）」にも大きく関わってきます。AIが読み込むファイルが減れば、それだけAPIに送信されるデータ量（トークン）も減るからです。本章では、コストを最小限に抑えながら、回答の精度を最大化するための賢い運用のコツを整理します。
入力トークンを節約して課金額を抑える
Claude Codeは従量課金制のAPIを利用しているため、指示を出すたびに読み込むファイルの量が料金に直結します。インデックスを最適化し、無駄なファイルを読み込ませないようにすることは、そのままお財布を守ることに繋がります。
「数秒待てばインデックスが終わるからいいや」と放置していると、知らぬ間に巨大なファイルを裏側で読み続け、一回の質問で数百円単位のコストが発生してしまうこともあります。
節約の意識を持つことは、AIへの指示をより明確にする訓練にもなります。
「今、本当に必要な情報は何か」を厳選してAIに渡すことで、最小限のコストで最高の結果を引き出しましょう。
必要なコンテキストだけを渡して回答の精度を上げる
AIに情報を渡しすぎると、かえって回答がぼやけてしまうことがあります。これを「コンテキストの汚染」と呼びます。
例えば、関係のない古いプロジェクトのコードがインデックスに含まれていると、AIが今のプロジェクトにそぐわない古い書き方を提案してしまうかもしれません。
.claudeignore で適切に情報を遮断することは、AIに「今取り組んでいる課題」に集中させるためのメンタルケアのようなものです。
情報を絞れば絞るほど、AIはあなたの意図を鋭く捉えるようになります。
「多すぎる情報は毒になる」という言葉を忘れずに、常に最適な情報の分量を意識しましょう。
プロンプトキャッシュが効きやすい状態を作る
AnthropicのAPIには、一度送った情報を再利用して料金を安くする「プロンプトキャッシュ」という仕組みがあります。
インデックスするファイルが頻繁に変わったり、巨大なファイルが混ざっていたりすると、このキャッシュがうまく機能しなくなります。
除外設定をしっかり行い、AIに送るデータの塊（コンテキスト）を安定させることで、2回目以降のやり取りを高速かつ安価にすることが可能です。
「安定した環境」はAIにとっても、あなたにとってもメリットしかありません。
キャッシュの恩恵を最大限に受けるためにも、インデックスの最適化をまずは完璧に終わらせましょう。
それでもインデックスが進まない時のチェックリスト
設定ファイルを整えても、なぜか進捗が止まってしまうことがあります。そんな時は、環境やPCの設定など、目に見えにくい部分に原因があるかもしれません。本章では、トラブルが発生した際にまずチェックすべき項目をまとめました。一つずつ潰していくことで、必ず解決の糸口が見つかるはずです。
ターミナルの権限設定を確認する
Claude Codeが特定のディレクトリを読み込もうとした際、権限不足（Permission Denied）で内部的に止まっているケースがあります。
特にシステム関連のフォルダや、管理者権限で作られたファイルがモノレポ内に混ざっていると、スキャナーがそこで立ち往生してしまいます。
一度ターミナルを管理者権限で実行してみるか、プロジェクト内のファイルの所有権を確認してみてください。
意外と盲点なのが、ウイルス対策ソフトやセキュリティツールがAIのスキャン動作を「怪しい挙動」としてブロックしている場合です。
もし動作が不自然に遅いなら、一時的に監視対象から外してみるのも有効なテストになります。
メモリ消費量を確認してPCの負荷を減らす
数万ファイルをインデックスする作業は、PCのメモリを大量に消費します。もし他のアプリケーションでメモリが圧迫されていると、Claude Codeの動作が極端に重くなり、止まったように見えることがあります。
特にDockerや複数のブラウザタブ、VS Codeなどがメモリを食い合っている場合は注意が必要です。
タスクマネージャー（またはアクティビティモニタ）を開き、CPUやメモリの余裕を確認しましょう。
PCが悲鳴を上げている状態では、AIも本領を発揮できません。
大きなリポジトリを扱うときは、不要なアプリを一度閉じて、Claude Codeにリソースを集中させてあげる環境作りも大切です。
Claude Codeのキャッシュを一度クリアして再起動する
AIツールの内部でキャッシュが壊れてしまい、設定を変更しても反映されない、あるいはエラーを吐き続けることがあります。
そんなときは、一度Claude Codeのセッションを完全に終了し、内部のキャッシュファイルを削除して「まっさらな状態」からやり直すのが最も手っ取り早い解決策です。
設定ファイルを書き換えた後は、 /compact コマンドなどで履歴を整理するのも一つの手です。
「困った時の再起動」は、AIエージェントの世界でも共通の鉄則です。
何をやっても直らないときは、一度全てをリセットして、新しい気持ちで claude と打ち込んでみてください。
パッケージを跨ぐ開発でClaude Codeを使いこなす
モノレポ開発の醍醐味は、複数のパッケージを連携させることにあります。インデックスを制限しつつも、必要な時だけ他のパッケージの情報を参照させる「いいとこ取り」の使いかたを紹介します。本章では、AIの視野を適切に広げるためのプロンプト技術と、クロスパッケージ開発のコツを伝授します。
共有ライブラリだけはスキャン対象に残す
全てのパッケージを隠すのではなく、共通で使っている packages/ui や packages/utils だけは、常にインデックスに含めておく設定がおすすめです。
こうすることで、個別パッケージ（ apps/web など）で作業していても、AIが「あ、その関数は共有ライブラリにありますね」と気づいてくれます。
共通部分を .claudeignore に入れてしまうと、AIが車輪の再発明（すでに存在する関数を新しく作ってしまうこと）をしてしまうリスクがあります。
- 重いビルドフォルダだけを消す。
- ソースコード（
src）は残す。 package.jsonは必ず読ませる。
この絶妙なバランス設定が、モノレポでの開発効率を最大化させます。
何でもかんでも隠すのではなく、AIに持たせておくべき「武器（共有コード）」は選別して残しましょう。
必要なファイルだけを個別に指定して読み込ませる
普段はスキャン対象外にしている場所でも、特定の修正でどうしても参照したい場合があります。その時は、プロンプトで直接パスを指定しましょう。
「今回の修正には packages/legacy/old-logic.ts の内容を参考にしたいから、読んでみて」
このように指示を出せば、AIはインデックスの範囲外であっても、そのファイルだけを一時的に取得しにいきます。
「必要なときだけ、必要な情報を与える」というスタンスは、AIとのやり取りを非常に効率的にします。
全体スキャンという重い作業に頼らずとも、言葉一つでAIの視界を広げられることを覚えておきましょう。
複雑な依存関係をAIに正しく伝えるプロンプトの出し方
モノレポでの開発では、パッケージ間の依存関係をAIに正しく認識させることが重要です。
「このプロジェクトはTurborepoで管理されていて、 web パッケージは ui パッケージに依存しています」といった前提条件を最初に伝えておきましょう。
AIはこの背景を知ることで、どのファイルを優先的に探すべきか、どのインポートパスが正しいかを正確に判断できるようになります。
指示を出す前に「見取り図」を言葉で共有してあげるだけで、AIの働きぶりは劇的に変わります。
AIを魔法の杖だと思わず、優秀な新入りエンジニアだと思って接することが、成功への一番の近道です。
まとめ：設定を最適化してモノレポ開発を爆速にしよう
モノレポでClaude Codeのインデックスが終わらない問題は、適切な除外設定と運用の工夫で必ず解決できます。今回の要点を振り返ります。
- 除外の徹底：
.claudeignoreを作成し、node_modulesやビルド生成物、巨大なデータを徹底的に隠す。 - 起動場所の工夫： ルートディレクトリにこだわらず、作業するパッケージの階層で起動してAIの視界を絞る。
- 環境の整備： メモリ負荷や権限を確認し、AIが迷いなく動ける清潔なリポジトリ構造を保つ。
インデックス作成の待ち時間をゼロに近づけることは、あなたの開発のリズムを守り、創造的な作業に集中するための第一歩です。この記事で紹介したテクニックを実践すれば、モノレポという巨大な迷宮も、AIという相棒と共に軽やかに駆け抜けられるようになるはずです。
