Antigravity × Monorepo Development Masterclass — Optimize AI Context in Nx & Turborepo Environments for Seamless Cross-Package Changes

Monorepo Structure and Antigravity's Pain Points

A typical monorepo layout

An Nx or Turborepo monorepo commonly looks like this:

my-monorepo/
├── apps/
│   ├── web/              # Next.js frontend
│   ├── mobile/           # React Native app
│   └── api/              # Node.js backend
├── packages/
│   ├── ui/               # Shared UI component library
│   ├── utils/            # Common utility functions
│   ├── types/            # Shared TypeScript types
│   └── config/           # Shared config (ESLint, TypeScript, etc.)
├── nx.json               # Nx config (or turbo.json)
├── package.json
└── AGENTS.md             # Root-level Antigravity config

Common Antigravity problems in monorepos

Problem 1: Context contamination. Antigravity defaults to pulling in the entire workspace as context. When editing apps/web, it may suggest types or functions from apps/api.

Problem 2: Import path confusion. Monorepos use package names like @my-org/ui or @my-org/utils. Without understanding the path resolution rules, Antigravity suggests relative imports or wrong paths.

Problem 3: Ignoring build dependencies. When you change packages/types, both apps/web and apps/api need updating. Without enough context, Antigravity misses this dependency graph entirely.

Step 1: Designing the Root AGENTS.md

The root AGENTS.md is the single most important file for conveying your monorepo's "blueprint" to Antigravity. Place it at the root, and use it to describe the overall structure, conventions, and hard rules.

# AGENTS.md (root level)
 
## Project structure
This is a Turborepo monorepo.
 
- apps/web: Next.js 16 App Router frontend (port 3000)
- apps/mobile: React Native 0.76 + Expo 52
- apps/api: Hono + Cloudflare Workers backend
- packages/ui: Shared component library (shadcn/ui based)
- packages/types: Shared TypeScript type definitions
- packages/utils: Common utility functions
 
## Package name resolution
Always use package names for imports — relative paths are forbidden.
- UI components: @my-org/ui
- Types: @my-org/types
- Utilities: @my-org/utils
 
## TypeScript configuration
Each tsconfig.json extends packages/config/tsconfig.base.json.
strict: true. The `any` type is forbidden.
 
## Coding conventions
- React components: function components + hooks only (no class components)
- State management: Zustand (Redux is banned)
- API client: use createApiClient from packages/utils
- Error handling: use Result type (packages/utils/result.ts)
 
## Change rules
When modifying packages/types, update all dependent apps/ code simultaneously.
When changing packages/ui component APIs, always create a migration guide.
 
## Forbidden
- console.log in production code (use logger.ts instead)
- The `any` type
- Creating files directly in packages/ root (always place inside the correct package)

Key principle: The root AGENTS.md acts as a "map." Detailed rules belong in per-package AGENTS.md files, keeping the root lean and focused.

Step 2: Per-Package AGENTS.md Design

Adding a dedicated AGENTS.md to each app and package lets the AI make accurate suggestions within that package's context.

# apps/web/AGENTS.md
 
## About this app
An e-commerce frontend built with Next.js 16 App Router.
 
## Routing structure
- app/(auth)/: Auth pages (login, register, password reset)
- app/(shop)/: Shop pages (product list, detail, cart, checkout)
- app/admin/: Admin panel (requires auth + admin role)
 
## Data fetching strategy
Always fetch data in Server Components — client-side fetching via useEffect is forbidden.
Caching: use next/cache unstable_cache.
Mutations: use Server Actions (API Routes are banned).
 
## Styling
- Tailwind CSS v4
- Import components from packages/ui
- Page-specific styles go in page.css alongside page.tsx
 
## Images and assets
- Always use next/image (raw img tags are banned)
- Add external image domains to next.config.ts images.remotePatterns

# packages/ui/AGENTS.md
 
## About this package
A shared component library based on shadcn/ui.
React 19 + TypeScript strict mode.
 
## Component creation rules
1. File names: kebab-case.tsx (e.g., button.tsx, user-card.tsx)
2. Component names: PascalCase
3. Props type: define as `interface ComponentNameProps` in the same file
4. Create a Storybook story at the same time (button.stories.tsx)
5. Add appropriate WAI-ARIA attributes for accessibility
 
