Frontend with Claude Code

The method in one sentence

Each card becomes one Claude session, in its own worktree, with a clear kickoff prompt and two checkpoints: the plan and the evidence. Claude handles everything else (code, checks, screenshots, tests, PR) and shows me the result. Commits and PRs happen only when I ask.

What changed the outcome most was making the decision boundary explicit: Claude settles anything technical and reversible on its own, and checks with me when the decision is about product or visuals, involves someone else, or can't be undone.

The flow of a PR

Ten steps in four phases. Pick a step on the timeline or use the arrow keys. Checkpoints are in yellow: Claude stops and waits for my call.

Lessons

The method above didn't come out fully formed. Each rule came from something that went wrong, or that worked better than expected.

1. 01

   Before and after is the deliverable

   Without the comparison, fix-up work goes unnoticed: reviewers can't see what changed, and users never knew there was a problem. That's why evidence is a checkpoint, not an attachment.

2. 02

   The scoreboard lives in code, not in a spreadsheet

   A script counts, on every merge, how many uses of the old component remain, and a lint rule blocks new ones. Without that guardrail, five new files using the old component showed up in four days.

3. 03

   Measure back to back, in the same window

   A performance run done hours apart showed a 21% regression that didn't exist. Once both branches were measured back to back, the difference disappeared.

4. 04

   Swapping components is an audit

   The most serious bugs were on screens nobody had asked me to look at. Opening each screen to swap the component exposes what was already broken around it.

5. 05

   AI executes; design judgment decides

   The AI rewrote a set of tabs to make them “cleaner” and broke the platform's identity. That became a rule: don't rebuild what already exists, and reuse the component from the reference screen.

6. 06

   Independent review catches what the author misses

   A second session, looking only at the diff, found a bug that was already in production. Since then, the review runs again whenever something changes after it.

7. 07

   Measure before you promise, one area per PR

   The number comes before the commitment. And each PR touches a single area, so it can be rolled back without undoing the rest.

8. 08

   A fixed mistake becomes memory

   When Claude makes a mistake that must not happen again, the fix goes into the project memory, along with the reason. Over time, the process lives in memories and rules files, and prompts get short.

Evidence

The comparison is always the same grid: before on the left, after on the right; light on top, dark below. Reviewers spot the difference without reading a word.

Performance criteria

LCP

No regression above 10%

CLS

No increase

Long tasks

No new ones above 50 ms

The orchestrator session

Each PR runs in its own session and worktree, but there's usually only one local environment: fixed ports, one database. Only one worktree can be running at a time. The orchestrator is its sole owner and decides who gets it.

Organizing the app

Simulator: switching the environment

An afternoon with two PRs and the orchestrator. Step through it; the note below explains why each thing happens.

Ground rules

• One environment at a time, always. Starting one can kill any extra server, including the main-branch server used for the “before” screenshots. Start that one afterward.
• Nothing heavy while the environment is running. Global type checks and large builds overload the machine.
• Infrastructure is shared. Don't start the database and queues from inside a worktree: that can create a new, empty database.
• Two PRs in flight at most: one builds, the other proves and documents. More than that just creates queues and conflicts.
• Tell the team before touching an area, especially whoever is changing the same screens.

Known pitfalls

And how to avoid each one. The skill warns Claude about all of them.

• What happenedA screen in an unexpected theme: the environment was running from an outdated branchHow to avoid itA fresh worktree off main for each card; check where the environment is running from before taking screenshots.
• What happenedA fresh worktree with dozens of “module not found” errorsHow to avoid itRun the setup (install and build the internal libraries) before running any checks.
• What happenedA file regenerated by the local server ended up in the PRHow to avoid itNever git add -A with the environment running; stage only what's in scope and check the diff before pushing.
• What happenedA global check with the environment running froze the machineHow to avoid itCheck only the packages touched; anything heavy runs with the environment stopped.
• What happenedFrontend written against an endpoint the backend hadn't shipped yetHow to avoid itConfirm it exists in the API contract or the generated types before starting.
• What happenedA component rewritten from scratch drifted from the visual identityHow to avoid itReuse the component from the reference screen and adjust it only through props and classes.
• What happenedPerformance measured at different times showed a false 21% regressionHow to avoid itBoth branches back to back, in the same time window.
• What happenedSwitching the environment by hand turned into a waiting lineHow to avoid itThe orchestrator takes over the switching, keeping the machine awake while there's work.

Getting started: two paths

Start with A. When the work is bigger than one PR, move on to B.

The full toolkit

Loading…

# Evidence · <ID> <title>

## Screenshots
Before (main) on the left, after (branch) on the right; light on top, dark below.
- <screen>: default, error, disabled

## E2E for the area
- Main: <x of y> · Branch: <x of y>
- Pre-existing (already failing on main): <test and reason>

## Performance (both back to back, in the same window)
| Screen | LCP before | LCP after | Difference | CLS before | CLS after | New long tasks |
|-|-|-|-|-|-|-|

## Behavior
- Validation, copy, payload and data-testid unchanged: <how it was checked>

## Checks
- <lint, types, tests>: <result>
- Didn't run, and why: <...>

## Independent review
- Round 1: <findings and what changed>
- Round 2: <if anything changed afterward>

Glossary

Every technical term on this page. In the text, terms have a dotted underline; click one to see its definition.