Claude Code 大規模コードベース運用のベストプラクティス

はじめに

サーバーワークスの池田です。

Anthropic（Claude を開発している会社）が 2026 年 5 月 14 日に How Claude Code works in large codebases: Best practices and where to start を公開しました。数百万行のモノレポや数十年もののレガシーで Claude Code を運用するチームから抽出した、大規模コードベース向けのベストプラクティス集です。

本記事は、

【公式】公式記事の主張を整理したパート
【仕様】公式ドキュメントで挙動を裏取りしたパート
【筆者】実務でどう活かすかを書いたパート

の3つを見出しで明示しながら進めます。特にモノレポでハマりがちな「CLAUDE.md の階層化はいつ読まれるのか」については、仕様ドキュメントを参照して挙動を整理しました。

【公式】Claude Code がコードベースを探索する仕組み

Claude Code はエンジニアと同じやり方でコードを探します。ファイルシステムを辿り、ファイルを読み、grep で必要な箇所だけ拾い、参照を追う、という動作です。ローカル完結なので、サーバー側にインデックスを構築する必要がありません。

公式記事は、RAG（埋め込みベース検索）が大規模環境で抱える根本的な問題を指摘しています。数千人規模の組織ではコードが毎日大量にコミットされるため、インデックスの更新が追いつかず、「2 週間前にリネームした関数」や「前回のスプリントで削除済みのモジュール」が検索結果に返ってくる、という陳腐化が起きます。Claude Code は毎回 live なコードを直接読むため、この問題が原理的に発生しません。

ただし限界もはっきり書かれています。

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. （翻訳：10 億行規模のコードベースで曖昧なパターンの全インスタンスを探させると、作業開始前にコンテキストウィンドウの上限に達してしまう）

つまり、Claude が「どこを探せばいいか」を把握できるよう、コードベース側を整備する必要がある — これが記事全体の出発点です。

【公式】Claude Code を効かせる harness — 5 つの拡張ポイント + 2 つの追加機能

公式記事は、Claude Code の性能を左右する仕掛けを harness（ハーネス） と呼びます。中核は 5 つの拡張ポイント（CLAUDE.md、Hooks、Skills、Plugins、MCP Servers）で、そこに LSP 統合と Subagents という 2 つの追加機能 が加わって全体像になる、という整理です。モデル単体の性能よりも、これらの整備度合いで結果が決まるというのが核心の主張です。

区分	#	拡張ポイント / 機能	役割	よくある失敗
拡張ポイント	1	CLAUDE.md	毎セッション自動ロードされる指示ファイル	再利用可能な専門知識まで詰め込む
拡張ポイント	2	Hooks	特定タイミングで走るスクリプト	プロンプトで頑張ろうとする
拡張ポイント	3	Skills	オンデマンドで読み込む専門知識パック	CLAUDE.md にすべて入れてしまう
拡張ポイント	4	Plugins	Skills・Hooks・MCP 設定をまとめた配布パッケージ	良い設定が個人やチームに閉じる
拡張ポイント	5	MCP Servers	社内ツール・API・データソース接続	基礎が整う前に作り始める
追加機能	6	LSP 統合	シンボルレベルのコード理解	自動で効くと勘違いする
追加機能	7	Subagents	隔離コンテキストの別 Claude インスタンス	探索と編集を同じセッションで混ぜる

ここからは、特にモノレポで影響が大きい 4 つ（CLAUDE.md、Hooks、Skills、LSP）について公式の主張を整理します。

CLAUDE.md — 薄く、階層化する

公式の推奨は 「薄く、階層化する」。ルートには全体像とポインタを、サブディレクトリにはローカル規約を置く、という分担です。

注目すべきは、公式記事が 「ルートではなくサブディレクトリで /init せよ」 と書いている点。一見直感に反しますが、上位の CLAUDE.md は自動で取り込まれる仕組みになっているため、サブディレクトリ初期化のほうがスコープが適切に絞られる、という理屈です。なおコンパイル言語のモノレポは横断依存が深く、サブディレクトリ単位のスコープ化が難しいケースもある、と注意書きがあります。

