Richie
9f5848b8a3
Human-readable reference for day-to-day use: when to use which tool, typical flows for page tweaking and component building, workflow quick reference, and how things change when backend work starts. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
212 lines
7.8 KiB
Markdown
212 lines
7.8 KiB
Markdown
# 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) |
|