Antigravity Planning Mode — AI-Driven Design Strategy for Large Projects

Large-scale codebase redesigns and architecture overhauls remain among the toughest challenges teams face. Refactoring legacy systems exceeding 100K lines, migrating to new frameworks, integrating multiple microservices—one planning mistake can translate directly into weeks of productivity loss.

Antigravity's Planning Mode is a tool where AI deeply understands your entire codebase and auto-generates stepwise, executable implementation plans. This guide walks you through strategies for maximizing Planning Mode in large projects, complete with real-world examples.

What is Planning Mode?

Planning Mode is an advanced context engine feature in the Antigravity editor. Unlike traditional "code generation" tools, Planning Mode delivers:

1. Deep Codebase Analysis

   • Automatic dependency graph construction
   • Function call chain tracing
   • Architecture pattern detection
   • Technical debt identification

2. Stepwise Plan Generation

   • Topological sorting of implementation prerequisites
   • Risk classification per phase
   • Concurrent test plans
   • Auto-designed rollback procedures

3. Team Review Integration

   • Plans revealed progressively (Phase 1, 2, 3...)
   • Lead engineer revisions reflected automatically
   • Objection content auto-documented
   • Decision records maintained

How the Context Engine Works

Planning Mode's power stems from its context engine. Standard LLMs can only handle ~100KB of context, making 100K-line codebases impossible to analyze whole. Antigravity's context engine combines techniques to handle massive codebases:

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)

The engine analyzes each module independently, generating concise summaries. It then creates "architecture layer summaries" from these. Finally, the LLM receives compressed system intent (~5,000 tokens).

2. Automatic Dependency Graph Construction

// 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 uses this graph to auto-determine: "To refactor this feature, fix this first."

3. Pattern Recognition

Planning Mode automatically detects common architecture anti-patterns:

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

These patterns inform refactoring priorities.

Large Project Planning Mode Workflow

Phase 1: Scope Definition and Current State Analysis

Before launching Planning Mode, clarify "what do we want to achieve?"

Input: Refactoring goal
"We have a legacy Next.js app (95,000 lines) on Pages Router.
150+ pages total. Goal: migrate to App Router in 8 weeks,
zero production downtime. Team of 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)

This phase outputs:

• Optimal phase splits
• Parallelization opportunities
• Critical path identification
• Risk areas flagged upfront

Phase 2: Detailed Plan Generation

Based on Phase 1 analysis, generate detailed implementation plans:

PHASE 1 DETAILED PLAN (Week 1-2)

Task 1.1: Infrastructure Setup
  Goal: Prepare App Router environment alongside production

  Step 1.1.1: Create /app directory structure
    Files to create: 9
    Dependencies: None
    Estimated time: 2 hours
    Risk: LOW
    Test plan: Verify `yarn build` succeeds with new structure

  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 depend on this middleware
      Fallback plan: Keep old middleware working in parallel
    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: Team Review, Revision, and Iteration

The generated plan is a "proposal." Incorporate feedback from lead engineers and architects:

Review session with team lead:

Lead: "In Task 1.2.1, you're inlining getStaticProps, but each rebuild
      triggers full recompilation. How do we handle KV cache invalidation?"

Planning Mode adjustment:
  Step 1.2.1 updated:
    - Old getStaticProps was populating KV cache
    - New app router uses revalidateTag('blog-posts') for manual control
    - Add step to call revalidateTag during build

  Updated time estimate: 30 min → 45 min

Lead: "The Stripe pricing page currently uses Stripe CLI for local testing.
      How do we handle this with App Router?"

Planning Mode adjustment:
  Step 1.2.3 integration scenarios enhanced:
    - Stripe webhook listening
    - Test mode end-to-end flow
    - Production sync (Stripe Dashboard)

  Test plan detailed

This phase:

1. Records objections
2. Auto-adjusts plans
3. Maintains decision logs

Phase 4: Stepwise Implementation with Parallelization

All Phase 1 tasks are implemented per Planning Mode's recommendations:

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 prep (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 not recognizing new /app/webhooks route
      Resolution: Update webhook URL in Stripe Dashboard

Planning Mode auto-adjustment:
  - Task 1.2.3 risk: LOW → MEDIUM
  - Future phases verify Stripe earlier
  - Rollback procedures more detailed

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

Quantitative Technical Debt Analysis and Prioritization

Planning Mode auto-analyzes technical debt discovered during refactoring:

=== 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 in Team Development

Pattern 1: PR Review Efficiency

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: Migration Checkpoints

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, stakeholder approval documented.

Large Project Implementation Checklist

Planning Phase

• [ ] Run full codebase analysis in Planning Mode
• [ ] Team reviews detected technical debt list
• [ ] Lead engineer approves phase splits
• [ ] Verify parallelization opportunities per phase
• [ ] Critical path visualization (whiteboard)

Execution Phase

• [ ] Prefix commit messages with phase ID
• [ ] Per-PR comparison: Planning Mode expected vs actual
• [ ] Weekly status reviews (plan vs actual)
• [ ] Act immediately on Planning Mode risk warnings
• [ ] Pre-validate rollback procedures per phase

Validation Phase

• [ ] Automated tests (unit + integration + E2E) green per phase
• [ ] Performance regression testing (Lighthouse, Core Web Vitals)
• [ ] User acceptance testing (critical flows)
• [ ] Security scanning (new APIs, new auth logic)

Deployment Phase

• [ ] Canary deployment (1% traffic, 24h)
• [ ] Full soak test in staging (48h+)
• [ ] Production monitoring dashboard ready
• [ ] Team walkthrough of rollback plan
• [ ] On-call coverage confirmed

Looking back

Planning Mode empowers AI to play the architect's role in large-scale projects. Its essence:

1. Deep Understanding: Analyze 100K+ line codebases instantly
2. Stepwise Planning: Executable plans considering risk, resources, time
3. Team Integration: Review, revision, and decision records unified

Combining these, you safely execute migrations that traditionally take months. Try it on your next large project.