AIコーディングのスケールアップ：Claude Codeはいかにして大規模コードベースをナビゲートするか

数百万行のモノレポや数十年前のレガシーシステムを管理するエンジニアリングチームにとって、AIコーディングツールの主な課題はモデルの推論能力ではなく、コンテキストウィンドウです。従来のRAG (Retrieval-Augmented Generation) システムは、埋め込みパイプラインがアクティブなエンジニアリングチームの速度に追いつけず、名前が変更された関数や削除されたモジュールの「古い」検索結果を返してしまうことが多いため、大規模な環境では苦戦することがよくあります。

Claude Codeは、**エージェンティック・サーチ（agentic search）**アプローチを採用することで、この問題に対処します。事前に構築されたインデックスに頼るのではなく、開発者のローカルマシン上で動作し、ファイルシステムを探索し、ファイルを読み込み、grepを使用してリアルタイムで情報を検索します。これにより、AIは常にライブのコードベースから作業を行うことができますが、一方で新しい依存関係が生じます。それは、コードベース自体の構造の質と、モデルを取り巻く「ハーネス（harness）」です。

「ハーネス」：モデルを超えて

大規模な導入を成功させるための核心的な洞察の一つは、モデル単体では製品ではないということです。「ハーネス」——モデルを取り巻く設定やツールのエコシステム——が、本番環境での実際のパフォーマンスを決定します。このハーネスは、いくつかの主要な拡張ポイントで構成されています。

1. コンテキストと自動化

• CLAUDE.md ファイル: これらは、すべてのセッションの開始時に自動的に読み込まれます。コンテキストウィンドウの肥大化を避けるため、成功しているチームは階層的なアプローチを採用しています。つまり、ルートファイルで高レベルのアーキテクチャを定義し、サブディレクトリのファイルでローカルな規約を定義します。
• フック (Hooks): 特定のイベントによってトリガーされるスクリプトです。リンティングやフォーマットに使用されることが多いですが、最も強力な用途は継続的な改善です。「ストップ・フック」を使用して、セッションの内容を振り返り、コンテキストが新鮮なうちにCLAUDE.mdへの更新を提案させることです。

2. 特化型知識と配布

• スキル (Skills): これにより「段階的な開示（progressive disclosure）」が可能になります。すべてのセッションでスペースを占有するのではなく、タスクが必要とする時にだけ、特化されたドメイン知識（例：セキュリティレビューやデプロイメントワークフロー）をロードします。
• プラグイン (Plugins): これらはスキル、フック、およびMCP構成をパッケージ化してインストール可能なパッケージとしてまとめ、チームのすべてのエンジニアが同じ最適化されたセットアップから開始できるようにすることで、「部族的な知識（tribal knowledge）」を防ぎます。

3. 深い統合

• LSP (Language Server Protocol): LSPと統合することで、Claude Codeはテキストベースのパターンマッチングからシンボルレベルの精度へと移行します。これにより、関数の定義を追跡し、IDE内の人間の開発者と同じ精度でファイル間で参照を追跡することが可能になります。
• MCP (Model Context Protocol) サーバー: これらは、AIが本来アクセスできない内部ツール、チケット管理システム、および独自のAPIへの架け橋として機能します。
• サブエージェント (Subagents): これらは、探索と編集を分離するために使用される独立したインスタンスです。読み取り専用のサブエージェントはサブシステムをマッピングし、その結果をメインエージェントに報告します。メインエージェントは、完全な全体像を把握した上で編集を実行します。

スケールに対応するための構成パターン

これらのツールを大規模な組織に展開するには、単なる技術的なセットアップ以上のものが必要です。特定のアーキテクチャ・パターンが必要です。

• サブディレクトリの初期化: モノレポにおいて、Claudeをルートではなくサブディレクトリで初期化することで、AIが不適切なデータに圧倒されるのを防ぎつつ、ルートレベルのCLAUDE.mdファイルを辿って見つけることができるようにします。
• ノイズの削減: .claude/settings.jsonを使用してpermissions.denyルールをバージョン管理することで、生成されたファイルやビルド成果物がすべてのチームメンバーに対して一貫して除外されるようにします。
• コードベースのマッピング: 非標準的なディレクトリ構造の場合、ルートに軽量なMarkdownによる「目次」を置くことで、エージェントが特定のファイルに飛び込む前に、ディレクトリの森をナビゲートするのに役立ちます。

人間と組織的な要素

技術的な構成は、戦いの半分に過ぎません。導入を成功させるには、通常、DevEx（Developer Experience）チーム内に専任の「エージェント・マネージャー」またはDRI（Directly Responsible Individual）が必要です。この役割は、何が機能するかを中央集約化し、プラグイン・マーケットプレイスを管理し、CLAUDE.mdの規約を規約が組織全体で断片化しないように管理します。

さらに、メンテナンスは継続的なプロセスです。モデルが進化するにつ早、古いモデルに必要だった指示（例：「リファクタリングは単一ファイルへの変更に分割せよ」）が、より有能な新しいモデルにとっての制約となって作業を妨げる可能性があります。3〜6ヶ月ごとの構成レビューを推奨します。古いフックやスキルをロードして整理（prune）することが重要です。

批判的な視点とトレードオフ

公式のガイダンスは「ハーネス」の力の強さを強調していますが、開発者コミュニティのフィードバックからは、いくつかの摩擦点が見つかっています。

• 「指示のギャップ (Instruction Gap)」: 一部のユーザーは、CLAUDE.mdに明示的なルールがあるにもかかわらず、エージェントが重要な指示を無視したり、すでに完了した作業をハラシネーション（幻覚）として報告したりすることがあると報告しています。これには、複雑な変更を行う際に、かなりの「ベビーシッティング（付き添い）」が必要になります。
• トークン効率: エージェンティック・サーチのコストと使用制限に関する懸念があります。エージェントがコンテキストを見つけるために、複数のgrepコマンドを実行したり、ファイルを繰り返し読み込んだりするため、、正確なインデックスベースの検索と比較して、トークンを急速に消費する可能性があります。
• 「インデックス作成の論争」: 一部の開発者は、インデックス作成の破棄は時期尚早であると主張しています。IDEのようなJetBrainsは、Claude CodeがLSPプラグインを通じて達成しようとしているシンボルレベルのナビゲーションを、インデックス作成を効果的に利用して提供しています。

ある開発者がCLAUDE.mdファイルの有用性について次のように述べています。

"CLAUDE.mdは、モデルがあなたのアーキテクチャをどのように理解しているかを説明するものではありません。むしろ、ある種の回帰（regression）が発生するのを防ぐためのものです。'ワークスペースのプロビジョニング・ステップを呼び出さずにユーザーを作成してはならない'は、正しい制約約。'これは私たちのシステム全体の仕組みです'は、誤りです。モデルはコードベースからそれを学習します。"

最終的に、大規模な環境におけるエージェンティックAIコーディングへの移行は、「プロンプト」から「環境エンジニアリング」へのシフトです。目標は、AIが人間のエンジニアのように効率的に探索できる、ナビゲート可能で、ドキュメント化されたワークスペースを構築することです。