Hooks — 抑止より「継続的改善」に使う

最も興味深い視点転換が Hooks の使い方です。

Most teams think of hooks as scripts that prevent Claude from doing something wrong, but their more valuable use is continuous improvement. （翻訳：多くのチームは Hooks を「Claude に間違ったことをさせないためのスクリプト」と捉えているが、本当に価値のある使い方は継続的改善である）

例として、セッション終了時の Stop hook で「学んだ内容を CLAUDE.md に反映する提案」を自動で出す、という設計が紹介されています。Linting や Formatting も、プロンプトで毎回指示するのではなく Hooks で決定論的に強制するパターンが推奨されています。

Skills — Path で scope できる

Skills は必要なときだけロードされる「専門知識パック」です。決済サービスを所有するチームがデプロイ Skill をそのディレクトリに紐づければ、モノレポの他の場所で作業するときは自動ロードされない、という具体例が挙がっています。「他チームの Skill が暴発する」問題を避ける手段として位置づけられています。

LSP — 「自動で効く」と思わない

大規模コードベースで「よくある関数名」を grep すると数千件マッチし、どれが本命か判断するために Claude がファイルを次々開いてコンテキストを浪費します。LSP（IDE のシンボル解析サーバー）を統合すれば「定義へジャンプ」「参照を全部探す」がシンボルレベルで事前にできるため、この浪費が抑えられます。公式記事は、ある大手エンタープライズソフト企業が C と C++ のナビゲーションを大規模に信頼できるものにするため、Claude Code 全社展開に先立って LSP 統合を全社整備した例を紹介しています。

【仕様】CLAUDE.md はいつ読み込まれるのか

このセクションは How Claude remembers your project の公式ドキュメントに基づいています。

「階層化すると何が嬉しいのか」を理解するには、いつどのファイルが読み込まれるか を正確に把握する必要があります。公式ドキュメントは、上方向と下方向で挙動が異なることを明記しています。

親方向は起動時、子方向はオンデマンド

CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded in full at launch. Files in subdirectories load on demand when Claude reads files in those directories. （翻訳：作業ディレクトリより上の階層にある CLAUDE.md と CLAUDE.local.md は、起動時にすべて読み込まれる。サブディレクトリのファイルは、Claude がそのディレクトリのファイルを読むときにオンデマンドで読み込まれる）

作業ディレクトリが foo/bar/ のときの挙動は次のとおりです。

ファイル位置	読み込みタイミング
`/CLAUDE.md`	セッション起動時
`/foo/CLAUDE.md`	セッション起動時
`/foo/bar/CLAUDE.md`	セッション起動時
`/foo/bar/baz/CLAUDE.md`	Claude が `/foo/bar/baz/` のファイルを読んだとき

CLAUDE.local.md は同じディレクトリの CLAUDE.md の直後に連結されます。

`/compact` 後の挙動も階層によって違う

位置	`/compact` 後
ルートの CLAUDE.md	自動で再読み込みされて再注入される
サブディレクトリのネスト CLAUDE.md	再注入されない。次にそのディレクトリのファイルを読んだとき再ロード

長時間セッションで /compact が走ったあと、ネスト CLAUDE.md の指示が一時的に効かなくなる現象はこの挙動が原因です。

200 行以下が目安、`@import` ではコンテキスト節約にならない

target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.

@path/to/file 構文で別ファイルを取り込むこともできますが、取り込まれたファイルは起動時に展開されてコンテキストに入るため、コンテキストの節約にはなりません。節約したい場合は、Path 指定のルールや Skills を使うのが正しい選択肢です。

CLAUDE.md と `.claude/rules/` の違い

CLAUDE.md と並ぶ仕組みとして .claude/rules/ ディレクトリがあります。YAML フロントマターでパスを指定できるルールファイル群です。

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

