I once asked Antigravity to "implement the validation for my login screen." What came back was a single validation function — no error message rendering, no focus management, no integration with the server-side check. In my head, "validation is complete" meant the entire screen behaving correctly. To the agent, "complete" meant one function being written.
The misalignment had nothing to do with how cleverly the prompt was phrased. We had simply never agreed on what "Done" meant. This article walks through the practice I built after that day for agreeing on a Definition of Done with Antigravity agents.
When "Done" isn't shared, the loop never closes
If you have ever handed a slice of work to another person, you know that a request without a definition of done almost always comes back needing rework. The same pattern shows up with AI agents.
The painful part is that context decays with every round trip. Conditions you forget to include in the first message can be added in the second or third, but by then the agent's reasoning has moved on, and the original design decisions don't get revisited. Even with well-sized tasks, a vague Done definition still leads to mismatches later.
The fix is almost embarrassingly simple: write the Definition of Done into the very first request.
Build Definition of Done in three layers
The framework I use day to day breaks Done into three layers.
Layer 1: Functional requirements — what behavior counts as working
"When the user fills in email and password and submits, the form sends a POST to the server. On a successful response the user is taken to the home screen. On failure an error appears." Most engineers stop here. That's the problem.
Layer 2: Observable behavior — how I will recognize that it works
"Working" and "observable as working" are not the same thing. Code that runs in the agent's sandbox and code that I can confirm is running in front of me are different artifacts. The gap between the two is exactly where the most painful end-of-day surprises happen — features that "passed" yesterday turn out to have never been verified by a human.
- The POST request is visible in the browser's network panel
- On error, an error message appears below the input field in red, 14px text
- The submit button is disabled while the request is in flight, preventing double submission
If you skip this layer, the agent will write code that runs, but not code that you can confirm runs. You can't trust the completion report unless Layer 2 is written down.
Layer 3: Operational constraints — what must not break
The "while a new feature works, something else quietly broke" failure mode has, honestly, become more frequent for me since adopting AI agents. That's why I now spell out what not to touch.
- Don't modify the existing user-settings validation logic — reuse it as a shared module
- Don't break landscape layouts on smartphones
- Add tests alongside the new feature
This third layer constrains the agent's freedom, and that constraint is what shortens review time the most. There is a counterintuitive lesson here. Adding constraints does not make the agent slower; it makes the agent more decisive, because the search space of acceptable solutions has been narrowed before the work begins. I started writing Layer 3 reluctantly, expecting it to feel like over-engineering for solo development. Instead it removed entire categories of "wait, the agent touched the wrong file" incidents.
A prompt template you can paste
Here is the template I currently keep in my snippets and paste at the top of any non-trivial Antigravity prompt.
Task: [What to build]
Definition of Done:
1. Functional requirements
- [What the user does, and what should happen]
2. Observable behavior
- [Concrete steps I can run to verify]
- [Error display spec — location, color, exact text]
3. Operational constraints
- [Files / modules that must not be touched]
- [Existing behavior that must not change]
- [Tests that must accompany the change]
Before reporting completion, score yourself against each item above
and explicitly mark any item as "not met" if it isn't fully satisfied.The final sentence — "score yourself and mark any unmet item" — is the workhorse. It nudges the agent into auditing its own output against the Definition of Done. The "looks complete to me" responses go away once the agent is forced to compare the output to the criteria item by item.
A practical note on length: the template above looks long, but in practice each layer often has just two or three bullet points. The goal is not exhaustive specification — it is making sure that the parts of "Done" you would have evaluated mentally during review are visible to the agent before the work starts. Treat it as the contract you would have written down anyway, just earlier in the process.
Hand the agent an acceptance script it can run
You can take this further by handing the agent the Definition of Done as executable tests. This pairs naturally with verifying a background agent's "done" report.
// acceptance/login-validation.spec.ts
describe('Login Validation — Definition of Done', () => {
it('Done-1: shows an error for an invalid email', async () => {
await page.fill('#email', 'invalid');
await page.click('button[type=submit]');
await expect(page.locator('.email-error')).toHaveText('Please enter a valid email');
});
it('Done-2: returns focus to the empty password field', async () => {
await page.fill('#email', 'user@example.com');
await page.click('button[type=submit]');
await expect(page.locator('#password')).toBeFocused();
});
it('Done-3: surfaces a network error on connection failure', async () => {
await page.route('**/api/login', route => route.abort());
await page.fill('#email', 'user@example.com');
await page.fill('#password', 'password');
await page.click('button[type=submit]');
await expect(page.locator('.network-error')).toHaveText("Can't reach the network");
});
});When you hand this to Antigravity and say "Done means all of these tests pass," the agent's behavior tightens noticeably. The output you get when there is a concrete target — these tests must pass — is meaningfully different from what you get when the goal is the abstract phrase "build a login screen."
Three failure modes I see when Done is missing
Before adopting this practice I kept hitting the same three failure modes, and noticing them is part of what made the change feel necessary.
The first is interface-first / behavior-last. The agent renders a beautiful screen, the buttons line up, the spacing is correct — and none of them do anything when clicked. This happens when only Layer 1 of Done is in the prompt and Layer 2 is missing. The agent has no signal that "wired up" matters more than "looks correct."
The second is scope creep without notice. I ask for a small change, and quietly a shared utility module gets renamed across the codebase, or the agent decides to "improve" the lint config. Layer 3 was missing, so the agent assumed any improvement was welcome. With Layer 3 in place the agent will pause and explicitly ask before touching anything outside the named scope.
The third is quiet completeness. The agent reports completion, the code looks fine, and a week later I notice an edge case that was never even attempted. This one is the most expensive, because it doesn't surface in the same review session. The "self-score against Definition of Done" instruction at the end of the prompt is what closes this gap. The agent now flags missing edge cases out loud rather than silently skipping them.
Watching for these three patterns in your own work makes the value of writing Done explicit a little easier to feel.
Turn the three layers into review checkpoints
The three layers aren't just something you write once — they double as the lens you review the completion report through. I keep this mapping next to me and walk down it every time a report comes back.
| Layer | What to verify at review | Typical symptom when it's missing |
|---|---|---|
| Layer 1: Functional requirements | Does the requested behavior actually happen? | The requirement simply isn't met |
| Layer 2: Observable behavior | Can I reproduce it working with my own hands? | "Should work," but you can't confirm it |
| Layer 3: Operational constraints | Is everything off-limits still intact? | Something elsewhere quietly broke |
That rightmost column is, to me, the real reason to write a Definition of Done. The first two columns confirm what went right; the third catches what silently went wrong — and the silent failures were always the expensive ones.
Rewriting a fuzzy Done into a concrete one
Here is what it looks like to take an abstract request and rewrite it along the three layers.
[Before]
Implement the validation for the login screen.
[After]
Task: Implement input validation for the login screen
Definition of Done:
1. Functional requirements
- Submitting a malformed email does not send the request and shows an error
2. Observable behavior
- The error appears below the field in red, 14px
- The submit button is disabled while the request is in flight
3. Operational constraints
- Do not modify the shared validation used by the settings screen
- Add a spec test covering the new behaviorThe "before" line silently omits at least five conditions that only existed in my head. The "after" version doesn't add new information — it just surfaces those omissions. You aren't specifying more; you're making the implicit contract visible before the work starts.
The day too much Done made things worse
It would be easy to read all of this as "the more detailed the Done, the better." I overdid it once.
I listed more than a dozen visual specs under Layer 2 — button color, 12px padding, 14px font. The agent focused on satisfying every line, and the check against the server-side validation slipped to the back. Its self-score came back all "met." The screen matched the spec exactly, and the behavior I actually cared about was missing.
What I noticed is that the items in a Done list have a priority order, and a flat list hides it.
So I now keep each layer to about three items — only the conditions where I would say "if this is off, I won't accept it." Visual fine-tuning can wait until the first report comes back.
- If a condition decides whether I accept the work, it goes into Done.
- If it is a matter of taste, I raise it during review.
- If I am unsure whether to include an item, I ask whether missing it would cause rework.
Done is not a document that covers everything. It is the standard that decides whether you can trust the completion report.
What to try next
Pick one task you're about to send to Antigravity where Done feels fuzzy, and rewrite it using the three-layer template above. A single task is enough to feel the difference in how few rework rounds you need. I admit my first reaction to writing this much upfront was "this feels heavy" — but the time I would have spent on round-trip fixes was always longer than I expected.
Thanks for reading along.