How to Build an Astro Website with Claude Code

Use Claude Code as a repository collaborator

Claude Code can read a project, edit files, run commands, and work through multi-step implementation tasks. Astro can turn components and content into static HTML with no client runtime by default. The combination is effective for marketing and editorial sites because the result stays easy to inspect.

The weak version of the workflow starts with: “Build me a beautiful Astro website.” Claude has to infer the business, routes, visual system, content boundaries, quality standard, and deployment target at once. A strong-looking first draft is possible. Consistency over the full project is much less certain.

The stronger workflow places durable decisions in the repository, then gives Claude one bounded implementation goal at a time.

Start with the environment

Before generating a route, confirm the project already answers these questions:

• Which package commands install, check, test, build, and preview the site?
• Is output static or server-rendered?
• Where do page data and long-form content live?
• Which layout owns metadata, navigation, and the page shell?
• Which tokens and primitives define the visual language?
• What may hydrate on the client?
• Which failures block a release?
• Which branch and service publish production?

If the repository cannot answer them, resolve the foundation first. Page production will otherwise multiply uncertain choices.

Establish a clean starting record

Ask Claude to report the current branch, working-tree state, runtime version, package manager, and available scripts before it edits. Existing uncommitted work belongs to someone; it should not be discarded or reformatted as collateral damage. If the project has no Git remote or deployment configuration, that is a finding, not permission to invent replacements.

For an existing Astro project, the first read should usually cover:

