Claude Code を大規模コードベースで使うベストプラクティス

Claude Code の精度は、使うモデルよりハーネス（CLAUDE .md などの設定）の整備で決まる。RAG みたいなインデックスを持たず grep でその場で探すから、設定の質がそのまま探索の精度になる

大規模なコードベースほど、事前のセットアップが効いてくる

Claude Code、大規模コードベースでの公式ベストプラクティスが出てた

CLAUDE .md はルートを薄く、ローカルな規約はサブディレクトリに書く
作業はリポジトリルートやなくサブディレクトリで始める
ハーネスは基本 CLAUDE .md → hooks → skills → plugins → MCP の順で積む
stop hook でセッションの学びを CLAUDE .md に反映させる
CLAUDE .md は3〜6ヶ月ごとに棚卸しする

Claude Code はインデックスを作らない

RAG 型のツールは、コードベース全体を埋め込み（ベクトル）に変換してインデックスを作り、質問のたびに関連しそうな断片を引っぱってくる。これが大規模やと厳しい。何千人ものエンジニアが毎日コミットするから、埋め込みパイプラインが更新に追いつかない

インデックスを引いた時点で、それは数時間前、下手したら数週間前のコードベースを指してる。2週間前に名前を変えた関数や、先週消したモジュールが、古いという表示もなく平気で返ってくる

Claude Code はそこを避けてる。インデックスを作らず、人間のエンジニアと同じようにファイルツリーをたどって、grep で必要なところを探して、参照を追っていく。開発者のマシン上でそのまま動くから、サーバーにインデックスを構築・維持・アップロードする必要もない。常にライブのコードベースを見てるってことや

ただ、これには裏返しがある。Claude が「どこを見ればいいか」の手がかりを持ってないと効かない。何の文脈もないまま「この曖昧なパターンを全部探して」と頼むと、作業を始める前にコンテキストの上限に達してしまう。だから次に出てくる CLAUDE .md やハーネスの整備が効いてくる

性能はモデルよりハーネスで決まる

Claude Code でいちばん誤解されてるのが、性能はモデルで決まるという思い込みや。みんなモデルのベンチマークや、お試しタスクでの出来を気にする。けど実際に効くのは、モデルの周りに組み上げた仕組み、つまりハーネスのほうやと公式は言い切ってる

土台になる拡張ポイントは5つで、CLAUDE .md、hooks、skills、plugins、MCP サーバー。それぞれ役割が違う。CLAUDE .md は文脈、hooks は自動化、skills は専門知識、plugins は配布、MCP は外部ツールへの接続

積む順は基本この通り。前の層の上に次が乗るから、順番が効いてくる。土台ができてないのに MCP だけ先に生やしても、ぐらついたまま機能が増えるだけや。さらに LSP 連携とサブエージェントが加わって、ハーネス全体ができあがる

CLAUDE .md は薄く、階層的に

CLAUDE .md は、Claude が毎セッションの最初に自動で読む文脈ファイル。ここがポイントで、タスクに関係あるかどうかに関わらず毎回読まれる。だから何でもかんでも書き込むと、そのぶん毎セッションのコンテキストを食って、性能を落とす方向に働く

ルートの CLAUDE .md は、全体像と「これを踏むと事故る」っていうハマりどころだけに絞る。それ以外は基本ノイズになる。細かいローカルな規約は、その規約が効くサブディレクトリの CLAUDE .md に書く

Claude はディレクトリを下りながら、見つけた CLAUDE .md を順に追加で読んでいく。だからルートを薄くしても、深い階層の文脈はちゃんと積み上がる。薄く、階層的に、が基本やな

起動はルートやなくサブディレクトリ

作業を始めるとき、リポジトリのルートやなく、タスクに関係するサブディレクトリで Claude を起動したほうが精度が出る。モノレポやと、ツールがルート前提で動くことが多いから直感に反するけど、効くのはこっち

Claude は起動した場所から親をたどって、道中の CLAUDE .md を全部拾う。だからサブディレクトリで起動しても、ルートの文脈が失われることはない

ついでに、テストやリントのコマンドもサブディレクトリ単位で CLAUDE .md に書いておくといい。1つのサービスをいじっただけで全スイートを回すと、タイムアウトするし、関係ない出力でコンテキストを無駄に食う

hooks の本当の使いどころは自己改善

hooks は、Claude が変なことをするのを止めるスクリプト、と思われがちや。けど真価はそこやない。もっと価値があるのは、セットアップを自己改善させる使い方のほう

たとえば stop hook。セッションが終わるタイミングで、その回に何が起きたかを振り返らせて、CLAUDE .md の更新案を出させる。文脈がまだ新しいうちにやるから精度が高い。これを回すと、設定が勝手に育っていく

start hook なら、セッション開始時にチーム固有の文脈を動的に読み込ませられる。各開発者が、自分のモジュールに合ったセットアップを手動設定なしで受け取れる。あとリントやフォーマットみたいな決まりきったチェックは、hooks で機械的に効かせたほうが、Claude に「覚えといてね」と頼むより結果が安定する

古い CLAUDE .md は足かせになる

モデルは進化する。今のモデル向けに書いた指示が、次のモデルでは逆に足を引っ張ることがある

わかりやすいのが「リファクタは1ファイルずつに分けて」みたいなルール。昔のモデルが脱線しないように書いたんやろうけど、今のモデルはファイルをまたいだ協調的な編集を普通にこなす。古いルールが残ってると、その能力を止めてしまう

skills や hooks も同じや。モデルの弱点や Claude Code のツールの穴を埋めるために作ったものは、その穴が塞がった瞬間にただのオーバーヘッドになる。実際、Perforce のコードベースでファイル書き込みに p4 edit を強制してた hook は、Claude Code が Perforce にネイティブ対応した時点で不要になった

だいたい3〜6ヶ月ごとに設定の棚卸しをするといい。大きなモデルが出たあと、性能が頭打ちに感じたタイミングでやるのも効く

設定をまとめる人を1人決める

技術的なセットアップだけでは、組織への普及は進まない。うまくいってる組織は、組織側の仕組みにも投資してる

いちばん速く広がったのは、広くアクセスを開ける前に、専任の少人数チーム（ときに1人）が先にツールを整えたケースや。開発者が初めて触った時点で、もう自分のワークフローに馴染んでる状態を作る。最初の体験が「使えない」やなくて「生産的」になるから、そこから自然に広がっていく

最近は「エージェントマネージャー」という、PM とエンジニアを兼ねたような役割を置く組織も出てきてる。専任チームが無理でも、最低限ほしいのは DRI を1人決めること。設定、権限ポリシー、プラグインのマーケットプレイス、CLAUDE .md の規約に責任を持って、最新に保つ人

ボトムアップの盛り上がりは熱量を生むけど、まとめ役がいないと断片化する。良い設定が属人化したまま、普及が頭打ちになる

おわりに

ここまでが、公式のベストプラクティス記事から読み取れた要点や。元記事はエンタープライズ規模を念頭に書かれてるけど、CLAUDE .md の書き方、起動位置、ハーネスの積み方あたりは、個人開発や小さなチームでもそのまま効く

まずは CLAUDE .md をルートとサブディレクトリに分けて薄く整えるところから始めるのがいいと思う