## API stability
All exports from this package are depended on by every app.
For breaking changes:
1. Add the new API (mark old API as deprecated but keep it)
2. Update MIGRATION.md
3. Bump the major version
 
## Exports
Only export from src/index.ts.
Direct imports to individual files are forbidden.

Step 3: Cross-Package Refactoring with Antigravity

The true power of a monorepo is the ability to make safe, coordinated changes across multiple packages. With the right Antigravity setup, this work becomes dramatically faster.

Example: Adding a field to a shared type

Consider adding a new field to packages/types/src/user.ts.

// packages/types/src/user.ts (before)
export interface User {
  id: string
  email: string
  name: string
  createdAt: Date
}

Ask Antigravity:

Add a `role: 'admin' | 'member' | 'guest'` field to the User type.
After updating packages/types/src/user.ts,
identify all files in apps/ and packages/ that use this type
and propose the necessary updates.

Drawing on the AGENTS.md content, Antigravity traces the dependency graph and lists affected files. Always review the proposed changes yourself before applying them.

// packages/types/src/user.ts (after)
export interface User {
  id: string
  email: string
  name: string
  role: 'admin' | 'member' | 'guest'  // added
  createdAt: Date
}
 
// apps/api/src/auth/user.service.ts (Antigravity-suggested change)
const newUser: User = {
  id: crypto.randomUUID(),
  email,
  name,
  role: 'member',  // added default
  createdAt: new Date(),
}

Example: Safe UI component API change

When adding a loading prop to the Button component in packages/ui, here's an Antigravity-assisted migration workflow:

// packages/ui/src/button.tsx (after)
export interface ButtonProps {
  children: React.ReactNode
  variant?: 'primary' | 'secondary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  loading?: boolean        // new
  loadingText?: string     // new (falls back to children if omitted)
  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>
  )
}

Since loading is optional, this change is backward-compatible. Ask Antigravity to verify:

I've added a loading prop to packages/ui/src/button.tsx.
Please confirm this doesn't break any existing code in apps/,
and flag anything that needs attention.

Step 4: Optimizing Turborepo / Nx Build Pipelines with AI

Optimizing turbo.json

Turborepo's build pipeline is defined in turbo.json. Antigravity can analyze your current config and suggest improvements.

// turbo.json (before)
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "test": {
      "dependsOn": ["build"]
    },
    "lint": {}
  }
}

// turbo.json (after — Antigravity-optimized)
{
  "$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
    }
  }
}

Key improvements:

• The env field ensures cache is properly invalidated when environment variables change — a common source of stale-cache bugs
• test:unit and test:e2e are separated so you can run unit tests without triggering a full build
• type-check becomes a standalone, cached task that runs in parallel with lint, cutting CI time significantly
• dev uses persistent: true so Turborepo correctly handles long-running watch processes without marking them as stalled

Understanding cache keys in Turborepo

Turborepo's caching model is hash-based: it computes a cache key from your source files, environment variables, and task configuration. Understanding this model helps you make better decisions.

# See what Turborepo would hash for a given task
npx turbo run build --dry=json | jq '.tasks[].hashOfExternalDependencies'
 
# Force a cache miss (useful when debugging stale caches)
npx turbo run build --force
 
# Show why a task was a cache miss
npx turbo run build --verbosity=2

Ask Antigravity to interpret the output when cache behavior seems unexpected:

Here's the output from `turbo run build --verbosity=2`.
Why is the build for apps/web always a cache miss,
even when I haven't changed anything in that package?

GitHub Actions with Turborepo Remote Cache

# .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
 
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: 'npm'
 
      - 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 }}

Step 5: Antigravity with Nx

Optimizing nx.json

// 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"]
  }
}

Using Nx Generators with Antigravity

# Generate a new shared library
$ npx nx generate @nx/react:library feature-auth \
  --directory=libs/feature-auth \
  --importPath=@my-org/feature-auth \
  --bundler=vite \
  --unitTestRunner=vitest

After generation, ask Antigravity to review the scaffolded files and flag anything that should be customized to match your project's conventions. A typical prompt:

I just ran the nx generate command and it created these files: [list files].
Review them against our project's AGENTS.md conventions and tell me
what needs to be changed to match our patterns.

Running targeted tasks with Nx

One of Nx's most powerful features is the ability to run tasks for a specific project and all its dependencies:

# Build a specific app and everything it depends on
npx nx run web:build
 
