Anthropic が公式ブログで公開した How Claude Code works in large codebases: Best practices and where to start は、エンタープライズ規模で Claude Code を運用する際の指針として、公開時点（2026 年 5 月）で実務的によくまとまった一次情報です。
「コードベースが大きくなると AI コーディングは破綻するのではないか」という、現場で繰り返し問われる懸念に対して、Anthropic 自身が「破綻させないための設計」を体系的に示しています。本記事では、その要点と、私たちが実装現場で観測している知見を重ね合わせる形で整理します。
なぜ Claude Code は大規模コードベースでも動くのか
最初の論点は、検索方式の選択です。
多くの「コードベースを理解する」型の AI ツールは、リポジトリ全体を埋め込みベクトル化してインデックスを作り、クエリ時に関連チャンクを取り出す RAG（Retrieval-Augmented Generation） に依存しています。これは小〜中規模では機能しますが、開発が活発なコードベースでは、埋め込みパイプラインが現実の変更に追いつけません。削除されたモジュール、改名された関数、置き換わったパターンが、古いインデックスから「あたかも現在の真実であるかのように」呼び戻されてしまうのです。
Claude Code はこの問題を構造から避けています。
採用しているのは Agentic Search、すなわちエージェントがファイルシステムを歩き、必要なファイルを読み、grep で探し、参照を辿るというアプローチです。これは人間のエンジニアが新しいリポジトリに飛び込んだときに行う動作とほぼ同じで、各セッションは常に「現在のコードベース」を直接見ます。インデックスのドリフトは原理的に発生しません。
トレードオフはあります。Agentic Search は 起点の質に依存します。どこから探索を始めるか、何を読むべきか、どの方向に参照を辿るべきか。ここを支えるのが、Claude Code のもう一方の主役である ハーネス（harness） です。
Claude Code を取り囲む7つの要素
Anthropic はこの記事で、モデル単体ではなく モデルを取り巻く実行環境＝ハーネスこそが大規模コードベースでの成否を分ける、と明言しています。
原文での harness の定義は 5 つの拡張点（CLAUDE.md / Hooks / Skills / Plugins / MCP servers）です。本記事ではこれに、harness と連携してシンボル探索や独立コンテキストを補う LSP と Subagents を加えて、Claude Code を実用に乗せるために理解しておきたい 7 つの要素として整理します。
1. CLAUDE.md（プロジェクト憲章）
セッション開始時に自動で読み込まれる、プロジェクトの常識を書いた文書です。重要なのは「ルートに1枚」ではなく 階層的に配置すること。Claude はディレクトリツリーを上に辿りながら、見つけたすべての CLAUDE.md を加算的にロードします。
そして、CLAUDE.md は毎セッションで必ず読み込まれるため、肥大化はそのままコンテキスト消費と認知ノイズに直結します。「広く適用される指示だけを残す」「ローカルな慣行はサブディレクトリ側に書く」という剪定が常に必要です。
2. Hooks（自動化フック）
ツール呼び出しの前後で確定的に動くスクリプトです。Lint・Format・型チェックのように 「Claude に覚えさせるよりルールで強制した方が確実」 な領域は、Hooks で固めるのが定石です。
Stop hook でセッション後に CLAUDE.md の更新案を提示させる、Start hook でチーム固有のコンテキストを動的にロードする、といった運用も紹介されています。各開発者が手動セットアップせずに同じ環境を得られる、配布可能な仕組みです。
3. Skills（オンデマンドの専門知識）
特定タスクのときだけロードされる再利用可能なノウハウ集です。特定パスにスコープを縛れることが重要で、たとえば決済サービスを所有するチームが「デプロイ用 Skill」をそのディレクトリ配下に紐付ければ、別チームが他の領域で作業しているときに自動ロードされてコンテキストを汚すことがありません。
4. Plugins（組織的配布の単位）
Skills・Hooks・MCP 設定をひとまとめにし、Marketplace 経由で組織全体に配れる仕組みです。「動く設定」を1人のエキスパートから組織全体へスケールさせる導線になります。
5. LSP（Language Server Protocol）統合
IDE が持つ シンボル単位のナビゲーション能力を、そのまま Claude に渡す統合です。LSP がないと Claude は文字列一致でファイルを当たるしかなく、命名衝突や同名関数の判別が脆くなりますが、LSP があれば「同名だが別スコープのシンボル」を正しく見分けて参照を辿れます。
C/C++ のように静的解析が複雑な言語の大規模 Monorepo では、LSP 連携が 組織横断で事前配備されるケースまで出てきている、と紹介されています。
6. MCP Servers（社内ツール／データへの接続）
社内分析プラットフォーム、ドキュメント、チケットシステムなどに Claude を繋ぐ標準プロトコルです。コードだけでなく「業務知識」「過去のチケット」「ダッシュボード」を扱えるようになると、エージェントの守備範囲は大きく広がります。
7. Subagents（独立コンテキストの分身）
親エージェントとは別のコンテキストウィンドウを持つ、隔離された Claude インスタンスです。代表的な使い方は探索と編集の分離で、「Read-only な Subagent にサブシステム全体を読ませて要点ファイルを書かせ、親エージェントはその要点だけを携えて編集に集中する」というパターンが紹介されています。親エージェントのコンテキストを汚さず、深い探索をやらせるためのよく紹介される構成です。
大規模コードベースを「歩ける」状態にする3つのパターン
これらの要素を揃えるだけでは不十分で、Anthropic は 3つの設計パターン にまとめて運用方針を示しています。
パターン1：Navigability（歩ける構造を作る）
エージェントが効率よくコードを巡れるための、地形整備です。
- CLAUDE.md は薄く・階層化する：ルートには全体像と注意事項だけ、サブディレクトリにローカル慣行
- 整備の起点はルートではなく、サブディレクトリから。これは直感に反しますが、Claude はディレクトリツリーを自動的に上方向に走査するため、サブから書き始めてもルートの大域コンテキストは結局ロードされます。Monorepo では、まずチーム所有のサブディレクトリ側に整備するほうが投資対効果が高い
- ビルドコマンド・テストコマンドはサブディレクトリごとに定義する（モノレポでは特に）
.gitignore等の.ignoreファイルで生成物・ビルド成果物・サードパーティコードを排除し、ノイズで探索を腐らせない。Claude Code 側に追加の境界を引きたい場合は.claude/settings.jsonのpermissions.denyルールを版管理する手も Anthropic が推奨しています- 慣習から外れた構造にはコードベースマップ（地図ファイル）を置く
- シンボル中心の言語には LSP を必ず入れる
パターン2：CLAUDE.md・Skills・Hooks を 3〜6 ヶ月で見直す
Anthropic がパターン2 として明示しているのは、CLAUDE.md を中心とした モデルの進化に合わせた継続的なメンテナンス です。Skills や Hooks も、過去のモデル制約を補うために書かれたものは、現行モデルが同じ課題を自力で解けるようになった瞬間に オーバーヘッド になる、と原文は指摘しています。
たとえば「リファクタは1ファイル単位に分割せよ」という指示は、過去のモデルには有効でも、現行モデルが整合的なクロスファイル編集をこなせるようになると、むしろ作業を遅らせます。3〜6 ヶ月ごと、あるいは大きなモデル更新の直後に CLAUDE.md・Skills・Hooks を見直す運用が推奨されています。
パターン3：Ownership（誰が所有するか）
最小実装版は DRI（Directly Responsible Individual）モデルです。Claude Code の設定・パーミッションポリシー・Plugin Marketplace・CLAUDE.md の慣習について、決定権を持つ1人を置く。多くの組織ではこの DRI が Developer Experience / Developer Productivity 部門 に属し、エンジニアのオンボーディング責任と接続されています。
さらに大規模な組織では、PM とエンジニアのハイブリッド職である Agent Manager という新しいロールが立ち上がりつつあること、そして エンジニアリング × 情報セキュリティ × ガバナンス の代表者によるクロスファンクショナル・ワーキンググループが要件定義を共同で進めている事例も紹介されています。
どこから始めるか
「いきなり全部やろうとしない」が、この記事から読み取れる最も実務的なメッセージです。優先度の高い順に並べると、次のようになります。
- CLAUDE.md の階層構造を整える：ルートには全体像と注意事項だけ、サブディレクトリにローカル慣行
.gitignore等の.ignoreで雑音を捨てる：生成物・ビルド成果物・サードパーティコード。必要なら.claude/settings.jsonのpermissions.denyで版管理する境界も合わせて整える- サブディレクトリごとに build / test コマンドを定義する
- Hooks で linting / formatting を確定的に強制する
- 複数言語が混在するなら LSP を入れる（特に C/C++、TypeScript、Rust などシンボル中心の言語）
- チーム固有のノウハウを Skill 化する：オンデマンドで、スコープを絞って
- MCP で社内データ／ツールに接続する
- Plugin にまとめて組織配布する
そして上記すべてを まずは DRI 1人 で所有するところから始める、というのが Anthropic 推奨の最小構成です。組織規模が大きくなったら、Agent Manager や エンジニアリング × 情報セキュリティ × ガバナンス のクロスファンクショナル WG への発展も視野に入ります。
フィールフロウからの視点
私たちが AI 駆動開発の伴走支援で繰り返し見ているのは、「ハーネスの整備に投資した組織だけが、AI コーディングの ROI を本当に取り切れる」という事実です。
モデルそのものは、もはやどの組織も同じものを使えます。差がつくのは、CLAUDE.md・Hooks・Skills・MCP・LSP といった「モデルを取り囲む設計」と、それを継続的に整備するオーナーシップです。
特に日本企業の場合、「AI を試したけれど期待ほど動かない」という声の 少なくない部分 は、モデルの限界ではなく ハーネス未整備 が原因です。Anthropic のこの記事は、その診断と処方を、極めて簡潔に整理してくれています。
実装を始めるとき、まず CLAUDE.md の階層化と .gitignore まわりの整備、そして DRI を1人指名すること。この3つから着手するのが、最も投資対効果の高い始め方です。フィールフロウでは AI Web 伴走支援 を通じて、この「ハーネス整備」を含めた AI 駆動開発の立ち上げを並走しています。
参考
- How Claude Code works in large codebases: Best practices and where to start — Anthropic 公式ブログ
- Codified Context: Infrastructure for AI Agents in a Complex Codebase（日本語訳） — 関連する論文の翻訳記事
- Claude Code ベストプラクティス完全ガイド：実践と設計思想 — 一般的なベストプラクティス
- Claude Codeを本気で使う人のための設定大全【v2.1.32対応】 — 設定項目の詳細リファレンス（執筆時点のバージョン）