Claude Code モノレポ運用 サブパッケージ単位のコンテキスト切り方（概念）

Anthropic が提供する CLI 型コーディングエージェント「Claude Code」は、リポジトリを直接読み込み、編集・テスト・コミットまでを自律的にこなす強力なツールです。しかし、大規模なモノレポ（Monorepo）構成で Claude Code をそのまま運用しようとすると、巨大なファイル群に起因するトークンの浪費や、コンテキスト（文脈）の混濁による精度低下という壁に突き当たります。

本記事では、IT実務の最前線で求められる「モノレポ環境における Claude Code のサブパッケージ単位での運用術」について、概念から具体的な設定ファイルの書き方までを徹底解説します。単にツールを動かすだけでなく、AIに「今、どの領域の責任を負っているのか」を正確に理解させるための設計指針を提示します。

Claude Code によるモノレポ運用の課題と「サブパッケージ単位」の重要性

モノレポは、一つのリポジトリ内にフロントエンド、バックエンド、共有ライブラリ、インフラ定義（IaC）などが同居する構成です。人間にとっては全体を俯瞰しやすいメリットがありますが、Claude Code のような AI エージェントにとっては、情報の海に溺れる原因となります。

なぜモノレポ全体を一度に読ませてはいけないのか

Claude Code をリポジトリのルートディレクトリで起動すると、エージェントはデフォルトでプロジェクト全体のファイル構造を把握しようとします。以下の 2 点が大きなボトルネックとなります。

• コンテキストウィンドウの圧迫： 不要なファイル（例：ドキュメント、別の言語のパッケージ、古いビルド成果物）がコンテキストに含まれることで、肝心の実装ロジックに割けるトークンが減少します。
• 「推論」のノイズ： 例えば、サブパッケージ A で npm test を実行したいのに、ルートや別のパッケージ B にある package.json の設定と混同し、誤ったテストコマンドを実行してしまうケースが多発します。

サブパッケージ単位でのコンテキスト制御がもたらす 3 つのメリット

パッケージごとにコンテキストを切り分けることで、以下のメリットが得られます。

1. 応答速度の向上： インデックス対象が絞られるため、Claude Code の起動やファイル読み込みが劇的に速くなります。
2. 正確なビルド・テスト実行： 各ディレクトリに最適化された CLAUDE.md を参照させることで、エージェントが迷わずに正しいツールチェーンを選択できます。
3. コスト（トークン）の最適化： 必要なファイルのみをプロンプトに含めるため、API 消費コストを最小限に抑えられます。

こうした効率的なデータ管理の考え方は、マーケティング領域におけるデータ基盤構築にも通じます。例えば、CAPIとBigQueryで構築するデータアーキテクチャのように、膨大なデータから「今、必要な情報」を抽出し、最適化のループを回すことが、AI活用の成功を左右します。

モノレポにおける Claude Code のコンテキスト切り分け 3 つのアプローチ

実務上、モノレポ内の特定のサブパッケージを Claude Code に担当させるには、主に 3 つの階層で制御を行います。

1. カレントディレクトリ移動による「物理的セグメント」

最もシンプルかつ強力な方法は、作業したいサブパッケージのディレクトリに cd してから claude コマンドを叩くことです。Claude Code は起動したディレクトリを「プロジェクトのルート」として認識する傾向があるため、物理的にスコープを限定できます。

2. CLAUDE.md の階層化による「論理的命令セットの適用」

Claude Code には、プロジェクト固有の指示を記述する CLAUDE.md という仕組みがあります。これをモノレポのルートだけでなく、各サブパッケージのディレクトリ配下にも配置します。Claude Code はカレントディレクトリの CLAUDE.md を最優先で読み込むため、パッケージごとの個別ルール（コーディング規約、テスト方法）を確実に伝えることができます。

3. .claudeignore による「視覚情報のフィルタリング」

ルートディレクトリから起動せざるを得ない場合（例：パッケージ間を跨ぐリファクタリング）、.claudeignore を活用して、今触る必要のないディレクトリを徹底的に隠蔽します。Git における .gitignore と同様の記法が使えます。

実務で使える CLAUDE.md / AGENTS.md の階層設計ガイド

モノレポ運用の肝は、「共通ルール」と「個別ルール」の責務分解にあります。これは、経理業務において基幹システムと周辺 SaaS の役割を分ける考え方に似ています。例えば、受取SaaSと会計ソフトの責務分解を正しく行うことで全体の整合性が保たれるのと同様に、設定ファイルの階層化が必要です。

ルート階層：全パッケージ共通の「規約・辞書・ツール」を定義

リポジトリのルートにある CLAUDE.md には、プロジェクト全体のアーキテクチャ方針や、共通して使用する技術スタックを記述します。

• 命名規則： 「変数名はキャメルケース、定数はスネークケース」など。
• 禁止事項： 「外部ライブラリの勝手な追加禁止」「console.log の残置禁止」など。
• Skills（カスタムツール）： 全パッケージで使う可能性がある共有スクリプト（例：全パッケージ一括ビルド、ライセンスチェック等）。

