How Claude Code works in large codebases: Best practices and where to start

原典: How Claude Code works in large codebases: Best practices and where to start

一行要約

大規模コードベースでの Claude Code の実運用パターン。エージェント検索は索引を持たないから腐らないが、その代償として「どこを見ればいいか」の初期 context を人間が用意する必要がある。そして harness は積む順序が決まっていて、3〜6ヶ月ごとに削る前提で持つ。

要点

なぜ索引を作らないのか

Claude Code navigates a codebase the way a software engineer would: it traverses the file system, reads files, uses grep to find exactly what it needs, and follows references across the codebase. It operates locally on the developer’s machine and doesn’t require a codebase index to be built, maintained, or uploaded to a server.

Claude Code はソフトウェアエンジニアと同じやり方でコードベースを渡り歩く。ファイルシステムを辿り、ファイルを読み、grep で必要なものだけを見つけ、コードベース中の参照を追う。開発者のマシン上でローカルに動作し、コードベースの索引を構築・保守・サーバへアップロードすることを要求しない。

RAG 型が大規模で壊れる理由が明示されている。

By the time a developer queries the index, it reflects the codebase as it previously existed weeks, days, or even hours before. Retrieval then returns a function the team renamed two weeks ago, or references a module that was deleted in the last sprint, with no indication that either is out of date.

開発者が索引に問い合わせる頃には、それは数週間・数日・あるいは数時間前のコードベースを映している。検索は2週間前にチームが改名した関数や、前のスプリントで削除されたモジュールを返す。どちらも古くなっているという表示は無い。

代償も同じ段落で認めている。

But the approach has a tradeoff: it works best when Claude has enough starting context to know where to look. (…) If you ask it to find all instances of a vague pattern across a billion-line codebase, you’ll hit context-window limits before the work begins.

だがこの手法にはトレードオフがある。Claude がどこを見ればいいか分かるだけの初期 context を持っているときに最もうまく働く。（略）10億行のコードベースで曖昧なパターンの全出現箇所を探せと言えば、作業が始まる前に context window の上限に当たる。

harness はモデルと同じくらい効く

One of the most common misconceptions about Claude Code is that its capabilities are solely defined by the model used. (…) In practice, the ecosystem built around the model—the harness—determines how Claude Code performs more than the model alone.

Claude Code について最もよくある誤解の一つは、その能力が使用モデルだけで決まるというものだ。（略）実際には、モデルの周りに構築されたエコシステム —— harness —— の方が、モデル単体よりも Claude Code の性能を決めている。

拡張点は5つ（CLAUDE.md / hooks / skills / plugins / MCP servers）で、積む順序が決まっている。加えて LSP と subagent の2つの能力が補う。

構成要素	いつ読まれるか	向くもの	よくある取り違え
CLAUDE.md	毎セッション	プロジェクト固有の規約・コードベースの知識	skill に属する再利用可能な専門知識をここに入れる
Hooks	イベント契機	一貫した振る舞いの自動化、セッションの学びの回収	自動で走るべきものを prompt でやろうとする
Skills	必要時（オンデマンド）	セッションやプロジェクトを跨ぐ再利用可能な専門知識	代わりに全部を CLAUDE.md へ入れる
Plugins	設定後は常時	動く設定を組織へ配布する	良い設定が属人的なまま留まる
LSP	設定後は常時	シンボル単位の探索、型付き言語での自動エラー検出	自動で有効だと思い込む
MCP servers	設定後は常時	他の手段では届かない内部ツールへの接続	基礎が動く前に MCP 接続を作る
Subagents	呼び出し時	探索と編集の分離、並列作業	探索と編集を同じセッションでやる

hook の本命は禁止ではない。

Most teams think of hooks as scripts that prevent Claude from doing something wrong, but their more valuable use is continuous improvement. A stop hook can reflect on what happened during a session and propose CLAUDE.md updates while the context is fresh.

ほとんどのチームは hook を「Claude が間違ったことをするのを防ぐスクリプト」と考えるが、より価値のある使い道は継続的改善である。 stop hook はセッション中に起きたことを振り返り、context が新鮮なうちに CLAUDE.md の更新を提案できる。

コードベースを読めるようにする

CLAUDE.md は薄く、層にする。

The root file should be pointers and critical gotchas only; everything else drifts into noise.

ルートのファイルはポインタと決定的な落とし穴だけにすべきである。それ以外はノイズになっていく。

初期化はリポジトリルートではなくサブディレクトリで。 直感に反するが理由がある。

Claude automatically walks up the directory tree and loads every CLAUDE.md file it finds along the way, so root-level context is never lost.

Claude は自動的にディレクトリツリーを遡り、途中で見つけた CLAUDE.md をすべて読み込む。だからルートの context が失われることはない。

テストと lint のコマンドはサブディレクトリごとに区切る。 1つのサービスを変えただけで全スイートを走らせるとタイムアウトし、無関係な出力で context を浪費する。ただしコンパイル言語のモノレポでディレクトリ間の依存が深い場合は、この区切りは難しいと限界も併記されている。

