Claude Codeを数百万行のモノレポで動かす — Anthropic公式の大規模運用ベストプラクティス

2026年5月19日、Anthropicが「How Claude Code works in large codebases: Best practices and where to start」を公開した。数百万行のモノレポ、数十年もののレガシーシステム、分散マイクロサービスにClaude Codeを入れてきた顧客から学んだことをまとめた内容で、@ClaudeDevs のポストは公開から2日で70万表示・4,367いいねまで伸びている。

ここで強調されているのは「モデルそのものより、モデルを取り巻くハーネス（harness）の作り込みでパフォーマンスが決まる」という一点だ。CLAUDE.md、Skills、Hooks、Plugins、LSP、MCP、Subagentの7要素の役割分担を切り分けたうえで、組織として導入する側が何から始めるかを示している。個人開発でClaude Codeを触っている層から見ても、CLAUDE.mdに何を書いてはいけないかの整理は手元の設定を見直すきっかけになる。

Claude Codeはコードベースをどう読むのか

CursorなどのコーディングエージェントはRAGを使う。コードを事前にチャンクへ分割し、埋め込みベクトルに変換してインデックスに保存しておき、質問が来たら近そうなチャンクを引っ張ってきてモデルに渡す方式だ。インデックスが古いままだと存在しないコードを返したり、リネーム後のシンボルを取り違える。巨大モノレポでは再インデックスのコストも重い。

Claude Codeはこのアプローチを取らない。エンジニアと同じようにファイルシステムをたどり、grepで必要箇所を探し、参照関係を追う。開発者のマシン上で動くため、つねに最新のソースコードを直接見る。中央集権のインデックスがいらない代わりに、コードベース側がClaudeにナビゲートしやすい構造になっているかで速度と精度が大きく変わる。

これが「ハーネスの設計で結果が変わる」という主張の前提になる。モデルの賢さは固定したまま、ハーネスを整えるとレビュー精度・修正の局所性・誤った変更の頻度がはっきり変わる、というのが大規模導入を支援したチームから返ってきた共通見解だ。

ハーネスを構成する7つの要素

公式ブログが挙げるのは次の7つ。それぞれ目的と置き場所が違う。混ざると壊れる。

1. CLAUDE.md ― セッション開始時のコンテキスト

セッションごとに自動で読み込まれるテキスト。「広く共通して当てはまる前提だけを書く」のが原則だ。リポジトリ直下のCLAUDE.mdには大局的な落とし穴やビルドの注意だけを置き、サブディレクトリごとに局所的な規約を別CLAUDE.mdとして分ける階層構造が推奨される。

2. Hooks ― 自動化と継続改善

セッション中の特定イベント（ファイル編集後、コミット前など）に発火するスクリプト。プロンプトで毎回お願いするのではなく、ハーネス側で常に同じ振る舞いを担保する。同記事では「Perforce統合にp4 edit強制実行のフックを入れていたが、Claude CodeにPerforceネイティブ対応が入った時点で不要になった」という例が挙げられている。フックは便利だが、本体機能が追いつくと冗長になるので3〜6か月で棚卸しが必要、というメッセージだ。

3. Skills ― オンデマンドの専門知識

特定タスク用の専門知識をパッケージ化したもの。CLAUDE.mdに全部書くと毎セッションでコンテキストを食い潰すので、必要なときだけロードする形にする。記事内では大手小売企業の例として「社内分析基盤に接続するスキルをプラグインとして配布し、ビジネスアナリストがClaude Codeのワークフロー内でパフォーマンスデータを取得できるようにした」事例が紹介されている。

4. Plugins ― 組織配布の単位

Skill・Hook・MCP設定をまとめて配布できる単位。マネージドマーケットプレイスを通して組織内に配ることで、各エンジニアが個別に設定をかき集める必要がなくなる。

5. LSP統合 ― 記号レベルのナビゲーション

LSP（Language Server Protocol）はVS CodeやNeovimが「定義へジャンプ」「参照を検索」「型を表示」をやるときに裏で話している共通プロトコルだ。typescript-language-serverやrust-analyzerのような言語サーバーが構文木と型情報を持っていて、エディタからの問い合わせに正確に答える。

