How to Build a Website With Claude Code: Complete Guide

The short answer

Building a website with Claude Code is not one prompt. It is a sequence of small, verifiable steps, each of which you review before the next one starts:

Define → Inspect → Plan → Configure → Architect → Build
      → Optimise → Secure → Test → Deploy → Index → Improve

The model is rarely the bottleneck. Claude Code will produce plausible, well-structured code for almost anything you describe. The bottleneck is that plausible and correct are different things, and the gap between them is where projects die: a canonical tag that points at a redirect, a button whose text colour matches its background, a migration that drops a column, a credential that reaches a public bundle.

Everything below is a way of closing that gap without giving up the speed. This guide covers the full lifecycle. Where a stage deserves its own treatment, it links to a deeper guide: prompts, CLAUDE.md, Shopify, and SEO.

What Claude Code actually is

Claude Code is a terminal-based agentic coding tool. That phrase does real work, so it is worth separating from two things it is not.

It is not browser chat. In a chat window you paste code in and copy code out. Claude Code runs in your project directory, reads your actual files, runs your actual commands, and edits your actual repository. It sees the tests fail.

It is not autocomplete. Editor completion predicts the next few tokens from nearby context. Claude Code takes a goal, decides which files to open, makes a plan, executes multiple steps, and reports what happened.

The practical consequence is that context is your job. An autocomplete tool needs no briefing. An agent working across your repository needs to know what the project is, what conventions it follows, what it must never do, and what "finished" means. Most of the difference between people who get good results and people who get frustrated is how much of that they write down.

Anthropic's documentation is the authority on installation, authentication, and current features; it changes often enough that it is worth checking rather than remembering. As of writing, the recommended install is a single command:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

Then claude --version to confirm, and claude doctor for read-only diagnostics on install health and settings. Claude Code requires a paid Claude account — Pro, Max, Team, Enterprise, or Console — or a third-party provider such as Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. The free Claude.ai plan does not include it.

What it does well for website work

Being specific about strengths is more useful than enthusiasm.

• Reading a codebase you did not write. This is arguably its best trick. Point it at an inherited repository and ask it to map the architecture, and you get in ten minutes what would otherwise take a morning.
• Mechanical work with a clear specification. Converting a design system into tokens, wiring up responsive images, writing the twentieth similar API endpoint, adding alt attributes across a template.
• Audits. Anything with a checklist — technical SEO, accessibility, security review, dependency hygiene — is a good fit, because the output is findings you verify rather than code you trust.
• Debugging with real evidence. Give it the stack trace, the failing command, and permission to run things, and it is genuinely good at tracing a cause.
• Migrations and refactors where the target state is well defined and there are tests to prove behaviour did not change.
• Documentation that reflects what the code actually does, written at the moment the code is fresh.

What ties these together: they are all tasks where you can check the answer. That is the reliable predictor of whether an agentic workflow will work well.

What not to trust it with blindly

These are not theoretical. Every item here is something that has gone wrong in real projects.

Version-specific facts

API shapes, configuration keys, CLI flags, platform limits, and framework behaviour all change. A model will produce a confident, correctly-formatted, entirely fictional configuration option, and it will read exactly like a real one. The habit that fixes this is asking for a source: "cite the primary documentation URL for that and quote the relevant line." If it cannot, treat the claim as unverified.

A concrete example from building this site. Shopify's theme documentation lists the template types a theme can define. It does not include policy. When we tried to add one anyway, Shopify's own upload validation rejected it:

Template type 'policy' does not support JSON templates

That is the useful kind of error, because the platform tells you the truth. Plenty of wrong assumptions are not caught that way.

Destructive and irreversible operations

Deleting files, dropping or altering database columns, rewriting git history, force-pushing, changing DNS, publishing to production. These deserve an explicit stop-and-ask rule in your project instructions, not a hope that the model will be careful.

Credentials

