Anthropic が 2026 年 5 月 14 日に公開した How Claude Code works in large codebases: Best practices and where to start は、Claude Code を大規模コードベースへ導入するときに、何を先に整えるべきかを整理した記事です。ここでいう大規模コードベースには、数百万行のモノレポ、長年育ったレガシーシステム、複数リポジトリにまたがる分散アーキテクチャ、C / C++ / C# / Java / PHP などを含む多言語環境が含まれます。この記事では、元記事の内容に沿って、導入時に押さえるべきポイントをまとめます。
Claude Code は巨大なコードベースをどうたどるのか
元記事が最初に説明しているのは、Claude Code がコードベースをどう探索するかです。Claude Code はローカルのファイルシステムをたどり、必要なファイルを読み、grep のような検索で該当箇所を見つけ、参照を追いかけながら理解を進めます。コードベース全体のインデックスを事前に作ってサーバーへ載せる前提ではありません。
この説明は、大規模導入で何が効くかを考えるうえで重要です。元記事では、RAG ベースの AI コーディングツールだと埋め込みの更新が開発速度に追いつかず、すでに名前が変わった関数や削除済みのモジュールを返してしまうことがあると述べています。Claude Code はその代わりに、その時点のコードベースを直接見ますが、その方式にも前提があります。Claude Code がどこを見るべきかを最初に判断できるだけの文脈が必要だということです。
そのため、大規模コードベースでの精度はモデル単体よりも、コードベースの見通しの良さや補助情報の置き方に大きく左右されます。曖昧な依頼をそのまま巨大なコードベースへ投げると、探索だけでコンテキストウィンドウを消耗します。逆に、Claude Code が最初に進むべき方向を与えられれば、インデックスなしでもかなり実務的に動ける、というのが元記事の前提です。
モデルよりハーネスが効く
元記事の中心にあるのは、Claude Code の性能はモデルだけで決まらない、という整理です。Anthropic は、実運用で効いているのはモデルのベンチマーク値よりも、その周囲にあるハーネスだと説明しています。ここでいうハーネスは、Claude Code を実務に合わせて使うための設定や拡張のまとまりです。
元記事では、特に次の要素が重要だとされています。
CLAUDE.md- フック
- スキル
- プラグイン
- MCP サーバー
- LSP 連携
- サブエージェント
役割の切り分けも明確です。CLAUDE.md は毎回読む共通知識、フックはイベント時に自動で走る処理、スキルは必要なときだけ読む専門知識、プラグインはそれらの配布単位、MCP サーバーは社内ツールやデータへの接続です。さらに LSP 連携がシンボル単位の正確な探索を支え、サブエージェントが探索と編集を分離します。
ここで大事なのは、全部を最初から盛り込むことではありません。元記事は、各拡張ポイントには順番があるとしています。毎回必要な知識を CLAUDE.md に寄せ、毎回は不要な専門知識をスキルに分け、共有すべき構成をプラグインとして配る。このレイヤー分けが崩れると、毎セッション不要な情報を読み込んで重くなったり、逆にチームごとのノウハウが属人化したりします。
元記事には、この関係を整理した Claude Code の拡張レイヤー図も載っています。図の要点は、Claude Code の力を「モデル単体」ではなく、周囲の設定、道具、接続、委譲の仕組みを含めたハーネスとして見ることです。
出典: How Claude Code works in large codebases: Best practices and where to start
元記事の図では、CLAUDE.md、フック、スキル、プラグイン、MCP サーバーが拡張ポイントとして扱われ、LSP 連携とサブエージェントはそれを補う機能として位置づけられています。LSP はプラグイン層から利用され、サブエージェントは設定ファイルを増やすというより、作業を分けるための委譲機能です。
うまくいっている導入に共通する 3 つのパターン
元記事では、成功している導入に 3 つの構成パターンがあると整理しています。
1. コードベースを探索しやすくする
最初のパターンは、Claude Code が迷わない状態を先に作ることです。元記事で挙がっている具体策はかなり実務的です。
-
CLAUDE.mdを薄く保ち、ルートには全体像と重要な注意点だけを書く - サブディレクトリごとにローカルな慣習を書く
- モノレポでもリポジトリのルートではなく対象サブディレクトリから始める
- テストと lint のコマンドをサブディレクトリ単位で分ける
- 生成ファイルやビルド生成物、外部コードを
.ignore系設定で除外する - ディレクトリ構造だけでは把握しにくい場合は、ルートに簡単なコードベース地図を置く
- LSP を使って文字列検索ではなくシンボル単位でたどれるようにする
特に印象的なのは、Claude Code はディレクトリを移動しながら CLAUDE.md を加算的に読むので、ルートから始めなくてもルートの文脈は失われない、という説明です。人間の感覚だとモノレポはルートから入るほうが自然ですが、Claude Code では「今触る範囲に寄せて始める」ほうが探索効率は上がる、ということになります。
ここでいう LSP は Language Server Protocol のことです。TypeScript なら TypeScript 用の language server、Python なら Pyright、C / C++ なら clangd のように、言語ごとの解析器を共通のプロトコルで呼び出す仕組みを指します。Claude Code 側には LSP プラグインの仕組みがあり、言語サーバーをつなぐと定義ジャンプ、参照検索、診断などのコード理解に使えます。
また、LSP の扱いも重要です。大規模コードベースで共通名の関数を grep すると膨大な候補が返りますが、LSP があれば同名でも別シンボルを区別できます。元記事では、多言語コードベースではこれが特に投資対効果の高い改善だと述べています。
2. 設定を固定資産だと思わない
2 つ目のパターンは、いま効いている設定が次のモデルでも効くとは限らない、という前提です。元記事では、以前のモデル向けに書いた指示が、新しいモデルには過剰な制約になる例を挙げています。たとえば「リファクタリングは必ず単一ファイルの変更に分ける」というルールは、以前は安全策でも、より賢いモデルでは複数ファイルをまたぐ整合的な変更を妨げるかもしれません。
同じことはフックやスキルにも起きます。昔は必要だった回避策が、Claude Code 本体の改善で不要になることもあります。元記事は、3 か月から 6 か月ごと、あるいは大きなモデル更新のあとに、設定の棚卸しをするべきだと勧めています。
これは「一度整えたら終わり」ではなく、「モデルの進化に合わせて余計な補助輪を外していく」という運用です。AI コーディングツールを入れるとき、追加する設定ばかり考えがちですが、元記事は削るメンテナンスも同じくらい大事だと示しています。
3. 導入の責任者を決める
3 つ目は、技術設定だけでは導入は進まない、という話です。元記事では、うまくいった組織は広い展開の前に、少人数でもよいので道具立てを整える担当を持っていたと説明しています。開発者体験や開発生産性のチームが担うこともあれば、エージェント活用の担当役のような役割が立つこともあるそうです。
専任チームがなくても、最低限 DRI を置くべきだとも述べています。その人は、設定、権限ポリシー、プラグイン配布の仕組み、CLAUDE.md の運用方針に責任を持ちます。理由は単純で、現場から使い始めるだけでは、便利な設定やノウハウが個人に閉じてしまい、組織全体への導入が頭打ちになりやすいからです。
さらに大規模組織では、統制の論点も早めに出ます。どのスキルやプラグインを許可するのか、同じものを各チームが重複して作らないようにどうするのか、AI が作ったコードを既存のレビュー工程にどう乗せるのか。元記事は、最初から承認済みスキルの集合、必須のコードレビュー工程、限定的な初期アクセスを用意し、信頼度に応じて広げる流れを勧めています。
どこから始めるべきか
記事タイトルにもあるとおり、元記事はベストプラクティスだけでなく、どこから始めるかも扱っています。内容を見る限り、最初の一歩は次の順番で考えるのが自然です。
- ルートとサブディレクトリの
CLAUDE.mdを整理し、Claude Code が迷わない最小限の文脈を置く - 対象領域ごとにテスト、lint、ビルドコマンドを分ける
- 生成ファイルや無関係なディレクトリを除外して探索ノイズを減らす
- 可能なら LSP を導入してシンボル単位の探索を有効にする
- そこまで整ってからスキル、プラグイン、MCP サーバーを追加する
- 運用責任を持つ DRI か小さな担当チームを決める
この順番は、元記事が「MCP 接続を作る前に基本を動かすべきだ」と書いていることとも一致しています。派手な拡張に入る前に、Claude Code がその時点のコードベースを読みやすい状態にすることが先です。
まとめ
この元記事が一貫して伝えているのは、Claude Code を大規模コードベースで活かすには、巨大なインデックスを用意することより、Claude Code が必要な文脈へ速くたどり着ける構造を整えることが重要だという点です。そしてその成否は、モデル単体よりもハーネスの設計に強く依存します。
Claude Code 導入を検討しているなら、まずはプロンプトの工夫より前に、CLAUDE.md の階層、サブディレクトリ単位のコマンド、ignore 設定、LSP、責任者の 5 点から見直すのがよさそうです。元記事は、大規模導入で本当に効くのは「万能な 1 つの設定」ではなく、探索しやすさ、共有しやすさ、更新しやすさを揃えた運用だと示しています。