Claude Codeでモノレポを制する——階層CLAUDE.md・Skills自動検出・Virtual Monorepoパターンで「35リポジトリを1つのコンテキスト」で扱う

はじめに
階層的CLAUDE.md設計：「薄いルート」と「遅延読み込み」
1. 設計原則：ルートは200〜300行以内に保つ
プロジェクト概要
共通規約
パッケージ一覧
1. 遅延読み込みの仕組み
ビルドシステム
1. @記法でさらに細分化する
API規約
データベーススキーマ
Skills自動検出：パッケージ固有のSkillをサブディレクトリに配置
Cross-packageリファクタリング：モノレポの最大の強み
1. 共有ライブラリの関数名変更
2. データモデルの変更波及確認
Virtual Monorepoパターン：35リポジトリを1つのコンテキストで扱う
1. 問題：35リポジトリに分散したシステム
2. 解決策：シンボリックリンクで仮想統合する
システム概要
サービス一覧
横断的な変更時のルール
ビフォーアフター
まとめ：今日からできること

はじめに

モノレポとClaude Codeの相性は良いはずだ——理論的には。

「単一のセッションでコードベース全体を見渡せる」「パッケージ間の依存関係を把握してリファクタリングできる」という強みがある。しかし実際に運用してみると、思わぬ問題にぶつかった。

ルートのCLAUDE.mdにフロントエンド・バックエンド・インフラ・共有ライブラリの規約を全部書いたら500行を超え、`⚠ Large CLAUDE.md will impact performance` の警告が出た。フロントエンドの作業をしているのに、バックエンド固有のルールが全部ロードされている状態になった。

これらを解決するのが本記事で解説する3つの設計パターンだ。階層的CLAUDE.md設計、Skills自動検出、そしてマルチリポ環境でも単一コンテキストで扱うVirtual Monorepoパターン。

階層的CLAUDE.md設計：「薄いルート」と「遅延読み込み」

設計原則：ルートは200〜300行以内に保つ

モノレポのルートCLAUDE.mdには「全パッケージに共通するものだけ」を書く。

project/
├── CLAUDE.md              # 全体共通（薄く）
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md     # フロントエンド固有
│   ├── backend/
│   │   └── CLAUDE.md     # バックエンド固有
│   └── shared/
│       └── CLAUDE.md     # 共有ライブラリ固有
└── infra/
    └── CLAUDE.md          # インフラ固有

実際にこんな内容を書いている。

# CLAUDE.md（ルート）

プロジェクト概要
このリポジトリはフロントエンド・バックエンド・共有ライブラリを含むモノレポ。

共通規約

コミットメッセージ：日本語でconventional commits形式
パッケージマネージャー：pnpm workspaces（npmは使わない）
変更前にルートで `pnpm test` を実行

パッケージ一覧

packages/frontend/ → Reactアプリ（詳細はpackages/frontend/CLAUDE.md参照）
packages/backend/  → Node.js API（詳細はpackages/backend/CLAUDE.md参照）

遅延読み込みの仕組み

Claude Codeはサブディレクトリのファイルにアクセスした時点で、そのディレクトリ以下のCLAUDE.mdを自動的に読み込む。

packages/frontend/ のファイルを読んだ瞬間
    ↓
packages/frontend/CLAUDE.md が自動ロード
（フロントエンド固有のルールが初めて適用）

バックエンド作業中はバックエンドのルールだけが有効で、フロントエンドのルールはコンテキストを消費しない。`/memory` コマンドで現在セッションにロードされているCLAUDE.mdの一覧を確認できる。ファイルが表示されない場合、Claudeはそのファイルを参照できていない。

TurborepoやPNPMワークスペースを使っている場合は、ルートで参照させることでパッケージ間の依存関係をClaudeが正確に把握できる。

# CLAUDE.md（ルート）
ビルドシステム
このモノレポはTurborepoを使用。パッケージ依存関係は @turbo.json 参照。
packages/frontend/ を変更した場合の影響範囲確認時はturbo.jsonのpipelineを確認すること。

@記法でさらに細分化する

# packages/backend/CLAUDE.md

API規約
詳細はこちら @packages/backend/docs/api-conventions.md

データベーススキーマ
@packages/backend/schema/DB.md

@記法を使うとCLAUDE.md自体を薄く保ちながら、必要な情報を別ファイルで管理できる。注意点として、バッククォートで囲むとインポートとして評価されない（`` `@docs/spec.md` `` はインポートされない）。

Skills自動検出：パッケージ固有のSkillをサブディレクトリに配置

Claude Codeはネストされた `.claude/skills/` ディレクトリを自動検出する。

project/
├── .claude/skills/            # 全体共通Skills
│   └── ci-check/
├── packages/frontend/
│   └── .claude/skills/        # フロントエンド固有Skills（自動検出）
│       ├── component-gen/
│       └── storybook-doc/
└── packages/backend/
    └── .claude/skills/        # バックエンド固有Skills（自動検出）
        ├── api-route/
        └── migration/