AI-assisted development produces .env files, seeded credentials, and hardcoded test keys with real enthusiasm. Anything in a client-side bundle is public regardless of what it is named. Scan before your first push to a remote — a secret that has been pushed must be rotated, and removing it from history does not un-expose it.

Anything it claims to have verified

"Tests pass" and "I ran the build" need to be true. Ask for the output. A related habit worth building: ask "what did you not verify?" at the end of any substantial piece of work. The answer is often the most useful thing in the report.

Factual content

Statistics, prices, dates, credentials, comparisons, case studies. Claude drafts; a human publishes. Keep a running list of every claim that needs checking before anything goes live.

Prerequisites

One habit matters more than any of the tooling: launch Claude Code from the project root. It loads CLAUDE.md files from the working directory and every directory above it. Start it somewhere else and you either starve it of context or hand it someone else's.

1. Define the website before you open a terminal

The most expensive mistake in AI-assisted development is building a well-engineered answer to the wrong question, quickly.

Before any code, write down five things:

1. What this site is, in one sentence a stranger would understand. If you cannot write that sentence, the problem is not technical.
2. Who it is for — defined by situation, not demographics. "Owners of two-to-ten-person trades businesses who currently book jobs by text message" is an audience. "Small business owners" is not.
3. The single action that defines success. One. If you name two, decide which you would keep.
4. What it will deliberately not do. This is the section people skip and the one that saves the most time.
5. What is being assumed that has not been validated.

You can do this with Claude Code as a structured interview rather than a blank page — ask it to interview you, one area at a time, and to push back on vague answers. The point is not the document. It is that every architectural decision afterwards has something to be measured against.

2. Make Claude read the repository first

On an existing project, the first session should change nothing. Reconnaissance before surgery.

This prompt is genuinely one of the highest-value things you can paste into an unfamiliar repository:

Analyse this repository. Do not modify anything.

Map:
1. Structure — what lives where, and the convention behind it
2. Stack — languages, frameworks, versions. Read the manifest and
   lockfile; do not infer from directory names.
3. Entry points — how it starts, builds, tests, and deploys
4. Data — where it comes from, where it is stored
5. Configuration — what environment variables are expected
6. Conventions in force — naming, structure, error handling, styling
7. Tests — what exists, what it covers, whether it currently passes

Then tell me:
- The three things I most need to understand before changing anything
- Anything that looks unusual, and whether it seems deliberate
- Anything you are uncertain about

Cite file paths for every claim. If you could not determine
something, say so rather than guessing.

Three details in there are doing most of the work. "Do not modify anything" keeps it read-only. "Read the manifest and lockfile; do not infer from directory names" prevents a whole class of confident wrong answers. "Cite file paths for every claim" makes the output checkable — and you should spot-check two or three.

Two things to look for immediately in the result: any committed credential, and whether the documented commands actually work. The gap between the README and reality is usually where the bugs live.

For a large codebase, delegate the exploration to a subagent so the file reads land in its context instead of yours — "use a subagent to investigate how our auth system handles token refresh" returns the findings without the noise.

3. Get a plan before you get code

Claude Code has a plan mode for exactly this: it reads files and proposes an approach but makes no edits until you approve. Start a session in it with claude --permission-mode plan, or press Shift+Tab mid-session until the status bar shows ⏸ plan mode on.

Plan mode is worth using more than people do, because the economics are lopsided. A wrong architectural decision caught in a plan costs one message. The same decision caught after implementation costs a rewrite. There is no other point in the process with that ratio.

What a plan should contain before you approve it:

• Milestones that are each independently demonstrable and independently revertible
• The specific files each step will touch
• The verification for each step — how will we know this worked?
• The rollback
• What the plan is uncertain about

If a proposed step touches more than roughly ten files or spans more than one architectural layer, ask for it to be split. Long unreviewed stretches of generated code are where architectural drift accumulates, and drift is much harder to fix than bugs.

4. Establish CLAUDE.md

