Antigravity Best Practices

Overview

Master Antigravity with proven best practices from experienced users. This guide covers prompt engineering, workflow optimization, error handling, code quality, and team collaboration.

Table of Contents

1. Prompt Engineering
2. Workflow Optimization
3. Code Quality
4. MCP Integration
5. Error Handling
6. Performance
7. Security
8. Team Collaboration
9. Common Mistakes

Prompt Engineering

Be Specific and Detailed

Bad:

Create a form

Good:

Create a user registration form with:
- Fields: email, password, confirm password, name
- Validation: email format, password min 8 chars with 1 uppercase and 1 number
- Error messages displayed inline
- Submit button disabled until valid
- Loading state during submission
- Success toast notification
- Use React Hook Form + Zod
- shadcn/ui components

Specify Tech Stack

Bad:

Build a dashboard with charts

Good:

Build a dashboard using:
- Next.js 14 App Router
- Recharts (not Chart.js)
- Prisma + PostgreSQL
- TanStack Query for data fetching
- shadcn/ui components
Include revenue line chart, user bar chart, and metric cards

Include Constraints

Bad:

Add authentication

Good:

Add authentication with:
- Email/password only (no OAuth)
- JWT tokens (not sessions)
- Protected routes via middleware
- Token expiry: 7 days
- Refresh token rotation
- Rate limit: 5 login attempts per hour

Break Down Large Tasks

Instead of:

Build a complete e-commerce platform

Do this:

Phase 1: Build product catalog with:
- Product grid
- Search and filters
- Product detail page

Then:

Phase 2: Add shopping cart with:
- Add/remove items
- Quantity adjustment
- Persistent cart (localStorage)

Use Project Blueprints

Structure complex requests:

Goal: User authentication system

Stack:
- Next.js 14 App Router
- NextAuth.js v5
- Prisma + PostgreSQL

Steps:
1. Setup Prisma User model with email, password hash
2. Configure NextAuth with Credentials provider
3. Create login and register pages
4. Add protected route middleware
5. Create user session context

Constraints:
- Email/password only (no OAuth)
- Password hashing with bcrypt
- Email verification not required (Phase 2)
- Simple error messages (not detailed security info)

Workflow Optimization

Review Plans Before Proceeding

Always check implementation plans:

• Verify file structure
• Check tech stack choices
• Validate data models
• Review API endpoint design

Use comments to adjust:

"Use server actions instead of API routes"
"Add optimistic updates to the like button"
"Include loading skeletons for all components"

Leverage MCP Early

Connect integrations before starting:

Essential MCPs:

• Prisma: Schema awareness for database work
• GitHub: Pattern discovery and code search
• Linear: Automatic issue creation
• Netlify/Heroku: Deployment monitoring

Use the Right Model

Gemini 3 Pro (High)

• Complex architecture
• Large refactors
• New feature design

Gemini 3 Pro (Low)

• Simple CRUD operations
• Bug fixes
• Documentation updates

Claude Sonnet 4.5

• High code quality needed
• Complex business logic
• API design

Claude Sonnet 4.5 (Thinking)

• Debugging difficult issues
• Performance optimization
• Security analysis

Iterate in Phases

Don't request everything at once:

Phase 1: Core Functionality

Build basic task list with create, read, update, delete

Phase 2: Enhancements

Add categories, tags, due dates, and priority levels

Phase 3: Polish

Add drag-and-drop reordering, keyboard shortcuts, and export

Monitor Task Groups

Watch task groups execute:

• Expand details to understand what's happening
• Approve pending steps promptly
• Check file changes as they occur

Save Walkthroughs

After completion:

• Review the walkthrough artifact
• Copy important implementation notes
• Document any manual changes needed

Code Quality

Request Tests

Always include testing:

Build a user authentication system with:
[... requirements ...]

Include:
- Unit tests for auth functions
- Integration tests for API endpoints
- E2E tests for login flow
- Mock Prisma for testing
- Use Jest + React Testing Library

Ask for TypeScript

Specify type safety:

Use TypeScript with:
- Strict mode enabled
- No 'any' types
- Proper interface definitions
- Zod for runtime validation

Request Error Boundaries

Include:
- Error boundary for React components
- Global error handler for API routes
- User-friendly error messages
- Error logging (console in dev, Sentry in prod)

Demand Input Validation

Client-side:

Validate all form inputs with:
- Zod schemas
- React Hook Form integration
- Inline error messages
- Disabled submit until valid

Server-side:

Validate all API inputs with:
- Zod schemas
- Proper error responses
- SQL injection prevention (via Prisma)
- XSS protection

Ask for Loading States

Include loading states for:
- Initial data fetch (skeleton loaders)
- Button actions (spinner + disabled)
- Page navigation (progress bar)
- Infinite scroll (bottom spinner)

MCP Integration

Prisma Best Practices

Connect Prisma MCP before schema work

When extending schema:
- Ask agent to review existing models first
- Verify relation names match conventions
- Check for duplicate indexes
- Request migration review before applying

