Claude Code を大規模コードベースで使いこなす実践ガイド 2026 — モノレポ・レガシー・多言語リポジトリの公式プラクティス
Claude Code を大規模コードベースで使いこなす実践ガイド 2026 — モノレポ・レガシー・多言語リポジトリの公式プラクティス
PR: 本記事にはアフィリエイトリンク（プロモーション）が含まれます。掲載するサービスは編集部が記事内容との関連性で選定しており、報酬の有無で評価を変えていません。
情報の取り扱いについて: 本記事の機能・コマンド仕様（CLAUDE.md /
@import//clear//compact/ サブエージェント / plan mode 等）は 2026 年 5 月時点の Anthropic 公式ドキュメント（code.claude.com/docs/docs.claude.com）および開発者コミュニティの先行事例（Qiita / dev.to / Zenn）をベースに整理したものです。コマンド名・挙動・上限値は更新が早いため、必ず公式ドキュメントの最新版で確認してください。本記事は運用ノウハウの体系化であり、公式仕様書の代替ではありません。
この記事でわかること
- 対象読者: 数十万行規模のモノレポ・レガシーコード・多言語混在リポジトリで Claude Code を使い、「context が足りずに迷子になる」「無関係なファイルを編集される」「トークンが爆発する」に悩むエンジニア／開発リーダー
- 読了時間: 本文 約 10 分 + 図表 約 2 分
- 得られるもの: ① 大規模リポジトリで Claude Code が失敗する 4 つの構造的原因 ② Anthropic 公式が推奨する CLAUDE.md 階層化・
@import・サブエージェント・plan mode の実装テンプレ ③ 10 名規模チームへの段階導入手順とトークンコスト最適化 - 得られないもの: 各コマンドの正確な最新仕様（必ず公式ドキュメントを併読してください）／特定言語フレームワーク固有の設定値
- 前提知識: Claude Code の基本操作（プロンプト入力・ファイル編集）、git・モノレポ／マルチパッケージ構成の基礎用語
なぜ大規模コードベースで Claude Code は「迷子」になるのか
小〜中規模リポジトリ（数千〜数万行）では、Claude Code はほぼ設定なしで快適に動く。ところが数十万行のモノレポやレガシーコードに持ち込むと、途端に挙動が崩れる。原因は大きく 4 つに整理できる。
| # | 失敗パターン | 構造的原因 | 公式プラクティスでの対処 |
|---|---|---|---|
| 1 | 無関係なファイルを編集する | リポジトリ全体の規約・所有権が context に入らず、AI が「正解の場所」を推測する | CLAUDE.md 階層化でディレクトリ単位の規約を明示 |
| 2 | context 上限に到達して話が破綻する | 巨大ファイルや長い探索ログで context window を食い潰す | /clear・/compact・サブエージェントで context を分割 |
| 3 | トークン消費が爆発する | 関連ファイル探索を毎回ゼロから繰り返す | @import で必要ファイルだけを参照、探索を subagent に隔離 |
| 4 | 多言語・多パッケージで規約が混線する | 単一の CLAUDE.md にすべての言語規約を詰め込み矛盾が生じる | ネストした CLAUDE.md で言語／パッケージ別に分離 |
ポイントは、これらは「Claude Code の性能の問題」ではなく「context をどう設計して渡すか」の問題だという点だ。大規模リポジトリでの成否は、モデルの賢さよりも「リポジトリ側の context 設計」で決まる。
既存記事との差別化 — 本記事の独自軸
弊ブログでは Claude Code カスタムサブエージェント完全ガイド、Claude Memory Tool 完全実践ガイド、Async Hooks × GitHub Actions パイプライン など Claude Code の個別機能を扱ってきた。本記事はそれらと以下 3 点で軸を分離する。
- 機能単位ではなく「大規模リポジトリ」という制約条件で横断整理 — CLAUDE.md・
@import・サブエージェント・plan mode を「数十万行で破綻しないため」という 1 つの目的で束ねる - 個人ではなく「チーム導入」の視点 — 10 名規模で CLAUDE.md をどう共有・レビューし、トークンコストを管理するかの運用設計を提示
- レガシー・多言語という現実の泥臭さに対応 — 理想的な新規プロジェクトではなく、規約が散らかった既存リポジトリへの後付け導入手順に焦点
公式プラクティス 1: CLAUDE.md を「階層化」する
Anthropic 公式ドキュメントが繰り返し推奨しているのが、CLAUDE.md（プロジェクトメモリ）の活用だ。これはセッション開始時に自動で context へ読み込まれる「リポジトリの取扱説明書」にあたる。大規模リポジトリでは、これを ルート 1 枚に詰め込まず、ディレクトリ単位で階層化するのが定石になる。
repo-root/
├── CLAUDE.md # 全体共通の規約（コミット規約・PR フロー・禁止事項）
├── packages/
│ ├── api/
│ │ └── CLAUDE.md # API パッケージ固有（言語=Go・DB スキーマ・命名規則）
│ └── web/
│ └── CLAUDE.md # フロント固有（言語=TS・デザインシステム・状態管理方針）
└── services/
└── legacy-batch/
└── CLAUDE.md # レガシー固有（触ってよい範囲・既知の地雷・移行方針）公式メモリ仕様では、サブディレクトリ内の CLAUDE.md は そのディレクトリ配下を扱うときに参照される設計になっている。これにより「フロントの規約とバックエンドの規約が context 上で衝突する」問題を構造的に防げる。
ルート CLAUDE.md の推奨サイズ
公式ベストプラクティスでは **CLAUDE.md は簡潔に保つ（目安として 200 行以下）**ことが推奨される。巨大化すると指示の要点が埋もれ、AI が規約に従いにくくなるためだ。本体は要点に絞り、詳細仕様は @import でファイル分割して読みやすさと保守性を高める（次節）。
公式プラクティス 2: @import で必要なときだけ読み込む
CLAUDE.md には他ファイルを取り込む @path 構文がある。本体は薄く保ち、詳細仕様は別ファイルに分けて @import するのが大規模運用の基本だ。
<!-- ルート CLAUDE.md -->
# プロジェクト規約
@docs/conventions/commit-rules.md
@docs/conventions/review-checklist.md
@docs/architecture/overview.mdここで重要な注意点がある。@import で取り込んだファイルもセッション開始時に context へ読み込まれるため、@import は「context 量そのものを削減する仕組み」ではない。あくまで規約を整理し、本体ファイルの保守性・可読性を高めるための構成だ。入れ子のネストにも上限があり、公式ドキュメントでは最大 4 階層（hops）までとされる（上限値は更新が早いため必ず最新版で確認すること）。
これを使うと、ルート CLAUDE.md 本体を「目次」として読みやすく保ちつつ、詳細仕様をファイル単位で分割管理できる。本ブログ運営リポジトリでも、ルート CLAUDE.md 本体を約 40 行に抑え、ルール群を複数ファイルに分割して @import する構成を実運用しており、規約の網羅性と保守性を両立できている。
エージェント運用スキルを体系的に学びたい人へ: AI 時代のエンジニア学習サービス Coloso（プログラミング・AI 活用講座を深掘り） には、コンテキスト設計やエージェント運用を体系立てて学べる講座がある。大規模リポジトリでの Claude Code 活用は「ツールの使い方」ではなく「context をどう設計するか」という設計スキルであり、独学で断片的に拾うより体系的に学ぶ方が遠回りにならない。
公式プラクティス 3: /clear と /compact で context を能動的に管理する
大規模リポジトリでの最頻出トラブルは「会話が長くなり context が破綻する」だ。Claude Code には context を意図的に整理する 2 つのコマンドがある。
| コマンド | 役割 | 使うタイミング |
|---|---|---|
/clear | 会話履歴をリセット（context をほぼ空に） | 1 つのタスクが完了し、無関係な次タスクに移るとき |
/compact | 会話を要約して圧縮（重要文脈を残す） | 同一タスク継続中で context が膨らんできたとき |
公式が強調するのは「タスクの切れ目で /clear する」習慣だ。前タスクの探索ログを引きずったまま次タスクに入ると、無関係な context がトークンを食い続け、精度も落ちる。大規模リポジトリほど 1 タスクの探索ログが巨大になるため、この効果は大きい。
公式プラクティス 4: サブエージェントで「探索」を隔離する
最も効果が大きいのがサブエージェント（subagents）の活用だ。サブエージェントは独立した context window で動くため、「巨大リポジトリを探索して結論だけ返す」用途に最適化されている。
親エージェント（context: 編集タスクに集中）
└── Explore サブエージェント（context: 全リポジトリ探索専用）
→ 「該当ロジックは packages/api/billing/calc.go の 120 行目」とだけ返す探索の生ログ（数百ファイルの grep 結果など）はサブエージェント側の context に閉じ込められ、親には結論だけが戻る。これにより親の context window を節約しつつ、広範囲の探索が可能になる。Anthropic 公式の subagents ドキュメントでも、読み取り専用の探索エージェントを別 context で走らせるパターンが推奨されている。詳しい設計は弊ブログのカスタムサブエージェント完全ガイドも参照してほしい。
公式プラクティス 5: plan mode で「破壊」の前に止める
レガシーコードで最も怖いのは「AI が良かれと思って広範囲を書き換える」ことだ。これを防ぐのが plan mode（計画モード）で、実装の前に計画を提示させ、承認してから実行する流れを作れる。
- 計画を先に出させる → 触る範囲・副作用・テスト方針を人間がレビュー
- 承認後に実行 → 想定外の広域変更を着手前に止められる
- 大規模・レガシーほど「着手前に止める」価値が高い（後から戻すコストが大きいため）
公式ドキュメントでも、大きな変更の前には plan mode / 計画提示を挟むことが推奨されている。「速く動かす」よりも「壊さない」を優先すべきレガシー領域では、このひと手間が事故を防ぐ。
チーム導入手順 — 10 名規模での段階展開
ここまでの 5 つを、10 名規模の開発チームにどう入れるか。一度に全部入れると形骸化するため、段階展開を推奨する。
| フェーズ | やること | 期間目安 | 成功指標 |
|---|---|---|---|
| Phase 1 | ルート CLAUDE.md にコミット規約・PR フロー・禁止事項だけを記載 | 1 週間 | 全員が CLAUDE.md を読み、PR で規約違反が減る |
| Phase 2 | パッケージ別 CLAUDE.md を主要ディレクトリに追加 | 2〜3 週間 | パッケージをまたぐ誤編集が減る |
| Phase 3 | 探索系サブエージェントを共有テンプレ化 | 1 ヶ月 | 1 タスクあたりの探索トークンが下がる |
| Phase 4 | plan mode をレガシー領域のレビュー必須ルールに | 継続 | レガシー改修での想定外変更がゼロに近づく |
CLAUDE.md は git 管理してコードレビュー対象に含めるのが鉄則だ。属人化させず、規約変更を PR でレビューすることで「チームの共有知」として育つ。
トークンコスト最適化 — 大規模ほど効く 4 つの勘所
大規模リポジトリは放っておくとトークン消費が膨らむ。コスト最適化の勘所を 4 点。
- CLAUDE.md を薄く保つ — 毎セッション読まれる固定 context なので、肥大すると全セッションのコストに乗る
- 探索はサブエージェントに隔離 — 親 context に探索ログを溜めない（前述）
- タスクの切れ目で
/clear— 無関係な context を引きずらない - モデルを使い分ける — 重い設計判断は上位モデル、定型探索・要約は軽量モデルに寄せる
これらは「AI を使わない」方向のコスト削減ではなく、「同じ成果をより少ないトークンで出す」方向の最適化だ。大規模リポジトリほど効果が複利で効く。
大規模開発・AI 案件で自分の市場価値を確かめたい人へ: 大規模コードベースを AI で扱える人材は、2026 年の転職市場で評価が上がりやすい領域だ。AI / LLM 領域に強いエンジニア転職エージェント TechGo（AI/LLM 案件に強い無料面談はこちら） は新規無料面談で AI 案件の単価レンジ提示まで対応している。「Claude Code をモノレポで運用できる」というスキルは、面談で具体的にアピールしやすい差別化要素になる。
別の見方（両論併記）
本記事で紹介した公式プラクティスにも、過信すべきでない論点がある。
- 「CLAUDE.md を厚くすれば賢くなる」わけではない: 規約を詰め込みすぎると固定 context が肥大し、かえって精度とコストが悪化する。薄く保つことと網羅性はトレードオフであり、
@importでの外出しは万能薬ではない - サブエージェントは万能ではない: 親子間の情報受け渡しで文脈が落ちるケースがあり、密に往復が必要なタスクではむしろオーバーヘッドになる。「探索と編集の分離が効くタスク」かどうかの見極めが要る
- plan mode は速度とのトレードオフ: すべてのタスクで計画を挟むと、軽微な修正まで遅くなる。レガシー・広域変更に限定し、軽微タスクでは省くメリハリが現実的
- コマンド仕様は変わる:
/clear・/compact・サブエージェントの挙動や上限は更新が早い。本記事の手順も公式ドキュメントの最新版で必ず裏取りしてほしい
つまり「公式プラクティスを全部入れれば解決」ではなく、自分のリポジトリの規模・構成・チーム文化に合わせて取捨選択するのが正解だ。
まとめ
- 大規模リポジトリでの成否は「context 設計」で決まる — モデルの賢さより、リポジトリ側の取扱説明書（CLAUDE.md 階層化・
@import）の質が効く - context は能動的に管理する —
/clear・/compact・サブエージェントで「context window を食い潰さない」運用を習慣化する - レガシーは plan mode で守る — 「速く動かす」より「壊さない」を優先し、着手前に計画をレビューする
- チーム導入は段階展開 — ルート CLAUDE.md → パッケージ別 → サブエージェント → plan mode の順で、形骸化を避けて定着させる
各コマンドの正確な仕様・上限値は更新が早いため、必ず Anthropic 公式ドキュメント（code.claude.com/docs / docs.claude.com）の最新ページで確認してほしい。本記事は運用ノウハウの体系化であり、公式仕様書の代替ではない。
関連記事
- Claude Code カスタムサブエージェント完全ガイド 2026
- Claude Memory Tool 完全実践ガイド 2026
- Claude Code Async Hooks × GitHub Actions パイプライン構築 2026
- Claude Code を大規模に使う前に：6/15 料金改定の論点整理
次の一手
- まずルート CLAUDE.md に「コミット規約・PR フロー・禁止事項」の 3 点だけを書いて運用を始める
- context が膨らんできたら
/compact、タスクの切れ目で/clearを習慣化する - エージェント運用スキルを体系的に学ぶなら Coloso、大規模開発スキルを単価に変えたいなら TechGo の無料面談で市場感を確かめる
大規模コードベースでの Claude Code 活用は、「賢い AI に丸投げする」ことではなく、「AI が迷わない context をどう設計するか」というエンジニアリングそのものだ。この設計力こそが、2026 年に差がつくスキルになる。