ロード条件だけ見ると CLAUDE.md と似ていますが、性格が違います。

	CLAUDE.md	`.claude/rules/`
性格	このディレクトリの説明書	このファイル種別の規約集
例えるなら	新人へのオンボーディング資料	コーディング規約・lint ルール
書く内容	構成、ビルド方法、ハマりポイント	命名、書式、禁止事項、必須項目

Terraform で言えば、terraform/CLAUDE.md には「このディレクトリは本番 IaC で、envs/<env>/ で terraform init を実行する」のような 動かし方 を書き、.claude/rules/terraform.md（paths: "**/*.tf"）には「リソース名は snake_case、variable には description 必須、count より for_each」のような 書き方の規約 を書きます。

構造面では .claude/rules/ でしか表現できないことが3つあります。

拡張子ベースの指定: paths: "**/*.tf" でモノレポ内のどこでも Terraform ファイルにルールが当たる。サービスごとに terraform/ を持つ構成だと CLAUDE.md ではコピペが必要
1トピック 1ファイルの粒度: terraform-naming.md / terraform-security.md のように責務ごとに分割でき、それぞれ別 paths を当てられる
プロジェクトを跨いだ共有: シンボリックリンクに対応しているため、共通規約を別リポジトリにまとめて全プロジェクトから参照できる

Skills との違い

Skills は「何かをするとき」の手順書、.claude/rules/ は「ファイルを書くとき」の規約集、と整理できます。Skills は常時コンテキストに乗らず、呼び出されたときや Claude が関連すると判断したときだけロードされます。

仕組み	使い分け
CLAUDE.md	このディレクトリは何か、どう動かすかの説明書
`.claude/rules/`	このファイル種別を書くときの規約
Skills	デプロイ、レビューなど特定タスクの手順書

階層化の効果

ここまでの仕様をまとめると、CLAUDE.md を階層化する効果は次の 4 点です。

効果	仕組みからの根拠
コンテキスト節約	サブディレクトリの CLAUDE.md は触らない限りロードされない
詳細と一般性の両立	ルートに全体像、サブにモジュール固有の詳細
オーナーシップの明確化	ディレクトリ単位の責任が CLAUDE.md にも対応
コンパクション耐性	ルートは `/compact` 後に再注入される

モノレポで全規約をルート 1 ファイルに集約すると 200 行制限を簡単に超えます。階層化は モノレポ運用ではほぼ前提条件 と言っていいでしょう。

【公式】運用パターンと組織導入

公式記事は、大規模環境で Claude Code を機能させる 3 つのパターンと、組織導入で必要になる新しい役割を提示しています。

パターン1：コードベースをナビゲート可能にする

具体的なアクションは次のとおりです。

CLAUDE.md は薄く、階層化する
ルートではなくサブディレクトリで /init する
テスト・lint コマンドはサブディレクトリ単位でスコープする
.claudeignore で生成物やビルド成果物を除外する
ディレクトリ構造が非標準ならコードベースマップを作る
LSP サーバーを言語ごとに導入する
.claude/settings.json の permissions.deny で触れて欲しくない領域を制限する

パターン2：設定を能動的にメンテナンスする

CLAUDE.md・Skills・Hooks は 3〜6 ヶ月ごとに見直し が推奨されています。特にモデルのメジャーリリース後は、過去モデルの制約を補うために作った Skills や Hooks が、新しいモデルの足を引っ張ることがある、と警鐘が鳴らされています。「動いているからそのまま」が長期負債になる、というシンプルな指摘です。

パターン3：組織的なオーナーシップを確立する

ボトムアップで広がる Claude Code の採用熱を組織として活かす仕組みがないと、良い設定が個人やチームに閉じ、部族知（tribal knowledge）として断片化 する、と明示されています。

