要点

Anthropic は 2026年5月14日、Claude Code を大規模コードベースに導入した事例から共通パターンを抽出したブログ記事を公開しました。数百万行のモノリポ、数十年のレガシー、数千人の開発組織が対象です。
中心的な主張は「Claude Code の性能はモデルだけで決まらない。モデルを取り巻く仕組み（ハーネス）が決める」です。
ハーネスは CLAUDE.md、フック、スキル、プラグイン、MCP サーバの5つの拡張点と、LSP・サブエージェントの2つの追加機能から成ります。この記事では便宜上まとめて7層と呼びます。各層は前の層を土台にするため、構築する順序が重要です。
この記事では7層を構築順に、役割、大規模で効く理由、最初に置く設定を1つずつ説明します。あわせて、成功事例に共通する3つのパターンと、導入チェックリストを整理します。
具体的な設定値は Claude Code の公式ドキュメントで確認したものを使っています。
7層の監査と構築を支援する Claude Code のプラグイン cc-harness-kit（MIT）を公開しています。詳細は本文末の節で説明します。

はじめに

対象は、チームや組織で Claude Code を大きなコードベースに導入する立場の方です。個人で小さなリポジトリに使う分には、ここまでの構成は要りません。

前提環境は Claude Code の 2026年9月時点の版です。CLAUDE.md、スキル、フック、プラグインの存在は知っている前提で書きます。CLAUDE.md 自体の書き方と軽量化は別記事で扱うため、ここでは配置と階層に絞ります。

大規模コードベースで何が起きるか

Claude Code はコードをどう辿るか

Claude Code は、人間のエンジニアと同じ方法でコードベースを辿ります。ファイルシステムを歩き、ファイルを読み、grep で探し、参照を追跡します。開発者のマシン上で動くので、コードベースのインデックスを作って保守したり、サーバへアップロードしたりする必要がありません。

Anthropic は、RAG（検索拡張生成）型のコーディングツールとの違いをこう説明しています。RAG 型はコードベース全体を埋め込みベクトルにし、問い合わせ時に関連部分を取り出します。大規模になると、埋め込みの更新が開発速度に追いつきません。その結果、2週間前に改名された関数や、前のスプリントで削除されたモジュールが、「古い」という表示もなく返ることがあります。エージェント型の検索なら、各開発者の環境がライブのコードベースを対象にするため、この問題は起きません。

この比較は Anthropic 自身の設計を擁護する主張でもあるので、そのまま受け取るより「鮮度の問題をどう避けるか」という観点で読むのが妥当です。

引き換えに、初期コンテキストが要る

エージェント型にも弱点があります。Claude がうまく動くのは、どこを探せばよいかを判断できる初期コンテキストがあるときです。10 億行のコードベースに曖昧なパターンで検索をかけると、作業が始まる前にコンテキストウィンドウを使い切ります。

つまり、ナビゲーションの質はコードベースの整備状況で決まります。Anthropic は「コードベースの整備に投資したチームほど良い結果を得ている」と述べています。この整備の中身が、次に説明するハーネスです。

「モデルが全て」は誤解。性能を決めるのはハーネス

Anthropic は、「Claude Code の能力は使うモデルで決まる」という考えをよくある誤解だと指摘します。モデルを取り巻くエコシステム、同社が「ハーネス」と呼ぶ仕組みが、モデル単体以上に性能を左右します。

Anthropic は、CLAUDE.md、フック、スキル、プラグイン、MCP サーバを「5つの拡張点」、LSP とサブエージェントを「2つの追加機能」と呼び分けています。この記事では構築順に並べて7層として扱います。

層	役割	いつ効くか
1. CLAUDE.md	土台。コードベースの知識	毎セッションの開始時
2. フック	自己改善と決定論的な強制	セッション開始時・応答終了時・ツール実行の前後
3. スキル	専門知識の段階的開示	タスクで必要になったとき
4. プラグイン	配布	導入後は常時
5. LSP	シンボル単位のナビゲーション	コードを読む・書くとき
6. MCP サーバ	社内ツール・データへの拡張	導入後は常時
7. サブエージェント	探索と編集の分離	大きな調査を切り出すとき

