Antigravity Planning Mode — 大規模プロジェクトの AI 駆動設計戦略

大規模なコードベースの設計変更やアーキテクチャ刷新は、開発チーム最大の課題の一つです。10万行を超えるレガシーシステムのリファクタリング、新しいフレームワークへのマイグレーション、複数の マイクロサービスの統合――こうしたプロジェクトは、計画の失敗が直結して数週間の生産性低下につながります。

Antigravity の Planning Mode は、AI がコードベース全体を深く理解し、段階的で実行可能な実装計画を自動生成するツールです。ここでは大規模プロジェクトで Planning Mode を最大限に活用する戦略を、実践例を交えながら解説します。

Planning Mode とは

Planning Mode は、Antigravity エディタの高度なコンテキストエンジン機能です。従来の「コード生成」ツールとは異なり、Planning Mode は以下を実現します。

1. ディープコードベース分析

   • 全ファイルの依存関係グラフを構築
   • 関数呼び出しチェーンの追跡
   • アーキテクチャパターンの自動検出
   • 技術負債スポットの特定

2. 段階的計画生成

   • 実装の前提条件をトポロジカルソート
   • リスクレベルごとの分類
   • 各フェーズのテスト計画を同時生成
   • ロールバック手順の自動設計

3. チームレビュー対応

   • 計画を段階的に開示（Phase 1, 2, 3...）
   • リードエンジニアの修正提案を反映
   • 異議内容の自動ドキュメント化
   • 意思決定記録の保持

コンテキストエンジンのしくみ

Planning Mode の強力さは、そのコンテキストエンジンにあります。通常、LLM は 100KB 程度のコンテキストウィンドウしか持たないため、10万行のコードベースを一度に分析できません。しかし Antigravity のコンテキストエンジンは、以下の技術を組み合わせることで、超大規模コードベースを処理します。

1. 階層的要約（Hierarchical Summarization）

Raw codebase (100,000 lines)
        ↓
Module-level summaries (10 modules × 200 lines each)
        ↓
Layer summaries (Architecture, UI, API, Database)
        ↓
System summary (5,000 tokens)
        ↓
LLM planning prompt (8,000 tokens + 5,000 summary)

コンテキストエンジンは、各モジュール（src/components/, src/services/ など）を個別に解析し、簡潔な要約を生成します。次に、これらの要約から「アーキテクチャレイヤーの要約」を作成。最終的に、LLM に与えるプロンプトには、システム全体の意図を 5,000 トークン以下で圧縮した情報が含まれます。

2. 依存関係グラフの自動構築

// Planning Mode automatically constructs this graph
const dependencyGraph = {
  'src/pages/Dashboard.tsx': {
    imports: ['DataFetcher', 'ChartRenderer', 'useAuth'],
    imports_from: ['src/services/api', 'src/hooks/auth'],
    imported_by: ['src/pages/Admin.tsx']
  },
  'src/services/api.ts': {
    imports: ['axios', 'retry-logic'],
    calls: ['src/utils/transform', 'src/db/query'],
    called_by: ['src/pages/Dashboard.tsx', 'src/workers/background']
  }
};
 
// Identify circular dependencies
// Find dead code (modules with no inbound imports)
// Detect layer violations (UI layer calling database layer directly)

このグラフを基に、Planning Mode は「この機能をリファクタリングするには、まずこれを修正すべき」といった順序を自動判定します。

3. パターン認識

Planning Mode は、よくあるアーキテクチャアンチパターンを自動検出します。

Detected patterns:
✓ God class: BlogService (4,200 lines, 80+ methods)
✓ Circular import: UserModel ← AuthService ← UserModel
✓ Layer violation: pages/Dashboard directly uses db/raw-query
✓ Dead code: legacy/oldAuth.ts (imported by nothing, 800 lines)
✓ Duplication: 3 independent implementations of "dateFormat"
✓ Hidden coupling: 42 files hard-code database URL string

