Building a website with Claude Code, from an agency that ships them

Most published guides to building a website with Claude Code are already wrong in their first paragraph. They tell you to install it through npm. That has not been the install path for some time, the documentation has moved from docs.claude.com to code.claude.com, and the tool now runs on five surfaces rather than one. This is what the workflow actually looks like in November 2026, written from building and shipping production sites with it rather than from a weekend experiment.

What Claude Code actually is

It is an agentic coding tool that reads a codebase, edits files, runs commands and uses your development tools. That last part is what separates it from a chat window that returns snippets: it runs the build, reads the error, and edits the file again. For a website that means it can start the dev server, open the page, read the console, and fix what it finds, which is a different activity from generating markup.

The single biggest difference between a site that takes two days and one that takes two weeks is whether the constraints were written down before the first file was created. Not the design, the constraints: which pages exist, what each one has to make happen, what the content model is, who edits it afterwards, and which facts are allowed to appear on the page. An agent will happily invent a testimonial, a statistic and a client name if the brief does not say not to, and finding those later is far more expensive than preventing them.

That brief belongs in a CLAUDE.md at the project root, which Claude Code reads at the start of every session. It is not documentation for humans that the agent happens to see. It is the thing that stops the same correction being needed in week three that you gave in week one.

Pick the stack once and say so

Left to itself an agent will reach for whatever is most common in its training, which for a marketing site usually means a framework heavier than the job needs. Decide the stack yourself, write it into the brief, and be specific about the version, because the difference between two major versions of a framework is the difference between code that builds and code that looks right and does not.

• Name the framework and its major version, because an agent trained before a breaking release will write the old API confidently.
• Name the styling approach. Mixing a utility framework with component CSS halfway through a build is the most common source of a site that works and is unmaintainable.
• Name where content lives. A marketing site whose copy is hard-coded in components cannot be edited by the client, and retrofitting that is a rebuild.
• Name the host before the first deploy, because the build output differs between a static export and a server runtime.

Let it plan before it writes

Asking for a plan first and reading it costs a few minutes and routinely saves a day. The plan is where you discover that it intends to install three dependencies you do not want, model the content in a way that will not support the second language, or build eight pages when the brief described five. Correcting a plan is a sentence. Correcting the same decision after it is spread across forty files is an afternoon. The common workflows guide covers the patterns, and best practices is worth reading once properly rather than skimming.

The part everyone skips: verification

An agent reports that it built the thing. Whether it built the thing is a separate question, and the gap between the two is where almost every bad outcome lives. The discipline that works is to check the built output rather than the source, and to look at the rendered page rather than measure it. We have had a heading pass every measurement we threw at it and still be visibly broken in a real browser, because the tool doing the measuring was not compositing the page the way a browser does.

What this means in practice is covered at length in what to check before you believe the agent built it, because it is the difference between a site that looks finished and one that is.

Where agent-built sites lose on search

They lose in the places nobody looks at on screen. Metadata inherited from a parent route so every child page shares one social image. A sitemap that never got generated. Structured data that validates and describes the wrong thing. Images served at the wrong size because a config allowlist was never extended. None of these show up in a design review and all of them show up in Search Console six weeks later. The full list, with the ones specific to this stack, is in the SEO checklist for a site an agent built.

Package the repeatable parts

By the third site you will be giving the same instructions again. That is what skills are for: a folder with a SKILL.md that packages a workflow, invoked with a slash command or loaded automatically when the description matches. A pre-launch SEO audit, a redirect map generator, an accessibility pass. Hooks cover the other half, running a shell command before or after an action, so formatting and linting stop being something anybody remembers to do. Which of these are worth building for website work specifically is in the skills worth having on a website build.

When this is the wrong tool

A codebase is a liability for a client who cannot maintain one. If the people who will own the site afterwards do not have a developer and the content changes weekly, a hosted builder is the better answer even though it is the less impressive one, and the reasoning is the same as in when a rebuild is the wrong answer. The comparison in full, including the cases where a codebase genuinely wins, is in an agent-built codebase against a hosted builder.

If you want to go deeper on the tool itself, Anthropic runs free self-paced courses at Claude Academy, and the full documentation index is published as a machine-readable file at code.claude.com/docs/llms.txt, which is the fastest way to find a page rather than searching for it.

The rest of this series

Each piece below takes one stage of the workflow above and goes deeper than this page can. Configuration first: a CLAUDE.md that changes decisions, the skills worth having, writing one of your own, and the three MCP servers worth connecting. Then the loop itself: the hooks that gate a website repository, what to delegate to subagents, and how to verify what the agent built. Then launch: the SEO checklist, Core Web Vitals on an agent-built site, and shipping to production without surprises.