Claude Code × モノレポ完全ガイド｜Turborepo・Nx・CLAUDE.md階層設計・クロスパッケージ保護・CI高速化【2026年最新】

my-monorepo/
├── CLAUDE.md                    # 全体共通ルール（常時ロード）
├── .claude/
│   └── rules/
│       ├── code-style.md        # コーディング規約（常時ロード）
│       └── api-design.md        # APIルール（paths指定で遅延ロード）
├── apps/
│   └── web/
│       └── CLAUDE.md            # Next.js専用ルール（遅延ロード）
└── packages/
    ├── ui/
    │   └── CLAUDE.md            # UIライブラリルール（遅延ロード）
    ├── api/
    │   └── CLAUDE.md            # API固有ルール（遅延ロード）
    └── shared/
        └── CLAUDE.md            # 共有型・変更制限（遅延ロード）

# Monorepo 共通ルール

## ビルドシステム
- パッケージマネージャ: pnpm
- ビルドシステム: Turborepo（turbo.jsonのtasksキーを使う。pipelineは旧記法）
- タスク実行: turbo run build / test / lint
- 特定パッケージ: pnpm --filter=@myapp/api run build

## 命名規則
- パッケージ名: @myapp/<name>（スコープ付き）
- 内部import: @myapp/shared（相対パスでの他パッケージ参照禁止）

## パッケージ間のルール
- 共有型・ユーティリティは必ず packages/shared 経由
- packages/shared を変更する際はチーム承認が必要（勝手に変更しない）
- パッケージ間の循環依存は禁止

## Claude Codeへの指示
- 作業ディレクトリ外のファイルは変更しない
- pnpm --filter=<package> でパッケージ限定コマンドを実行する
- turbo run build で全体のビルド確認をする

## 個人設定
@~/.claude/my-monorepo-preferences.md

# API パッケージルール

## スタック
- Express + Prisma + TypeScript strict

## アーキテクチャ
- router → controller → service → repository の4層
- ビジネスロジックは service 層のみ

## 作業スコープ（重要）
- 変更可能: packages/api/ 以下のファイルのみ
- 変更禁止: packages/ui/, apps/web/, packages/shared/
- packages/shared の型が不足している場合: 変更せず上位に報告する

## コマンド
- 開発サーバー: pnpm --filter=@myapp/api dev
- テスト: pnpm --filter=@myapp/api test
- 型チェック: pnpm --filter=@myapp/api typecheck

# UI パッケージルール

## スタック
- React + TypeScript + Tailwind CSS v4
- shadcn/ui（CLIでインストール。直接編集禁止）

## コンポーネントルール
- Server Components は apps/ 配下のみ（このパッケージはクライアントコンポーネント専用）
- すべてのコンポーネントに型定義ファイルを追加する
- アクセシビリティ属性（aria-*）を必ず含める

## エクスポート
- index.tsからのみエクスポート（内部ファイルの直接import禁止）

## 作業スコープ
- 変更可能: packages/ui/ 以下のファイルのみ
- apps/ 配下のファイルは変更しない

---
paths:
  - "packages/api/src/routes/**/*.ts"
  - "packages/api/src/controllers/**/*.ts"
---

# API設計ルール（APIファイル操作時のみロード）

## エンドポイント設計
- RESTful原則に従う（GETはデータ取得のみ、変更はPOST/PUT/DELETE）
- バージョニング: /api/v1/...
- レスポンス形式: { data: T, error: null } または { data: null, error: string }

## バリデーション
- すべてのエンドポイントにZodバリデーション必須
- リクエストボディ・クエリパラメータ・パスパラメータを個別にバリデート

turbo.jsonを生成してください。

構成:
- apps/web: Next.js 16
- apps/admin: Vite + React
- packages/ui: 共有コンポーネント
- packages/api: Express + Prisma