CLAUDE.md is a Markdown file Claude Code loads at the start of every session in that project. It is where your architecture, conventions, and "always do X" rules live so you stop retyping them.

Without one, every session starts from zero, and the symptom is architectural drift: three form-handling patterns, two CSS strategies, a utility function written four times. Each session made a locally reasonable choice with no knowledge of the others.

The counter-intuitive part is that shorter files are followed more reliably. Anthropic's guidance is to target under 200 lines, because the file is loaded into the context window at the start of every session and a long one consumes context while reducing adherence. A 400-line CLAUDE.md is followed less well than a 150-line one.

So the discipline is subtraction. Delete anything that restates a default, anything Claude can read from the code itself, and — most importantly — anything you are not actually going to enforce. Rules you tolerate breaking teach the model that rules in this file are negotiable.

/init generates a starting file from your existing codebase, which is a good first draft: it documents what your code does. You then layer on what you want it to do. Run /context to confirm the file actually loaded; "Claude is ignoring my CLAUDE.md" is usually "Claude never saw it".

The full treatment — what belongs in each section, what must never go in, worked examples for Shopify, Astro, and SaaS projects, and how to split large rule sets into .claude/rules/ — is in the CLAUDE.md guide.

5. Design the information architecture

Three decisions here are effectively permanent once the site has traffic. Give them disproportionate attention.

URL structure

URLs are a contract. Every change afterwards needs a redirect, loses a little, and breaks external links you do not control. Decide them deliberately: lowercase, hyphenated, descriptive, short but complete before short, shallow, and no dates unless the content is genuinely time-bound. A URL like /blog/2024/guide/ looks stale in 2026 and cannot be updated without a redirect.

Canonical host and trailing slashes

Pick www or the apex. Either is fine. Serving both is not — it splits signals and creates duplicates. Same for trailing slashes: choose one, enforce it with redirects, never serve both with a 200.

The conversion path

Map the journey from every realistic entry point to the single action you defined in step 1. Then count the steps. Every unexplained requirement discovered mid-flow — an account, a card, a phone call — is a conversion loss and a trust cost.

6. Decide the technical architecture

The decision that drives the most downstream consequence is rendering strategy: static, server-rendered, client-rendered, or a deliberate mix. It determines performance, SEO risk, hosting cost, and complexity more than any framework choice.

Default to static unless something genuinely cannot be known at build time. "Content might change" is usually solved by rebuilding, not by a server.

Whatever you choose, ask one question about content before anything else: who updates this in six months, and what tool do they open? If the honest answer is "a non-technical person opens a Markdown file in a git repository," the architecture is wrong and the site will be stale within a quarter.

For each significant choice, insist on the shape: the decision, the alternative rejected, and the cost being accepted. A recommendation without a stated cost is marketing, not engineering. Write these into an architecture decision record; six months later it is the only thing that stops someone "fixing" a deliberate oddity.

7. Build in small, verifiable increments

Foundations before features. Design tokens, layout primitives, and the base template before any page, because everything else inherits from them.

Standing rules worth putting in CLAUDE.md so you stop repeating them:

• Work on a feature branch. Never commit directly to the default branch.
• Commit before every large change. A clean git status is your undo button, and it is the single highest-value habit in the whole workflow.
• Read the diff, not the summary. The summary is written by the thing being reviewed.
• Semantic HTML first. <button> for actions, <a href> for navigation, never a <div> with a click handler.
• Handle the unhappy paths as you go — loading, empty, error, offline. These are most of what separates a demo from a product.
• No dependency without stating what it does, what it weighs, and why the platform cannot do the job.

Follow the conventions already in the codebase even where you would have chosen differently. Consistency beats individual preference. If a pattern is genuinely wrong, change it everywhere in one deliberate pass rather than introducing a second way of doing the same thing.

Working across sessions, and in parallel

A real website build spans days, not one sitting. Three mechanics make that practical, and they are underused.

Resuming

