Parsons/docs/reference/how-to-work-with-both-tools.md

How to Work with Claude Code and Antigravity

A plain-English guide for day-to-day use.

---

The basic idea

You have two AI tools open at once. Claude Code runs in the terminal (inside Antigravity or standalone). Antigravity is the IDE with a built-in browser and its own AI chat panel. They each have strengths, and the setup is designed so they don't step on each other.

Think of it like having two specialists in the room:

• Claude Code is the engineer — writes code, manages tokens, runs quality checks, handles git, keeps the project memory files up to date.
• Antigravity is the visual reviewer — opens Storybook in a real browser, takes screenshots, checks how things look at different screen sizes, spots spacing and alignment issues.

They share the same project files and the same set of rules (AGENTS.md), so they're always on the same page about conventions.

---

When to use Claude Code

Use the terminal (Claude Code) when you need something built, fixed, or analysed.

Building things:

• "Build me a new Button atom" → Claude Code uses /build-atom
• "Create tokens for this new component" → Claude Code uses /create-tokens
• "Write stories for the VenueCard" → Claude Code uses /write-stories

Fixing things:

• "The spacing on ProvidersStep is off" → tell Claude Code what to fix
• "This component needs to handle empty states" → Claude Code edits the code
• "Update the copy on the intro page" → Claude Code modifies the JSX

Quality checks:

• "Audit this component" → Claude Code runs /audit, /critique, /harden
• "Is this ready to commit?" → Claude Code runs /preflight
• "Check consistency across all atoms" → Claude Code runs /normalize atoms

Project management:

• "What did we do last session?" → Claude Code reads the memory files
• "Log this design decision" → Claude Code updates decisions-log.md
• "Commit and push" → Claude Code handles git

Rule of thumb: if it involves writing or changing code, tokens, or memory files — use Claude Code.

---

When to use Antigravity

Use the Antigravity chat panel when you need something looked at visually.

Visual QA:

• "How does the HomePage look on mobile?" → type /fa-visual-qa HomePage in Antigravity. It opens the story, checks at 375px, 768px, and 1280px, takes screenshots, and reports issues.

Page review (your most common task right now):

• "Review the CoffinsStep" → type /fa-page-review CoffinsStep. It reads the source, opens the story, runs through the review checklist (spacing, typography, colour, responsive, copy, interactions, edge cases), and reports findings with severity ratings.

Quick checks:

• "Does this look right?" → open Storybook in Antigravity's browser panel and eyeball it yourself. The built-in browser is faster than using Playwright screenshots through Claude Code.

Pre-commit (either tool works):

• /fa-preflight in Antigravity runs the same checks as /preflight in Claude Code. Use whichever you have open.

Rule of thumb: if it involves looking at something in a browser and judging whether it looks right — use Antigravity.

---

The typical flow for your current work (tweaking pages)

Most of your work right now is reviewing and polishing existing pages. Here's the natural rhythm:

1. Start your session

In Claude Code: I automatically read the memory files and report what's pending. Or in Antigravity: type /fa-session-start for the same status report.

2. Pick a page to work on

You say something like "let's look at the ProvidersStep."

3. Assess (Antigravity)

In the Antigravity chat: /fa-page-review ProvidersStep

It opens the page in Storybook, checks it at three screen sizes, and gives you a list of issues — spacing inconsistencies, typography problems, copy that could be warmer, responsive breakpoint issues.

4. Fix (Claude Code)

You bring the findings to me: "Fix the spacing between the filter chips and the provider list, and tighten up the heading hierarchy."

I make the targeted changes in the code.

5. Verify (Antigravity)

Back in Antigravity: /fa-visual-qa ProvidersStep

It screenshots the page at all three breakpoints again so you can compare before and after.

6. Commit (Claude Code)

Once you're happy: "commit and push." I handle git.

That's the sandwich: Antigravity sees the problem → Claude Code fixes it → Antigravity confirms the fix.

---

The flow for building new components

When you need something new built (a new atom, molecule, organism, or page):

1. Tell Claude Code what you need. I'll check the component registry, verify dependencies, and build it following the lifecycle.
2. I run internal QA automatically (/audit, /critique, /harden) before showing it to you.
3. Visual sign-off in Antigravity. Use /fa-visual-qa ComponentName to check it at all breakpoints.
4. You give feedback. I fix, Antigravity re-verifies. One or two rounds.
5. Preflight and commit. Either tool can run preflight. I handle the commit.

---

What about the workflows?

You have six workflows available in Antigravity's chat. Type / followed by the name:

Workflow	What it does	When to use it
/fa-session-start	Reads memory files, reports project status	Start of a session
/fa-page-review	Full review of an existing page	When tweaking/polishing pages
/fa-visual-qa	Visual check at 3 breakpoints	After any visual change
/fa-preflight	Runs all quality checks (auto-approves)	Before committing
/fa-token-sync	Rebuilds token outputs (auto-approves)	After changing token JSON
/fa-build-component	Scaffolds a new component	When building something new

The ones marked "auto-approves" run without asking — they're safe, read-only or deterministic operations.

---

What not to worry about

You don't need to keep the tools in sync. They both read AGENTS.md for shared rules. Claude Code reads CLAUDE.md for its extra instructions. Antigravity reads GEMINI.md for its extra instructions. There's no overlap between those two files, so nothing drifts.

You don't need to tell both tools the same thing. If you make a design decision, tell Claude Code — I'll log it in decisions-log.md, and Antigravity can read it from there next time.

You don't need to worry about file conflicts. Claude Code writes code and memory files. Antigravity only reads those files and writes to its own workflow directory. They don't touch each other's files.

---

When the backend comes

When you start the Payload CMS work, the same structure holds:

• The backend agent (whether it runs in Antigravity or a separate Claude Code session) will own src/payload/ and src/api/. It reads the flow-definition YAML files to know what API endpoints and data shapes to build.
• Claude Code continues owning frontend components, tokens, and theme.
• Antigravity continues owning visual QA.
• The flow-definition.yaml is the contract between frontend and backend — it defines the step IDs, field names, branching logic, and visibility rules that both sides reference.

We'll add a backend section to AGENTS.md when that starts. For now, the boundaries are already defined so the transition will be smooth.

---

Quick reference card

I want to...	Use
Build a component	Claude Code
Fix spacing/copy/alignment	Claude Code
Check how something looks	Antigravity (/fa-visual-qa)
Review a whole page	Antigravity (/fa-page-review)
Run quality checks	Either (/preflight or /fa-preflight)
Rebuild tokens	Either (/sync-tokens or /fa-token-sync)
Commit and push	Claude Code
Log a design decision	Claude Code
Check project status	Either (/status or /fa-session-start)
Extract from Figma	Claude Code (has Figma MCP)