Claude Code Turborepo: Claude Code 활용 가이드

Turborepoモノレポの구축をClaude Code로 가속화하기

Turborepoは、Vercelが개발する高性能なモノレポ빌드システムです。インクリメンタル빌드とインテリジェント캐시により、大規模프로젝트でも高速な빌드を維持할 수 있습니다。Claude Codeを활용すれば、Turborepoの複雑な설정も효율적으로進められます。

프로젝트の初期구축

> 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"],
  "pipeline": {
    "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の파이프라인では、태스크間の依存関係を dependsOn で宣言します。

> 패키지間の依存を考慮して、build → test → deploy の
> 파이프라인を설계して。타입チェックはbuildと병렬で実行したい。

{
  "pipeline": {
    "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공식 문서를 참고하세요.