ハクソク

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

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

11時間前原文(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%で火曜日だけ現れるバグを直す」とかだと、もっと高度なツールがプログラマーを助けると思う。

└

大規模なコードベースではgrepやfindがタイムアウトすることがあるよね。そんな規模で作業してると、Claudeが検索を便利にするために作ったツールを使わないってことにすぐ気づくよ。

Claude.MDファイルって、具体的に何を入れるべきかも説明されてないのに、どれだけ重要なんだろう？

└

魚の話: ここで読めるよ: https://code.claude.com/docs/en/best-practices#write-an-effe... 釣りの手順: 1) 公式の skill-creator をインストール; 2) 上記のリンクを使って claude-md-improver を作成; 3) 公式ドキュメントの progressive-disclosure について調査するようにClaudeに指示してスキルを改善; 4) 新しいスキルを自分のCLAUDE.mdファイルに向けて、変更を受け入れる。

これ、明らかにClaudeが書いたね。内容は薄っぺらいし、実質的なことはあまりない。

Claude Codeがコードベースを調べて効果的なハーネスを生成できないのはなんでだろう？CLAUDE.md（またはAGENTS.md）、スキル、プラグインを定義してみたけど、他の人が言ってるほど効果が出てない。例えばLSPプラグイン、CCはLSPのシンボルリネームを使わないし、ファイルを一つずつ遅く編集するか、特定のヒントを含むプロンプトの時にスキルを呼び出すように頼んでも反応しない。使い方が間違ってるのかな？コピーできるロバストな例ってある？

└

これは何年も前から存在する痛点で、いまだに解決されてない。 「AならXをする。B、C、Dをする。Aをする」って感じで、Xを使うことは決してないんだよね、だって「忘れちゃった」から。ルールを作るのに費やした時間が本当に役立つかどうか、全然信じられない。実際、いつかは失敗するって信じられる。RAG、ハーネス、スキル…これらは全部解決するはずだったけど、実際には全然そうなってない。

└

いくつかのケースで効果的なのは、コンテキストウィンドウにフィードするスクリプト付きのフックだね（コンテキストを制限するために不要なリンターのメッセージを削除しなきゃいけなかった）。OSのパッケージリポジトリからインストールできるリンターや他の言語特有のチェッカーをスクリプト経由で呼び出すこともできる。あと、モデルとスキルのコンテキストが一緒になることで違いが出るかも。4.6で「うまくいった」スキルが4.7ではあまりうまくいかないこともあるし、4.7はより明示的な指示が必要だけど、4.6と比べると信頼性は高い。スキルを更新するのも役立つかも。テストして、前後で確認してみて。CCはコンテキストに不要なツールコールを注入することもあるから、例えばビーズファンならタスクを抑える必要があるかもね。

└

俺、使い方間違ってる？ /initを使うのをやめて、コードベースを説明するCLAUDE|AGENTS.mdファイルもやめた。残したのは、コードベースを探索する方法とリサーチのときにgit logを使うことだけ。これも多分冗長だよね。俺もわからない。自分が作業してるコードベースは大体10万行だから、大きいと見なされるかはわからない。個人的には、これまでで一番大きいリポジトリだよ。

ちょっとしたエピソード: LLMのオンボーディングとオーケストレーションのプロジェクトを設計してたんだけど、Claudeは各ファイルの最初の40行しか読まなかった。その後、別のセッションで低品質な結果の原因を探してたら、Claudeが問題を見つけてAST分析を行うようにコードを変更した。今はアナライザーがドキュメントの行と関数のシグネチャ（入力/出力）を入力として使うようになった。Claudeの最初のアプローチは本当にひどかった。Claudeのコードが改善のために何回修正/レビューされる必要があるのか、あるいは良いコードを作ることが本当に可能なのか、考えざるを得ない。編集: 一般化すると、Claudeは特定の、識別可能な悪い決定（例えば「最初の40行しか読まない」）を修正できるけど、その問題は一つのコードにトレースできるから。でも、実際のソフトウェアの品質問題は、多くの小さくて個々には合理的な決定から生じることが多くて、それが集まると悪い結果になることがある。どれも明らかに「問題」ってわけじゃない。その状況では、低品質なビルディングブロックを少しずつ生成するツールは、良いコードに収束することはないかもしれない。なぜなら、各部分は単体で見ると問題ないように思えるから。

└

ソースコードを覗き穴越しに見るように教えられてる気がするけど、これはサブロジックやフルサブエージェントの良い使い方になるかも。例えば、「サブエージェント、あのファイルをざっと見て要約して、XとYに関連する部分をハイライトしてくれたら、メインのコンテキストで見れるようにするから。」って感じで。メインの作業ストリームを定期的に観察して、考えてるファイルの中に自分の作業に関連することがあったら、気づいた時に中断してくれるといいな。

それには、チームがAIコーディングツールと必ずしも関連付けない言語で動いているコードベースも含まれる。例えばC、C++、C#、Java、PHPとか。なんでこんなコメントをするんだろうね。CCがこれらの言語でうまく動くと思わない理由がわからない。どの言語と関連付けるべきだと思う？ PythonとJavaScript？

Claude Codeは大きなコードベースでどう動くの？ 簡単だよ - 小さなプロジェクトでも最初のプロンプトで最大35%の5時間使用制限を食っちゃうし、すぐに反応しないと5分間のタイムアウトがあって、キャッシュが壊れちゃうから次のプロンプトでまた12%から15%払わなきゃいけなくなる。

└

記事にはこれを避ける方法が説明されてる。大きなコードベースに無邪気に放り込むと、そう、たくさんのトークンを消費しながら探し回ることになるよ。

Anthropicは、プロや5倍、20倍のサブスクリプションで自分たちの主張をテストしたのかな？ 無限に無料トークンがあれば、問題にトークンを投げるのも納得できるけど、限られた使用シナリオではあまりうまくいかないよね。