Claude Code は、数百万行のコードからなる monorepo、何十年もの歴史を持つレガシーシステム、数十のリポジトリからなるマイクロサービスアーキテクチャで、すでにその実力を証明しています。このガイドは Anthropic 公式ドキュメントの翻訳で、Claude Code を大規模コードベースで最大限に活かすための実践パターンをまとめたものです。

Claude Code は大規模コードベースをどう渡り歩くのか

Claude Code のコードベースの探索方法は、ベテランエンジニアのそれに似ています。ファイルシステムを渡り歩き、ファイルの中身を読み、grep で正確に位置を特定し、参照関係をたどります。ローカルで直接動作するため、コードベースのインデックスを事前に構築する必要も、コードをクラウドへアップロードする必要もありません。

従来の RAG ベースの AI コーディングツールはコードをベクトル化してから検索しますが、巨大なコードベースの前では、ベクトル化がコミットのスピードに追いつかず、検索でヒットするのはすでに名前が変わった関数や削除済みのモジュールかもしれません。Claude Code のエージェント型検索（Agentic Search）はこの問題を回避しますが、その代償として、効率よくナビゲートするには十分な「初期コンテキスト」が必要になります。

5 つの拡張ポイント：モデルよりインフラが重要

モデルを囲むように構築される「インフラストラクチャ」（Harness）は、最終的なパフォーマンスを決める上で、モデルそのものよりはるかに大きな決定打になります。このインフラストラクチャは 5 つの拡張ポイントで構成され、各レイヤーが前のレイヤーの上に成り立つため、構築の順序が非常に重要です。

第 1 層：CLAUDE.md ファイル

CLAUDE.md は Claude がセッションごとに自動で読み込むコンテキストファイルです。ルートディレクトリのファイルは全体に関わるケースで使われ、サブディレクトリのファイルはローカルな規約に使われます。

重要な原則：簡潔に保つこと。 これらのファイルは毎回読み込まれるため、最も汎用的な情報だけを残します。「スキル」として書くべき再利用可能な専門知識を詰め込んではいけません。

第 2 層：フック（Hooks）

フックは、設定全体に自己進化の力を与えます。多くのチームはフックを Claude のミスを防ぐスクリプトと見なしがちですが、より重要な価値は継続的な改善にあります：

• 停止フック（Stop Hook）：セッション終了時に直前の操作を振り返り、CLAUDE.md の更新を提案する
• 開始フック（Start Hook）：特定チームのコンテキストを動的に読み込む

コードチェック（linting）やフォーマットのような自動化において、フックは Claude に指示を覚え込ませるよりもはるかに信頼できます。

第 3 層：スキル（Skills）

スキルはある根本的な矛盾を解決します。すべてのタスクで専門知識をすべて読み込む必要はない、というものです。プログレッシブディスクロージャー（Progressive Disclosure）により、スキルは専門知識を切り出して独立させ、タスクで必要になったときだけ読み込みます。

スキルは特定のパスに紐付けることもできます。たとえば決済チームが「デプロイスキル」を決済ディレクトリにバインドすれば、他のディレクトリで作業するときには自動で読み込まれません。

第 4 層：プラグイン（Plugins）

プラグインは、スキル・フック・MCP 設定を 1 つのインストール可能なユニットにまとめます。入社初日のエンジニアがプラグインをインストールすれば、即座にベテランと同じコンテキスト知識を手に入れられます。企業は社内アプリマーケットを通じて更新を配布できます。

第 5 層：MCP サーバー

MCP サーバーは、Claude が社内ツール・データソース・API に接続するための通道です。最もヘビーに使いこなすチームは、構造化検索をツールとしてカプセル化し、MCP 経由で Claude に直接呼び出させます。

2 つの追加能力

• LSP 統合：Claude に「シンボル」レベルの正確なコードナビゲーション能力（定義へのジャンプ、すべての参照の検索）を持たせます。多言語が混在するコードベースでは、最も価値のある投資の 1 つです。
• サブエージェント（Subagents）：独立した Claude インスタンスで、探索と下調べを担当し、メインエージェントがその結果に基づいて全体の編集を行います。「探索」と「編集」を分離する仕組みです。

拡張ポイント早見表

成功する 3 つの導入パターン

パターン 1：コードベースをナビゲートしやすくする

これは最も基本的で、最も重要なパターンです：

• CLAUDE.md を簡潔かつ階層的に保つ：ルートファイルには核心的な指針と絶対に踏んではいけない落とし穴だけを書く
• ルートではなくサブディレクトリで初期化する：Claude はディレクトリツリーを自動的に上がりながら、途中のすべての CLAUDE.md を読み込む
• テストと lint コマンドはサブディレクトリレベルに限定する：1 つのマイクロサービスを修正しただけでプロジェクト全体のテストが走るのを避ける
• .ignore ファイルで生成ファイルやサードパーティコードを除外する：.claude/settings.json に permissions.deny ルールをコミットする
• コードベースの「地図」を作る：ルートディレクトリに軽量な Markdown ファイルを作り、各トップレベルフォルダの用途を列挙する
• LSP サーバーを動かす：Claude に「文字列」ではなく「シンボル」で検索させる

パターン 2：CLAUDE.md を継続的に更新する

モデルの進化に伴い、旧モデル向けに書いたルールが新モデルの足かせになることがあります。3-6 か月ごとに設定を棚卸しし、大規模モデルの更新リリース後にも見直しを行うことを推奨します。

パターン 3：専任の担当者を置く

技術的な設定だけでは、広く使われるようにはなりません。成功している組織はいずれも運営面に力を注いでいます：

• 権限を全面解放する前に、専任の人員を割いてインフラを整備する
• DRI（Directly Responsible Individual）を指定し、Claude Code の設定・権限ポリシー・プラグインを管理する
• 部門横断の合同ワーキンググループ（エンジニアリング、セキュリティ、コンプライアンス）を編成し、要件を定義して展開のロードマップを策定する

主要参考リンク

• CLAUDE.md ドキュメント：https://code.claude.com/docs/en/memory
• フックガイド：https://code.claude.com/docs/en/hooks-guide
• スキルドキュメント：https://code.claude.com/docs/en/skills
• プラグインドキュメント：https://code.claude.com/docs/en/plugins
• LSP コードインテリジェンスプラグイン：https://code.claude.com/docs/en/discover-plugins#code-intelligence
• サブエージェント：https://code.claude.com/docs/en/sub-agents