Claude Code × Monorepo開発 — Turborepo・pnpm Workspacesで大規模プロジェクトを効率化する

Monorepo開発にClaude Codeが効く理由

現代のフロントエンド・バックエンド開発では、複数のパッケージやアプリケーションを1つのリポジトリで管理するMonorepo構成が主流になりつつあります。Turborepo、pnpm Workspaces、Nx などのツールがその基盤を支えていますが、パッケージ間の依存関係、型定義の共有、一貫したコーディングスタイルの維持といった課題も生まれます。

Claude Code はリポジトリ全体のコンテキストを理解しながら作業できるため、Monorepo開発との相性が非常に優れています。Turborepoとpnpm Workspacesを例に、Claude Codeを活用してMonorepo開発を効率化する具体的な方法を順を追って整理していきます。

前提知識と環境準備

この記事を最大限に活用するために、以下の環境を準備してください。

• Node.js 20以上がインストール済み
• pnpmがグローバルインストール済み（npm install -g pnpm）
• Claude Codeが最新バージョンにアップデート済み（npm update -g @anthropic-ai/claude-code）
• Git の基本操作に慣れていること

まだMonorepoプロジェクトを持っていない場合は、Turborepoの公式スターターで素早く構築できます。

# Turborepo + pnpm のMonorepoを新規作成
pnpm dlx create-turbo@latest my-monorepo
cd my-monorepo
 
# 構成確認
ls -la packages/ apps/
# 出力例:
# packages/ui        — 共有UIコンポーネントライブラリ
# packages/config    — ESLint / TypeScript共有設定
# apps/web           — Next.jsフロントエンド
# apps/docs          — ドキュメントサイト

CLAUDE.md をMonorepo向けに設計する

Monorepoで Claude Code を使う場合、CLAUDE.md の配置戦略が成功の鍵を握ります。Claude Code はカレントディレクトリとその親ディレクトリの CLAUDE.md を自動的に読み込むため、階層構造を活かした設定が可能です。

ルート CLAUDE.md — プロジェクト全体のルール

# My Monorepo — CLAUDE.md
 
## プロジェクト構成
- Turborepo + pnpm Workspaces によるMonorepo
- apps/ にアプリケーション、packages/ に共有ライブラリ
 
## 共通ルール
- TypeScript strict モード必須
- ESLint + Prettier でフォーマット統一
- テストは Vitest を使用
- コミットメッセージは Conventional Commits 形式
 
## パッケージ間の依存関係
- 共有UIは @repo/ui からインポート
- 設定は @repo/config を参照
- 循環依存は絶対禁止
 
## よく使うコマンド
- pnpm dev         — 全アプリを並列起動
- pnpm build       — Turborepoで依存順にビルド
- pnpm test        — 全パッケージのテスト実行
- pnpm lint        — 全パッケージのLint実行

パッケージごとの CLAUDE.md — 個別のコンテキスト

# packages/ui — CLAUDE.md
 
## このパッケージの役割
- 全アプリで共有するUIコンポーネントライブラリ
- Radix UI プリミティブ + Tailwind CSS でスタイリング
 
## コンポーネント作成ルール
- src/components/ に1コンポーネント1ファイル
- 必ず index.ts で re-export する
- Storybook のストーリーファイルを同梱
- Props には JSDoc コメントを付与

この階層構造により、Claude Code は作業ディレクトリに応じて適切なコンテキストを自動的に取得します。apps/web/ で作業すればルートの共通ルールに加えてWebアプリ固有の指示が読み込まれ、packages/ui/ で作業すればUIライブラリの規約に従った提案が得られます。

パッケージ横断のリファクタリング

Monorepo開発で最も手間がかかるのが、共有パッケージの変更を全アプリに反映するリファクタリングです。Claude Code のサブエージェント機能とワークツリーを活用すれば、この作業を効率的に進められます。

例: 共有コンポーネントのAPI変更を全体に反映する

たとえば @repo/ui の Button コンポーネントに variant props を追加し、それを使っている全アプリを更新するケースを考えます。

# Claude Code にMonorepo全体を意識した指示を出す
claude "packages/ui の Button コンポーネントに variant props
('primary' | 'secondary' | 'danger') を追加して、
apps/ 配下のすべての Button 使用箇所を確認し、
適切な variant を設定してください。
変更後は pnpm build && pnpm test で
全パッケージのビルドとテストが通ることを確認してください。"

Claude Code はこの指示を受けて以下の処理を自動的に行います。

1. packages/ui/src/components/Button.tsx の型定義とコンポーネント実装を更新
2. grep や Glob で apps/ 配下の全 Button 使用箇所を検出
3. 各ファイルの文脈から適切な variant 値を推定して設定
4. pnpm build でTurborepoのビルドパイプラインを実行し、型エラーがないか確認
5. pnpm test で回帰テストを通過するか検証

ワークツリーで安全にリファクタリングする

大規模な変更を行う場合は、ワークツリーを使って安全に作業できます。

# ワークツリーで並行作業
claude "/worktree で新しいブランチを作成して
packages/ui の Button リファクタリングを行ってください。
既存のmainブランチに影響を与えずに作業してください。"

ワークツリーを使えば、メインブランチの作業を中断せずにリファクタリングを進められます。変更に問題がなければ、そのままPRを作成してレビューに回すワークフローが自然に構築できます。

Turborepoのタスク依存関係を活用する

Turborepo の最大の強みは、パッケージ間の依存関係を理解した上でビルドやテストを並列実行できることです。Claude Code にこの仕組みを理解させることで、より的確な提案が得られます。

turbo.json の設定を CLAUDE.md に含める

## Turborepo タスク依存関係
 
