ハクソク

世界を動かす技術を、日本語で。

大規模コードベースにおけるClaude Codeの動作原理

2026年5月15日原文(claude.com)

概要

  • Claude Code は大規模なモノレポやレガシーシステム、分散アーキテクチャにおいて実運用されているAIコーディングツール
  • 大規模コードベース 特有の課題と、その乗り越え方をパターン化して紹介
  • CLAUDE.md、フック、スキル、プラグイン などの拡張ポイントによる柔軟な構成が成功の鍵
  • LSP統合やMCPサーバー 連携による高精度ナビゲーションと拡張性
  • 最適な導入・運用パターン や、よくある失敗例も具体的に解説

Claude Codeの大規模コードベース対応パターン

  • Claude Code は、数百万行規模のモノレポ、数十年運用されたレガシーシステム、複数リポジトリに分散した分散アーキテクチャ、大規模な開発組織で実運用されているAIコーディングツール
  • 大規模コードベース の例
    • 数百万行のモノレポ
    • 数十年かけて構築されたレガシーシステム
    • 複数リポジトリにまたがるマイクロサービス群
    • C、C++、C#、Java、PHPなどAIツールが苦手とされる言語も対応
  • Claude Code は、開発者のようにファイルシステムを巡回し、必要なファイルを読み込み、grepで検索し、参照をたどるナビゲーションを実現
  • ローカル環境で動作 し、コードベースのインデックス作成やサーバーへのアップロード不要
  • RAG型AIツール のようなインデックス遅延による情報の陳腐化を回避
  • エージェント型検索 により、常に最新のコードベースで作業
  • 十分なコンテキスト提供 （CLAUDE.mdやスキルの整備）が精度向上の鍵
  • 曖昧なパターン検索 や膨大な範囲の探索はコンテキストウィンドウ制限に注意

モデルよりもハーネス（拡張構成）が重要

  • Claude Codeの性能 はモデル単体ではなく、周辺のエコシステム（ハーネス）で大きく左右
  • ハーネスの主な構成要素
    • CLAUDE.md ：各セッション自動読み込みのコンテキストファイル（ルートで全体像、サブディレクトリでローカルルール）
    • フック ：特定イベントで実行されるスクリプト（自動化や学習内容の反映、チーム固有のセットアップを動的読み込み）
    • スキル ：特定タスク用の知識やワークフローをパッケージ化し、必要時のみ読み込み（例：セキュリティレビューやドキュメント更新）
      • パス単位でスコープ指定可能
    • プラグイン ：スキルやフック、MCP設定を一括パッケージ化し、組織内で即時展開
    • LSP統合 ：IDE同様のシンボルレベルナビゲーション（多言語・型付き言語で特に効果大）
    • MCPサーバー ：社内ツールやデータソース、APIへ直接アクセスするための拡張
    • サブエージェント ：探索と編集を分離し、独立したClaudeインスタンスで並列作業や情報収集を実現

各構成要素の役割・タイミング・よくある誤解

| コンポーネント | 役割 | 読み込みタイミング | 適用範囲 | よくある誤解 | |---|---|---|---|---| | CLAUDE.md | プロジェクト固有知識の提供 | 毎セッション | コードベース知識 | スキル化すべき知識まで記載 | | フック | 自動化・学習内容の反映 | イベント時 | 一貫した動作・学習内容の記録 | プロンプト指示で済ませる | | スキル | 特定タスク用知識のパッケージ | 必要時 | 複数セッション・プロジェクト横断知識 | すべてCLAUDE.mdに記載 | | プラグイン | 構成一式の配布 | 設定後常時 | 組織横断的なセットアップ共有 | 良いセットアップが属人化 | | LSP | シンボルレベルナビゲーション | 設定後常時 | 型付き言語での精密な探索 | 自動的に有効になると誤解 | | MCPサーバー | 社内ツール連携 | 設定後常時 | 外部ツールアクセス | 基本設定前に連携構築 | | サブエージェント | 分割探索・編集 | 呼び出し時 | 並列作業・探索と編集の分離 | 同一セッションで探索・編集 |

成功導入事例に共通する3つの構成パターン

  • Claudeのナビゲーション精度 は適切なコンテキスト設計が前提
  • CLAUDE.mdのスリム化と階層化
    • ルートは全体像や重要な注意点のみ
    • サブディレクトリごとにローカルルールを記載
  • 初期化ディレクトリの最適化
    • 必要なサブディレクトリで初期化し、関連するCLAUDE.mdのみを読み込む
    • ルートの情報は自動的に上位から補完
  • テスト・Lintコマンドのサブディレクトリ単位管理
    • 変更箇所のみのテスト・ビルドを指定し、無駄な出力やタイムアウトを防止
    • 複雑な依存関係がある場合はプロジェクト固有のビルド設定を検討
  • .ignoreやpermissions.denyによるノイズ除去
    • 生成ファイル・ビルド成果物・サードパーティコードを除外
    • バージョン管理でチーム全体に共通適用
    • ジェネレーター開発者向けにローカル上書きも可能
  • ディレクトリ構造が不明瞭な場合のコードベースマップ
    • ルートにMarkdownで各トップレベルフォルダの説明を記載し、Claudeの索引として利用
    • フォルダ数が膨大な場合は階層的にマッピング

