Antigravity × モノレポ開発マスタークラス — Nx・Turborepo 環境でAIコンテキストを最適化し、複数パッケージを横断するコード変更を自在に操る

# AGENTS.md（ルートレベル）
 
## プロジェクト構造
このリポジトリは Turborepo を使ったモノレポです。
 
- apps/web: Next.js 16 App Router フロントエンド（ポート 3000）
- apps/mobile: React Native 0.76 + Expo 52
- apps/api: Hono + Cloudflare Workers バックエンド
- packages/ui: shadcn/ui ベースの共有コンポーネントライブラリ
- packages/types: 全アプリ共通の TypeScript 型定義
- packages/utils: 共通ユーティリティ関数
 
## パッケージ名の解決ルール
インポートは常にパッケージ名を使うこと（相対パスは禁止）。
- UI コンポーネント: @my-org/ui
- 型: @my-org/types
- ユーティリティ: @my-org/utils
 
## TypeScript 設定
各 tsconfig.json は packages/config/tsconfig.base.json を継承している。
strict: true。any 型の使用は禁止。
 
## コーディング規約
- React コンポーネント: 関数コンポーネント + hooks のみ（class component 禁止）
- 状態管理: Zustand（Redux 禁止）
- API クライアント: packages/utils の createApiClient を使うこと
- エラーハンドリング: Result 型（packages/utils/result.ts）を使用
 
## 変更時の注意事項
packages/types を変更するときは、依存する apps/ のコードも同時に更新すること。
packages/ui のコンポーネント API を変更するときは必ずマイグレーションガイドを作成すること。
 
## 禁止事項
- console.log の本番コードへの混入（logger.ts を使う）
- any 型の使用
- packages/ 直下への直接ファイル作成（必ず適切なパッケージ内に配置）

# apps/web/AGENTS.md
 
## このアプリについて
Next.js 16 App Router を使った E コマースフロントエンド。
 
## ルーティング構造
- app/(auth)/: 認証関連ページ（ログイン・登録・パスワードリセット）
- app/(shop)/: ショップページ（商品一覧・詳細・カート・購入）
- app/admin/: 管理画面（認証が必要・admin ロールのみ）
 
## データフェッチ戦略
- Server Components でデータを取得すること（useEffect でのクライアントフェッチは禁止）
- キャッシュ: next/cache の unstable_cache を使用
- ミューテーション: Server Actions を使うこと（API Routes は禁止）
 
## スタイリング
- Tailwind CSS v4
- コンポーネントは packages/ui から import
- ページ固有スタイルは page.tsx の同階層に page.css として配置
 
## 画像・アセット
- next/image を必ず使うこと（img タグ禁止）
- 外部画像ドメインは next.config.ts の images.remotePatterns に追加

# packages/ui/AGENTS.md
 
## このパッケージについて
shadcn/ui をベースにした共有コンポーネントライブラリ。
React 19 + TypeScript strict mode。
 
## コンポーネント作成規則
1. ファイル名: kebab-case.tsx（例: button.tsx, user-card.tsx）
2. コンポーネント名: PascalCase
3. Props の型定義: interface ComponentNameProps として同ファイル内に定義
4. Storybook のストーリーを同時に作成すること（button.stories.tsx）
5. アクセシビリティ: WAI-ARIA 属性を適切に付与すること
 
## API の安定性
このパッケージのエクスポートは全アプリが依存している。
破壊的変更が発生する場合は:
1. 新しい API を追加（旧 API は deprecated マークを付けて残す）
2. MIGRATION.md を更新
3. バージョンを major bump する
 
## エクスポート
src/index.ts からのみエクスポートすること。
個別ファイルへの直接インポートは禁止。

// packages/types/src/user.ts（変更前）
export interface User {
  id: string
  email: string
  name: string
  createdAt: Date
}

// packages/types/src/user.ts（変更後）
export interface User {
  id: string
  email: string
  name: string
  role: 'admin' | 'member' | 'guest'  // 追加
  createdAt: Date
}
 
