Add plain-English guide for Claude Code + Antigravity workflow
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>
This commit is contained in:
211
docs/reference/how-to-work-with-both-tools.md
Normal file
211
docs/reference/how-to-work-with-both-tools.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# 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) |
|
||||
Reference in New Issue
Block a user