各層は前の層を土台にします。基本構成が整う前に配布や外部接続を増やすと、何を共有し、何を強制すべきかの判断がつかないまま複雑さだけが増えます。順序を守ることが、この記事の一番の主張です。

もう1つ、先に押さえておく仕様があります。CLAUDE.md は親ディレクトリのものが継承されますが、.claude/settings.json（フック、権限、プラグインの設定）は継承されません。作業するパッケージのディレクトリから起動する運用にするなら、設定はそのパッケージの .claude/settings.json に置きます。以下の設定例はこの前提で読んでください。

構築順に見る7層

各層について、役割、大規模で効く理由、最初に置く設定を1つ示します。

第1層. CLAUDE.md を階層化する

役割: 毎セッションの開始時に Claude が自動で読むコンテキストです。コードベースの全体像とローカルな規約を渡します。

大規模で効く理由: 1つのルート CLAUDE.md にすべての部門の規約を書くと、無関係な指示でコンテキストを埋めるか、抽象的で役に立たない内容になります。Claude Code は作業ディレクトリから親へ向かってすべての CLAUDE.md を起動時に読み、下位ディレクトリの CLAUDE.md はそこにあるファイルを読んだときにだけ読み込みます。この性質を使い、ルートには全体共通の規約、サブディレクトリにはその領域の規約だけを置きます。

最初に置く設定: ルートとサブディレクトリの2段構成です。公式ドキュメントの目安は1ファイル 200 行未満です。

monorepo/
  CLAUDE.md                # 全体共通の規約だけ
  packages/
    api/CLAUDE.md          # API パッケージ固有の規約
    web/CLAUDE.md          # フロント固有の規約

作業するパッケージのディレクトリから claude を起動すると、そのディレクトリと親の CLAUDE.md だけが読み込まれ、隣のパッケージの規約は入りません。Anthropic はこの「サブディレクトリで初期化する」運用を成功事例の共通点として挙げています。ルートから起動せざるを得ない場合は、設定の claudeMdExcludes で他チームの CLAUDE.md を除外できます。

第2層. フックで「譲れないもの」を強制し、自己改善させる

役割: セッションの開始時、Claude が応答を終えたとき、ツール実行の前後に走るスクリプトです。

大規模で効く理由: Anthropic は、多くのチームがフックを「誤った動作を防ぐもの」と捉えているが、より価値があるのは継続的な改善だと述べています。応答終了時のフック（Stop）はセッションの内容を振り返り、コンテキストが新鮮なうちに CLAUDE.md の更新案を出せます。開始時のフック（SessionStart）はチーム固有のコンテキストを動的に読み込み、各開発者が手作業なしで正しい構成を得られます。リンティングやフォーマットのような自動チェックは、CLAUDE.md に「必ず実行する」と書くより、フックで決定論的に強制したほうが結果が安定します。

最初に置く設定: Edit・Write ツールでファイルを編集した直後に、フォーマッタや型チェックを走らせる PostToolUse フックです。CLAUDE.md の「必ず〜すること」の行を1つ、ここへ移すところから始めます。

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-and-typecheck.sh" }
        ]
      }
    ]
  }
}

スクリプトのパスは ${CLAUDE_PROJECT_DIR} で始めます。起動したディレクトリを基準に解決されるので、サブディレクトリから起動しても迷子になりません。

CLAUDE.md の指示は行動を誘導するもので、強制ではありません。導入チェックリストが「譲れないもの（フォーマット、テストコマンド、セキュリティチェック）はフックで、毎回、任意ではなく強制する」と書いているのはこのためです。

第3層. スキルで専門知識を段階的に開示する

役割: 特定のタスクに要る手順や知識を、必要なときだけ読み込む単位です。

大規模で効く理由: 数十種類のタスクがあるコードベースで、全部の手順を CLAUDE.md に書くと毎セッションが重くなります。スキルは本文がタスクで必要になったときだけ読み込まれる（段階的開示）ので、専門知識をいくら増やしてもセッションの土台は太りません。

最初に置く設定: 領域ごとの .claude/skills/ です。公式ドキュメントは、パッケージのディレクトリ配下にスキルを置く構成を示しています。API パッケージのテスト手順のスキルは、フロントの作業中には読み込まれません。