Claude Code saves conversations locally. claude --continue resumes the most recent session in the current directory; claude --resume opens a picker; /resume does the same from inside a running session. The point is not convenience — it is that you stop re-explaining the project every morning, which is where inconsistency creeps in.

Worth knowing about compaction: when a conversation grows long enough to be summarised, the project-root CLAUDE.md survives, because Claude re-reads it from disk. Instructions you only ever said out loud in the conversation do not. That is a practical argument for writing anything important into the file rather than repeating it in chat.

Parallel work with worktrees

Two agents editing the same checkout will collide. A git worktree is a separate checkout on its own branch, so they cannot:

claude --worktree feature-nav

Run the same command with a different name in another terminal and you have an isolated parallel session. The natural fit for website work is one worktree for a feature and another for an audit — the audit reads and reports while the feature branch changes things, and neither trips over the other. Note that the repository needs at least one commit for this to work.

Headless mode for CI and batch work

Print mode runs Claude non-interactively, which makes it a normal Unix tool:

git log --oneline -20 | claude -p "summarize these recent commits"

This is how you get an AI review step into a pipeline, or run the same audit prompt across twenty repositories. Be deliberate about permissions when you do — a non-interactive session cannot ask you whether it should delete something.

Delegating to subagents

Exploring a large codebase fills your context with file reads you will never look at again. Asking for a subagent — "use a subagent to investigate how the checkout flow handles discount codes" — pushes those reads into a separate context and returns only the findings. On a large site this is the difference between a session that stays sharp and one that runs out of room halfway through the job.

8. Build SEO into the architecture

Retrofitting SEO is where projects lose weeks. The structural parts — URLs, canonicals, heading semantics, metadata patterns, indexation rules — are architecture decisions, not a later content task.

Decide, before building:

• Title and description patterns per page type, not individual strings
• Exactly one <h1> per page; no skipped heading levels; headings describe content rather than styling text
• Self-referencing canonicals everywhere, and the canonical host decision from step 5
• Which structured data types genuinely describe each page type — and never review, rating, or aggregate-rating markup without real reviews behind it
• What is deliberately noindex: internal search results, thin utility pages, staging
• How the sitemap stays current automatically

A worked example of getting this wrong, from this site. After launch the homepage was serving <title>site-builder-stack.myshopify.com</title> with no meta description at all, because Shopify's page_title falls back to the store domain when the homepage title preference is unset. Nothing in the build flagged it; it only appeared when the live page was fetched and read. Which is the argument for the next section.

The full engineering workflow — audits, internal linking, schema, sitemap validation, Search Console — is in the SEO guide.

9. Security

Run a secret scan before your first push to a remote. Every other class of bug is recoverable by fixing forward; a leaked credential is not.

Scan four places, not one:

1. The working tree
2. The full git history, all branches and tags — a secret removed in a later commit is still there
3. The build output and client bundles — anything shipped to a browser is public
4. Deployed surfaces: is /.env reachable? Is /.git/config? Both are real, regularly exploited misconfigurations

Beyond secrets, the review areas that matter most for a website: input validated server-side at every trust boundary; output encoded for its specific context; every database query parameterised; authorisation checked on the server for every request including ownership; security headers present and verified on the live response, not in a config file; and cookies carrying Secure, HttpOnly, and SameSite.

The single most common serious vulnerability in web applications is worth testing explicitly: can user A reach user B's data by changing an ID in a URL or payload? It takes two minutes to check and is missed constantly.

One honest boundary: a code and configuration review is not a penetration test. It does not attempt exploitation and it has blind spots. Say so in your own reports.

10. Accessibility

Target WCAG 2.2 Level AA. The thing to internalise: automated tooling finds roughly a third of real accessibility problems. A page that passes an automated scan with zero violations and cannot be operated by keyboard is inaccessible, and that combination is common.

The manual checks that find the rest, in order of yield:

• Put the mouse aside and use the site. Every interactive element reachable, operable, and visibly focused. No traps. Logical order.
• Compute contrast ratios rather than asserting them. 4.5:1 for body text, 3:1 for large text and meaningful non-text elements.
• Check the focused element is not hidden behind a sticky header — tab down a long page and watch.
• Every form control programmatically labelled. A placeholder is not a label.
• 200% zoom and a 320px viewport without loss of content or horizontal scrolling.

A worked example of why measuring beats reviewing. On this site, a CSS selector for links (.sbs a, specificity 0,1,1) was beating the button rule (.sbs-btn--primary, specificity 0,1,0). The result: the primary buy button rendered accent text on an accent background — a computed contrast ratio of 1:1, completely invisible. It passed every static check. It was found by rendering the page in a browser and reading the computed styles of every text node. The fix was to give base element rules zero specificity with :where() so component rules always win.

11. Performance

Measure first. Optimising without a baseline is guessing with extra steps, and you will not be able to tell whether you helped.

In rough order of typical impact:

• Third-party scripts. Usually the single largest cost on an otherwise fast site. For each: what does it weigh, what does it deliver, can it be deferred, is it still needed?
• Images. Modern formats, correct dimensions, responsive srcset, explicit width and height to prevent layout shift, lazy loading below the fold — and never lazy-load the largest above-the-fold image. Lazy-loading the LCP element is a common and costly own-goal.
• JavaScript. Remove what is unused, split what is large, defer what is not needed for first render. Ask of every library whether it does something the platform cannot.
• Fonts. Subset, font-display: swap, preload only the face that renders first, and question every additional weight.
• Layout stability. Reserve space for anything that loads late: images, embeds, banners, injected widgets.

Report real numbers, before and after. And be careful with the claim: lab measurements from a testing tool are a diagnostic, not the measure. Field data from real users is what actually counts. Never remove conversion-critical functionality to improve a score — a faster page that does not convert is a worse page.

12. Validate

This is the stage most people compress, and it is where the interesting bugs live. On this project, four defects were invisible to every static check and only appeared when the page was rendered in a real browser and measured.

One specific bug worth describing, because it is a whole class. At a 320px viewport this site's page scrolled to 492px. The cause was not a stray width — it was that grid and flex children default to min-width: auto, so a pre-formatted block could not shrink below its content. No linter reports that. It shows up the moment you measure scrollWidth against clientWidth in a real browser.

A QA report with no findings is a QA report nobody should trust.

13. Deploy

A professional pipeline is not elaborate. It is:

feature branch
  → lint, typecheck, tests, secret scan, build
    → pull request
      → preview deployment
        → review
          → merge
            → production deploy
              → smoke test
                → monitor

Each stage catches a class of problem as early, and therefore as cheaply, as possible. If you add only one, add the secret scan — it is the only failure on that list that fixing forward cannot undo.

Two things that repay the effort immediately: preview deployments per pull request, which turn "looks right in the diff" into "I clicked it"; and smoke tests after deploy — three to five checks answering "is it actually up and serving the right thing", with automatic rollback if they fail.

Make previews non-indexable, and verify that on an actual preview URL rather than assuming the host handles it. A preview competing with production in search results is a real and avoidable problem.

Write the rollback procedure down before you need it, and read it once. During an incident nobody reads documentation for the first time. Roll back first, diagnose second — fixing forward under pressure is how a five-minute incident becomes an hour.

14. Get indexed

Verify the property in Google Search Console — prefer a domain property, since a URL-prefix property for https://example.com does not include https://www.example.com, and people lose a week to that. Submit the sitemap. Set up Bing Webmaster Tools, which can import from Search Console in about two minutes.

Then set expectations honestly, because this is where most disappointment comes from. Google's own documentation is unambiguous: "submitting a sitemap is merely a hint: it doesn't guarantee that Google will download the sitemap or use the sitemap for crawling URLs on the site." Submission aids discovery. It does not cause indexing, and indexing is not ranking.