これらのパターンは、改善計画の優先度を決めるのに役立ちます。

大規模プロジェクトの Planning Mode ワークフロー

Phase 1: スコープ定義と現状分析

Planning Mode を起動する前に、まず「何を実現したいのか」を明確にします。

Input: リファクタリング目標
"我々のレガシー Next.js アプリ（95,000 行）を App Router に移行したい。
現在は Pages Router を使っており、150+ ページがある。
目標は8週間で完了し、本番トラフィックを遮断せずに実行する。
チームは5人。"

Planning Mode analysis output:

=== CODEBASE OVERVIEW ===
- Total lines: 95,432
- Pages Router: 152 pages
- Api routes: 48 endpoints
- Shared components: 340
- Total files: 1,893

=== MIGRATION COMPLEXITY ===
Risk level: HIGH
- Dynamic routes with catch-alls: 12 pages
- API middleware dependencies: 23 routes
- Server-side authentication hooks: 8 custom implementations
- Database queries in getServerSideProps: 45 instances
- External API polling in useEffect: 67 instances

=== RECOMMENDED PHASES ===
Phase 1 (Week 1-2): Setup & Low-Risk Pages (30 pages)
Phase 2 (Week 3-4): Dynamic Routes & API (45 pages + 32 endpoints)
Phase 3 (Week 5-6): Complex Features (23 pages with auth/polling)
Phase 4 (Week 7-8): Cutover & Monitoring

=== TECHNICAL DEBT TO ADDRESS ===
While migrating, fix these issues:
- Consolidate 3 duplicate dateFormat implementations
- Remove 12 unused utility files (800 lines total)
- Refactor UserContext provider (currently 600 lines)

このフェーズでは、Planning Mode は以下を出力します。

• 実装フェーズの最適な分割
• 各フェーズの並列実装可能性
• クリティカルパスの特定
• リスク領域の事前警告

Phase 2: 詳細計画の生成

Phase 1 で得られた分析を基に、詳細な実装計画を生成します。

PHASE 1 DETAILED PLAN (Week 1-2)

Task 1.1: Infrastructure Setup
  Goal: App Router 環境を本番環境と並行で準備

  Step 1.1.1: Create /app directory structure
    Files to create: 9
    Dependencies: None
    Estimated time: 2 hours
    Risk: LOW
    Test plan: Yarn build で新構造がエラーなくビルドされることを確認

  Step 1.1.2: Migrate shared middleware
    Files to modify: 5 (currently in /pages/api/_middleware.ts)
    Dependencies: Step 1.1.1
    Estimated time: 4 hours
    Risk: MEDIUM
      ⚠️ CAUTION: 23 API routes が このミドルウェアに依存
      Fallback plan: 旧 middleware をしばらく共存させる
    Test plan:
      - Unit tests: 15 cases
      - Integration tests: Auth flow, CORS, rate limiting

  Step 1.1.3: Setup environment variables & dotenv
    Files to create: 1
    Dependencies: Step 1.1.1
    Estimated time: 1 hour
    Risk: LOW

Task 1.2: Simple Page Migration (Batch 1)
  Target pages: home, about, pricing, blog (4 pages)
  Dependencies: Task 1.1

  Step 1.2.1: Migrate /pages/index.tsx → /app/page.tsx
    Changes:
      - Remove getStaticProps, add async server component
      - Update imports (next/router → next/navigation)
      - Inline static props
    Estimated time: 30 minutes
    Risk: LOW
    Test plan:
      - Visual regression (Playwright)
      - Performance comparison (Lighthouse)
    Rollback: Revert single file

  Step 1.2.2: Migrate /pages/about.tsx → /app/about/page.tsx
    Similar pattern, 25 minutes

  Step 1.2.3: Migrate /pages/pricing.tsx → /app/pricing/page.tsx
    Changes required: Stripe metadata update
    Estimated time: 45 minutes
    Risk: MEDIUM
    Test plan: Stripe test integration

  Step 1.2.4: Migrate /pages/blog/[...slug].tsx → /app/blog/[...slug]/page.tsx
    Dynamic route, requires custom generateStaticParams
    Estimated time: 1 hour
    Risk: MEDIUM
    Test plan: 50+ blog slug variations