package.json
astro.config.*
tsconfig.json
src/content.config.*
src/pages/**
src/layouts/**
src/components/**
src/styles/**
public/**
deployment configuration
agent instruction files

Direct Claude to use targeted searches. It can locate every client: directive, metadata helper, content collection, or hard-coded canonical without dumping the entire repository into one response. The purpose is to find the system owners before proposing changes.

On a new project, make the same decisions explicitly. Confirm that static output satisfies the product. Select the official Astro starter or existing production base. Install only the dependencies the design and content require. Run the untouched baseline once so later failures can be attributed to an actual change.

Put Claude-specific guidance in CLAUDE.md

Claude Code supports project memory through CLAUDE.md. Keep it short enough to remain operational. Point to deeper documents when a task needs them instead of placing the entire design system, content strategy, deployment manual, and company history in one file.

A useful project file might begin like this:

# Project rules

- Astro outputs a fully static site. Do not add SSR without approval.
- Reuse tokens and components in `src/styles` and `src/components`.
- Do not hydrate components unless browser state or interaction requires it.
- Content claims must come from the approved brief or listed primary sources.
- Run `npm run check` and `npm run build` before declaring work complete.
- Never deploy, change DNS, or edit credentials without explicit authorization.

Write rules as actions and boundaries. “Keep performance in mind” is not actionable. “Do not add a client framework for static presentation” is.

For repositories used by several coding agents, shared conventions can live in AGENTS.md, but Claude Code does not read that filename directly. Import it from CLAUDE.md with @AGENTS.md or use a symlink, then keep Claude-specific routing in CLAUDE.md. Avoid maintaining two contradictory copies of the same rule.

Give the first task a narrow acceptance test

Do not start by asking for the entire site. Pick a representative route that exercises the actual system: a real heading, a card group, a visual asset, a CTA, and enough copy to test responsive density.

An implementation request should name scope and proof:

Implement the /services/ route from the approved brief.

Constraints:
- Reuse BaseLayout, Section, Button, and existing design tokens.
- Use semantic HTML and preserve the current heading hierarchy.
- Keep the route static. Add no client directives.
- Do not invent testimonials, prices, or credentials.

Acceptance:
- The route builds successfully.
- There is one H1 and a unique title and description.
- Long headings and cards work at narrow widths.
- Report changed files and command results.

Claude now has a local objective. Review the result before scaling the pattern across other pages.

Build the page shell before the page family

The base layout should own document concerns that cannot safely vary route by route: language, viewport, global styles, site header, main landmark, footer, metadata assembly, and any organization-level structured data. Page templates then provide the title, description, canonical path, and page-specific schema.

Ask Claude to trace existing ownership before moving code. If BaseLayout.astro already renders the title and canonical, a second SEO component inside an article layout can produce duplicate tags. If the header already includes the primary navigation, an article should not recreate it for visual convenience.

A useful interface keeps page requirements visible:

---
interface Props {
  title: string;
  description: string;
  canonicalPath: string;
  noindex?: boolean;
}

const { title, description, canonicalPath, noindex = false } = Astro.props;
---

<BaseLayout
  title={title}
  description={description}
  canonicalPath={canonicalPath}
  noindex={noindex}
>
  <slot />
</BaseLayout>

This is a shape, not a drop-in contract. Adapt property names and URL logic to the repository. Absolute canonicals should come from one trusted site origin, not a string repeated through content files.

Turn the visual direction into code Claude can reuse

Before scaling pages, implement the smallest representative set of design decisions: type roles, content measure, section spacing, surface treatment, border rules, action styles, focus state, and responsive container behavior. Use names that express purpose rather than one page’s appearance.

Then ask Claude to compose from those primitives. A request can state: “Use the existing section, cluster, and button patterns; if the source layout needs a callout, extend the current border and spacing tokens.” This gives the agent a path for missing editorial components without inviting a separate blog theme.

Stress the representative route with difficult content. Use the longest real heading, a dense paragraph, an empty optional field, several navigation items, and a table that must work on a narrow screen. Placeholder lorem ipsum hides the exact conditions that break a production layout.

When review exposes a global issue, ask Claude to patch the owning primitive and list affected routes. When it exposes a content-specific exception, keep the change local and document why. That distinction protects the design system from one-off overrides.

Preserve Astro’s static advantage

An .astro component renders HTML without sending its component logic to the browser. Framework components only become interactive in the client when you apply a client directive such as client:load or client:visible.

That makes hydration a reviewable decision:

---
import PricingCalculator from '../components/PricingCalculator.tsx';
---

<!-- Static markup: no browser component runtime -->
<section aria-labelledby="pricing-title">
  <h2 id="pricing-title">Choose the right production base</h2>
  <p>Compare the included architecture and workflow.</p>
</section>

<!-- Interactive state: load when the component approaches the viewport -->
<PricingCalculator client:visible />

Do not add the second pattern to solve a styling problem. Ask Claude to justify every client directive in the final report. The AI website performance guide explains what happens when hydration becomes an invisible default.

Build content around schemas, not copied routes

For a content family, use Astro content collections and a shared rendering template. Define fields that affect publishing decisions: title, description, slug, intent, status, dates, parent, related entries, sources, and quality review.

The schema should fail early when objective requirements are missing. It should not pretend to grade prose automatically. A numeric quality total can enforce a review gate only when a person has scored the underlying dimensions honestly.

Ask Claude to add one entry and prove the route, metadata, breadcrumbs, structured data, and internal links work. Then add the next entry. This reveals template weaknesses before a large content batch depends on them.

Connect status to every publishing surface

A content entry marked draft, review, index, or noindex needs consistent treatment. Claude should not filter drafts only from the hub while the dynamic route still generates them. Decide which states create a public route. For reachable noindex material, render the directive and keep it out of the sitemap. Indexable entries should meet the quality threshold, have an inbound path, and appear in the intended hub.

Ask for one function or clearly shared rule that identifies indexable entries. Reuse it in route generation, hub lists, related-content selection, and sitemap filtering where the framework permits. Test each state with a small fixture before importing a full content batch.

Structured data follows the same principle. An article can use Article when the visible page is editorial. Breadcrumb markup should mirror the rendered breadcrumb. Organization data should describe the real organization. Do not let Claude add ratings, reviews, offer prices, or people that the page cannot substantiate.

Make search and accessibility part of the component contract

For every new template, require a semantic outline and a keyboard path. The layout supplies one main landmark. The page supplies one H1. Sections use headings in order. Links explain their destination without relying on surrounding card art. Tables use captions or nearby context, header cells, and an overflow treatment that does not hide data.

Metadata needs an equally concrete contract: unique title, useful description, absolute canonical, truthful social preview, and a robots directive derived from status. Internal links should be present in rendered HTML and use the canonical slash convention.

These requirements belong in components and validation where they are objective. A reviewer still needs to judge whether the heading accurately represents the page and whether the link is useful in context.

Ask Claude to inspect the rendered output rather than the component source alone. Astro can make a template look correct while a prop mismatch leaves the final description empty. The built document settles the question.

Use the terminal as a feedback loop

Claude should run the smallest relevant check during implementation and the full required suite at completion. A typical sequence might be:

npm run check
npm run content:check
npm run build

Use only scripts that exist in the repository. If there is no content checker, define its responsibilities before adding one. Useful hard failures include duplicate slugs, duplicate primary keywords, broken related references, invalid dates, missing required metadata, and indexed entries below the approved quality threshold.

When a command fails, ask Claude to explain the failure against the changed files, fix the root cause, and rerun it. Do not accept deleting a validation rule simply to get a green build. If a rule is incorrect, change it with a documented reason and a fixture that demonstrates the intended behavior.

Review at three levels

Diff review

Check whether Claude stayed inside scope, reused existing primitives, avoided unnecessary dependencies, and preserved project conventions. Pay special attention to configuration and shared layouts because a small change there affects every route.

Built-output review

Open the generated HTML or inspect it with a script. Confirm the primary copy and links exist without client execution. Check title, description, canonical, robots directive, language, heading order, JSON-LD, and asset paths.

Browser review

Use representative narrow and wide viewports. Navigate by keyboard. Test visible focus, long content, tables, code blocks, reduced motion, and the actual purchase path. Build success does not validate visual or interaction quality.

Handle corrections at the right layer

If every article has an over-wide measure, fix the article layout. If one source title breaks a card, fix the card behavior. If Claude repeatedly invents supporting copy, add an instruction that unapproved claims must be marked as missing rather than completed creatively.

Do not accumulate prompt-only corrections. Promote recurring guidance into code, schemas, tests, or repository instructions. The next session should benefit from today’s review.

Troubleshoot the workflow, not just the symptom

Claude ignores a project rule

Confirm the applicable CLAUDE.md file is in the instruction hierarchy and that an imported file uses the supported @path form. Check for a closer instruction that conflicts. Rewrite broad prose as a short action plus acceptance test. Remember that instruction files guide behavior; filesystem permissions and deployment gates enforce safety.

The build sends unexpected JavaScript

Search for client: directives and integrations that inject scripts. Map each emitted chunk to its component. Remove hydration from presentation-only components, or switch to a later directive when interaction can wait. Rebuild and compare the artifact, not just the source diff.

A dynamic route generates the wrong path

Inspect the collection entry ID, explicit slug field, and getStaticPaths() return value together. Check the project’s trailing-slash and directory-format settings. Normalize the path in one helper, then validate that the file location, canonical, internal link, and output directory agree.

Content validation reports an orphan

Do not silence the error by adding an arbitrary footer link. Decide where a reader should discover the page: its parent hub, a contextual sibling, or a product route. Add the link where the relationship is understandable and keep the related-content data consistent.

Claude changes too much

Reduce the task boundary. Name owned files or directories. Ask for diagnosis without implementation when the cause is uncertain. Preserve unrelated working-tree changes and prohibit broad formatting. A smaller diff is easier to verify and easier to reverse.

Local preview and production disagree

Separate Astro output from hosting behavior. Inspect the built file first, then check Cloudflare status, redirects, headers, cache, and custom-domain routing. Do not keep changing components when the edge is serving an old deployment or different project.

Close with an evidence-based handoff

Before calling the work complete, ask Claude to run the repository’s real validation commands and provide the outcomes. Inspect git status so generated artifacts, credentials, and unrelated local files do not enter the commit. Review deployment configuration separately from application code.

For Cloudflare, continue with the Astro deployment guide after the production build is clean. Deployment is its own controlled step, not an automatic sequel to code generation.

Claude Code is capable of doing substantial implementation work. The quality of the shipped site depends on whether the repository gives that capability a precise job, visible constraints, and a release process that does not accept fluent confidence as proof.