Claude CodeとTurborepoで高速モノレポ開発を実現する方法

Turborepoモノレポの構築をClaude Codeで加速する

Turborepoは、Vercelが開発する高性能なモノレポビルドシステムです。インクリメンタルビルドとインテリジェントキャッシュにより、大規模プロジェクトでも高速なビルドを維持できます。Claude Codeを活用すれば、Turborepoの複雑な設定も効率的に進められます。

対象バージョン: 本記事のコード例はすべて Turborepo v2.x（2025年時点の最新安定版） を前提としています。Turborepo v2 では、v1 で使われていた "pipeline" キーが "tasks" に改名 されました。v1 の設定ファイルをそのまま使うと turbo CLI がエラーで停止するので注意してください（npx @turbo/codemod migrate で自動移行できます）。

プロジェクトの初期構築

> Turborepoでモノレポを新規作成して。
> 構成：
> - apps/web: Next.js App Router
> - apps/docs: Astroドキュメントサイト
> - packages/ui: 共通UIライブラリ
> - packages/utils: ユーティリティ関数
> - packages/tsconfig: TypeScript設定

Claude Codeが生成する turbo.json の設定例です。

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "out/**"],
      "env": ["NEXT_PUBLIC_API_URL"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"]
    }
  }
}

タスク依存関係の設計

Turborepo v2 では、タスク間の依存関係を tasks オブジェクト内で dependsOn を使って宣言します（v1 では pipeline でしたが v2 で tasks に改名されました）。

> パッケージ間の依存を考慮して、build → test → deploy の
> タスク依存グラフを設計して。型チェックはbuildと並列で実行したい。

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "type-check": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "deploy": {
      "dependsOn": ["build", "test", "type-check"],
      "cache": false
    }
  }
}

build と type-check は互いに依存しないため、Turborepoが自動的に並列実行してくれます。

リモートキャッシュの設定

チーム開発ではリモートキャッシュが欠かせません。

> Vercel Remote Cacheを設定して。
> CI環境でも使えるようにしたい。

# Vercelアカウントとリンク
npx turbo login
npx turbo link

# CI環境用の設定（GitHub Actions）
# TURBO_TOKEN と TURBO_TEAM を secrets に設定

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]
env:
  TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
  TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
      - run: pnpm install
      - run: pnpm turbo build lint test --filter=...[HEAD^]

--filter=...[HEAD^] を使うことで、変更のあったパッケージだけをビルド対象にできます。

フィルタリングで効率的な開発

> webアプリだけをdevモードで起動して。
> 依存パッケージのwatchも有効にして。

# 特定のアプリとその依存パッケージのみ実行
pnpm turbo dev --filter=web...

# 変更があったパッケージのみビルド
pnpm turbo build --filter=...[origin/main]

# 特定パッケージを除外
pnpm turbo build --filter=!./apps/docs

キャッシュのデバッグ

ビルドキャッシュが効かない場合、Claude Codeにデバッグを依頼できます。

> turbo buildのキャッシュがヒットしない原因を調査して。
> turbo run build --dry=json の出力を確認して。

# キャッシュステータスの確認
pnpm turbo build --dry=json | jq '.tasks[] | {taskId, cache}'

# 詳細なログ出力
pnpm turbo build --verbosity=2

まとめ

Claude Codeを使えば、Turborepoのパイプライン設計やキャッシュ戦略を素早く最適化できます。モノレポ管理の基本やCI/CD設定ガイドも合わせて参考にしてください。

Turborepoの詳しい設定はTurborepo公式ドキュメントを参照してください。