Before submitting anything, confirm the site is actually ready: publicly accessible, no sitewide noindex, no Disallow: / left over from staging, HTTPS working on every hostname, canonical host decided, and real content on every indexable page. Submitting a site that is not ready wastes crawl budget on pages you are about to change.

15. Monitor and improve

The launch is not the end of the process; it is the first moment you have real data to feed back into it.

First 24 hours: errors, uptime, the conversion path completed for real, analytics actually receiving events. Review 404s from real traffic — every one is a visitor who did not get where they were going, and they reveal links you did not know existed.

First week: crawl and indexing status, real user behaviour versus the journey you assumed, where people drop out of the conversion path. Internal search queries, if you have search, are a direct list of what people expected to find and could not.

First month: the review that turns a launch into a product. The highest-value report is pages with high impressions and low click-through — those are ranking but not being clicked, which usually means the title and description do not match what the searcher wanted. It is the cheapest improvement available, and it needs no code.

Then feed what you learned back into step 1.

Mistakes that cost the most time

Accepting a large diff without reading it

Twelve files change, the architecture drifts, and by the time anyone notices, unwinding it costs more than starting again. Small steps, each reviewed.

Letting the model decide what "done" means

Without stated completion criteria, done is whatever the model decides when it stops writing. Define it before it starts.

Trusting the summary over the diff

The summary is written by the thing being reviewed. git diff before every commit.

Skipping CLAUDE.md because the project is small

Small projects become medium projects. Twenty minutes of setup saves hours of correcting the same thing.

Writing a CLAUDE.md nobody enforces

The opposite failure. Aspirational rules teach the model that rules here are optional. Write fewer, truer ones.

Auditing in the same session that wrote the code

A session reviewing its own work will defend it. Start a fresh one; the findings improve noticeably.

Believing a passing automated check means the thing works

Automated accessibility tools find about a third of issues. Theme and lint checks find syntax, not intent. The remaining problems are found by using the thing.

Treating "it deployed" as "it works"

A deploy that succeeded and produced a broken page is the failure mode smoke tests exist for.

The workflow on one page

DEFINE     One-sentence description · audience · one conversion · non-goals
INSPECT    Read-only repo audit · secret scan · do the docs match reality?
PLAN       Plan mode · milestones that are revertible · verification per step
CONFIGURE  CLAUDE.md under 200 lines · only rules you will enforce
ARCHITECT  URLs · rendering strategy · content source · decisions + costs
BUILD      Branch · commit first · small diffs · read every one
OPTIMISE   Baseline, then images, JS, fonts, third parties · real numbers
SECURE     Secrets (tree, history, bundle, deployed) · authz · headers
TEST       Build · lint · tests · keyboard · contrast · 320px · console · links
DEPLOY     CI · preview · smoke test · rollback written down and read
INDEX      Search Console domain property · sitemap · honest expectations
IMPROVE    24h errors · 7-day behaviour · 30-day review · feed it back

None of this is exotic. It is ordinary engineering discipline applied to a tool that is fast enough to outrun your review if you let it. The speed is real; the discipline is what makes the speed worth having.

Where to go next

Four guides go deeper on the stages that deserve it:

• Claude Code prompts for web development — why structured prompts outperform conversational ones, with worked examples across discovery, architecture, debugging, security, and deployment.
• Creating a production CLAUDE.md — what belongs in it, what must never go in, and complete examples for Shopify, Astro, and SaaS projects.
• Building a Shopify store with Claude Code — the development-theme workflow, Liquid, the Admin GraphQL API, and the traps specific to the platform.
• Claude Code SEO — technical audits, structured data, sitemap validation, and where AI genuinely helps versus where it creates liability.

Sources and further reading

• Claude Code documentation — installation, authentication, plan mode, subagents, memory files
• Google Search Central: build and submit a sitemap
• Google Search Central: creating helpful, reliable, people-first content
• W3C: Web Content Accessibility Guidelines 2.2
• OWASP Top Ten
• Shopify: theme template types