packages/api/.claude/skills/api-testing/SKILL.md
packages/web/.claude/skills/component-patterns/SKILL.md

スキルの description は、Claude がそのスキルを開くかどうかを判断する材料です。スキルが増えると説明文は短く切られるため、「packages/api のテストを書く・直すとき」のように、依頼文に含まれそうな語を先頭に置きます。

第4層. プラグインで配布する

役割: スキル、フック、MCP 設定をひとつのパッケージに束ね、インストール可能な形で配布します。

大規模で効く理由: 良い構成を作っても、それが一部のチームの「部族知識」にとどまると、組織全体の生産性は上がりません。Anthropic は、大手小売企業が社内分析基盤に接続するスキルをプラグインとして配布し、業務アナリストが自分のワークフローから離れずにデータを引けるようにした例を挙げています。

最初に置く設定: リポジトリの .claude/settings.json に、自社マーケットプレイス（Git リポジトリで作れます）を extraKnownMarketplaces で登録し、使うプラグインを enabledPlugins に書きます。外部ソースのプラグインは、この2つを書いただけでは各メンバーの環境に入りません。Claude Code が未インストールを検知してインストールコマンドを案内するので、各メンバーがそれを実行します。全員に強制したい場合は、管理者が管理設定（managed settings）で配布します。

第5層. LSP でシンボル単位に辿る

役割: 言語サーバプロトコル（LSP）を通じて、IDE と同じ「定義へ移動」「すべての参照を検索」を Claude に与えます。

大規模で効く理由: 大きなコードベースで関数の定義や呼び出し元を探すと、多数のファイル読み取りと grep が要ります。LSP があれば、文字列の一致ではなくシンボルで解決でき、別言語で同名の関数を区別できます。Anthropic が協力したあるエンタープライズソフトウェア企業は、C と C++ のナビゲーションを大規模に安定させるため、Claude Code の展開前に LSP 統合を全社に配りました。Anthropic は、多言語のコードベースでは LSP が最も投資価値の高いものの1つだと述べています。

最初に置く設定: 公式マーケットプレイスのコードインテリジェンスプラグインです。プラグインは接続設定だけで、言語サーバ本体は含みません。先にバイナリを PATH に入れます。

# 1. 言語サーバ本体を入れる（例: TypeScript）
npm install -g typescript-language-server typescript

# 2. Claude Code のセッション内でプラグインを入れる
/plugin install typescript-lsp@claude-plugins-official

言語	プラグイン	必要なバイナリ
C / C++	`clangd-lsp`	`clangd`
C#	`csharp-lsp`	`csharp-ls`
Go	`gopls-lsp`	`gopls`
Java	`jdtls-lsp`	`jdtls`
Kotlin	`kotlin-lsp`	`kotlin-language-server`
Lua	`lua-lsp`	`lua-language-server`
PHP	`php-lsp`	`intelephense`
Python	`pyright-lsp`	`pyright-langserver`
Rust	`rust-analyzer-lsp`	`rust-analyzer`
Swift	`swift-lsp`	`sourcekit-lsp`
TypeScript	`typescript-lsp`	`typescript-language-server`

有効になると、Claude は編集直後に型エラーや import 漏れの診断を受け取り、同じターンで直します。ナビゲーションでは定義ジャンプ、参照検索、hover の型情報、呼び出し階層が使えます。使える機能は言語サーバと環境によって異なり、クラウドセッションではプラグインの言語サーバは起動しません。全員に効かせるには enabledPlugins に入れ、バイナリの配布は開発環境のセットアップ手順に組み込みます。

.claudeignore というファイルは Claude Code の正式機能にはありません（2026年9月時点）。検索結果からの除外は .gitignore が既定で効きます。ファイルの読み取り自体を止めるには、後述する permissions.deny を使います。

第6層. MCP サーバで社内ツールにつなぐ

役割: Claude を社内のツール、データソース、API に接続します。

大規模で効く理由: 大規模組織には、チケット、監視、社内 API、ドキュメント基盤など、コードの外に判断材料があります。MCP で接続すると、Claude がそれらを直接問い合わせられます。公式ドキュメントは、組織に既存のコード検索や RAG インデックスがあるなら、それを MCP ツールとして公開し、Claude がファイルを直接読む代わりに問い合わせる構成も示しています。