Task 1.3: Testing & Validation
  Dependencies: Task 1.2

  Step 1.3.1: End-to-end tests
    E2E test count: 20
    Duration: 8 minutes

  Step 1.3.2: Performance benchmarks
    Lighthouse score comparison (old vs new)
    First Contentful Paint (FCP) regression tolerance: <5%

  Step 1.3.3: Canary deployment to staging
    Traffic: 100% (staging only)
    Monitor: 24 hours

Phase 3: チームレビュー・修正・反復

生成された計画は「提案」です。リードエンジニアや技術アーキテクトからのフィードバックを取り込みます。

Review session with team lead:

Lead: "Task 1.2.1 で getStaticProps の inlining をしていますが、
      毎回フルビルドを再実行しますね。その際の KV キャッシュの
      invalidation はどう扱いますか？"

Planning Mode adjustment:
  Step 1.2.1 に追記:
    - 旧 getStaticProps が KV cache を populate していた
    - 新しい app router では revalidateTag('blog-posts') で手動制御
    - ビルド時に revalidateTag を呼び出すステップを追加

  Updated time estimate: 30 min → 45 min

Lead: "Stripe の pricing page ですが、現在 Stripe CLI で
      local testing をしています。App Router では どう接続しますか？"

Planning Mode adjustment:
  Step 1.2.3 に統合テストシナリオ追加:
    - Stripe webhook のリッスン
    - Test mode でのエンドツーエンド流れ
    - Production sync (via Stripe Dashboard)

  Test plan 詳細化

このフェーズでは、Planning Mode が以下を実行します。

1. 異議内容の記録

   • "Lead said: Stripe KV cache invalidation"
   • "Resolution: Added revalidateTag step"

2. 計画の自動調整

   • 時間見積もりの更新
   • テスト項目の追加

3. ドキュメント化

   • Decision Log として記録

Phase 4: 段階的実装と並列進行

すべての Phase 1 タスクが Planning Mode の提案に沿って実装されます。

Week 1 Monday:
  Developer A: Task 1.1.1-1.1.2 (Infrastructure)
  Developer B: Task 1.2.1-1.2.2 (Simple pages)
  Developer C: Task 1.3 準備 (Test environments)

Week 1 Thursday (Status check):
  ✓ Task 1.1 complete (Infrastructure ready)
  ✓ Task 1.2.1, 1.2.2 complete (2 simple pages)
  ⚠️ Task 1.2.3 delayed (Stripe integration issue)
      Issue: Stripe webhook URL が new /app/webhooks route を認識していない
      Resolution: Stripe Dashboard の webhook URL を更新

Planning Mode auto-adjustment:
  - Task 1.2.3 の risk レベルを LOW → MEDIUM に上げる
  - Future phases で Stripe integration を早期に verify する
  - Rollback procedure をより詳細化

Week 2 Wednesday (Phase 1 complete):
  All Phase 1 tasks done
  Staging に 4 pages + infrastructure deployed
  Performance metrics: Baseline established

技術負債の定量分析と優先度付け

Planning Mode は、リファクタリング中に発見された技術負債を自動分析します。

=== TECHNICAL DEBT INVENTORY ===

Issue #1: God class - BlogService (4,200 lines)
  Classes: BlogService (methods: 87)
  Impact:
    - Modification risk: HIGH
    - Testing difficulty: 10+ hours per test
    - Cognitive load: 3+ weeks to fully understand
  Refactor effort: 40 hours
  ROI: High (future dev velocity +20%)
  Phase: 3 (after App Router migration basics)

