I’ve been using Antigravity recently and overall the idea of an agent-first IDE is very interesting. However, one major issue that keeps coming up is the documentation quality and maintenance.
Many sections of the documentation currently have the same problems:
-
Information is fragmented
-
Lack of concrete examples
-
Missing practical usage explanations
-
Unclear file structure or configuration details
This makes it quite difficult for developers to actually adopt the features. In many cases, the only way to understand how something works is to search through GitHub issues, blogs, or other users’ repositories.
A good comparison example is Cursor’s documentation, especially the Rules page:
https://cursor.com/cn/docs/context/rules
This page is a great example of what good developer documentation looks like.
For example, the page clearly explains:
-
What Rules are (concept explanation)
Rules are persistent instructions that are automatically added to the model context. -
Where the rule files live
.cursor/rules/*.mdc
- What the file structure looks like
---
description: React project guidelines
globs: src/**/*.tsx
alwaysApply: false
---
# React Rules
- Use functional components
- Prefer hooks over class components
- How rules are triggered
The documentation explains different rule behaviors such as:
-
Always apply
-
Auto attach
-
Agent requested
-
Manual
After reading the page, developers can immediately understand how to use the feature in a real project.
In contrast, many parts of Antigravity’s documentation currently provide only high-level descriptions such as:
“Rules can guide agent behavior”
But what developers actually need to know is:
-
Where rule files should be placed
-
What the file format is
-
How the rules are loaded
-
How rules are triggered
-
Best practices for structuring them
Without this information, the feature becomes much harder to use in practice.
I believe Antigravity has a lot of potential as an agent-first development environment. But developer experience depends heavily on documentation.
Some suggestions that might help:
-
Rewrite documentation for core features with complete examples
-
Clearly describe file structure and configuration locations
-
Add real project examples
-
Keep documentation updated alongside feature changes
-
Consider adopting a documentation structure similar to Cursor’s (concept → usage → examples → advanced usage)
Good developer tools are not just about features — documentation is part of the product.
Improving the documentation could significantly lower the learning curve and make Antigravity much easier to adopt.