そのための役割として、公式記事は Agent Manager（PM とエンジニアのハイブリッド職、Claude Code エコシステム運用の専従）と、最小構成の DRI（Directly Responsible Individual） を挙げています。DRI の責務は「設定オーナーシップ」「permissions ポリシー」「プラグインマーケットプレイス管理」「CLAUDE.md 規約整備」の 4 点。規制業界では、エンジニアリング・情報セキュリティ・ガバナンスの 3 部門からなる横断ワーキンググループを早期に立ち上げ、限定アクセスで開始し、信頼が積み上がるにつれて拡大していく という段階展開が推奨されています。

【筆者】モノレポ運用の構成例

公式と仕様を踏まえると、モノレポでの実用的な構成はこんな形になりそうです。

your-monorepo/
├── CLAUDE.md                         # 全体地図（200行以下、薄く）
├── .claude/
│   ├── settings.json                 # permissions.deny、claudeMdExcludes
│   └── rules/
│       ├── testing.md                # paths: **/*.test.ts（横断ルール）
│       └── security.md               # paths: src/auth/**（横断ルール）
├── services/
│   ├── payments/
│   │   ├── CLAUDE.md                 # 決済モジュール固有（チーム所有）
│   │   └── .claude/
│   │       └── skills/
│   │           └── deploy-payments/  # Path-scoped Skill
│   └── notifications/
│       └── CLAUDE.md                 # 通知モジュール固有
└── docs/
    └── architecture.md               # CLAUDE.md から @import で参照

選定基準を整理するとこうです。

種類	適したケース
ルート CLAUDE.md	全体像、代表的なビルド/テストコマンド、致命的な落とし穴
サブディレクトリ CLAUDE.md	チーム所有モジュール固有の規約、固有のビルドコマンド
`.claude/rules/`（`paths` あり）	ファイル種別横断のルール（テスト、認証、API ハンドラなど）
Skills	特定タスク（デプロイ、レビュー、ドキュメント更新）で発動する手順書
Plugins	上記を社内マーケットプレイス経由で配布する形態

よくあるアンチパターン

公式と仕様から見えてくる、避けるべきパターンです。

アンチパターン	何が起きるか
ルート CLAUDE.md にすべての規約を詰める	200 行を超えてコンテキストが圧迫され、遵守度が低下
再利用可能な専門知識を CLAUDE.md に置く	Skills 化していないため、関係ないセッションでも常時ロード
プロンプトで lint・format を毎回指示する	Hooks で決定論的に強制できるため、コンテキストの無駄
LSP を導入せず grep に頼る	シンボル名衝突でコンテキスト浪費、回答精度が落ちる
Skills や Hooks を作りっぱなしにする	3〜6 ヶ月後、新しいモデルでむしろ足を引っ張る
良い設定をチーム内で抱え込む	部族知として断片化、組織全体の生産性が伸びない

まとめ

Claude Code の性能はモデル単体ではなく、harness（5 つの拡張ポイント = CLAUDE.md・Hooks・Skills・Plugins・MCP Servers、＋ 2 つの追加機能 = LSP 統合・Subagents）の整備度合いで決まる — これが公式記事の核心です。

モノレポ運用では、CLAUDE.md を階層化したうえで、ファイル種別横断のルールは .claude/rules/、タスク特化の知識は Skills、と役割を分けるのが効きます。読み込みタイミングが上方向と下方向で違うという仕様を理解すれば、コンテキストを節約しながら必要な指示だけを届ける構成が組めます。

そして、設定は 3〜6 ヶ月ごとに見直す。古いモデル向けに書いた設定が新しいモデルの足を引っ張る、という指摘は、Claude のモデル世代交代が速い現状では特に重く受け止めるべきです。組織導入の局面では、Agent Manager や DRI といった設定とポリシーを集中管理する責任者を置くのが今後標準化していきそうです。

参考リンク

Anthropic 公式記事: How Claude Code works in large codebases: Best practices and where to start（2026年5月14日公開）
公式ドキュメント: How Claude remembers your project
公式ドキュメント: Skills
公式ドキュメント: Hooks

はじめに

【公式】Claude Code がコードベースを探索する仕組み