Antigravity × モノレポ運用 — Turborepo/Nx で大規模プロジェクトを効率管理

取り組みの背景

モノレポ（monorepo）は複数のプロジェクトを単一のリポジトリで管理する強力なアプローチです。しかし規模が拡大すると、パッケージ間の依存関係の管理、ワークスペース設定、キャッシング戦略など、複雑さが急増します。

Antigravity エージェントは、大規模なコードベースを自動的に分析・理解し、Turborepo や Nx などのモノレポ管理ツールと組み合わせることで、開発効率を劇的に向上させます。ここではAntigravity がどのようにモノレポ運用を支援し、AI駆動の依存関係管理とコード共有パターンの実装を実現するかを詳しく解説します。

モノレポ環境の課題とAntigravityの役割

モノレポ管理の複雑性

大規模なモノレポでは以下の課題に直面します：

複雑な依存関係グラフ：10個以上のパッケージが相互に依存する場合、関係を把握しづらくなります
クロスパッケージリファクタリング：API変更時に、すべての使用箇所を正確に把握し更新する必要があります
ビルドパイプラインの最適化：不要な再ビルドを避け、変更の影響を受けたパッケージだけを再構築する必要があります
ワークスペース間のコード共有：共有パッケージの設計と、それぞれのパッケージでの正しい利用方法の確保が困難です

Antigravity エージェントの強み

Antigravity は LLM ベースのエージェントであり、以下の能力を備えています：

コードベース全体の自動分析：複数のパッケージ構造、依存関係、キャッシング戦略を一度に把握します
インテリジェントな依存関係追跡：変更の影響を受けるすべてのパッケージを自動検出します
マルチパッケージ間での型安全なリファクタリング：共有型定義を修正し、全使用箇所を一度に更新できます
ベストプラクティスの推奨：Turborepo や Nx の最適な設定パターンを提案します

Turborepo を使用したワークスペース設定

Turborepo は高速でシンプルなモノレポマネージャーです。以下は推奨される設定例です。

プロジェクト構造

my-monorepo/
├── apps/
│   ├── web/                # Nextアプリケーション
│   ├── admin/              # 管理画面
│   └── mobile/             # React Native アプリ
├── packages/
│   ├── ui/                 # 共有UI コンポーネント
│   ├── utils/              # ユーティリティ関数
│   ├── api-client/         # API クライアント
│   └── database/           # DB スキーマと ORM
├── turbo.json              # Turborepo 設定
└── package.json            # ルート設定

turbo.json の設定

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.local", ".env"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "build/**"],
      "cache": true
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"],
      "cache": true
    },
    "lint": {
      "outputs": [],
      "cache": false
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "type-check": {
      "dependsOn": ["^type-check"],
      "outputs": [],
      "cache": true
    }
  }
}

このパイプライン設定により、turbo build は依存関係を自動解決し、変更されたパッケージのみを再ビルドします。

ワークスペース package.json

各パッケージの package.json は以下の要素を含むべきです：

{
  "name": "@monorepo/ui",
  "version": "1.0.0",
  "description": "Shared UI components",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./button": {
      "import": "./dist/button.js",
      "types": "./dist/button.d.ts"
    }
  },
  "scripts": {
    "build": "tsc --project tsconfig.build.json",
    "dev": "tsc --project tsconfig.json --watch",
    "test": "vitest",
    "type-check": "tsc --noEmit"
  },
  "dependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

Nx を使用した高度なワークスペース管理

Nx は、より詳細な制御とプラグインエコシステムを提供します。

nx.json の設定

{
  "extends": "nx/presets/npm.json",
  "npxInstallPackage": "nx",
  "defaultBase": "main",
  "defaultProject": "web",
  "namedInputs": {
    "default": ["{projectRoot}/**/*"],
    "production": [
      "!{projectRoot}/**/*.spec.ts",
      "!{projectRoot}/jest.config.ts",
      "!{projectRoot}/.eslintrc.json"
    ]
  },
  "targetDefaults": {
    "build": {
      "cache": true,
      "inputs": ["production", "^production"],
      "dependsOn": ["^build"]
    },
    "test": {
      "cache": true,
      "inputs": ["default", "^production"],
      "dependsOn": ["^build"]
    }
  },
  "affected": {
    "defaultBase": "main"
  }
}