Issue #2: Circular imports - Auth system
  Files: auth/context.ts ← auth/hooks.ts ← auth/context.ts
  Impact:
    - Build warnings
    - Future typescript strict mode incompatible
    - Hot reload issues
  Refactor effort: 6 hours
  ROI: Medium (removes build warnings)
  Phase: 1 (quick win)

Issue #3: Duplicate dateFormat implementations
  Locations: 3 separate files
  Total LOC: 280
  Impact: Maintenance burden, consistency risk
  Refactor effort: 2 hours
  ROI: Low (mostly cosmetic)
  Phase: 4 (final polish)

=== RECOMMENDED ORDER ===
1. Circular import fix (Phase 1, 6 hours)
2. App Router migration (Phase 1-4, main track)
3. God class refactoring (Phase 3, 40 hours)
4. Duplicate cleanup (Phase 4, 2 hours)

チーム開発での Planning Mode 活用

Planning Mode は、単一エンジニアだけでなく、チーム全体で活用できます。

Pattern 1: PR レビューの効率化

Pull Request: Refactor auth system (500+ line changes)
Reviewer A (Senior): "Planning Mode, approve? Changes seem large."

Planning Mode analysis on PR:
✓ Files touched: 8
✓ Functions modified: 14
✓ Cyclomatic complexity: decreased (12 → 9)
✓ Test coverage: increased (71% → 84%)
✗ Backward compatibility: Breaking changes in 2 exports
  Solution: Provide deprecation shim for old exports

Planning Mode verdict: "APPROVE with condition: Deprecation shim"

Pattern 2: マイグレーション計画のチェックポイント

Midpoint check (Week 4/8):

Planning Mode status:
- Phase 1-2 complete: ✓
- Phase 3 progress: 60% (on track)
- Phase 4 risk assessment: MEDIUM
  Why: User authentication changes in Phase 3
  Detection: 14 user-facing flows depend on auth changes

Recommendation:
  "Extend Phase 4 to 2 weeks. Add UAT (User Acceptance Testing).
   Current 7-day cutover is too aggressive."

Team decision: Extend timeline, approval from stakeholders documented.

大規模プロジェクトの実装チェックリスト

Planning Phase

• [ ] Planning Mode で全コードベース分析を実行
• [ ] 検出された tech debt 一覧をチームレビュー
• [ ] Phase 分割の妥当性をリードエンジニア承認
• [ ] 各 Phase の並列実装可能性を確認
• [ ] クリティカルパスをホワイトボードで可視化

Execution Phase

• [ ] Phase ごとに commit メッセージに phase ID を付与
• [ ] PR ごとに Planning Mode の expected changes と actual を比較
• [ ] 週 1 回のステータスレビュー（計画 vs 実績）
• [ ] Risk の early warning を Planning Mode から受け取ったら即座に対応
• [ ] Rollback procedure を Phase ごとに事前検証

Validation Phase

• [ ] 自動テスト（unit + integration + E2E）が Phase ごとに全てグリーン
• [ ] パフォーマンス回帰テスト（Lighthouse, Core Web Vitals）
• [ ] ユーザー受け入れテスト（主要フロー）
• [ ] セキュリティスキャン（新 API、新認証ロジック）

Deployment Phase

• [ ] Canary deployment (1% traffic, 24h)
• [ ] Staging での full soak test (48h+)
• [ ] Production monitoring dashboard 準備
• [ ] Rollback plan の team walkthrough
• [ ] オンコール体制の確認

全体を振り返って

Planning Mode は、大規模プロジェクトで AI がアーキテクトの役割を果たすための強力なツールです。以下の 3 つが Planning Mode の本質です。

1. ディープ理解: 10万行超のコードベースを即座に分析
2. 段階的計画: リスク・リソース・時間を考慮した実行可能な計画
3. チーム対応: レビュー・修正・決定記録を一元管理

これらを組み合わせることで、本来は数ヶ月かかる大規模リファクタリングを、計画的かつ安全に実行できます。ぜひ次のプロジェクトで試してみてください。