このように Claude Code は、拡張性ある構成と適切なコンテキスト設計により、 大規模・複雑なコードベース でも高精度なAIコーディング支援を実現。 導入時の設計と運用ノウハウ が生産性向上のカギとなる。

Hackerたちの意見

すごく興味深いね。数ヶ月、いや数週間で変わる業界で、はっきりとしたパターンが現れるのに十分な時間があったし、そのパターンが大規模なコードベースで成功してるってことだよね。成功の基準は何？本番データベースを削除しなかった？チームの生産性が上がった？コードベースのTTLが増えた？運用チームが幸せになった？

└

本番データベースを削除しなかった？これがAIツールで起きたら、それは開発者に本番環境の権限を与えたあなたやあなたの組織の失敗だと思う。こんな盲目的なアクセスを与えられた職場で働いたことはないな。

コードベースのインデックスについての意見には賛成できないな。PHPStormや他のJetBrainsのIDEではかなりうまく機能するよ。

└

それに、Claude CodeはJetBrainsのMCPを使ってそのインデックスを利用できるよ。

└

PHPStormのインデックス機能はすごいよ。数回壊れたことがあったけど、それも簡単に直せるし、古い結果が出たことはない。Claudeの検索ツールを使ったことがあるなら、チームがインデックスについて何も知らないってのも納得だよね。テキストベースのチャットが主力商品なのに、そのチャット内で簡単にテキスト検索ができないって、理解に苦しむよ。

└

変な発言だね。AIのスラップ？GitHub Copilotも結構いいローカルインデックス持ってるし、コードをベクターデータベースに入れるのはそんなに難しい問題じゃないよ。

Claude Codeはソフトウェアエンジニアのようにコードベースをナビゲートする：ファイルシステムをたどり、ファイルを読み、grepを使って必要なものを正確に見つけ、コードベース全体の参照を辿る。開発者のマシン上でローカルに動作し、コードベースのインデックスを構築、維持、サーバーにアップロードする必要はない。… > エージェント検索はその失敗モードを避ける。何千人ものエンジニアが新しいコードをコミットする中で、維持すべき埋め込みパイプラインや中央集権的なインデックスはない。それぞれの開発者のインスタンスはライブのコードベースから動作する。「ソフトウェアエンジニアのやり方」という枠組みと結論は矛盾してる気がする。もし違うなら教えてほしいな。オートコンプリートやLSPはいつも使ってるし、便利だよ。それってインデックスなの？どうしてClaudeがそれを使えないの？それに「ソフトウェアエンジニア」はコードベースを覚えてるから、それは確実にRAGだよ。CMD+Pで必要なファイルを見つけるための筋肉記憶がたくさんある。何千人ものエンジニアの間でリアルタイムである必要はないし、ただ自分がいるブランチだけでいい。最初の原則からコードベースをナビゲートすることはめったにない。通常は新しいコードベースで、その場合は最適な体験とは言えないよ。

└

記事にはLSPについての段落が丸ごとあって、Claudeがそれを使えるって書いてあるよ。

└

コードベースの一部で最初の原則からの探索があったとしても、他の部分は絶対に変わらないし、毎回探索するのはトークンの無駄だよね。Claudeとのやり取りでは、あまり探索させないようにすることが多い。だって、変わらないものを遅くて高価なナビゲーションで探るより、私の方が早くて効率的だから。毎回同じような迷路に入っていくし。

└

答えはイントロにあるよ：> Claude Codeは数百万行のモノレポや数十年のレガシーシステム、数十のリポジトリにまたがる分散アーキテクチャで本番稼働している。(…) だから、特に大規模で混沌とした環境でも、どこでも動作する堅牢なツールを使って一般的なケースに最適化されているんだ。とはいえ、あなたの指摘は正しいし、整理された小さなリポジトリにはもっと良いツールがあるべきだと思う。でも、少なくともCodexはそうしてるから、Claudeもそうだと思うよ。例えば、Codexはgrepをする前に「go doc」を使うんだ。

└

自分がやるのと全く同じように動くね。LSPが存在する前から、大きなコードベースをナビゲートする方法を学んできたし。何年もvimを使って、関連するファイルを見つけるためにgrepを使ってた。去年Claude Codeを初めて試したときは、「なんだこれ、自分がやってることそのまんまじゃん！」って思ったよ。

└

それが問題だよね？ コードベースに放り込まれて、チケットを渡されたら、どうやって最速で状況を把握してチケットをこなすか。コードベースとチケットによるけど、どんなツールを使ってるかを見るのは面白そう。grepのようなツールをインデックスを使って早くすることで、スキルのあるオペレーターはかなり進めるけど、もっと複雑なチケット、例えば「ポーランドからのリクエストの2%で火曜日だけ現れるバグを直す」とかだと、もっと高度なツールがプログラマーを助けると思う。

Hacker Newsで議論の続きを見る