Best Practices
Antigravity amplifies your engineering — but it amplifies bad habits as well as good ones. These practices come from real usage patterns: what produces clean, reviewable, shippable code versus what produces a mess you spend hours unwinding. This module covers production patterns, cost management, agent design principles, error handling, monitoring, and security in depth.
The practices in this module are not theoretical — they are distilled from the first two months of Antigravity's public preview, during which thousands of developers experimented with the tool across projects ranging from hobby apps to multi-service backends. The patterns that follow are the ones that consistently produced good outcomes. The anti-patterns are the ones that consistently produced pain.
If you only remember three things from this module, remember these: (1) Task description quality is the single biggest factor in agent output quality. (2) Always review diffs — never batch-accept. (3) Commit immediately after accepting each diff. Everything else is refinement around these three core habits.
The Three Pillars of Effective Agent Use
Every effective Antigravity workflow rests on three pillars. Master all three and you will ship faster with higher quality. Neglect any one and the tool becomes a liability:
Precise Task Specification
The quality of the agent's output is directly proportional to the quality of your task description. Vague tasks produce vague solutions. Specific tasks — with file names, function names, expected behaviour — produce targeted, correct changes.
Think of task descriptions as engineering tickets, not chat messages. Include: what to change, where it lives, what the current behaviour is, what the expected behaviour should be, what constraints apply, and what tests to write. The more precise you are, the less the agent has to infer — and inference is where mistakes happen.
One Concern Per Agent
Resist the temptation to bundle multiple unrelated changes into a single task. A focused agent produces a focused diff that is easy to review. A sprawling agent produces a sprawling diff that is hard to trust.
The rule of thumb: if you cannot describe the task in a single sentence that a colleague would understand, it is too broad. Split it into multiple agents. "Fix the checkout null reference on empty cart" is one concern. "Fix the checkout bug and also update the returns API and add the new promo code feature" is three concerns — dispatch three agents.
Rigorous Diff Review
Multi-agent does not mean less review — it means more concurrent review. An agent can be individually correct but introduce a change that conflicts with another agent's output. You are the integration layer.
Review agent diffs with the same discipline you would apply to a colleague's pull request: Does it solve the stated problem? Does it introduce unexpected side effects? Are edge cases handled? Are there tests? Is the code readable and maintainable? Would you approve this PR from a human?
Agent Design Principles
Designing good agent tasks is itself a skill — and like all skills, it improves with practice. The difference between a developer who gets 50% accept rate and one who gets 85% almost always comes down to how they write task descriptions. These five principles, applied consistently, produce dramatically better results:
Name the Artifacts
Always specify the exact file paths, function names, and class names involved. Do not say "fix the bug in the checkout" — say "In api/checkout.py, the calculate_total() function returns None when the cart is empty (line ~84). It should return 0.00 instead." Named artifacts eliminate ambiguity and produce surgical diffs.
State the Acceptance Criteria
Tell the agent how to verify its own work: "After the fix, pytest tests/test_checkout.py should pass, including the existing test_empty_cart_total test." When the agent knows the acceptance criteria, it can self-verify and iterate without waiting for your review.
Provide Constraints, Not Implementation Details
Tell the agent what the boundaries are, not how to implement. "Do not change the public API signature" is a constraint. "Use an if-else statement" is an implementation detail. Agents produce better code when they have freedom to choose the approach within your constraints.
Include Context the Agent Cannot Infer
If there is domain knowledge the agent needs — business rules, team conventions, historical decisions — include it in the task description. "We use whole-order returns only (no partial returns) — this is a business decision, not a technical limitation" gives the agent context it cannot derive from the code alone.
Request Tests Explicitly
Agents do not always write tests unless asked. Always include: "Write tests for this change in [specific test file]. Cover: the happy path, the error case, and the edge case where [specific condition]." Being explicit about test expectations produces meaningful coverage, not token tests.
Good vs Poor Task Descriptions
Production Patterns
Teams using Antigravity in production (or production-like) workflows have converged on several patterns that reliably produce good results. These patterns are not unique to Antigravity — they are the habits of effective engineering adapted for an agent-first workflow. The tool changes; the discipline does not.
The common thread across all production patterns is rigour. Agents are fast but not infallible. Production quality comes from the human processes wrapped around agent output: clear specifications going in, thorough review coming out, and clean commits at the end. Speed without rigour produces technical debt faster than any human developer ever could.
The Sprint Batch
At the start of a sprint, write agent-ready task descriptions for all well-defined tickets. During development, dispatch agents for these pre-written tasks, 2-3 at a time. Review diffs as they arrive. This turns sprint execution from "write code for 10 days" into "review and integrate agent output for 10 days" — dramatically increasing throughput.
The Review Gate
Never accept a diff without verifying: (1) the code change matches the task description, (2) tests pass (check the test report artifact), (3) the diff does not touch files outside the stated scope, (4) no debugging code was left in (console.log, print statements). Create a mental checklist and apply it to every agent diff.
The Commit Convention
Commit accepted diffs immediately with a clear message that attributes the change: fix: checkout null on empty cart (agent-assisted). The "(agent-assisted)" suffix helps the team understand which changes were agent-generated during code review. Never batch multiple agent diffs into a single commit — each diff gets its own commit.
The Feedback Loop
When an agent produces poor output, do not just reject and move on. Read the timeline, identify where the agent went wrong, and improve the task description or .antigravity conventions. Every failed agent run is a learning opportunity. Over time, your task descriptions get more precise and agent output gets consistently better.
Cost Management
During Antigravity's free preview, cost is not a concern. But when production pricing launches, these patterns will help you manage spend:
| Strategy | Detail | Estimated Savings |
|---|---|---|
| Use the cheapest model that works | Start with Gemini 3 Pro (free/cheapest). Only use Claude Sonnet 4.6 for complex reasoning tasks. Do not default to the most expensive model. | 50-70% on model costs |
| Write precise tasks | Precise tasks resolve in fewer iterations. An agent that iterates 5 times consumes 5x the tokens of one that gets it right the first time. | 30-60% on token usage |
| Scope tasks narrowly | A task that touches 3 files uses less context than one that touches 20 files. The agent only needs to load relevant context, not the entire codebase. | 20-40% on context tokens |
| Use Plan-Only mode for experiments | If you are not sure how the agent will approach a task, use Plan-Only mode first. Reviewing a plan is much cheaper than executing a full task and then rejecting the result. | 80-90% on exploratory tasks |
| Monitor token usage per agent | Check the timeline token summary after each task. If an agent consumed more than expected, investigate — the task may have been too broad or the agent may have looped. | Varies |
A well-specified bug fix on a single file typically consumes 10K-30K tokens. A feature that touches 3-5 files consumes 50K-100K tokens. A broad, vague task can consume 200K+ tokens and still produce poor output. The relationship between task precision and token efficiency is nearly linear — precise tasks cost less and produce better results.
The Antigravity Workflow Loop
The core workflow in Antigravity is a five-step loop that repeats for every task. Internalise this loop and it becomes second nature within a few days. Each step is equally important — skipping any one of them degrades the quality of the outcome:
Write a precise task
Name the file, the function, the expected behaviour, and any constraints (e.g. "don't change the public API"). The more specific you are, the less the agent has to infer. Use the task template from Module 36 as a starting point.
Dispatch — then do other work
While the agent runs, write the next task description, review a design document, or dispatch a second agent on an unrelated problem. Antigravity is designed for parallelism — use it. A common mistake is watching the agent's timeline instead of doing productive work. Trust the process.
Answer clarifications promptly
If an agent surfaces a question in the Manager Surface, answer it quickly. A blocked agent is a wasted thread. Keep an eye on the agent list — WAITING status means it needs you. Consider keeping the Manager Surface open in a split view.
Review the diff with intent
Read the diff as you would a colleague's PR. Look for: does it solve the stated problem? Does it introduce anything unexpected? Does it have tests? Are there hardcoded values that should be configurable? Is error handling present? Reject and redirect if the diff does not meet your standards.
Accept and commit immediately
Accept the diff and commit with a message that attributes the change. git commit -m "fix: checkout null on empty cart (agent-assisted)". Do not batch accepted diffs — commit each one cleanly. This keeps your git history traceable and makes it easy to revert a specific agent's contribution.
Error Handling and Recovery
Agents fail. They misunderstand tasks, produce buggy code, get stuck in loops, and sometimes crash. Here is how to handle each failure mode:
| Failure Mode | Symptoms | Root Cause | Recovery |
|---|---|---|---|
| Wrong file modified | Diff touches unexpected files | Task description did not name the target file | Reject the diff. Re-dispatch with explicit file paths. |
| Infinite iteration loop | Agent runs for 10+ minutes, progress bar oscillates | Test failure the agent cannot fix; conflicting constraints | Pause the agent (Ctrl+P). Read the timeline. Add a steering instruction or cancel and re-dispatch with clearer constraints. |
| Tests pass but code is wrong | Diff accepted, but behaviour is incorrect | Tests were too weak or tested the wrong thing | Revert the commit. Re-dispatch with stronger test criteria. Consider writing the test assertions yourself and having the agent write only the implementation. |
| Agent crashes (FAILED status) | Red badge in agent list, error log in timeline | Usually a model API timeout or context overflow | Read the error log. If timeout, retry. If context overflow, break the task into smaller pieces. |
| Merge conflict on accept | Conflict markers shown during diff acceptance | Two agents modified overlapping code | Resolve the conflict manually, then run tests to verify the merged result. |
| Subtle regression | New feature works, but existing feature breaks | Agent's change had unexpected side effects | Revert the commit. Re-dispatch with an explicit constraint: "Do not change the behaviour of [existing function]." |
The most important error-handling habit is speed. When you detect that an accepted agent diff introduced a problem, revert immediately. Do not spend 30 minutes trying to manually fix agent-generated code. A clean revert takes 10 seconds. A manual fix in unfamiliar agent-generated code takes unpredictable time and may introduce new issues. Revert, learn from the timeline, improve the task, and re-dispatch.
The single most important recovery skill is fast, confident reverting. When an accepted agent diff causes problems, revert it immediately. Do not spend time trying to manually fix agent-generated code that went wrong. Revert, learn from the timeline, improve the task description, and re-dispatch. Clean reverts are cheap; manual fixes to bad agent output are expensive.
Monitoring and Observability
As you scale agent usage, you need to monitor patterns across many agent runs:
Success Rate Tracking
Track what percentage of dispatched agents produce accepted diffs on the first try. A healthy rate is 70-80%. Below 50% means your task descriptions need improvement. Above 90% means you might be giving tasks that are too simple to warrant agent use.
Token Efficiency
Monitor tokens consumed per accepted diff. If token usage is trending upward without a corresponding increase in task complexity, investigate — agents may be iterating unnecessarily due to vague constraints or conflicting requirements.
Common Failure Patterns
Keep a log of rejected diffs and the reason for rejection. After 10-20 rejections, patterns emerge: "agents always miss error handling" → add "include error handling" to your .antigravity conventions. "Agents always use wrong test framework" → add "use pytest, not unittest" to conventions.
Time to Accept
Measure the time from agent dispatch to diff acceptance. If this is growing, your review process may be the bottleneck. Consider: reviewing diffs immediately when they arrive, using the diff summary artifact for quick triage, or delegating reviews to teammates.
Security Best Practices
Agents have significant access to your codebase and can run terminal commands. Follow these security practices:
| Practice | Why | How |
|---|---|---|
| Protect sensitive files | Agents should never modify .env, credentials, or production configs | List sensitive files in .antigravity under protected_files |
| Review terminal commands | Agents can run arbitrary commands via the terminal | Check the timeline for terminal actions. Restrict command execution in settings if needed. |
| Use localhost for browser agents | Browser agents can click buttons and submit forms on any URL | Never provide production URLs. Use a dedicated Chrome profile with no saved sessions. |
| Audit accepted diffs for secrets | Agents may accidentally hardcode API keys or tokens | Scan accepted diffs for patterns like sk-, AKIA, ghp_ before committing. |
| Do not share API keys in task descriptions | Task descriptions may be logged or sent to the model API | Reference environment variables or config files instead: "Use the API key from .env" |
| Limit agent scope for shared codebases | Agents should not access code outside the project | Open only the project folder, not your home directory or a parent folder. |
What to Avoid
These anti-patterns have been observed repeatedly across Antigravity's early adopter community. Each one seems harmless in isolation but compounds over time into significant quality problems:
| Anti-Pattern | Why It Causes Problems | Better Approach |
|---|---|---|
| Vague task descriptions | Agent guesses intent, produces irrelevant or over-broad changes | Name the file, function, and expected outcome explicitly |
| Accepting diffs without reading | Agent errors compound; regressions ship | Read every diff as if it's a colleague's PR |
| Bundling unrelated tasks | Sprawling diffs that are hard to review or revert | One concern per agent — keep diffs focused |
| Running agents on shared core files | Merge conflicts between concurrent agents | Check for file overlap warnings before dispatching |
| Ignoring the clarification queue | Agents stay blocked; no progress | Monitor the Manager Surface — answer WAITING agents first |
| Letting accepted diffs pile up | Hard to trace which agent did what; messy git history | Commit after each accepted diff with a clear message |
| Using browser agent on prod | Risk of accidental form submission or state mutation | Always point browser agents at localhost or staging URLs |
| Defaulting to the most expensive model | Wastes budget on simple tasks | Start with Gemini 3 Pro, upgrade to Claude only for complex reasoning |
| Never reading the agent timeline | Missed learning opportunities; repeated mistakes | Read the timeline after every rejected diff to understand what went wrong |
Team Adoption Patterns
When introducing Antigravity to a team, these patterns help ensure successful adoption:
Start with one champion
Have one developer use Antigravity exclusively for 2 weeks. They learn the tool's strengths and limitations, develop good task-writing habits, and build the team's .antigravity config file. This person becomes the team's Antigravity expert and mentor.
Define the .antigravity config as a team
The .antigravity config file is a living document. Review it as a team: agree on coding conventions, protected files, test commands, and lint commands. Treat it like your linting rules — everyone contributes, everyone follows.
Require agent-assisted attribution in commits
All commits generated with agent assistance should include "(agent-assisted)" in the commit message. This is not about blame — it is about traceability. When reviewing code later, the team knows which changes to scrutinise more carefully for edge cases the agent might have missed.
Run a weekly retro on agent quality
Once a week, review: How many agent diffs were accepted vs rejected? What were the common rejection reasons? What changes should we make to the .antigravity config? Are task descriptions getting more precise? This continuous improvement loop is what separates teams that get value from Antigravity from teams that abandon it.
A developer who writes good code and reviews carefully gets dramatically faster with Antigravity. A developer who writes sloppy specs and rubber-stamps diffs gets faster at introducing bugs. The tool multiplies what you bring to it — bring your best engineering habits.
Antigravity agents are powerful but not infallible. They can misread intent, miss edge cases, or make individually correct changes that interact badly with other changes. Your job shifts from writing every line to reviewing every change — that is still a job that requires engineering judgement. The agents handle the mechanical work; you handle the decisions.
The Antigravity Maturity Model
Teams go through predictable stages as they adopt Antigravity. Understanding where you are helps you identify what to improve next:
| Stage | Characteristics | Typical Duration | Key Action |
|---|---|---|---|
| 1. Exploration | Using agents for simple tasks. High reject rate. Learning the interface. | Week 1-2 | Focus on writing better task descriptions. Read every timeline. |
| 2. Single-Agent Proficiency | Consistent success with one agent at a time. Accept rate above 60%. Good task descriptions. | Week 2-4 | Start using multi-agent for independent tasks. Build your .antigravity config. |
| 3. Multi-Agent Workflow | Routinely dispatching 2-3 agents in parallel. Using the queue. Reviewing diffs efficiently. | Week 4-8 | Optimise: model selection per task, review speed, commit conventions. |
| 4. Team Integration | Shared .antigravity config. Agent-assisted commits normalised. Weekly retros on agent quality. | Month 2-3 | Track metrics: accept rate, tokens per task, time to accept. |
| 5. Production Workflow | Agents handle 50%+ of implementation work. Developer focus shifts to design, review, and architecture. | Month 3+ | Continuous improvement of conventions, task templates, and review processes. |
Antigravity Track Summary
You have now completed the full Antigravity track. Here is what you have learned across all six modules:
Module 35: What is Antigravity?
Antigravity's agent-first architecture, 2M token context, multi-agent orchestration, and browser integration. How it compares to other AI IDEs. Where it excels and where it falls short.
Module 36: Setup & First Agent
Installation, configuration, project setup, the .antigravity config file, dispatching your first agent, execution modes, and troubleshooting common issues.
Module 37: Multi-Agent Orchestration
Parallel execution, isolated branches, agent communication patterns, result aggregation, conflict handling, and proven multi-agent patterns (Bug Swarm, Feature+Test+Docs, A/B Implementation).
Module 38: Manager Surface
The control centre for multi-agent work: agent timeline, steering, diff review, artifact management, task queues, debugging, and agent lifecycle.
Module 39: Browser Integration
Chrome extension setup, DOM interaction, form automation, visual testing, screenshot analysis, web scraping, security considerations, and code+browser combined tasks.
Module 40: Best Practices
Precise task specification, production patterns, cost management, error handling, monitoring, security, team adoption, and the maturity model.
Antigravity is in active development. New features — including agent memory (persistent context across sessions), team collaboration (shared agent pools), and CI/CD integration — are on the roadmap. Keep the application updated and revisit the Antigravity documentation monthly. The tool you learned today will be significantly more capable in 3 months.
Hands-On Exercises
.antigravity config file. Agree on: coding conventions (at least 5), protected files (at least 3), test and lint commands, and the default model. Commit the file to your repository. Review it again after 2 weeks of team use and update based on experience.