`packages/frontend/` のファイルを編集しているとき、Claude Codeは自動的に `packages/frontend/.claude/skills/` のSkillも利用可能にする。

# packages/frontend/.claude/skills/component-gen/SKILL.md

あなたはReactコンポーネントを生成するスペシャリストです。

このパッケージのコンポーネント生成ルール： 
 src/components/ に配置
 Storybook用の .stories.tsx を必ず同梱
 既存のコンポーネント命名規則に従う（packages/frontend/CLAUDE.mdを参照）
 テストは src/components/__tests__/ に配置

「Skillをどこに置くか」で迷いがちなモノレポの問題が、「作業中のパッケージの `.claude/skills/` に置く」で解決される。

Cross-packageリファクタリング：モノレポの最大の強み

モノレポでClaude Codeを使うことの恩恵が最もはっきり出るのが、パッケージをまたいだリファクタリングだ。

共有ライブラリの関数名変更

「packages/shared/utils/formatDate.ts の関数名を
 `formatDate` から `formatDateISO` に変更して。
 このリポジトリ全体で使われている全ての呼び出し箇所を特定して、
 一括で更新して」

Claude Codeはリポジトリ全体を横断的にGrep検索し、`packages/frontend/`・`packages/backend/`・`packages/shared/` のすべての呼び出し箇所を特定して一括更新する。マルチリポではこれが難しく、「更新漏れ」によるサイレントバグが発生しやすい。

データモデルの変更波及確認

「packages/shared/types/User.ts の User インターフェースに
 `lastLoginAt: Date` フィールドを追加して。
 このフィールドが必要になる全てのコンシューマーを特定して、
 型エラーを全て解消して」

型チェックとコードの整合性維持をClaudeが一括で行える。「モノレポ＋Claude Code」の組み合わせを試す価値を最も感じやすい場面だと思う。

Virtual Monorepoパターン：35リポジトリを1つのコンテキストで扱う

マルチリポ環境でも「モノレポのように扱う」設計が注目されている。

問題：35リポジトリに分散したシステム

ある実践者は35個のマイクロサービスリポジトリを運用していた。「`user-service` のAPIを変更したとき、どのサービスがこのAPIを使っているか分からない」という問題が常に発生していた（Medium・DevOps⬤AI、2026年3月）。

解決策：シンボリックリンクで仮想統合する

~/workspaces/
├── system-context/           # バーチャルモノレポのルート
│   ├── CLAUDE.md             # システム全体のコンテキスト
│   └── services/
│       ├── user-service/     # シンボリックリンク → /repos/user-service
│       ├── order-service/    # シンボリックリンク → /repos/order-service
│       └── ...（35リポジトリ）

シンボリックリンクを使って35のリポジトリを1つのディレクトリツリーに集約する。Claude Codeはこの `system-context/` を起動点とすることで、全35リポジトリを横断的に分析できる。

重要な点は、各リポジトリのコードには何も変更しないことだ。CI/CDにも影響しない。純粋にClaude Codeのコンテキスト管理のための構造だ。

# CLAUDE.md（Virtual Monorepo）

システム概要
このディレクトリは35個のマイクロサービスの仮想的なモノレポ。
実際のコードはservices/各ディレクトリにシンボリックリンクで配置。

サービス一覧

services/user-service/     → ユーザー管理・認証
services/order-service/    → 注文処理・在庫
services/notification/     → メール・プッシュ通知

横断的な変更時のルール

まず影響を受けるサービスを全て特定すること
変更の前後でAPIの互換性を確認すること
各サービスのCHANGELOGを更新すること

ビフォーアフター

Before（コンテキスト設計なし）

ルートCLAUDE.mdに全ての規約を記述 → 500行を超えてパフォーマンス警告 → フロントエンド作業中もバックエンドルールがロード → 「このルールはどのパッケージに適用するものか」が曖昧 → 共有ライブラリを変更したが呼び出し箇所を把握できず、リファクタリング漏れが発生。

After（階層的CLAUDE.md＋Skills自動検出＋Virtual Monorepo）

ルートCLAUDE.mdは200行以内（全体共通のみ）→ `packages/frontend/CLAUDE.md` はフロントエンド作業時のみロード → `packages/frontend/.claude/skills/` が自動検出 → 「formatDate を formatDateISO に変更して」で35ファイルの呼び出し箇所を全て更新・型エラーをゼロに → Virtual Monorepoで35リポジトリを横断的に管理。

まとめ：今日からできること

今すぐ（5分）: `/memory` でロードされているCLAUDE.mdを確認し、ルートが500行超なら分割計画を立てる
今日中: `packages/frontend/CLAUDE.md` と `packages/backend/CLAUDE.md` を作成し、固有の規約を移動する
今週: パッケージ固有のSkillを `.claude/skills/` に配置し、サブディレクトリでの自動検出を確認する
マルチリポの場合: シンボリックリンクを使ったVirtual Monorepoを構築し、横断的なコンテキストを実現する

モノレポとClaude Codeの相性が良いのは本当だ。ただし「コンテキスト設計」が前提になる。500行のCLAUDE.mdを分割するところから始めてほしい。