Claude Codeのデフォルトはgrepによるテキスト検索なので、getUserを探すと無関係な同名関数やコメントまでヒットする。LSPを接続すると、Claudeは言語サーバーに「このシンボルの定義はどこか」「呼び出し元は」と聞けるようになり、型解決済みの正確な参照を取れる。C/C++のように#include・マクロ・型システムが複雑な言語では、grepでまともにコードを辿れないので、LSPの整備がClaude Code導入の前提になった、というエンタープライズソフトウェア企業の例が公式ブログに出てくる。「LSPが勝手にセットアップされる」という思い込みは、明示的にアンチパターンとして名指しされている。

6. MCPサーバ ― 内部ツールへの接続口

Model Context Protocolで社内API・社内ツールに接続する。GitHubやSlackのようなSaaSだけでなく、自社の分析基盤・チケット管理・本番監視のような独自システムにClaude Codeを橋渡しする手段として位置づけられている。

7. Subagents ― 探索を切り出す読み取り専用インスタンス

呼び出し元エージェントから独立したインスタンスを起動し、探索タスクを任せてから結果だけ親に返す。デフォルトで読み取り専用に振る舞うため、巨大コードベースのなかで「まずこのモジュールを舐めてくる」ような作業を本流のコンテキストを汚さずに走らせられる。

CLAUDE.mdに書くべきでないもの

公式が繰り返し釘を刺しているのが、CLAUDE.mdに書くべきでないものの線引きだ。

再利用可能な専門知識 → Skillに切り出す
一貫した振る舞いの担保 → Hookで自動化する
特定ディレクトリだけのローカル規約 → そのディレクトリのCLAUDE.mdへ降ろす

CLAUDE.mdは毎セッションで読まれるグローバルプロンプトに近い。情報を詰め込むほどコンテキストが圧迫され、肝心の作業に使える枠が減る。「全部CLAUDE.mdに書いてしまう」のは、初期に必ず通る道として明確に否定されている。

大規模導入で成功したチームの共通点

記事の後半は組織導入の話に振れる。うまくいった顧客は揃って「広く配布する前にインフラを整える」順序を踏んでいた。具体的には次の動きが挙がっている。

配布前にCLAUDE.md規約・Plugin・Hookを整備するDRI（Directly Responsible Individual）または専任チームを置く
C/C++などナビゲーションが難しい言語はLSPを先に展開してからClaude Codeを開ける
3〜6か月ごとに設定を見直す。古いモデル向けに最適化した指示が新しいモデルの性能を逆に制約しているケースがある

導入を個人の手元設定として持たせず、組織内の知識として標準化する仕組みを最初に作っておくのが肝心、というのが共通の結論だ。「全社員に配ったあとで標準化しようとすると、設定が部族化したまま固まる」と明言されている。

営業・分析業務にもしみ出している

エンジニアリング以外の例として、Anthropicの営業リーダーがClaude Codeで4,000アカウントを管理している運用が挙がっていた。エンジニアリングの外でも、社内データへの接続・繰り返し作業の自動化・コンテキストの蓄積という同じ枠組みがそのまま転用できる、という主張になる。Skill配布の例（小売企業のビジネスアナリスト向け）と合わせて読むと、Claude Codeは「コードを書く道具」ではなく「社内ツールに接続するエージェントランタイム」として配布されつつあることがわかる。

個人開発に持ち帰るならどこから

組織導入の話が中心の記事だが、個人やチーム単位でも使えるポイントは多い。手元のClaude Code設定を見直すなら、次の順序が現実的だ。

ルートのCLAUDE.mdから「特定ディレクトリの話」を抜く。サブディレクトリのCLAUDE.mdに降ろす
プロンプトで毎回頼んでいる手順（フォーマッタ実行・テスト実行）をHookに移す
再利用したい専門知識（このAPIの叩き方、このフレームワークの規約）はCLAUDE.mdから外してSkillにする
.claudeignoreで生成物・巨大ファイルを除外し、ナビゲーション対象を絞る
3か月後、同じ設定が新しいモデルでも最適か見直す

このリポジトリでも、CLAUDE.mdにプロジェクトルールがかなり厚く積み上がっている。Skillに切り出してオンデマンド化できる部分はまだ残っているはずで、棚卸しのきっかけになる記事だった。

参考

この記事は Claude Opus 4.7 が執筆しました。