最初に置く設定: 公式マーケットプレイスの外部連携プラグイン（github、atlassian、slack など）を1つ入れるところからです。MCP のツール検索により未使用ツールのコンテキスト負荷は抑えられますが、接続先、権限、運用の複雑さは接続を増やすほど増えます。土台の層が整ってから足す順序にするのはこのためです。

第7層. サブエージェントで探索と編集を分ける

役割: 独自のコンテキストウィンドウを持つ独立した Claude インスタンスです。タスクを受け取り、作業し、最終結果だけを親に返します。

大規模で効く理由: 大きなコードベースの調査は、ファイル読み取りでコンテキストを大量に消費します。探索をサブエージェントに任せると、読んだファイルの中身は親の会話に残らず、結論だけが戻ります。Anthropic の図では「Map → findings file」、つまり探索結果をファイルにまとめて親へ渡す形が示されています。

最初に置く設定: 設定ではなく運用です。「まず調査して方針を出して」という依頼をサブエージェントに投げ、その結果を受けて親が編集する、という分業を習慣にします。

成功事例に共通する3つのパターン

Anthropic は成功事例に共通するパターンを3つ挙げています。7層の構築と重なる部分が多いので、対応する設定と一緒に整理します。

パターン1. コードベースを辿れるようにする

6項目が共通していました。

項目	対応する設定・運用
CLAUDE.md を簡潔かつ階層的に書く	第1層。1ファイル 200 行未満、ルート＋サブディレクトリ
リポジトリのルートではなくサブディレクトリで初期化する	作業するパッケージから `claude` を起動する
テストと lint のコマンドをサブディレクトリに限定する	全体スイートはタイムアウトする。各 CLAUDE.md にその領域のコマンドだけ書く
生成物・ビルド成果物・サードパーティコードを除外する	`.gitignore`（検索は既定で尊重）と `permissions.deny` の Read 拒否ルール
従来のディレクトリ構造にまとまっていないなら、コードベースマップを作る	ルートに、最上位フォルダごとの1行説明を並べた軽量な Markdown を置く
LSP サーバを動かし、文字列ではなくシンボルで探させる	第5層

除外について補足します。Claude の検索は .gitignore を既定で尊重するため、node_modules/ や dist/ は追加設定なしで検索結果から外れます。チェックインされている生成コードや vendored SDK は、permissions.deny に Read の拒否ルールを書きます。.claude/settings.json にコミットすれば全員に同じ除外が効きます。deny ルールはスコープ間でマージされ、個人設定で打ち消せないため、例外が要るパスは共有の deny に入れない設計にします。

