You've set up an Antigravity agent, given it a task, and watched it confidently do the wrong thing. Maybe it refactored files you didn't ask it to touch. Maybe it chose a technical approach that contradicts your project's conventions. Maybe it made assumptions that seemed reasonable in isolation but missed the point entirely.
This is one of the most common agent frustrations—and in most cases, it's not a bug. It's a communication problem. This guide walks through the root causes and practical fixes.
Why Agents Misunderstand Instructions
There are five common reasons an agent ends up off-track:
① Instructions are too vague Phrases like "make it better" or "clean this up" leave too much interpretation room. The agent will make a call, but it may not be your call.
② Tasks are too large "Refactor the entire app" gives the agent no clear boundary for where to start or stop. Large scopes invite scope creep into areas you didn't intend to change.
③ Context is missing The agent doesn't know your constraints unless you tell it. Without knowing what to preserve, what to avoid, or why the task matters, the agent is reasoning from incomplete information.
④ agents.md is underdeveloped
Antigravity uses the agents.md file at your project root to provide the agent with persistent context. A sparse agents.md means the agent rediscovers your project's rules from scratch every session.
⑤ Wrong mode for the task Using Fast mode for complex decisions, or Planning mode for routine changes, can lead to behavior that doesn't match your expectations.
Fix 1: Build a Solid agents.md
The agents.md file is the most direct lever you have for improving agent behavior across all tasks. A well-written one functions like onboarding documentation for a new developer—the more complete it is, the less guesswork the agent has to do.
A working agents.md template
# Project: [Project Name]
## What This Project Is
[Brief description of what you're building and the tech stack]
## Rules the Agent Must Follow
- Never modify files in [list protected paths]
- Always follow [naming convention / code style]
- Do not introduce [library / pattern] under any circumstances
- When in doubt, ask before proceeding—do not guess
## How to Run and Test
- Development server: [command]
- Run tests: [command]
- Build: [command]
## Key Constraints
- Production environment: [description]
- Dependencies: [anything unusual or locked to specific versions]
- Known fragile areas: [files or systems that require extra care]What people typically leave out The most common omission is the prohibition list—what the agent should not do. Without it, the agent may optimize something you didn't want touched. Adding a "when in doubt, ask" rule is also high-value: it prevents the agent from bulldozing through an ambiguous situation without checking.
Fix 2: Reduce Task Scope
The ideal agent task has one to two concrete actions. Larger tasks should be broken into a sequence of smaller ones, confirmed at each step.
Before (too broad) "Implement a user authentication system."
After (appropriately scoped)
Step 1: "Create src/auth/AuthContext.tsx. It should support Google login and email/password login and export an AuthProvider and useAuth hook."
Step 2 (after reviewing Step 1): "Create src/hooks/useAuth.ts with three methods: login, logout, and getUser. Import from AuthContext."
Step 3 (after reviewing Step 2): "Create src/components/LoginForm.tsx that uses the useAuth hook. Mirror the layout in src/components/SignupForm.tsx for visual consistency."
This structure keeps each step reviewable and lets you catch misalignments early.
Fix 3: Add Background and Constraints to Every Instruction
A complete instruction answers three questions: what to do, why it matters, and what to avoid. Most instructions only answer the first.
Before "Improve performance."
After
"Users have reported slow image loading on the gallery page. Add lazy loading to src/components/ImageGallery.tsx using the Intersection Observer API (no new third-party packages). The existing tests in ImageGallery.test.tsx must continue to pass."
The improved version specifies the file, the approach, the constraint on dependencies, and the success condition. None of that is obvious without being told.
Fix 4: Use Checkpoints to Validate Direction Early
Antigravity's Checkpoint feature saves the working state of your project at key moments, letting you restore if the agent goes off in the wrong direction.
Before starting any non-trivial task, ask the agent to describe its plan before executing: "Tell me what changes you plan to make before making them." This surfaces misalignments before any code is touched, and costs nothing if the plan is correct.
If the agent does go off-course, rolling back to a Checkpoint gets you to a clean state quickly without manual reversions.
Fix 5: Choose the Right Mode
Planning mode is the right choice for tasks that require judgment: deciding between architectural approaches, refactoring that touches many files, or implementing a new feature from a rough specification. The agent drafts a plan and waits for approval before acting.
Fast mode works well for bounded, well-defined work: adding tests to an existing function, updating a configuration file, or fixing a specific bug with clear reproduction steps.
Applying Fast mode to ambiguous tasks is the most common mode mismatch. The agent picks a direction and runs with it—which is great when the direction is obvious, and frustrating when it isn't.
When Things Go Sideways: Reset and Restart
If the agent is already heading in the wrong direction:
Stop the agent with Ctrl+C or the Stop button in the UI. Restore from the most recent Checkpoint to get back to a clean state. Update agents.md with whatever rule would have prevented the problem. Break the task into smaller steps and start again.
Looking back
Most agent instruction failures come from one of three things: instructions that lack specificity, tasks that are too large, or an agents.md that doesn't reflect your project's actual constraints. None of these require code changes to fix.
Make instructions concrete—specify the target file, the approach, and what to avoid. Break tasks into steps and review between them. Build up agents.md over time as a record of everything the agent needs to know about your project.
The agent gets better at understanding your project the more context you give it. Each improvement to agents.md compounds across every future task.