GitHub Integration

Connect GitHub MCP for:
- Searching codebase patterns
- Finding similar implementations
- Checking API usage examples
- Reviewing commit history

Example prompts:

"Search our GitHub repos for authentication implementations"
"Find examples of Stripe integration in our codebase"
"Show me how we've handled file uploads before"

Deployment Monitoring

Connect Netlify/Heroku MCP to:
- Monitor build logs during development
- Debug deployment errors
- Verify environment variables
- Check runtime logs

Error Handling

Standardize Error Responses

// Define error format once
type APIResponse<T> =
  | { success: true; data: T; message?: string }
  | { success: false; error: string; code: string; issues?: any[] }

// Use consistently across all endpoints

Use Custom Error Classes

class ValidationError extends Error {
  constructor(message: string, public issues: any[]) {
    super(message);
  }
}

class AuthenticationError extends Error {
  constructor() {
    super('Unauthorized');
  }
}

Log Errors Appropriately

Development:

console.error('Detailed error:', error.stack);

Production:

// Send to error tracking service
Sentry.captureException(error);
// Log minimal info to console
console.error('Error:', error.message);

Provide User-Friendly Messages

Bad:

Error: P2002: Unique constraint failed on fields: (`email`)

Good:

This email address is already registered. Please use a different email or log in.

Performance

Request Optimization

Prompt:

Optimize the user list page:
- Implement pagination (cursor-based)
- Add search debouncing (300ms)
- Use React Query with caching
- Add loading skeletons
- Lazy load images
- Virtualize long lists (react-virtual)

Database Optimization

Add indexes to Prisma schema for:
- Frequently queried fields (status, createdAt)
- Foreign keys
- Unique constraints
- Composite indexes for multi-field queries

Use Prisma query optimization:
- Select only needed fields
- Batch queries with findMany
- Use transactions for multiple operations

Image Optimization

Use Next.js Image component for:
- Automatic size optimization
- Lazy loading
- Blur placeholder
- WebP format conversion

Include:
- Responsive sizes
- Priority loading for above-fold images

Code Splitting

Implement code splitting:
- Dynamic imports for heavy components
- Route-based splitting (automatic in Next.js App Router)
- Lazy load modals and dialogs
- Split vendor chunks

Security

Never Skip Validation

Always validate:

Server-side validation for all inputs:
- API routes: Zod validation
- Database: Prisma type checking
- File uploads: size, type, malware scan

Implement Rate Limiting

Add rate limiting to:
- Authentication endpoints (5 attempts/hour)
- API routes (100 requests/hour per user)
- File uploads (10 files/hour)
- Password reset (3 requests/hour)

Sanitize User Input

Sanitize all user-generated content:
- Strip HTML tags (unless rich text editor)
- Escape SQL (use Prisma, never raw queries)
- Validate URLs before redirects
- Check file types on upload

Secure Authentication

Authentication requirements:
- HTTPS only (no HTTP)
- Secure cookie flags (httpOnly, secure, sameSite)
- CSRF protection
- Password hashing (bcrypt, min 10 rounds)
- JWT secret from environment variables

Environment Variables

Prompt:

Use environment variables for:
- Database URLs
- API keys
- JWT secrets
- Third-party service keys

Never hardcode sensitive data
Create .env.example with dummy values
Add .env to .gitignore

Team Collaboration

Use Consistent Patterns

Establish conventions:

File structure conventions:
- Components in /components
- Server actions in /app/actions
- API routes in /app/api
- Utils in /lib
- Types in /types

Naming conventions:
- Components: PascalCase (UserProfile.tsx)
- Functions: camelCase (getUserById)
- Constants: UPPER_SNAKE_CASE (MAX_FILE_SIZE)

Document Generated Code

Request documentation:

Add JSDoc comments to:
- All exported functions
- Complex logic
- API endpoints
- Reusable components

Include:
- Description
- Parameters with types
- Return value
- Examples
- Edge cases

Version Control

Git best practices:

Before committing Antigravity-generated code:
1. Review all changes thoroughly
2. Run linting and type checks
3. Run test suite
4. Test manually in browser
5. Write descriptive commit messages

Commit message format:
feat: Add user authentication with NextAuth
- Email/password login
- Protected routes
- Session management

Code Reviews

What to check:

• [ ] Code follows project conventions
• [ ] No security vulnerabilities
• [ ] Error handling comprehensive
• [ ] Tests included and passing
• [ ] TypeScript types correct
• [ ] No console.logs in production code
• [ ] Performance acceptable

Common Mistakes

1. Vague Prompts

Mistake:

"Add a form"

Why it's bad: Agent makes assumptions about fields, validation, styling

Fix: Specify all requirements explicitly

2. Skipping Plan Review

Mistake: Clicking "Proceed" without reading the plan

Why it's bad: May use wrong tech stack, incorrect architecture, or miss requirements

Fix: Always review plans, add comments if adjustments needed

3. Not Connecting MCP

Mistake: Working on database schema without Prisma MCP