.claude/settings.json

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/*.generated.*)",
      "Read(./vendor/**)"
    ]
  }
}

パターン2. モデルの進化に合わせて CLAUDE.md を能動的に保守する

現行モデル向けに書いた指示は、将来のモデルでは足かせになり得ます。Anthropic が挙げる例は、Perforce のコードベースでファイル書き込みを横取りして p4 edit を強制していたフックです。Claude Code が Perforce をネイティブに扱えるようになった時点で、このフックは冗長になりました。

推奨は、3〜6か月ごとに構成を見直すことです。加えて、主要なモデルのリリース後に性能が頭打ちだと感じたときも見直しの合図です。第2層の Stop フックで更新案を出させる仕組みは、この保守を日常に組み込む手段です。

パターン3. 導入と管理の責任者を置く

技術的な構成だけでは導入は進みません。導入が速かった組織は、広く使い始める前に専用のインフラ整備に投資し、開発者が初日から生産的に使える状態を作っていました。Anthropic はこれを3つのフェーズで示しています。

フェーズ	内容
1. 静かな投資	広く公開する前に、責任者がインフラを1つずつ組み立てる
2. 展開	インフラが整った状態で、最初の開発者たちが生産的に使い始める
3. 拡大	口コミでチームからチームへ広がり、ハーネスの利用者が増える

責任の置き方には段階があります。専任チームがあるなら、通常は開発者体験や開発生産性を担う部門が持ちます。いくつかの組織で生まれている役割が「エージェントマネジャー」です。プロダクトマネジャーとエンジニアの中間に位置し、Claude Code のエコシステム管理に専念します。専任チームを持てない組織でも、最低限1人の DRI（直接責任者）を置きます。DRI は、設定、権限ポリシー、プラグインマーケットプレイス、CLAUDE.md の規約を決める権限と、それらを最新に保つ責任を持ちます。

規制業種ではガバナンスの問いが早く出ます。誰がどのスキルとプラグインを使えるかを決めるのか。数千人が同じものを別々に作るのをどう防ぐのか。AI が生成したコードを人間のコードと同じレビューに通すにはどうするか。Anthropic は、承認済みのスキル一式、必須のコードレビュー、限定的な初期アクセスから始め、信頼とともに広げることを勧めています。最も円滑だったのは、エンジニアリング、情報セキュリティ、ガバナンスの代表を早期に集めて部門横断のワーキンググループを作り、そこで要件と展開ロードマップを定めた組織でした。

導入チェックリスト

Anthropic の記事は、「最初の広範な展開の前に整える6つのこと」を図（Getting started checklist）として載せています。7層の順序に沿って並べ直すと、最初の1か月の作業順になります。

CLAUDE.md を構造化する。ルートは組織全体の文脈、サブディレクトリはチーム固有の規約。各 200 行程度まで。
譲れないものはフックで配線する。フォーマット、テストコマンド、セキュリティチェックは毎回強制し、任意にしない。
専門知識はスキルとプラグインに入れる。CLAUDE.md の指示に属さない、再利用可能な知識をここへ。
コードベースを辿れるようにする。除外設定、LSP サーバ、コードベースマップで雑音を減らす。
構成の定期見直しを予定に入れる。3〜6か月ごと、または新しいモデルが出たとき。古い回避策は負債になる。
オーナーを決める。最低でも、CLAUDE.md の階層を所有し最新に保つ人を1人。

この6つを手作業で1つずつ確認するのは負担なので、後の節で紹介する cc-harness-kit は同じ順序を採点と提案書という形で自動化しています。

前提と、当てはまらない環境

Claude Code は従来のソフトウェアエンジニアリング環境を前提に設計されています。エンジニアがコードベースの主な貢献者で、バージョン管理に Git を使い、コードが標準的なディレクトリ構造に従う環境です。

大規模コードベースの多くはこれに当てはまります。一方、大きなバイナリ資産を持つゲームエンジン、非標準的なバージョン管理、非エンジニアがコードベースに貢献する組織では、追加の構成作業が要ります。Anthropic のガイダンスは従来型の環境を前提にしており、そこから外れる部分は各組織のコードベース、ツール、体制に応じた判断が必要です。

7層の構築を支援するツール ── cc-harness-kit

ここまでの7層は、狙いが分かっても、既存リポジトリのどこから手を付けるかで迷います。この手順を「探索 → 提案書 → 承認 → 書込」という固定の流れに落とし込んだ Claude Code のプラグインが cc-harness-kit です。スキル9本で構成し、MIT ライセンスで公開しています。DRI と構成レビュー日を文書に残す役目は、後述する harness-ownership が担います。

導入は Claude Code のセッション内で完結します。

/plugin marketplace add nogataka/cc-harness-kit
/plugin install cc-harness-kit@cc-harness-kit

スキルと担当範囲は次のとおりです。

層	スキル	何を書くか
監査	`harness-audit`	7層それぞれの充足度を採点する。読み取り専用で、何も書き込みません
第1層 CLAUDE.md	`harness-claudemd`	ルート/サブディレクトリの2段構成、各200行未満に整える案
第2層フック	`harness-hooks`	フォーマット・型チェックの強制、不可逆操作の停止、応答終了時の更新案収集
第3層スキル	`harness-skills`	CLAUDE.md の手順をスキルへ、領域の規約を paths 付き rules へ切り出す案
第5層 LSP	`harness-lsp`	言語と言語サーバのバイナリを検出し、公式コードインテリジェンスプラグインの導入と `enabledPlugins` への追加を提案する案
第4層プラグイン	`harness-plugin`	公式プラグインの有効化、社内マーケットプレイスの登録案
除外	`harness-exclusions`	`.gitignore` の点検、`permissions.deny` の読み取り拒否ルール案
DRI	`harness-ownership`	DRI と構成レビューの周期を文書に残す案

第6層 MCP と第7層サブエージェントは専用スキルを持たず、監査が現状を報告し、harness-init が運用上の判断として案内します。

第5層 LSP を第4層プラグインより先に案内するのは、LSP の有効化がそのまま最初の enabledPlugins になり、プラグイン層で扱う判断（社内マーケットプレイスの登録、チームで共有するかどうか）がしやすくなるためです。

使い方の入口は /harness-init です。内部でまず harness-audit を呼んで7層の充足度を採点し、未充足の層から順に1つだけ次のスキルを案内します。案内された各 setup スキルは対象リポを探索し、harness-proposal-<層>.md に変更案を書いて止まります。採用する項目を選んで承認すると、スキルがその項目だけを書き込み、既存ファイルは .claude/harness-kit/backup/ 配下の日時付きディレクトリに退避します。書き込み後は、各スキルの確認手順で結果を見ます。現状だけ知りたいときは /harness-audit を単独で実行できます。こちらは読み取り専用で、書き込みは一切しません。

設計上のこだわりが3点あります。

生成する設定は、対象リポで claude を起動するディレクトリの .claude/settings.json に置きます。第1層の節で触れたとおり、この設定ファイルは親ディレクトリから継承されないためです。
.claudeignore は作りません。この記事でも触れたとおり Claude Code の正式機能にはなく、除外は .gitignore と permissions.deny の Read(...) ルールで分けます。
不可逆操作を止めるフックの JSON 解釈は python3 → node → sed/grep の順にフォールバックします。python3 や node が「存在するが実行に失敗する」環境（未導入バージョンを指す shim など）でも、無音で判定を諦めず次の手段に落とします。deny/pass の期待を136件のコーパスとして持ち、通常PATH・nodeのみ・sed/grepのみ・壊れたpython3 の4つのテスト構成で全件を回します。grep が無い構成では、判定できない旨を警告して通すことを代表ケースで確認します。このテストで上記の挙動を守っています。

注意点もあります。各 setup スキルは提案書を出した時点で必ず止まり、人が項目を選んで承認した後に限り、承認済みの変更を書き込みます。不可逆操作を止めるフックは、見逃すより過検知する方を安全側として許容する設計で、対象リポの事情に合わせてパターンを増減させる前提です。

まとめ

Claude Code を大規模コードベースで生かす鍵は、モデルの選択ではなく、モデルを取り巻くハーネスの構築です。CLAUDE.md の階層化から始め、フックで譲れないものを強制し、スキルとプラグインで知識を配り、LSP と MCP で到達範囲を広げ、サブエージェントで探索を切り出す。この順序が、各層が前の層を土台にする構造に合っています。

技術構成と同じ重さで、責任者の設置と定期的な見直しが要ります。3〜6か月ごとの構成レビューと、最低1人の DRI。これが Anthropic が成功事例を踏まえて示した推奨です。

単一のパッケージに閉じた作業なら、そのディレクトリから claude を起動し、その領域の CLAUDE.md を 200 行未満に整えるところから始めるのが、実践しやすい第一歩です。

参考

"How Claude Code works in large codebases: Best practices and where to start", Anthropic, 2026年5月14日
https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start
Claude Code 公式ドキュメント「Set up Claude Code in a monorepo or large codebase」
https://code.claude.com/docs/en/large-codebases
Claude Code 公式ドキュメント「Discover and install prebuilt plugins」（Code intelligence の節）
https://code.claude.com/docs/en/discover-plugins
Claude Code 公式ドキュメント「Plugins reference」（LSP servers）
https://code.claude.com/docs/en/plugins-reference
Claude Code 公式ドキュメント「Hooks reference」
https://code.claude.com/docs/en/hooks
Claude Code 公式ドキュメント「How Claude remembers your project」（CLAUDE.md の読み込み順序・200 行の目安・claudeMdExcludes）
https://code.claude.com/docs/en/memory
Claude Code 公式ドキュメント「Subagents」
https://code.claude.com/docs/en/sub-agents
cc-harness-kit（本記事の7層を監査し、構築順に整えるための Claude Code プラグイン、MIT）
https://github.com/nogataka/cc-harness-kit