turbo.json の主要タスク:
- build: dependsOn ["^build"] — 依存パッケージのビルドが先
- test: dependsOn ["build"] — ビルド完了後にテスト
- lint: 依存なし — 並列実行可能
- dev: cache: false, persistent: true

この情報があると、Claude Code は「packages/ui を変更したら apps/web のビルドも影響を受ける」ことを理解し、ビルド順序を考慮した作業を行えます。

実際の turbo.json 設定例

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "test": {
      "dependsOn": ["build"]
    },
    "lint": {},
    "dev": {
      "cache": false,
      "persistent": true
    },
    "type-check": {
      "dependsOn": ["^build"]
    }
  }
}
// 期待する動作:
// pnpm build 実行時 → packages/config → packages/ui → apps/web, apps/docs の順にビルド
// pnpm lint 実行時 → 全パッケージが並列でLint実行

依存関係の追加と管理

Monorepoで新しい依存関係を追加する際、Claude Code に正しいスコープを指示する点が肝心です。

# 特定パッケージへの依存追加
claude "apps/web に react-hook-form を追加して、
お問い合わせフォームを実装してください。
pnpm add は apps/web のスコープで実行してください。"

Claude Code はこの指示を受けて、以下のように正しいコマンドを実行します。

# Claude Codeが実行するコマンド
cd apps/web
pnpm add react-hook-form
 
# または pnpm のフィルター構文を使用
pnpm --filter web add react-hook-form

共有パッケージの内部依存を設定する

パッケージ間の内部依存を追加するときは、pnpm の workspace:* プロトコルを使います。

# apps/web から packages/ui を参照する設定
claude "apps/web の package.json に @repo/ui への
workspace 依存を追加してください。
pnpm の workspace:* プロトコルを使ってください。"

{
  "name": "web",
  "dependencies": {
    "@repo/ui": "workspace:*",
    "next": "^16.0.0",
    "react": "^19.0.0"
  }
}

新しいパッケージを追加するワークフロー

Monorepoに新しい共有パッケージを追加する作業は、ディレクトリ構成、package.json、TypeScript設定、ビルド設定など多くのファイルを整合性を保ちながら作成する必要があります。Claude Code に一括で任せるのが効率的です。

claude "packages/ に @repo/utils という新しい共有ユーティリティパッケージを追加してください。
要件:
- TypeScript + Vitest でテスト
- tsup でバンドル（ESM + CJS 出力）
- 日付フォーマット、文字列操作、バリデーションのユーティリティ関数を3つ以上実装
- 各関数にユニットテストを作成
- packages/ui と apps/web から import できるように設定
- pnpm build && pnpm test が通ることを確認"

Claude Code は以下のファイルを一括で生成します。

packages/utils/
├── package.json           # name: @repo/utils, tsup設定
├── tsconfig.json          # 共有TSConfig を extends
├── tsup.config.ts         # ESM + CJS ビルド設定
├── src/
│   ├── index.ts           # re-export
│   ├── date.ts            # 日付フォーマットユーティリティ
│   ├── string.ts          # 文字列操作ユーティリティ
│   └── validation.ts      # バリデーションユーティリティ
├── tests/
│   ├── date.test.ts
│   ├── string.test.ts
│   └── validation.test.ts
└── CLAUDE.md              # パッケージ固有のコンテキスト

よくあるエラーと対処法

Monorepo環境で Claude Code を使う際に遭遇しやすいトラブルとその解決策を紹介します。

pnpm の hoisting 問題

Monorepoで特に起きやすいのが、依存パッケージの hoisting（巻き上げ）に関する問題です。

# .npmrc でhoistingを制御する
shamefully-hoist=true
# もしくは特定パッケージのみ
public-hoist-pattern[]=@prisma/*

Claude Code に .npmrc の設定も CLAUDE.md に記載しておくと、依存関係のトラブル時に的確な対処を提案してくれます。

TypeScript のパス解決エラー

パッケージ間の参照でTypeScriptのパス解決が失敗する場合があります。

{
  "compilerOptions": {
    "paths": {
      "@repo/ui": ["../../packages/ui/src"],
      "@repo/utils": ["../../packages/utils/src"]
    }
  }
}
// これを各 apps/*/tsconfig.json に設定することで
// エディタ上での型解決とClaude Codeの型理解が両立する

Turborepo キャッシュの不整合

ビルドキャッシュが原因で変更が反映されない場合は、キャッシュをクリアします。

# Turborepo キャッシュクリア
pnpm turbo clean
# もしくは特定タスクのみ
pnpm turbo build --force

全体を振り返って

Claude Code とMonorepo開発の組み合わせは、パッケージ横断の変更管理、依存関係の整合性維持、新パッケージの足場構築といった手間のかかる作業を大幅に効率化します。ポイントをおさらいしましょう。

1. CLAUDE.md を階層的に配置して、ルートの共通ルールと各パッケージ固有の指示を分離する
2. Turborepoのタスク依存関係を CLAUDE.md に明記して、ビルド順序を理解させる
3. パッケージ横断のリファクタリングは Claude Code に全体を見渡した指示を出す
4. ワークツリーを活用して安全に大規模変更を行う
5. pnpm のフィルター構文を CLAUDE.md に含めて正しいスコープで操作させる

まずは既存のMonorepoプロジェクトのルートに CLAUDE.md を作成するところから始めてみてください。それだけでも Claude Code の提案品質が大きく向上するはずです。

Claude Codeの基本的なセットアップについては「Claude Code セットアップガイド」を、ワークツリーの詳細については「Claude Code ワークツリーガイド」を、サブエージェントの並列実行については「Claude Code サブエージェント並列実行」もあわせてご覧ください。