Setup and context — Why Two Developers Get Different Results From the Same Tool
Developers using the same Antigravity installation can get dramatically different output quality. The difference almost always comes down to context.
Out of the box, Antigravity reads your code and builds a picture of the project's surface structure. But it doesn't automatically know your conventions, your forbidden patterns, your business rules, or the half-finished features in progress. Explicitly providing that information is what separates teams getting 70% correct suggestions from teams getting 95%.
Pillar 1: AGENTS.md — Your Project's Manual
What Is AGENTS.md?
AGENTS.md is a Markdown file placed at your project root. Antigravity reads it automatically when a session starts — it's the first thing the AI sees before any conversation begins. Think of it as "everything I'd want a new AI assistant to know before touching this codebase."
Template: A Complete AGENTS.md
# Project Overview
## About This Project
[Project name] is a [tech stack] application for [purpose].
Target users: [user description]
Scale: [DAU / MAU / team size]
## Tech Stack
- Frontend: Next.js 15 (App Router), TypeScript, Tailwind CSS
- Backend: Hono (Cloudflare Workers), Zod
- Database: Supabase (PostgreSQL), Drizzle ORM
- Auth: Supabase Auth
- Testing: Vitest, Playwright
## Directory Structure
src/
├── app/ # Next.js App Router pages
├── components/ # Reusable UI components
│ ├── ui/ # Primitives (Button, Input, etc.)
│ └── features/ # Feature-scoped components
├── hooks/ # Custom hooks
├── lib/ # Utilities and service layer
└── types/ # TypeScript type definitions
## Coding Conventions
- Components: PascalCase, one component per file
- Hooks: useXxx naming, placed in src/hooks/
- Error handling: use AppError from src/lib/errors.ts (never throw raw Error)
- API calls: use wrapper functions from src/lib/api.ts (never call fetch directly)
- State: TanStack Query for server state, useState for UI state
## Do Not
- Write fetch() anywhere outside src/app/
- Leave console.log in production code
- Use the any type (if unavoidable, add a comment explaining why)
## Current Development State
- Done: user auth, profile view, article list
- In progress: comments feature (src/features/comments/)
- Not started: notifications, followsPriority Order for What to Include
Must include (highest impact): Library versions (Next.js 15 vs 14 have different App Router behavior), project-specific patterns (your custom error handling, API wrappers), and forbidden patterns (anti-patterns your team has agreed to avoid).
Recommended (improves suggestion accuracy): Directory structure and responsibilities, where major type definitions live, and your testing strategy.
Optional (nice to have): Planned future features, performance and security requirements, business domain glossary.
Pillar 2: Knowledge Items — Detailed Reference Material
Concept
Knowledge Items are reusable context blocks managed in Antigravity's Manager Surface. Where AGENTS.md provides a project overview, Knowledge Items hold detailed reference information about specific topics — API specs, database schemas, business rules.
// Example Knowledge Item: "API Auth Spec"
/*
## Authentication Flow
All API requests require an Authorization header:
Authorization: Bearer {JWT_TOKEN}
### Get Token
POST /api/auth/login
Body: { email: string, password: string }
Response: { accessToken: string, refreshToken: string, expiresIn: number }
### Refresh Token
POST /api/auth/refresh
Body: { refreshToken: string }
Response: { accessToken: string, expiresIn: number }
### Error Codes
401: Token invalid or expired
403: Insufficient permissions
*/
// Use it with:
// "@API Auth Spec Implement auth in this API client"Effective Knowledge Item Organization
Knowledge Items structure:
├── API Specs/
│ ├── Auth Flow # JWT, OAuth details
│ ├── Error Codes # All error codes and handling
│ └── Rate Limits # Limits and retry strategy
│
├── UI Components/
│ ├── Design System # Colors, spacing, typography
│ ├── Animation Rules # Transition and timing standards
│ └── Accessibility # ARIA and keyboard requirements
│
├── Database/
│ ├── Schema Overview # Key tables and relations
│ ├── Query Patterns # Common Drizzle ORM patterns
│ └── Migration Policy
│
└── Business Logic/
├── Pricing Rules # Discount and tax calculation specs
└── Permission Model # Role and permission definitions
Pillar 3: Project Structure as Implicit Context
File and Directory Names as Silent Communication
Antigravity reads your folder structure and infers context from it. Consistent naming means the AI makes correct placement decisions without being told.
// ✅ Structure that communicates intent clearly
src/
├── features/
│ ├── auth/
│ │ ├── components/ # Auth UI components
│ │ ├── hooks/ # Auth-related hooks
│ │ ├── api.ts # Auth API calls
│ │ └── types.ts # Auth type definitions
│ └── comments/
│ ├── components/
│ ├── hooks/
│ ├── api.ts
│ └── types.ts
└── shared/
├── components/ui/ # Generic UI primitives
└── lib/ # Shared utilities
// With this structure, asking "add a hook for the comments feature that needs auth"
// causes Antigravity to automatically target src/features/comments/hooks/
// and reference src/features/auth/
Rich Type Definitions Improve Everything
// src/types/domain.ts — centralize domain types
export interface User {
id: string;
email: string;
displayName: string;
avatarUrl: string | null;
role: "admin" | "member" | "guest";
createdAt: Date;
updatedAt: Date;
}
export interface Article {
id: string;
title: string;
slug: string;
content: string;
authorId: string;
author?: User; // Optional relation
publishedAt: Date | null;
status: "draft" | "published" | "archived";
tags: string[];
}
export interface Comment {
id: string;
articleId: string;
authorId: string;
author?: User;
content: string;
createdAt: Date;
updatedAt: Date;
deletedAt: Date | null; // Soft delete
}
// Utility types
export type WithPagination<T> = {
items: T[];
total: number;
page: number;
perPage: number;
hasNext: boolean;
};Sharing Context Across a Team
Treating AGENTS.md as a Living Document
Keep AGENTS.md in version control (never .gitignore it) and review it in code review just like source code.
# AGENTS.md Update Guidelines
## When to update
- A new library is added
- A coding convention changes
- A new standard pattern is established (error handling, API wrappers, etc.)
- An architectural decision is made
## Process
1. Include AGENTS.md changes in the same PR as the code change
2. PR reviewers should review AGENTS.md changes just like source changes
## Monthly review
Once a month, the team discusses "cases where Antigravity's suggestions
were off-target" and adds the missing information to AGENTS.md.Documenting Team-Specific Patterns
Write your team's established patterns explicitly. This lets new team members use Antigravity effectively from day one.
## Common Patterns
### API error handling
```typescript
// Use apiClient from src/lib/api.ts
const { data, error } = await apiClient.get<User>(`/users/${id}`);
if (error) {
// error is AppError type
toast.error(error.userMessage);
return;
}
// data is fully typed hereForm validation
React Hook Form + Zod. Schemas go in src/lib/schemas/.
Dates
Use date-fns. moment.js is banned. Always display in JST.
---
## Rollout Plan: Improving Context Step by Step
**Week 1 (minimum viable):** Write project overview, tech stack, and directory structure in AGENTS.md. This alone cuts "suggestions using the wrong library" dramatically.
**Week 2 (medium):** Add coding conventions, forbidden patterns, and common patterns. Anything your team corrects in code review every week belongs here.
**Week 3 (full setup):** Create Knowledge Items for API specs, database schema, and business logic. Complex implementation tasks show the biggest accuracy improvement here.
**Month 2+ (continuous improvement):** Note cases where Antigravity suggestions were wrong. Run a monthly AGENTS.md update to patch those gaps.
---
## A Note from an Indie Developer
## Key Takeaways
Context design is the skill of knowing what to tell Antigravity before it starts working. `AGENTS.md`, Knowledge Items, and consistent project structure each contribute — but AGENTS.md's "Do Not" section often delivers the fastest return. It converts recurring code review comments into AI constraints, reducing the same mistakes from appearing repeatedly.
Start with a minimal AGENTS.md this week, and add to it whenever Antigravity's suggestions go off-track.
For more, see the AGENTS.md Usage Guide and [Daily AI Partner Workflow](/articles/tips/ai-partner-daily-workflow).