Antigravity Background Agent 上級実践ガイド — タスク設計・並列実行・CI/CD統合の完全メソッド

## 目標
UserProfile コンポーネントのテストカバレッジを80%以上に引き上げてください。
現在のカバレッジ: 約35%（`npx vitest coverage` で確認済み）
 
## 対象ファイル
- src/components/UserProfile.tsx（主要対象）
- src/components/UserProfile.test.tsx（新規または追記）
- src/types/user.ts（参照のみ）
 
## 使用するテストフレームワーク
- vitest + @testing-library/react
- モックは vi.mock() を使用
- ユーザーイベントは @testing-library/user-event
 
## 完了条件（全て満たすこと）
1. `npx vitest coverage` でカバレッジ80%以上
2. 既存のテストが全てパス（変更禁止）
3. TypeScript のビルドエラーがゼロ
4. 各テストケースに日本語のdescribeとitコメント付き
 
## 禁止事項
- UserProfile.tsx の既存の props インターフェースを変更しない
- 外部APIのモックに実際のエンドポイントURLを使わない
- スナップショットテストは作成しない（メンテコストが高いため）
 
## 参考情報
- 既存のAuthコンポーネントのテスト（src/components/Auth.test.tsx）が参考になります
- テスト実行: `npx vitest run --reporter=verbose`

# ❌ 大きすぎるタスク（失敗リスク高）
"プロジェクト全体をリファクタリングして、型安全性を向上させてください"
 
# ✅ 適切な粒度（1つのセッションで完結）
"src/api/ ディレクトリ内のすべてのAPIクライアント関数に、
 zod スキーマを使った入出力バリデーションを追加してください"

# プロジェクト: MyApp — エージェント向け作業指針
 
## このプロジェクトについて
Next.js 16 App Router + TypeScript + Cloudflare Workers で構築された
個人向けタスク管理SaaSです。日英2言語対応（next-intl v4）。
 
## 技術的な制約（必読）
- Node.js は使用不可（Cloudflare Workers 環境）
- `fs` モジュールは使用不可 — ファイルI/Oはすべて ASSETS バインディング経由
- npm run build の前に `node scripts/generate-content.mjs` が必要（prebuildに設定済み）
- テストランナー: vitest（jest ではない）
 
## コーディング規約
- 型定義は `src/types/` に集中管理
- コンポーネントは Server/Client を明示（'use client' ディレクティブ）
- APIルートは `src/app/api/` 配下、命名は `route.ts`
- 日本語コメントを推奨（英語も可）
 
## よくある間違いと回避方法
### ❌ よくやってしまうこと
- `headers()` を同期で呼ぶ → async/await 必須
- `cookies().set()` をクライアントコンポーネントで使う → サーバーコンポーネントのみ
 
### ✅ 正しいパターン
- 環境変数: `process.env.NEXT_PUBLIC_*` (クライアント) / `process.env.*` (サーバー)
- DBアクセス: `getCloudflareContext().env.DB` を使用
 