# Test a specific package
npx nx run ui:test
 
# Run all tasks for affected projects only (great for CI)
npx nx affected -t build test lint
 
# Open the interactive dependency graph
npx nx graph

The dependency graph visualization is particularly useful to share with Antigravity when you want it to reason about the impact of a change:

I'm adding a new function to packages/utils.
Here's the current dependency graph: [paste graph output].
Which apps and packages will be affected by this change?
What do I need to update to keep everything working?

Step 6: Team AGENTS.md Governance

PR-based change management

Treat AGENTS.md changes like code — require PR reviews:

# .github/CODEOWNERS
AGENTS.md @team/tech-lead
apps/web/AGENTS.md @team/frontend-lead
apps/api/AGENTS.md @team/backend-lead
packages/*/AGENTS.md @team/platform

Templating per-package AGENTS.md

Manually writing AGENTS.md for every new package is tedious. Use Antigravity to scaffold them:

// 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
 
## About this package
${packageJson.description ?? '(Add a description)'}
 
## Responsibilities
- (List what this package does)
 
## API
- Only export from src/index.ts
- Maintain backward compatibility on type changes
 
## Dependencies
- Internal: (list @my-org/* packages used)
- External: (list key npm packages)
 
## Change notes
- (Add any special considerations when editing this package)
`
 
writeFileSync(resolve(packageDir, 'AGENTS.md'), template)
console.log(`✅ Created ${packageDir}/AGENTS.md`)

Step 7: Large-Scale Refactoring in Practice

Phased refactoring strategy

When undertaking a large refactor (e.g., migrating from Redux to Zustand), use this Antigravity-assisted workflow:

Phase 1: Impact analysis

Analyze the entire codebase and provide:
1. A list of all files using Redux
2. A frequency ranking of Redux actions and selectors
3. Patterns that need extra attention during a Zustand migration
4. A recommended migration order (low-impact to high-impact)

Phase 2: Migration plan

Based on the impact analysis, generate a structured migration plan:

## Redux → Zustand Migration Plan
 
### Phase 1 (Week 1): Shared utility prep
- Add Zustand factory helpers to packages/utils
- Convert Redux Store type definitions to Zustand-compatible format
 
### Phase 2 (Weeks 2–3): apps/web migration
- Migrate pages in order of lowest to highest impact
- Every PR must pass all tests before merging
 
### Phase 3 (Week 4): apps/mobile migration
- Follow the patterns established in the web migration
- Account for React Native-specific considerations
 
### Done criteria
- All tests pass
- Redux packages removed from package.json
- Bundle size equal or smaller

Step 8: Performance Profiling and Context Window Budgeting

How Antigravity's context window gets used in a monorepo

Understanding how Antigravity consumes your context window is key to maintaining both speed and accuracy in large codebases. In a monorepo, the context window pressure is much higher than in a single-package repo.

Every file that Antigravity reads counts against the context budget. In a monorepo with 500+ files across 10 packages, naive context loading can result in:

• Slower response times as the model processes more tokens
• Lower answer quality as older, less-relevant context gets pushed out
• Higher AI compute costs if you're on a usage-based plan

The solution is deliberate context budgeting.

Tier 1 — Always in context (root AGENTS.md): Your root AGENTS.md should be concise enough to fit comfortably in every context window — ideally under 200 lines. Think of it as a business card: enough to know who you're dealing with, not a full résumé.

Tier 2 — In context when working in a package (per-package AGENTS.md): When you're inside apps/web, Antigravity reads both the root AGENTS.md and apps/web/AGENTS.md. The per-package AGENTS.md can be more detailed since it's only loaded when relevant.

Tier 3 — Explicitly requested (using @mentions): For cross-package work, explicitly mention the relevant files with @packages/types/src/user.ts rather than expecting Antigravity to locate them automatically. This gives you precise control over what's included.

Tier 4 — Excluded (.antigravityignore): Everything that can be excluded, should be excluded. Here's a thorough .antigravityignore for a monorepo:

# Build outputs
.next/
dist/
build/
out/

# Dependencies
node_modules/
.turbo/
.nx/

# Test artifacts
coverage/
.nyc_output/

# Generated files
*.generated.ts
__generated__/
src/generated/

# Logs and temp files
*.log
*.lock
*.snap

# Storybook build
storybook-static/
.storybook/public/

# Environment files (never expose to AI)
.env*
!.env.example

# Large data files
*.csv
*.json.bz2
fixtures/large/

Measuring the impact of your context setup

You can benchmark Antigravity's response quality before and after optimizing your context setup using a simple repeatable test:

# Create a benchmark prompt file
cat > /tmp/antigravity-benchmark.md << 'EOF'
Task: Create a new UserProfile component in apps/web that:
1. Fetches user data from apps/api using the shared createApiClient from packages/utils
2. Uses the User type from packages/types
3. Renders with components from packages/ui
4. Follows all project conventions
 
Provide the complete implementation.
EOF

Run this prompt before and after your AGENTS.md setup, and compare:

• How accurately does it choose import paths?
• Does it suggest the right React patterns for this project?
• Does it avoid patterns your AGENTS.md explicitly forbids?

The difference is often striking — especially for the import path accuracy.

Step 9: Real-World Activation Patterns

Here are practical prompts you can use today to get value from the Antigravity × monorepo setup.

Pattern 1: Create a shared hook

Add a useDebounce hook to packages/utils that:
- Works with TypeScript strict mode
- Is compatible with React 19 Concurrent Mode
- Accepts a generic value type
- Has a delay parameter in ms (default: 300)
- Goes in packages/utils/src/hooks/use-debounce.ts
- Is exported from packages/utils/src/index.ts
- Comes with a Vitest unit test in the same directory

Pattern 2: Set up cross-app E2E testing

Set up a Playwright E2E test environment that can start both apps/web and apps/api simultaneously.
Add a test:e2e task to turbo.json.
Create an apps/e2e directory.
Write a basic test for the auth flow: login → view protected page → logout.

Pattern 3: Audit and update dependencies

Analyze the monorepo's dependencies and report:
1. Libraries used at different versions across packages
2. Packages that need security updates (use npm audit)
3. Deprecated packages with available replacements
4. Version inconsistencies worth resolving

Then propose a plan to update them starting from lowest-impact to highest.

Pattern 4: Move a component to the shared library

Migrate apps/web/src/components/Button.tsx to packages/ui.
- Follow packages/ui/AGENTS.md conventions (filename, export pattern)
- Update all existing imports within apps/web
- Create a Storybook story
- Confirm apps/web tests still pass after migration

For managing the multi-file changes this produces, see the Antigravity Diff View Complete Guide. For advanced context control techniques that complement AGENTS.md, see the Antigravity Editor Context Control Complete Guide. For tackling major architectural refactors, Advanced Large-Scale Refactoring in Antigravity Editor covers the full strategy.

Pattern 5: Standardize error handling across packages

Review all error handling in apps/api and identify places where raw errors are thrown
or where the error format differs from our Result type in packages/utils/result.ts.

Create a migration plan to standardize on the Result type, starting with the highest-risk
areas (auth, payments, data mutations).

For the first 3 cases, generate the refactored code.

Pattern 6: Generate a changelog from recent commits

Look at the git log for the past 2 weeks across all packages.
Generate a human-readable changelog organized by:
1. Breaking changes
2. New features
3. Bug fixes
4. Performance improvements
5. Internal / developer experience improvements

Format it as Markdown suitable for CHANGELOG.md.

Automated Code Review for Monorepos

PR templates with Antigravity

Combine GitHub PR templates with Antigravity to automate pre-review self-checks:

# .github/PULL_REQUEST_TEMPLATE.md
 
## What changed
<!-- Ask Antigravity to help fill this in -->
 
## Impact checklist (have Antigravity verify each)
- [ ] Modified packages/types → all dependent packages updated
- [ ] Changed packages/ui API → MIGRATION.md updated
- [ ] Added env variable → added to turbo.json env field
- [ ] Added external dependency → same version across all packages
- [ ] Changed DB schema → migration file created
 
## Testing
- [ ] Added or updated unit tests
- [ ] Manual verification of affected areas completed
- [ ] CI passes

Selective CI with affected packages

For large monorepos, running tests for unchanged packages every CI run wastes time and money:

# Test only affected packages (Turborepo)
npx turbo run test --filter=...[HEAD^1]
 
# Build only affected packages (Nx)
npx nx affected --target=build --base=origin/main

Ask Antigravity to optimize your CI config:

Review .github/workflows/ci.yml and optimize it to use
Turborepo's --filter flag for selective CI execution.
On PRs, test and build only changed packages and their dependents.
On pushes to main, run everything.

Step 9: Common Errors and Fixes

Error 1: TypeScript "package not found" errors that won't go away

The usual cause is paths not being properly inherited in each package's tsconfig.json.

// 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": "."
  }
}

Error 2: Turborepo cache used when it shouldn't be

If environment variables aren't listed in turbo.json's env field, changing them won't bust the cache:

{
  "tasks": {
    "build": {
      "env": ["NODE_ENV", "NEXT_PUBLIC_API_URL", "DATABASE_URL"]
    }
  }
}

Ask Antigravity: "Check whether any environment variables are missing from turbo.json and suggest what to add."

Error 3: Nx dependency graph not recognized correctly

If implicitDependencies isn't set in project.json, Nx may miss the dependency:

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

Error 4: Antigravity suggests wrong import paths even after AGENTS.md setup

This usually happens when the AGENTS.md doesn't explicitly state the full list of package names. Make your package name resolution rule unambiguous:

# In AGENTS.md — be explicit about every package
## Import rules
ALWAYS use these exact package names for imports. Never use relative paths between packages.
 
| Package directory       | Import as           |
|-|-|
| packages/ui             | @my-org/ui          |
| packages/types          | @my-org/types       |
| packages/utils          | @my-org/utils       |
| packages/config         | (internal only, not imported directly) |

Additionally, confirm that tsconfig.json's paths field aligns with these names. A mismatch between the two will confuse both TypeScript and Antigravity.

Error 5: CI runs full test suite despite --filter flag

If Turborepo's --filter=...[HEAD^1] isn't narrowing the scope as expected, check that:

• Your GitHub Actions workflow uses fetch-depth: 2 (not 1) so there's a comparison base
• The inputs field in turbo.json isn't overly broad (e.g., including {workspaceRoot}/** matches everything)
• You're on a branch that actually diverges from the base commit

# Debug: see which packages Turborepo considers "affected"
npx turbo run build --filter=...[HEAD^1] --dry=json | jq '.tasks[].taskId'

Step 10: Team Onboarding and Knowledge Sharing with Antigravity

One of the most underrated benefits of a well-configured Antigravity monorepo setup is how dramatically it shortens onboarding time for new team members. When your AGENTS.md files are thorough, a new developer can get Antigravity to act as a knowledgeable guide through the codebase from day one.

The "new team member" prompt pattern

Encourage new engineers to start with this kind of broad-context request:

I'm a new developer on this project. I've read the root AGENTS.md.
Can you give me a guided tour of the codebase? I'd like to understand:
1. The main data flow from the user's browser to the database and back
2. The most important shared abstractions in packages/
3. The areas of the codebase that are most actively developed right now
4. Common gotchas or things that aren't obvious from just reading the code

This produces a personalized orientation that a wiki page never quite matches, because Antigravity reads the actual current state of the code and synthesizes it with the AGENTS.md context you've provided.

Teaching Antigravity your team's vocabulary

Every team develops its own vocabulary — terms that mean specific things in the context of your product. Document these in AGENTS.md:

# Domain glossary (in AGENTS.md)
 
## Key concepts
- "Workspace": a top-level tenant in our multi-tenant system. A user can belong to multiple workspaces.
- "Member": a user who has accepted an invitation to a workspace. Different from a "User" (which is a global concept).
- "Project": a collection of tasks within a workspace. Not to be confused with the Nx "project" concept.
- "Activity feed": the real-time event stream displayed to members. Powered by Supabase Realtime.
- "Seat": a billable unit in our Stripe subscription. One seat = one member slot in a workspace.

When this vocabulary is in AGENTS.md, Antigravity's suggestions will use your team's language rather than generic names, which keeps generated code consistent with existing code.

Capturing architectural decisions

Architecture Decision Records (ADRs) are a great complement to AGENTS.md. Store them in docs/adr/ and reference the most impactful ones from AGENTS.md:

# In AGENTS.md
## Key architectural decisions
See docs/adr/ for the full record. The most important decisions for day-to-day development:
- ADR-003: Why we use Server Actions instead of API Routes (Next.js)
- ADR-007: Why we chose Zustand over Redux or Jotai
- ADR-012: The data fetching strategy (Server Components first, client-side as fallback)
- ADR-019: Why packages/types is the single source of truth (no backend-generated types)

Referencing ADRs from AGENTS.md gives Antigravity access to the "why" behind your conventions, not just the "what." This is especially powerful for complex constraints that might otherwise seem arbitrary.

Regular AGENTS.md reviews

Schedule a monthly "AGENTS.md audit" in your team calendar. The goal is to:

• Remove rules that are no longer relevant
• Add rules that have emerged from recent incidents or code reviews
• Clarify wording that's caused AI misunderstandings
• Check that new packages have their own AGENTS.md

Keep a brief changelog at the bottom of each AGENTS.md to track what changed and why:

# Changelog (in AGENTS.md)
## 2026-04-06
- Added rule forbidding console.log (caught in 3 PRs this month)
- Clarified createApiClient usage (was causing confusion with native fetch)
## 2026-03-15
- Initial version

Measuring ROI and Continuous Improvement

Tracking the impact of your Antigravity monorepo setup helps you justify the investment and identify areas for further improvement. Here are the metrics worth watching:

Developer experience metrics (qualitative):

• Ask team members to rate Antigravity suggestion accuracy on a 1-5 scale, once a week in a quick async check-in
• Track how often developers say "the AI got it wrong" in PR comments — this is a leading indicator that AGENTS.md needs updating

Development velocity metrics (quantitative):

• PR cycle time (open to merge): aim for a 15-20% reduction after 6 weeks of optimized AGENTS.md
• Time from task assignment to first commit: cross-package tasks should see the biggest improvement
• CI duration: track week-over-week after turbo.json optimization

Code quality metrics:

• "Type any" lint violations: should decrease as Antigravity stops suggesting any after you add the rule to AGENTS.md
• Import path violations: should drop to near zero after the path resolution rules are clearly stated
• Test coverage: often increases as Antigravity gets better at suggesting test files alongside implementations

A simple approach is to track these monthly in a shared doc, with a brief note on what AGENTS.md change (if any) coincided with a significant movement.

Step 12: Incremental Adoption Strategy

Retrofitting an existing monorepo

Apply these changes in priority order for maximum impact with minimum disruption:

Week 1: Create root AGENTS.md (highest priority)

If no AGENTS.md exists, use this prompt to generate a solid first draft:

Analyze this repository's package.json, tsconfig.json, turbo.json,
and key source files to understand the architecture, tech stack, and main conventions.
Then generate a draft AGENTS.md that gives Antigravity the best possible understanding
of this project.

Review the output and manually add team-specific knowledge (unwritten rules, historical decisions, things to avoid).

Week 2: Set up .antigravityignore

Exclude noise and improve context quality. Start conservative and adjust as needed.

Weeks 3–4: Add per-package AGENTS.md

Start with the most actively developed packages. Don't try to cover everything at once — prioritize packages your current sprint touches.

Month 2: Optimize build pipelines

Have Antigravity analyze your turbo.json or nx.json for cache strategy and parallelization improvements. Faster CI feedback improves development rhythm.

Step 14: Advanced Context Techniques for Monorepo Power Users

Once you've mastered the fundamentals, these advanced techniques will take your Antigravity monorepo workflow to the next level.

Using @-mentions to pull precise cross-package context

When working on a cross-package change, don't rely on Antigravity to automatically discover the relevant files. Use @-mentions to be explicit:

I need to add email notifications to the checkout flow.
@apps/api/src/orders/checkout.service.ts
@packages/types/src/order.ts
@packages/utils/src/email.ts

Looking at these files, what changes are needed to add an order confirmation email?
The email should be triggered after successful payment (after the Stripe webhook fires).
Propose a full implementation including the template structure.

By explicitly citing the three relevant files, you ensure Antigravity reasons from the actual current state of each package rather than a stale mental model.

Structured prompts for impact analysis

When you're unsure how far a change will ripple, use a structured impact analysis prompt:

I'm planning to [describe the change].

Please analyze the impact in three tiers:
1. DIRECT: Files I'll need to edit
2. INDIRECT: Files that depend on the directly edited files
3. POTENTIAL: Files that might be affected but need human judgment

For each tier, list the file paths and a one-line reason why they're affected.

This structured output is far more actionable than a free-form analysis and makes it easy to track which files you've updated as you work through the change.

Keeping AGENTS.md honest with periodic audits

The most common failure mode for AGENTS.md is drift — the rules describe how the codebase used to work rather than how it works now. An automated audit can catch this:

#!/bin/bash
# scripts/audit-agents-md.sh — run monthly via cron or CI
 
echo "=== AGENTS.md Drift Audit ==="
 
# Check if a rule about Zustand is still valid
if grep -r "useSelector\|useDispatch\|createSlice" --include="*.ts" --include="*.tsx" apps/ packages/ > /dev/null 2>&1; then
  echo "⚠️  Redux patterns detected — AGENTS.md says we use Zustand. Review needed."
fi
 
# Check if console.log is still forbidden
if grep -r "console.log" --include="*.ts" --include="*.tsx" apps/ packages/ | grep -v "node_modules\|.test\." > /dev/null 2>&1; then
  echo "⚠️  console.log found in production code — AGENTS.md says use logger.ts. Review needed."
fi
 
# Check if any type is explicitly forbidden
if grep -r ": any" --include="*.ts" --include="*.tsx" apps/ packages/ | grep -v "node_modules\|.test\." > /dev/null 2>&1; then
  echo "⚠️  'any' type found — AGENTS.md says strict: true with no 'any'. Review needed."
fi
 
echo "Audit complete."

Run this script monthly and share results with your team. If violations are consistently found, either update the codebase to match AGENTS.md, or update AGENTS.md to reflect the actual state — but never leave them out of sync.

Using Antigravity as an architecture advisor

As your monorepo grows, you'll face architectural decisions that have long-term consequences. Antigravity can serve as a sounding board, especially when you've given it solid AGENTS.md context:

We're seeing slow startup times in apps/web because packages/ui is doing heavy initialization.
I'm considering two approaches:
A) Lazy-load the heavy initialization in packages/ui using a React context + Suspense
B) Move the initialization to apps/web and pass it into packages/ui as a prop

Given our codebase (read the AGENTS.md for context), which approach would cause less
downstream impact? Are there other options I haven't considered?

This kind of architectural dialogue is where a well-configured Antigravity truly earns its premium value — it's not just writing code, it's helping you make better design decisions.

Summary

Monorepo development with Antigravity can feel like a mismatch without the right setup. But the patterns in this guide — AGENTS.md design, context optimization, cross-package workflows, and build pipeline tuning — deliver real productivity gains when put into practice.

Key takeaways:

• Use root AGENTS.md to give the AI a project-wide "map" and architectural understanding. Keep it concise — under 200 lines — so it fits comfortably in every context window.
• Use per-package AGENTS.md for detailed conventions, keeping context precise at the unit of work. These can be more detailed since they're only loaded when relevant.
• For cross-package changes, always ask Antigravity to analyze the impact first, then apply changes incrementally and verify after each step.
• Let Antigravity optimize turbo.json / nx.json to improve build speed and reduce CI costs — even small cache improvements compound significantly over time.
• Version-control AGENTS.md changes through PR review to keep the AI's knowledge current across the team. Treat AGENTS.md changes as seriously as API changes.
• Adopt incrementally — start with the root AGENTS.md alone and work outward. Even a 20-line AGENTS.md is better than none.
• Audit regularly — stale AGENTS.md actively misleads Antigravity. A monthly 15-minute review prevents drift.
• Use @-mentions for precise cross-package context rather than relying on automatic discovery in large codebases.

The complexity of monorepo development transforms into a "multiple brains working in parallel" experience when Antigravity is properly configured. The investment in AGENTS.md design, context optimization, and pipeline tuning pays dividends from the very first sprint — and continues to grow as your codebase scales. Start today with just the root AGENTS.md, and build from there.

Think of the process as an ongoing conversation between you and your AI editor. The clearer you are about your project's structure and conventions, the more accurately Antigravity can anticipate what you need. In a well-configured monorepo, Antigravity stops feeling like a generic code completion tool and starts feeling like a senior colleague who genuinely understands your codebase.

If you're new to managing multi-file changes in Antigravity, the Antigravity Diff View Complete Guide is a great starting point. For context-precision techniques that complement what we covered in AGENTS.md design, see the Antigravity Editor Context Control Complete Guide. And when you're ready to tackle major architectural refactors across your monorepo, Advanced Techniques for Large-Scale Refactoring in Antigravity Editor walks through the full strategy. It explores the relationship between team structure and system design in ways that directly apply to monorepo strategy.