LSP は文字列ではなくシンボルで探させる。

Grep for a common function name in a large codebase returns thousands of matches and Claude burns context opening files to figure out which matters. LSP returns only the references that point to the same symbol, so the filtering happens before Claude reads anything.

大規模コードベースでありふれた関数名を grep すれば数千件が返り、Claude はどれが重要かを判断するためにファイルを開いて context を燃やす。LSP は同じシンボルを指す参照だけを返すので、絞り込みは Claude が何かを読む前に済んでいる。

C / C++ の探索を大規模で確実にするため、ある企業は Claude Code 展開前に組織全体へ LSP を先に配備した。多言語コードベースでは最も価値の高い投資の一つとされる。

CLAUDE.md は積むだけでなく削る

harnessing-claudes-intelligence の「何をやめられるか」と同じ主張が、設定ファイルの側から出てくる。

As models evolve, instructions written for your current model can work against a future one. CLAUDE.md files that guided Claude through patterns it used to struggle with may either become unnecessary or actively constraining when the next model ships.

モデルが進化すると、現在のモデル向けに書いた指示が将来のモデルに対して逆に働きうる。かつて苦手だったパターンを導いていた CLAUDE.md は、次のモデルが出た時点で不要になるか、積極的に足枷になる。

例が2つ挙がる。「すべてのリファクタを1ファイル単位の変更に分割せよ」というルールは、旧モデルを軌道に乗せる役には立ったが、新しいモデルが得意な協調的なファイル横断編集を妨げる。Perforce コードベースで p4 edit を強制するためファイル書き込みを捕まえていた hook は、Claude Code が Perforce ネイティブ対応を入れた時点で冗長になった。

Teams should expect to do a meaningful configuration review every three to six months, but it’s also worth doing one whenever performance feels like it’s plateaued after major model releases.

チームは 3〜6ヶ月ごとに意味のある設定見直しを行うことを見込むべきである。加えて、大きなモデルリリースの後に性能が頭打ちに感じられたときにも行う価値がある。

組織側 — 設定だけでは普及しない

最も速く広がった展開には共通点があった。広く開放する前に、少人数（時に1人）が配線を済ませていたこと。開発者が最初に触れた体験が生産的だったので、そこから広がった。

新しい役割として agent manager（PM とエンジニアの中間で Claude Code エコシステムを管理する）が挙がる。専任チームを置けない組織向けの最小構成は DRI 1名で、設定・権限方針・plugin マーケットプレイス・CLAUDE.md 規約に対する決定権と、それらを最新に保つ責任を持つ。

Bottoms-up adoption generates enthusiasm but can fragment without someone to centralize what works. (…) Without that work, knowledge will stay tribal and adoption will plateau.

ボトムアップの普及は熱意を生むが、うまくいくものを中央に集める人がいないと断片化する。（略）その仕事が無ければ、知識は属人的なまま留まり、普及は頭打ちになる。

適用範囲の限界（原典が自分で認めている）

Claude Code is designed around conventional software engineering environments where engineers are the primary codebase contributors, the repo uses Git, and code follows standard directory structures.

Claude Code は、エンジニアが主たるコードベースの寄与者であり、リポジトリが Git を使い、コードが標準的なディレクトリ構造に従う慣習的なソフトウェア開発環境を前提に設計されている。

外れるものとして、大きなバイナリ資産を持つゲームエンジン、非慣習的なバージョン管理、非エンジニアが寄与するコードベースが名指しされる。また数十万フォルダ・数百万ファイル規模や非 git のレガシーでは、階層 CLAUDE.md 方式そのものが破綻することも明記されている。

そのまま使える具体例

CLAUDE.md の層構成:

置き場	書く内容
リポジトリルート/CLAUDE.md	ポインタと決定的な落とし穴だけ
services/payments/CLAUDE.md	そのディレクトリのテスト・ビルドコマンド
services/search/CLAUDE.md	同上

Claude はツリーを遡って全部読むので、ルートの内容は失われない。

ノイズ削減をチーム全員に配る:

.claude/settings.json の permissions.deny をコミットする。生成物・ビルド成果物・サードパーティを除外し、個人設定で上書きもできる。

ディレクトリ構造が語らない場合の目次:

リポジトリルートに軽量な markdown を1枚置き、トップレベルの各フォルダに1行の説明を付ける。フォルダが数百あるなら、ルートは最上位だけにして、詳細はサブの CLAUDE.md へ送る。

原典で言及されている関連文書

• features-overview — CLAUDE.md / skills / hooks / MCP / plugins の使い分け
• skills — progressive disclosure とパス限定
• hooks-guide — stop hook / start hook
• mcp — MCP サーバ
• sub-agents — 探索と編集の分離
• memory — CLAUDE.md の階層読み込み
• settings — permissions.deny のコミット