Directing Claude Code on real client builds.

Claude Code works inside a project folder, reading files and running commands in your terminal. It is far more accurate in a codebase that is conventional and well organised. Before any real work starts, put the foundations in place:

• A standard framework setup (for example Next.js with TypeScript) with linting and formatting configured.
• Design tokens for colour, type, spacing and motion in one place.
• A small set of base components — buttons, headings, section wrappers — that everything else reuses.
• Git from the first commit, so every change can be reviewed and reversed.

Claude Code reads a CLAUDE.md file at the root of the project at the start of each session. Use it to record what a new developer would need to know: the stack, the folder structure, the commands to run, naming conventions, the design system, and rules the project must follow.

# Project: <client> marketing site

## Stack
Next.js (App Router), TypeScript, Tailwind CSS, GSAP.

## Commands
npm run dev · npm run build · npm run lint

## Conventions
- Reuse components in src/components/ui before creating new ones.
- Colours, type and spacing come from tokens in globals.css only.
- All animation respects prefers-reduced-motion.

## Content rules
- Never invent statistics, testimonials, client logos or results.
- Copy comes from the approved content doc; flag gaps instead of filling them.

Keep it short and current. When you correct the same mistake twice, add a line to CLAUDE.md so it doesn't happen a third time.

Large, vague requests ("build the homepage") produce large, vague results. Specific tasks produce work you can actually review.

1. 01Describe one piece of work with its context: "Build the pricing section from the Figma frame, reusing SectionHeading and Button."
2. 02Ask for a short plan first on anything non-trivial, and correct it before code is written.
3. 03Let it implement, then review the diff yourself — not just the rendered page.
4. 04Run lint, type checks and the page in a browser.
5. 05Commit with a clear message, then move on to the next piece.

Claude Code builds closer to the design when it has precise references. Share the design file or screenshots of the exact frames, name the components it should reuse, and call out the details that matter: spacing, type scale, breakpoints and hover states.

Review at real breakpoints — narrow phones, tablets and wide desktop screens — and give feedback as specific, measurable corrections ("the card gap should match the 24px grid gap") rather than general impressions.

Treat Claude Code like a capable contractor with access to your machine. Keep production credentials, client data and API keys out of the repository and out of prompts. Use environment files that are excluded from Git, and review any command that deletes files, changes infrastructure or touches live systems before approving it.

Be clear with clients about how AI tools are used in delivery, and check your agreements cover it.

Because Claude Code works best in a tidy codebase, it also leaves one behind when it is directed well. At handover, make sure the README explains how to run, build and deploy the site, CLAUDE.md reflects the final conventions, and the content editing workflow is documented for the client.

That same documentation makes later changes fast — for your team or for whoever maintains the site next.