// apps/api/src/auth/user.service.ts（Antigravity が提案する変更）
// role フィールドのデフォルト値を設定
const newUser: User = {
  id: crypto.randomUUID(),
  email,
  name,
  role: 'member',  // 追加
  createdAt: new Date(),
}

// packages/ui/src/button.tsx（変更後）
export interface ButtonProps {
  children: React.ReactNode
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  loading?: boolean        // 新規追加
  loadingText?: string     // 新規追加（省略時は children を表示）
  onClick?: () => void
  disabled?: boolean
  type?: 'button' | 'submit' | 'reset'
}
 
export function Button({
  children,
  variant = 'primary',
  size = 'md',
  loading = false,
  loadingText,
  onClick,
  disabled,
  type = 'button',
}: ButtonProps) {
  return (
    <button
      type={type}
      className={buttonVariants({ variant, size })}
      onClick={onClick}
      disabled={disabled || loading}
      aria-busy={loading}
    >
      {loading ? (
        <>
          <span className="animate-spin mr-2">⟳</span>
          {loadingText ?? children}
        </>
      ) : (
        children
      )}
    </button>
  )
}

// turbo.json（最適化前）
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "test": {
      "dependsOn": ["build"]
    },
    "lint": {}
  }
}

// turbo.json（Antigravity による最適化後）
{
  "$schema": "https://turbo.build/schema.json",
  "ui": "tui",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**", ".turbo/**"],
      "env": ["NODE_ENV", "NEXT_PUBLIC_API_URL"],
      "passThroughEnv": ["VERCEL_GIT_COMMIT_SHA"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"],
      "cache": true
    },
    "test:unit": {
      "dependsOn": [],
      "outputs": ["coverage/unit/**"],
      "cache": true
    },
    "test:e2e": {
      "dependsOn": ["build"],
      "cache": false
    },
    "lint": {
      "dependsOn": [],
      "outputs": [],
      "cache": true
    },
    "type-check": {
      "dependsOn": ["^type-check"],
      "outputs": [],
      "cache": true
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

# .github/workflows/ci.yml
name: CI
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
 
jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # turbo prune で差分検出するために必要
 
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'npm'
 
      - name: Install dependencies
        run: npm ci
 
      - name: Type check
        run: npx turbo run type-check
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
 
      - name: Lint
        run: npx turbo run lint
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
 
      - name: Unit tests
        run: npx turbo run test:unit
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
 
      - name: Build
        run: npx turbo run build
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ secrets.TURBO_TEAM }}

// nx.json
{
  "$schema": "./node_modules/nx/schemas/nx-schema.json",
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "inputs": ["production", "^production"],
      "cache": true
    },
    "test": {
      "inputs": ["default", "^production", "{workspaceRoot}/jest.preset.js"],
      "cache": true
    },
    "lint": {
      "inputs": [
        "default",
        "{workspaceRoot}/.eslintrc.json",
        "{workspaceRoot}/.eslintignore"
      ],
      "cache": true
    }
  },
  "namedInputs": {
    "default": ["{projectRoot}/**/*", "sharedGlobals"],
    "production": [
      "default",
      "!{projectRoot}/**/?(*.)+(spec|test).[jt]s?(x)?(.snap)",
      "!{projectRoot}/tsconfig.spec.json",
      "!{projectRoot}/.eslintrc.json"
    ],
    "sharedGlobals": ["{workspaceRoot}/babel.config.json"]
  },
  "plugins": [
    {
      "plugin": "@nx/next/plugin",
      "options": {
        "buildTargetName": "build",
        "devTargetName": "dev",
        "startTargetName": "start"
      }
    }
  ]
}

# 新しいライブラリを作成するとき
$ npx nx generate @nx/react:library feature-auth \
  --directory=libs/feature-auth \
  --importPath=@my-org/feature-auth \
  --bundler=vite \
  --unitTestRunner=vitest

# .github/CODEOWNERS
# AGENTS.md の変更は必ずテックリードがレビュー
AGENTS.md @team/tech-lead
apps/web/AGENTS.md @team/frontend-lead
apps/api/AGENTS.md @team/backend-lead
packages/*/AGENTS.md @team/platform

# .github/workflows/agents-md-check.yml
name: Check AGENTS.md
 
on:
  pull_request:
    paths:
      - '**/AGENTS.md'
 
jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '⚠️ AGENTS.md が変更されています。チーム全員への周知と、変更内容が AI の挙動に与える影響を確認してください。'
            })

# packages/scripts/create-package-agents-md.ts
import { readFileSync, writeFileSync } from 'fs'
import { resolve } from 'path'
 
const packageDir = process.argv[2]
const packageJson = JSON.parse(
  readFileSync(resolve(packageDir, 'package.json'), 'utf-8')
)
 
const template = `# ${packageJson.name}/AGENTS.md
 
## このパッケージについて
${packageJson.description ?? '（説明を追加してください）'}
 
## 主な責務
- （このパッケージが担う機能・役割を記述）
 
## API
- エクスポートは src/index.ts からのみ
- 型の変更は後方互換を保つこと
 
## 依存関係
- 内部依存: （使用している @my-org/* パッケージを列挙）
- 外部依存: （主要な外部 npm パッケージを列挙）
 
## 変更時の注意事項
- （このパッケージを変更するときの注意点を記述）
`
 
writeFileSync(resolve(packageDir, 'AGENTS.md'), template)
console.log(`✅ ${packageDir}/AGENTS.md を作成しました`)

# 移行計画テンプレート（Antigravity に生成させる）
## Redux → Zustand 移行計画
 
### Phase 1（1週目）: 共有ユーティリティの準備
- packages/utils に Zustand のファクトリ関数を追加
- 既存の Redux Store の型定義を Zustand 互換に変換
 
### Phase 2（2〜3週目）: apps/web の移行
- 影響範囲が小さいページから順に移行
- 各 PR でテストを必ず通過させること
 
### Phase 3（4週目）: apps/mobile の移行
- web の移行パターンを踏襲する
- React Native 固有の考慮点を反映
 
### 完了基準
- 全テストがパス
- Redux 関連のパッケージが package.json から削除されている
- bundle size が同等以下

# .github/PULL_REQUEST_TEMPLATE.md
 
## 変更内容
<!-- 何をなぜ変えたか（Antigravity に記入を手伝ってもらう） -->
 
## 影響範囲チェック（Antigravity に確認させること）
- [ ] packages/types を変更した → 影響パッケージを全て更新済み
- [ ] packages/ui の API を変更した → MIGRATION.md 更新済み
- [ ] 新しい環境変数を追加した → turbo.json の env フィールドに追加済み
- [ ] 外部依存を追加した → 全パッケージで同一バージョンを使用
- [ ] DB スキーマを変更した → マイグレーションファイル作成済み
 
## テスト
- [ ] ユニットテストを追加・更新した
- [ ] 影響範囲の手動確認を行った
- [ ] CI が通ることを確認した

# 変更影響を受けるパッケージのみテストする（Turborepo）
npx turbo run test --filter=...[HEAD^1]
 
# 変更影響を受けるパッケージのみビルドする（Nx）
npx nx affected --target=build --base=origin/main

// packages/config/tsconfig.base.json
{
  "compilerOptions": {
    "paths": {
      "@my-org/ui": ["../../packages/ui/src/index.ts"],
      "@my-org/types": ["../../packages/types/src/index.ts"],
      "@my-org/utils": ["../../packages/utils/src/index.ts"]
    }
  }
}

// apps/web/tsconfig.json
{
  "extends": "../../packages/config/tsconfig.base.json",
  "compilerOptions": {
    // アプリ固有の設定のみここに記述
    "baseUrl": "."
  }
}

// turbo.json
{
  "tasks": {
    "build": {
      "env": [
        "NODE_ENV",
        "NEXT_PUBLIC_API_URL",
        "DATABASE_URL"  // 追加が必要だった環境変数
      ]
    }
  }
}

// apps/web/project.json
{
  "name": "web",
  "implicitDependencies": ["ui", "types", "utils"],
  "targets": {
    "build": { ... }
  }
}