Antigravity がモノレポ管理を支援する実践的な方法

1. 依存関係グラフの自動分析

Antigravity エージェントは、モノレポ全体をスキャンし、パッケージ間の依存関係を視覚化します：

antigravity analyze --monorepo-path ./

このコマンドにより、エージェントは：

すべてのパッケージの package.json を解析
内部依存関係（@monorepo/*）と外部依存関係を分類
循環依存の検出
バージョンの不一致を警告

2. クロスパッケージリファクタリング

API が変更される場合、Antigravity は自動的に影響を受けるすべてのパッケージを特定し、一括更新を提案します。

例えば、api-client パッケージの関数シグネチャを変更した場合：

// packages/api-client/src/user.ts
// 変更前: export function getUser(id: string): Promise<User>
// 変更後: export async function getUser(userId: string): Promise<User | null>

Antigravity は以下を自動検出します：

web アプリの 15 箇所での使用
admin アプリの 8 箇所での使用
不適切な null チェック漏れ箇所

そして、修正パッチを生成し、型安全性を保証します。

3. 共有パッケージの設計支援

Antigravity は、コード重複を検出し、共有パッケージに抽出すべき共通ロジックを提案します：

antigravity suggest-shared-packages --analyze-duplication

結果例：

apps/web/utils/validation.ts と apps/admin/utils/validation.ts が 92% 一致
提案：packages/validation を作成し、共有ロジックを移行

4. タスクパイプラインの最適化

Turborepo/Nx のパイプライン設定を、エージェントが自動推奨します：

antigravity optimize-pipeline --suggest-cache-keys

推奨内容：

inputs を細かく設定し、不要なキャッシュ無効化を防止
dependsOn の依存関係を最小化
並列実行可能なタスクを識別

キャッシング戦略とパフォーマンス最適化

リモートキャッシング

Turborepo のリモートキャッシングは、チーム全体でビルド結果を共有し、CI/CD パイプラインを高速化します。

{
  "globalDependencies": ["turbo.json"],
  "pipeline": {
    "build": {
      "outputs": ["dist/**"],
      "cache": true
    }
  }
}

Antigravity は、キャッシュキーの最適化を提案します：

// キャッシュキーの安定性を確保
const stableInputs = [
  "src/**/*.ts",
  "src/**/*.tsx",
  "tsconfig.json",
  "package.json"
];

増分ビルド

turbo build --filter='[HEAD~1]' を使用し、変更されたパッケージのみをビルドします。Antigravity は依存関係グラフから、影響を受けるすべてのパッケージを正確に判定します。

AI駆動のコード共有パターン

パターン 1: 共有型定義

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: "admin" | "user";
}
 
export type UserInput = Omit<User, "id">;

Antigravity は、このパターンが他のパッケージでも適用すべきか分析します。

パターン 2: API クライアント層の共有

// packages/api-client/src/index.ts
import { User } from "@monorepo/types";
 
export const userAPI = {
  get: (id: string): Promise<User> => { /* ... */ },
  create: (input: UserInput): Promise<User> => { /* ... */ },
  update: (id: string, input: Partial<UserInput>): Promise<User> => { /* ... */ }
};

パターン 3: 環境設定の一元管理

// packages/config/src/env.ts
export const config = {
  apiUrl: process.env.REACT_APP_API_URL || "http://localhost:3000",
  isDev: process.env.NODE_ENV === "development"
};

まとめ

Antigravity エージェントと Turborepo/Nx の組み合わせは、大規模モノレポの管理を大幅に簡素化します。自動化された依存関係管理、クロスパッケージリファクタリング、ベストプラクティスの提案により、開発チームは戦略的なアーキテクチャに集中できます。

モノレポを採用する際は、Antigravity のような AI駆動ツールを活用し、複雑性を最小限に抑えながら、スケーラビリティと保守性を両立させましょう。