## テスト実行コマンド
\`\`\`bash
npx vitest run          # 全テスト実行
npx vitest coverage     # カバレッジ計測
npx tsc --noEmit        # 型チェック
\`\`\`
 
## 変更してはいけないファイル
- src/config/pricing.ts（Stripe price ID が格納されている）
- public/robots.txt（SEO設定）
- wrangler.toml（Cloudflare設定）

# worktreeの事前準備スクリプト
#\!/bin/bash
 
PROJECT_DIR="$HOME/myapp"
WORKTREES_DIR="$HOME/myapp-worktrees"
 
# 3つの並列タスク用worktreeを作成
for task in "test-coverage" "api-validation" "docs-update"; do
  branch="agent/$task-$(date +%Y%m%d)"
  worktree_path="$WORKTREES_DIR/$task"
  
  # worktreeを作成（新規ブランチ）
  git -C "$PROJECT_DIR" worktree add \
    -b "$branch" \
    "$worktree_path" \
    main
  
  echo "✅ Created worktree: $worktree_path (branch: $branch)"
done
 
# 確認
git -C "$PROJECT_DIR" worktree list

# 各worktreeのブランチをmainにマージ
for task in "test-coverage" "api-validation" "docs-update"; do
  branch=$(git -C "$WORKTREES_DIR/$task" rev-parse --abbrev-ref HEAD)
  
  echo "Merging $branch..."
  git -C "$PROJECT_DIR" merge --no-ff "$branch" \
    -m "Merge: agent/$task auto-generated changes"
  
  # 完了したworktreeを削除
  git -C "$PROJECT_DIR" worktree remove "$WORKTREES_DIR/$task"
  git -C "$PROJECT_DIR" branch -d "$branch"
done

# .github/workflows/auto-test-generation.yml
name: Auto Test Generation
 
on:
  pull_request:
    types: [opened]
    paths:
      - 'src/components/**'
      - 'src/api/**'
 
jobs:
  generate-tests:
    runs-on: ubuntu-latest
    # テストカバレッジが70%未満のファイルのみ対象
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Check coverage
        id: coverage-check
        run: |
          npx vitest coverage --reporter=json 2>/dev/null || true
          
          # カバレッジが低いファイルを特定
          LOW_COVERAGE_FILES=$(node -e "
            const report = require('./coverage/coverage-summary.json');
            const files = Object.entries(report)
              .filter(([file, data]) => 
                file \!== 'total' && 
                data.lines.pct < 70
              )
              .map(([file]) => file)
              .slice(0, 5); // 最大5ファイル
            console.log(files.join(','));
          ")
          echo "files=$LOW_COVERAGE_FILES" >> $GITHUB_OUTPUT
          
      - name: Trigger Background Agent for test generation
        if: steps.coverage-check.outputs.files \!= ''
        env:
          ANTIGRAVITY_API_KEY: ${{ secrets.ANTIGRAVITY_API_KEY }}
        run: |
          FILES="${{ steps.coverage-check.outputs.files }}"
          
          # Background Agent の起動（APIが利用可能な場合）
          curl -X POST "https://api.antigravity.google/v1/agents/background" \
            -H "Authorization: Bearer $ANTIGRAVITY_API_KEY" \
            -H "Content-Type: application/json" \
            -d "{
              \"task\": \"以下のファイルのテストカバレッジを80%以上に引き上げてください: $FILES\",
              \"branch\": \"${{ github.head_ref }}\",
              \"constraints\": [
                \"既存テストは変更しない\",
                \"vitestを使用\",
                \"TypeScriptエラーをゼロにする\"
              ]
            }"

# .github/workflows/auto-docs-update.yml
name: Auto Documentation Update
 
on:
  push:
    branches: [main]
    paths:
      - 'src/app/api/**'
 
jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
          
      - name: Detect API changes
        id: api-changes
        run: |
          # 変更されたAPIファイルを取得
          CHANGED=$(git diff HEAD~1 HEAD --name-only -- 'src/app/api/**' | head -10)
          echo "changed_files=$CHANGED" >> $GITHUB_OUTPUT
          
      - name: Update API documentation
        if: steps.api-changes.outputs.changed_files \!= ''
        env:
          ANTIGRAVITY_API_KEY: ${{ secrets.ANTIGRAVITY_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          CHANGED_FILES="${{ steps.api-changes.outputs.changed_files }}"
          
          # Background Agentに変更されたAPIのドキュメント更新を依頼
          echo "変更されたAPIファイル: $CHANGED_FILES"
          echo "Background AgentによるAPI仕様書更新を開始..."
          
          # 実装: docs/api/ 配下のMarkdownを自動更新
          # エラーハンドリング: 更新失敗時はSlack通知

## タスク：src/utils/ の型安全性改善
 
### 目標
`src/utils/` 配下の全ファイルで以下を達成してください：
- `any` 型の使用をゼロにする
- 明示的な型注釈を全関数に追加
- JSDocコメントを全エクスポート関数に追加
 
### 完了条件
1. `npx tsc --noEmit` でエラーゼロ
2. `any` 型が `grep -r "any" src/utils/` でゼロ件
3. 既存テストが全てパス
4. 各関数に@param/@returns のJSDocあり
 
### 対象外
- src/utils/legacy/ 配下（別途対応予定）
- テスト用のモックファイル

## タスク：通知設定ページの初期実装
 
### 目標
/settings/notifications ページの基本実装を作成してください。
デザインはMockup.pngを参考に（添付）。
 
### 実装範囲
- NotificationSettings コンポーネント
- 設定の保存/読み込み（Zustandストア）
- 4種類の通知タイプのトグルUI
 
### あえて実装しなくて良いもの
- 実際の通知送信ロジック（バックエンド未実装）
- アニメーション
- モバイル対応（後工程で対応）
 
### 完了条件
1. ページが表示される（エラーなし）
2. TypeScriptエラーゼロ
3. 各トグルのON/OFFがストアに反映される