サブパッケージ階層：固有の「ビルド・テスト・デプロイ」を定義

packages/frontend/CLAUDE.md や packages/api/CLAUDE.md には、そのディレクトリ内だけで有効なコマンドを記述します。

• Build command: npm run build (frontend) vs go build (api)
• Test command: vitest (frontend) vs pytest (api)
• Context info: 「このパッケージは React + Tailwind を使用している」「このパッケージはステートレスな Lambda 関数である」といった固有の文脈。

プロジェクト全体を俯瞰させるための構造定義

Claude Code に全体の依存関係を知らせる必要がある場合は、ルートに architecture.md のようなファイルを置き、どのパッケージがどこに依存しているかの「地図」をテキストで持たせておくのが有効です。Claude Code は必要に応じてこのファイルを読み取り、サブパッケージ間の境界を認識します。

【比較表】モノレポ運用における Claude Code vs 他社エージェントツール

モノレポのような複雑な構造を扱う際、Claude Code と他の AI エージェントツールの特性を整理しました。

具体的な運用フロー：Claude Code でサブパッケージを開発する 5 ステップ

ここでは、実際にモノレポ環境で Claude Code を使って特定のサブパッケージに機能追加を行う実務フローを解説します。

Step 1：特定ディレクトリへの移動と初期化

まず、対象のパッケージディレクトリに移動します。

cd packages/payment-gateway
claude

ここで /init を実行すると（初回のみ）、プロジェクト構造の読み込みが始まります。このとき、ルートの .claudeignore で他パッケージを除外していれば、スキャンは一瞬で終わります。

Step 2：パッケージ固有のコンテキストの注入（CLAUDE.md）

packages/payment-gateway/CLAUDE.md を作成し、以下のような情報を記述しておきます。

Payment Gateway Package Context

Tech Stack: Node.js, Fastify, Stripe SDK

Main Entrypoint: src/index.ts

Build: npm run build

Test: npm test

Note: Sensitive data must use the Environment Vault.

Step 3：サブパッケージを横断する「共通 Skills」の呼び出し

モノレポでは、ルートにある共有ライブラリを更新した後に、サブパッケージ側で反映を確認する必要があります。Claude Code の AGENTS.md に、ルートのスクリプトを叩く「スキル」を登録しておけば、サブパッケージのディレクトリにいながら全体の整合性をチェックできます。

Step 4：実装とテストの自律サイクル

「Stripe の決済成功イベントを処理する Webhook エンドポイントを追加して」と指示します。Claude Code は CLAUDE.md に書かれたテストコマンドを見て、実装後に自ら npm test を実行し、エラーが出れば自動で修正案を提示・適用します。

Step 5：プルリクエスト（PR）作成とルートでの整合性チェック

作業が完了したら、/pr "Add Stripe webhook handler to payment package" と指示して PR を作成します。最終的な CI（GitHub Actions 等）がルートディレクトリで走り、モノレポ全体の整合性を担保します。この「手元の高速な AI 開発」と「厳格な CI による品質管理」の切り分けが、モダンな DX の形です。

このような自動化の恩恵は、エンジニアリング以外でも同様です。例えば、楽楽精算とfreeeの連携自動化のように、手作業を AI やシステムに委ねることで、人間はより高度なアーキテクチャ設計に集中できるようになります。

注意点とトラブルシューティング

Claude Code をモノレポで運用する際、ハマりやすいポイントがいくつかあります。

依存関係の解決エラーへの対処

サブパッケージ単体で Claude Code を動かしている際、共有ライブラリ（packages/shared 等）の型定義が見つからないというエラーが出ることがあります。これは Claude Code の視界から共有パッケージが外れているためです。

• 解決策： .claudeignore で packages/shared だけは除外対象から外しておくか、CLAUDE.md に「型定義はルートの node_modules も参照せよ」と明記します。

トークン枯渇を防ぐためのフィルタリング技術

デフォルトでは、Claude Code は多くのファイルを見ようとします。/compact コマンドを定期的に使い、履歴を整理することで、長時間のセッションでも精度を維持できます。また、AGENTS.md に「常に現在のパッケージディレクトリ以外のファイルは無視してよい」という強い制約を書き込むのも効果的です。

セキュリティとプライバシー

モノレポには組織全体の重要情報が含まれることが多いため、.env や secrets/ ディレクトリは必ず .claudeignore に追加してください。Anthropic はデータを学習に利用しないと明言していますが（ビジネスプラン等）、意図しないデータ送信は未然に防ぐのが実務者の鉄則です。

Claude Code を使いこなすことは、単なるコーディングの効率化に留まりません。リポジトリという「情報の貯蔵庫」を AI が正しく扱える形に整理するプロセスは、組織全体のナレッジマネジメントそのものです。まずは小さなサブパッケージから Claude Code を「住まわせる」感覚で、CLAUDE.md の整備を始めてみてください。

3. **追記するHTMLだけ**（通常は `