Why it's bad: Agent can't see existing models, may create conflicts

Fix: Connect relevant MCPs before starting

4. Requesting Too Much

Mistake:

Build a complete social network with posts, comments, likes, follows, messages, notifications, etc.

Why it's bad: Overwhelming, hard to review, likely errors

Fix: Break into phases, tackle one feature at a time

5. Ignoring Validation

Mistake: Accepting code without input validation

Why it's bad: Security vulnerabilities, data corruption

Fix: Always request validation with Zod schemas

6. No Error Handling

Mistake: Not requesting error handling

Why it's bad: App crashes, poor user experience

Fix: Explicitly request comprehensive error handling

7. Missing Loading States

Mistake: Forgetting to request loading indicators

Why it's bad: App feels broken, users confused

Fix: Always request loading states for async operations

8. Hardcoding Values

Mistake: Accepting hardcoded API keys or URLs

Why it's bad: Security risk, not portable

Fix: Request environment variables for all config

9. No Testing

Mistake: Not requesting tests

Why it's bad: Bugs in production, hard to refactor

Fix: Always include test requirements in prompt

10. Poor TypeScript

Mistake: Accepting 'any' types

Why it's bad: Loses type safety benefits

Fix: Request strict TypeScript with no 'any'

Prompt Templates

Feature Request

Build [feature name] with:

Requirements:
- [Specific requirement 1]
- [Specific requirement 2]
- [Specific requirement 3]

Tech Stack:
- [Framework]
- [Database]
- [UI library]
- [Other tools]

Data Models:
[Model name] {
  [field]: [type]
  ...
}

Validation:
- [Field]: [rules]
- [Field]: [rules]

Design:
- [Visual requirement]
- [Responsive requirement]
- [Accessibility requirement]

Include:
- Unit tests
- Error handling
- Loading states
- TypeScript types

Bug Fix

Fix the following bug:

Issue:
[Describe the problem]

Expected Behavior:
[What should happen]

Current Behavior:
[What actually happens]

Reproduction Steps:
1. [Step 1]
2. [Step 2]
3. [Step 3]

Error Message:
[Copy exact error if available]

Relevant Files:
- [File path 1]
- [File path 2]

Refactoring

Refactor [component/function/module] to:

Goals:
- [Improvement goal 1]
- [Improvement goal 2]

Requirements:
- Maintain existing functionality
- Add unit tests
- Improve performance by [metric]
- Follow [pattern/principle]

Do NOT change:
- [Preserve API compatibility]
- [Keep existing behavior]

Advanced Tips

1. Chain Conversations

Build incrementally:

Conversation 1: "Build basic task list"
[Review, test, commit]

Conversation 2: "Add categories to tasks"
[Review, test, commit]

Conversation 3: "Add drag-and-drop reordering"
[Review, test, commit]

2. Use Artifacts Effectively

• Implementation Plans: Comment with detailed feedback
• Task Lists: Monitor progress, understand agent's approach
• Walkthroughs: Save as documentation, reference later

3. Experiment with Models

Try different models for same task:

• Compare code quality
• Check approach differences
• Find best model for your use cases

4. Build a Prompt Library

Save successful prompts:

• Create prompts folder in workspace
• Document what works well
• Reuse and adapt for similar tasks

5. Learn from Failures

When agent produces incorrect code:

• Analyze what went wrong
• Improve prompt specificity
• Add constraints to prevent recurrence
• Document learnings

Checklist: Before Clicking "Proceed"

• [ ] Tech stack matches requirements
• [ ] Data models include all fields
• [ ] Relations are correct (one-to-many, many-to-many)
• [ ] API endpoints cover all CRUD operations
• [ ] Validation included (client and server)
• [ ] Error handling comprehensive
• [ ] Loading states for async operations
• [ ] TypeScript types proper
• [ ] File structure makes sense
• [ ] No security vulnerabilities visible

Checklist: Before Committing Generated Code

• [ ] Code reviewed line by line
• [ ] All features tested manually
• [ ] Test suite passes
• [ ] TypeScript compiles without errors
• [ ] ESLint passes
• [ ] No console.logs remaining
• [ ] Environment variables configured
• [ ] Dependencies installed correctly
• [ ] Database migrations applied
• [ ] Code follows project conventions

Resources

• Antigravity Documentation
• Example Projects
• Community Discord
• GitHub Discussions

Next Steps

Apply these best practices:

1. Try Examples: Antigravity Projects Examples
2. Build Dashboard: How to Build a Dashboard
3. Learn CRUD: How to Build CRUD with Antigravity
4. Compare Tools: Antigravity vs Cursor vs Windsurf

Conclusion

Following these best practices will help you:

• Get better results from Antigravity
• Avoid common pitfalls
• Produce production-quality code
• Accelerate development workflow

Master prompt engineering, leverage MCPs, review plans carefully, and iterate in phases for the best experience.

---

Keywords: antigravity tips, antigravity best practices, antigravity how to avoid mistakes, antigravity prompt engineering, antigravity workflow, antigravity guide