「個人開発では Claude Code が爆速で動くのに、会社の数百万行ある巨大リポジトリに持ち込んだ瞬間に急に頼りなくなる」と感じたことはありませんか？
これは Claude Code の限界ではなく、コードベース側の整え方の問題であることがほとんどです。Anthropic の Applied AI チームが大企業の導入事例から抽出したパターンを見ていくと、「モデルの賢さ」よりも「Claude が動くハーネスの設計」のほうが、最終的なアウトプットを大きく左右していることが分かります。
この記事では、モノレポ・レガシーシステム・分散リポジトリといった大規模コードベースに Claude Code を導入するときに押さえておきたい考え方と、設定の具体的なパターンを整理していきます。個人開発ではあまり気にしなくていい部分が多いので、チーム開発や業務コードで Claude Code を本格的に使い始めるタイミングで読んでもらえると効きやすい内容です。
大規模コードベースで Claude Code が苦戦する本当の理由
まず前提として、Claude Code はソフトウェアエンジニアと同じやり方でコードベースを歩き回ります。ファイルシステムを ls でたどり、grep で必要な文字列を探し、参照を追って関連ファイルを開く、という流れです。事前にインデックスを作って永続化したりはしません。すべてローカルマシン上のライブなコードベースに対して動きます。
ここが、いわゆる RAG（Retrieval-Augmented Generation）型の AI コーディングツールとの一番大きな違いです。RAG 型はコードベース全体を埋め込み（embedding）にしてサーバーに保管し、クエリのたびに関連チャンクを引っ張ってくる方式ですが、開発スピードが速いチームでは埋め込みパイプラインがコミットに追いつきません。気がつくと「2週間前にリネームされた関数」や「先週のスプリントで削除されたモジュール」が検索結果に普通に出てきて、しかも古いという情報すらありません。
Claude Code が採用しているエージェント型のサーチには、その種の腐敗が原理的に発生しません。インスタンスは常に「いま手元にあるコード」を読みます。
ただし、この方式には別のトレードオフがあります。「どこから探せばいいか」のヒントが少ないと、巨大なツリーの中で Claude が迷子になりやすいのです。たとえば「決済まわりのバグを直して」とだけ言って 10 億行のリポジトリに放り込むと、関連ファイルにたどり着く前にコンテキストウィンドウを使い切ります。
つまり、大規模コードベースで Claude Code を機能させたいなら、「Claude にどう探させるか」を設計するフェーズが必要になるということです。
モデルよりも「ハーネス」が成果を決める
もう一つ、大規模導入の現場でよくある誤解があります。「Claude Code の性能 ＝ モデルの性能」だと思い込んでしまうケースです。実際には、モデルの周りに組まれている ハーネス（harness） の出来の方が、日々のアウトプットには効いてきます。
ハーネスは大きく5つの拡張ポイントで構成されます。
- CLAUDE.md ファイル
- Hooks（フック）
- Skills（スキル）
- Plugins（プラグイン）
- MCP サーバー
これに加えて、横断的に効く2つの能力として LSP 連携 と サブエージェント があります。
ここからは、これらをどの順番で、何のために積み上げていくのかを順番に見ていきます。
CLAUDE.md：すべてのベースになる文脈
CLAUDE.md は、Claude Code がセッション開始時に必ず読み込む文脈ファイルです。ルートに置いたものはプロジェクト全体の概観、サブディレクトリに置いたものはそのモジュール固有の規約、という分担で機能します。
ここで効くコツは、「常にロードされる」という性質を逆手にとることです。毎回読まれるということは、書きすぎるとそれだけで毎セッションのコンテキストを圧迫します。だからルート CLAUDE.md には、「これだけは知っておかないと事故る」というポインタとガッチャ（落とし穴）だけを書きます。
具体的には次のような内容に絞ると失敗しません。
- 主要ディレクトリの役割（モノレポなら top-level の説明）
- ビルド・テスト・lint の主要コマンド
- 「これを直接編集しないで」という生成ファイルや自動更新ファイルの注意
- リポジトリ独自の用語、社内呼称
逆に、特定タスクでしか使わない長い手順書や、コーディングスタイルの細かい例文などはここに書くべきではありません。それらは後述する Skills に逃します。
Hooks：セットアップを自己改善させる仕組み
Hooks は「Claude が誤った操作をしないようにブロックするスクリプト」として認識されがちですが、本当に強力なのは 継続的な改善 の用途です。
たとえば、
- Stop hook（セッション終了時に走る）で、その回のやり取りを振り返らせ、CLAUDE.md に追記すべき学びを提案させる
- Start hook（セッション開始時に走る）で、いま編集対象になっているモジュールに応じた追加コンテキストを動的に注入する
- lint や フォーマッタの実行を Hook 経由で強制する（Claude に「lint を忘れずに」と毎回言わせるより、決定的に走らせた方が安定）
特に最後の点は重要です。「Claude にお願いするより、決定的に走らせた方が確実」という判断は、ハーネス設計のあらゆる場面で活きてきます。
Skills：必要なときだけロードされる専門知識
Skills は、CLAUDE.md と相補的に使う仕組みです。CLAUDE.md が「常時ロード」なのに対して、Skills は タスクに応じてオンデマンドにロード されます。
例を挙げると、
- セキュリティレビュー用スキルは、脆弱性チェックの依頼を受けたときだけ展開される
- 決済モジュールのデプロイ手順スキルは、
payments/配下のファイルを触っているときだけ展開される - ドキュメント更新スキルは、公開 API に手が入ったときだけ展開される
このように タスク種別やパスにスコープを切れる のが Skills の大きな利点です。「CLAUDE.md に全部書いておけば安全」と思いがちですが、それをやると毎回 5000 行のシステムプロンプトを読まされる Claude が出来上がってしまい、肝心のコードを読む余裕がなくなります。
「全員に毎回必要な知識 → CLAUDE.md」「特定タスクで必要な知識 → Skills」、これが原則です。
Plugins：チーム全員に同じセットアップを配るための器
ここまでの CLAUDE.md・Hooks・Skills を、個人が頑張ってチューニングしても、それが他のメンバーに広がらないと組織全体の生産性は上がりません。大企業で実際によく起きるのが、「一部のエンジニアだけがやたら Claude Code を使いこなしているが、ノウハウが本人の .claude/ ディレクトリに閉じ込められている」 状態です。
Plugins はこの問題を解くための仕組みで、Skills・Hooks・MCP の設定をひとつのインストール可能なパッケージにまとめます。新しいメンバーが入ってきたとき、プラグインを 1 つインストールするだけで、ベテランと同じ「整った Claude Code 環境」が手に入ります。
組織として運用する場合は、社内マーケットプレイス的にプラグインを管理し、アップデートを配布できるようにしておくのが理想です。
LSP：シンボル単位で正確に追える目を持たせる
大規模コードベースで一番きついのは、同名関数の取り違えです。handleClick のような関数名を grep すると数千件ヒットして、Claude がどれを開けばいいか分からずコンテキストを食い潰します。
これを解消するのが LSP（Language Server Protocol） との連携です。LSP は IDE が「定義へジャンプ」「参照を検索」を実現している裏側の仕組みで、これを Claude に渡すと、文字列ベースではなく シンボルベース でコードを追えるようになります。
たとえば、
- C/C++ の巨大モノレポで関数定義に一発でジャンプする
- TypeScript で同名の型/関数を文脈で正しく区別する
- Java の継承ツリーをまたいで参照を辿る
このあたりは、LSP を入れているかどうかで体感速度が露骨に変わる領域です。複数言語が同居するコードベースでは、ハーネス強化のなかでもっとも費用対効果が高い投資のひとつ だと言えます。
MCP サーバー：外の世界に手を伸ばす
MCP サーバーは、Claude を社内ツール・データ・API につなぐための仕組みです。
具体的には、
- 社内の構造化された検索エンジンを Claude のツールとして呼べるようにする
- Linear/Jira などのチケットシステムから関連 Issue を引っ張ってくる
- 社内ダッシュボードや分析基盤の数値を直接読みに行く
ここで一つ注意したいのは、基本のハーネス（CLAUDE.md・Hooks・Skills）が整っていない段階で MCP を増やしすぎない ことです。MCP は「届く範囲」を広げる仕組みなので、土台が整っていない状態で増やしても、Claude が新しい道具に振り回されるだけになりがちです。
サブエージェント：探索と編集を分ける
最後にサブエージェントです。これは「親 Claude から切り離された別インスタンス」で、独立したコンテキストウィンドウを持ち、結果だけを親に返します。
大規模コードベースでありがたい使い方が、read-only のサブエージェントに探索させ、その要約だけを親が受け取って編集に専念する というパターンです。
たとえば、
- サブエージェントに「
payments/配下の決済フローを map にしてmap.mdに書き出して」と頼む - 親エージェントは出力された要約だけを読み、無駄に多くのファイルを開かずに編集にかかれる
こうすると、親側のコンテキストが「探索で消費した記憶」で汚れないので、長丁場のタスクが安定します。
拡張ポイントを一枚で整理する
ここまで紹介した拡張ポイントを、用途を間違えやすい部分込みで整理すると次のようになります。
| 構成要素 | 何か | いつロードされるか | 向いている用途 | よくある誤用 |
|---|---|---|---|---|
| CLAUDE.md | 自動読込される文脈ファイル | 毎セッション | プロジェクト固有の規約・全体像 | Skills に逃すべき専門知識を書く |
| Hooks | 任意のタイミングで走るスクリプト | イベント駆動 | 定型処理の自動化、学びの収集 | プロンプトで頼むべきでない事を頼む |
| Skills | タスク特化の知識パック | オンデマンド | 再利用可能な専門知識 | 全部 CLAUDE.md に書こうとする |
| Plugins | Skills/Hooks/MCP のバンドル | 設定すれば常時利用可 | 組織全体への配布 | 良い設定を個人で抱え込む |
| LSP | 言語サーバー経由のコード解析 | 設定すれば常時利用可 | シンボル単位の正確な探索 | 自動で有効になっていると思い込む |
| MCP サーバー | 外部ツール・データへの接続 | 設定すれば常時利用可 | 社内ツール連携 | 土台が出来ていないうちから増やす |
| サブエージェント | 別コンテキストの Claude インスタンス | 呼び出し時 | 探索と編集の分離、並列処理 | 探索と編集を同じセッションで混ぜる |
大規模コードベース向けの3つの設定パターン
ここからは、実際にどう設定していくかの話です。Anthropic の Applied AI チームが多数の導入事例で共通して観測している、3つのパターンを紹介します。
パターン1：Claude にとってコードベースを読みやすくする
Claude のパフォーマンスは「正しい文脈にどれだけ早くたどり着けるか」に強く縛られます。文脈を入れすぎても性能が落ち、入れなさすぎても迷子になる。このバランスを取るために効くテクニックを並べます。
CLAUDE.md は薄く、階層的に
ルートはポインタと致命的なガッチャだけ。詳細はサブディレクトリの CLAUDE.md に任せます。Claude はディレクトリツリーを上向きに歩きながら CLAUDE.md を追加でロードしてくれるので、深い階層から始めても、上位の文脈は自動的に取り込まれます。
ルートよりサブディレクトリでセッションを起動する
モノレポではつい repo-root/ で claude を起動したくなりますが、実は タスクが対象とするサブディレクトリで起動した方が うまくいきます。Claude は階層を遡って CLAUDE.md を集めるので、ルートの全体像も失われません。
テストと lint のコマンドはディレクトリ単位でスコープする
1 つのマイクロサービスを直したのに全社的なテストを全部走らせるのは、時間と Claude のコンテキストの両方を浪費します。各サブディレクトリの CLAUDE.md に「このディレクトリのテストはこのコマンド」と書いておきます。
.ignore と permissions.deny を使ってノイズを切る
生成ファイル、ビルド成果物、サードパーティのコードを .claude/settings.json の permissions.deny で除外しておくと、Claude が無駄なファイルを開かなくなります。これをリポジトリに commit しておけば、新しく入ってきたメンバーも自動的に同じ静かな環境を手に入れられます。
ディレクトリ構造で語れない場合は「コードベースマップ」を作る
歴史的な事情で命名がバラバラなリポジトリでは、ルートに MAP.md のようなファイルを置き、「このフォルダには何があるか」を 1 行ずつ列挙しておくと効きます。Claude が最初に開く目次として機能してくれます。
LSP を有効にして「シンボルで検索」させる
前述の通り、これは特に複数言語の大規模リポジトリで効きます。
パターン2：モデルの進化に合わせて設定を更新する
これは見落とされがちですが、非常に大事な観点です。
CLAUDE.md や Hooks のなかには、「過去の Claude モデルの弱点を補うために書いた指示」 が含まれていることがあります。たとえば、
- 「リファクタは1ファイルずつ分けて行うこと」
- 「変更前に必ず該当ファイル全体を読むこと」
- 「複数ファイル変更時は段階的に commit を分けること」
こうした指示は、当時のモデルでは有効でも、より賢いモデルがリリースされた瞬間に 逆にパフォーマンスを縛る制約 に変わることがあります。新しいモデルは複数ファイル横断の編集を自然にこなせるのに、わざわざ「1ファイルずつ」と縛られて遅くなる、というのは典型例です。
そのため、CLAUDE.md・Hooks・Skills は 3〜6ヶ月に一度 見直すのがおすすめです。新しいモデルがリリースされて、なんとなく「前ほど凄くなくなった気がする」と感じたときは、モデルではなく 過去に積み上げた制約が足を引っ張っていないか を疑ってみてください。
パターン3：オーナーシップを誰が持つかを決める
ここまでは技術的な設定の話でしたが、大規模導入が成功するかどうかは、最終的には 誰が責任を持って育てるか で決まります。
うまくいっている組織には、ほぼ例外なく次のいずれかが存在します。
- 専任の小さなチーム（Developer Experience や Developer Productivity 配下）
- Agent Manager という新しい肩書きを持つハイブリッド人材（PM とエンジニアの中間）
- 少なくとも 1 人の DRI（Directly Responsible Individual） がいて、設定・権限・プラグインマーケットプレイス・CLAUDE.md 規約に責任を持っている
逆に、ボトムアップの熱量だけで導入が広がっている組織は、ある段階で必ずプラトーに当たります。「人によって CLAUDE.md の書き方がバラバラ」「同じ Skill を別々の人が作り直している」「便利な MCP がチームに共有されない」といった、いかにも組織的な分断が起き始めるからです。
特に規制業界では、初期段階から以下のような問いに答えておくと後で楽です。
- どの Skill・Plugin を組織として承認するか
- どのコードレビュー基準を AI 生成コードにも適用するか
- アクセスをどの順序で広げていくか
エンジニアリング・情報セキュリティ・ガバナンスのクロスファンクショナルな小さなワーキンググループを早めに作り、要件とロードマップを一緒に定義する。これが「導入後に大事故にならない」ための一番安いコストです。
個人開発者にも持ち帰ってほしいポイント
ここまでは大企業向けの話に寄せて書きましたが、実は個人開発・小規模チームにも応用できるエッセンスがいくつかあります。
CLAUDE.md は「常時ロード」だと意識する
何でも書きたくなる気持ちを抑えて、ポインタと注意点に絞る。詳細は Skills に逃す。これだけで体感の精度が変わります。
lint・format は Hook で決定的に走らせる
「Claude に毎回お願いする」より「機械的に強制する」の方が確実、というのはあらゆる場面で効きます。
探索は別エージェントに分ける
大きめの修正に入る前に、サブエージェントに read-only で探索させて要約だけもらう。これは数百行のコードベースでも有効です。
設定を半年に一度見直す
モデルが賢くなった世界では、過去の指示が足枷になっていないか定期的に疑う。これは個人でもやる価値があります。
まとめ
大規模コードベースで Claude Code を機能させるコツは、ひとことで言えば 「モデルを賢く使うのではなく、Claude が動きやすい環境を整える」 という発想の転換にあります。
- ライブなコードベースを直接読む Claude Code は、インデックスの腐敗とは無縁な代わりに、文脈設計が品質を決める
- CLAUDE.md・Hooks・Skills・Plugins・MCP・LSP・サブエージェントを役割で使い分ける
- 大規模では「誰がこの環境を育てるか」を決めることが、技術的な設定と同じくらい重要
「巨大コードベースに Claude Code を入れたいけど、何から手をつければ良いか分からない」と感じている方は、まずは ルートとサブディレクトリの CLAUDE.md を整え、lint/format を Hook 化し、重い専門知識を Skills に切り出す、というところから始めてみてください。ここまでやるだけでも、Claude の振る舞いはガラッと変わります。