How I actually build with Claude Code

Most advice about coding with AI is about prompts. In practice the prompt is maybe a quarter of it. The rest is the loop you run around it — what context is always present, how big a step you take before checking, and what "checking" actually means.

This is the loop I use. The examples are from building this site, because it is the one project where I can show you every decision.

1. Two documents, always

A permanent standard that never changes and a project brief that changes every time. The standard stops the work being sloppy; the brief stops it being generic.

Everything below assumes those are already in place.

2. Put the project context in the repo, not in the chat

CLAUDE.md at the root of the project, read automatically at the start of every session. Not the whole architecture — just the things that are true and non-obvious:

- Stack and versions, if anything is unusual
- Commands that matter: build, lint, dev
- Conventions this repo actually follows
- Anything that has already been decided, so it does not get re-litigated

The test for whether a line belongs in there: would a competent developer joining the project get it wrong without being told? If yes, it goes in. If it is derivable from the code, leave it out — it will go stale and start lying to you.

3. Make it ask before it builds

The single highest-leverage instruction in my standard is the one that says ask me these questions first. Skip it and you get a website for a business that does not exist, confidently built, with invented opening hours.

Ten minutes of questions up front beats an hour of corrections afterwards, every time.

4. Build a thin slice and verify it before going wide

Scaffold, then build one thing end to end — for this site that was the design tokens plus the hero, nothing else — and run the build. Only then expand.

It feels slower. It is not. Foundation mistakes are cheap to fix when three files depend on them and expensive when thirty do.

5. Run the build and the linter constantly

Not at the end. After every meaningful chunk.

On this project the linter caught a setState called synchronously inside an effect, which I would not have noticed until the page started re-rendering in a loop. Fixing it also surfaced a second bug I had introduced in the same edit: I had changed a state setter's signature and the menu toggle was still calling it the old way, so the mobile menu would have opened and never closed.

That is two real bugs from one lint run, before either reached a browser.

6. Open the browser. Do not trust the summary

This is the part people skip, and it is the part that matters most.

Three bugs on this site were invisible in the code and obvious the moment I actually inspected the running page:

Everything was invisible. Scroll reveals start at opacity: 0 and are revealed by an IntersectionObserver. In a backgrounded tab the observer never fires — so the page loaded and stayed blank. The code read perfectly. Fix: gate the entry styles behind @media (scripting: enabled) and add a failsafe timer.

The mobile menu was 0.63 pixels tall. The header had backdrop-blur, which quietly makes an element a containing block for position: fixed children. The full-screen panel inside it was being sized against a 72px header. No error, no warning, just a menu button that appeared to do nothing.

The primary button failed contrast. White on the accent orange measured 3.12:1 — below the WCAG AA threshold of 4.5:1. Nothing flags this. You have to compute it. Near black on the same orange is 6.18:1 and looks better anyway.

None of these three would have been caught by reading the diff.

7. Ask for the weaknesses before you ask for more features

The last step of my standard is a self-critique pass: list what is weak in the visual design, UX, responsive behaviour, accessibility and performance — then fix what actually matters.

On this build that pass is what caught the homepage stacking four "nothing here yet" boxes in a row, which read as broken rather than honest. The fix was to have empty sections hide themselves entirely.

Asking "what did you get wrong?" reliably produces a better list than asking "is this done?".

Where this breaks down

It does not survive vague goals. "Make it better" and "add some animations" produce motion for its own sake, every time. Every good result in this loop traces back to a specific decision someone made — usually before any code was written.

It also does not replace knowing what good looks like. The loop catches bugs. It does not tell you the layout is boring.