要件:
- buildは依存パッケージのbuild完了後に実行（^buildで宣言）
- devはキャッシュなし・永続化
- testはsrc/**とtest/**のみ変更検知
- Next.jsのoutputは.next/**（キャッシュ除く）
- Turbopack v2の最新記法（pipeline→tasks）を使う

{
  "$schema": "https://turborepo.org/schema.json",
  "globalEnv": ["NODE_ENV", "GITHUB_TOKEN"],
  "globalDependencies": [".env"],
  "tasks": {
    "build": {
      "description": "本番ビルド",
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "env": ["DATABASE_URL", "API_KEY"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "inputs": ["src/**/*.ts", "test/**/*.ts"],
      "outputs": ["coverage/**"]
    }
  },
  "remoteCache": {
    "enabled": true,
    "signature": true
  }
}

{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": [".next/**", "!.next/cache/**"]
    }
  }
}

packages:
  - "apps/*"
  - "packages/*"

{
  "name": "my-monorepo",
  "private": true,
  "packageManager": "pnpm@9.0.0",
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev",
    "lint": "turbo run lint",
    "test": "turbo run test"
  },
  "devDependencies": {
    "turbo": "latest"
  }
}

# packages/api ディレクトリで起動（このパッケージのコンテキストのみ）
cd packages/api
claude

# 起動後にセッション開始プロンプト
> packages/api 内の作業のみ行います。
> 他パッケージのファイルは変更しないでください。
> コマンド実行は pnpm --filter=@myapp/api <cmd> を使ってください。

# Nx CLIがClaude Code向け設定を全自動生成
npx nx configure-ai-agents

# 生成されるもの:
# - .mcp.json（Nx Cloud MCPサーバー設定）
# - CLAUDE.md / AGENTS.md（Nx操作ガイドライン）
# - Claude Code Skill（nx show projects・nx graphの使い方）

# 変更されたパッケージとその依存先のテストのみ実行
npx nx affected:test

# 依存グラフをビジュアル確認
npx nx graph

# Claude Codeにaffectedを使って指示
> nx affected:testを実行して、失敗したテストの原因を特定して修正してください

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c \'FILE=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r \".file_path // empty\"); CWD=$(pwd); if [[ -n \"$FILE\" ]] && [[ \"$FILE\" == */packages/shared/* ]] && [[ \"$CWD\" != */packages/shared* ]]; then echo \"ERROR: packages/shared への直接変更は禁止されています。変更が必要な場合は確認してください。\" >&2; exit 2; fi\'"
          }
        ]
      }
    ]
  }
}

# packages/api/CLAUDE.md に追記

## 作業スコープ制限（IMPORTANT）
- ONLY modify files under: packages/api/
- NEVER touch: packages/shared/, packages/ui/, apps/
- If shared types need updating: describe what's needed but DO NOT edit directly

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build-test:
    runs-on: ubuntu-latest
    env:
      # Vercel Remote Cache を使う場合
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v3
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile

      # Vercel不使用の場合はローカルキャッシュで代替
      - name: Cache turbo build
        uses: actions/cache@v4
        with:
          path: .turbo
          key: ${{ runner.os }}-turbo-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-turbo-

      - name: Build & Test
        run: pnpm turbo run build test lint

name: Deploy Web

on:
  push:
    branches: [main]
    paths:
      - "apps/web/**"
      - "packages/ui/**"
      - "packages/shared/**"
      - ".github/workflows/deploy-web.yml"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v3
        with:
          version: 9
      - run: pnpm install --frozen-lockfile
      - run: pnpm --filter=@myapp/web build
      - name: Deploy to Vercel
        run: npx vercel --prod
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

このモノレポ（pnpm workspace + Turborepo）のGitHub Actionsを生成してください。

構成:
- apps/web（Next.js → Vercelにデプロイ）
- apps/admin（Vite → S3にデプロイ）
- packages/*（共有パッケージ）

要件:
- apps/webの変更時のみwebデプロイジョブを実行
- apps/adminの変更時のみadminデプロイジョブを実行
- packages/の変更は両方の下流デプロイをトリガー
- Turboリモートキャッシュ（TURBO_TOKEN/TURBO_TEAM）を使う
- pnpm install はNode.jsキャッシュを活用する