Claude Code with Astro: a practical setup guide

Claude Code is Anthropic’s terminal coding agent; you start it with claude in an Astro project folder and it reads, edits, and runs commands in that directory. This guide shows how to make Claude Code effective for Astro work: content collections, islands, static builds, and integrations. It assumes you know Astro and want concrete setup, prompts, and verification steps, not generic AI advice.

Why Claude Code fits Astro projects well

Astro projects separate concerns clearly: .astro files combine markup, frontmatter, and component composition; content collections give typed data; islands isolate client JavaScript. Claude Code can use those boundaries because they are explicit in the repo. It reads src/content/config.ts, understands collection schemas, and can update both schema and route files together. Astro’s static-first model makes many edits local with predictable effects, so the agent can iterate quickly with astro check and pnpm build. It is especially useful for repetitive edits across many content entries, layout refactors, and island conversions. Because Astro components are mostly declarative, the agent can locate component boundaries quickly and avoid editing generated output. The static build step gives a deterministic check, so the agent can learn from build output and fix issues without guessing.

Preparing your Astro project for Claude Code

Claude Code reads CLAUDE.md at the project root for instructions. Keep it short and Astro-specific: commands, folder conventions, and rules that prevent the agent from breaking static builds or content types. Avoid generic advice; state exact commands and paths. The file should tell the agent which directories are source and which are generated, and which island framework integrations are installed so it does not try to add a component that requires an uninstalled integration. For more on what belongs in project instructions, see Claude Code best practices: a practical checklist.

# CLAUDE.md

## Commands
- Install: `pnpm install`
- Dev: `pnpm dev`
- Build: `pnpm build`
- Preview: `pnpm preview`
- Lint: `pnpm lint`
- Check: `pnpm astro check`

## Project layout
- `src/content/` — content collections, schema in `src/content/config.ts`
- `src/components/` — reusable `.astro` and framework components
- `src/components/islands/` — components with `client:*` directives
- `src/pages/` — file-based routes
- `src/layouts/` — layout components
- `src/styles/` — global CSS
- `public/` — static assets served as-is

## Rules
- Use `astro:content` and typed `getCollection()`; do not read content with raw `fs`.
- Keep client-side logic in islands under `src/components/islands/`.
- For static builds, avoid server-only APIs unless an adapter is configured.
- Run `pnpm astro check` after any change that touches content schemas, routes, or component props.
- Do not edit generated files in `.astro/` or `dist/`.

The example uses pnpm; use the package manager your repo actually uses. Include astro check as a non-negotiable verification step. If you use an adapter for SSR, add the adapter-specific command and note which routes are server-rendered.

A safe iteration loop for Astro changes

Do not ask for a large rewrite at once. Start with plan mode for cross-cutting changes, then let the agent make small edits, run verification, and show a diff. An effective loop is: state the goal and constraints; ask for a plan before changes; review the plan against Astro’s static build and content collection rules; approve small edits; run pnpm astro check and pnpm build; inspect git diff; repeat. After each change, ask the agent to summarize which files it touched and why, so the review stays focused. For complex refactors, see Claude Code plan mode: plan first, then let it build.

Example prompts for typical Astro tasks:

• Add a notes content collection to src/content/config.ts with fields title, publishedAt, draft, and tags. Then add two sample entries under src/content/notes/.
• Create src/pages/notes/[...slug].astro that uses getStaticPaths and getCollection('notes') to statically render each note. Sort by publishedAt descending and skip entries where draft is true.
• Refactor the header search box in src/components/Header.astro into a React island with client:idle, keeping the existing class names and moving state into the island component.
• Run pnpm astro check, fix every error it reports, and explain why each change was needed in the final commit message.
• Review the last build output for warnings about missing client directives or large islands; propose specific component changes to reduce JavaScript shipped to the client.

Common Astro tasks and the pitfalls to watch

Claude Code handles many Astro-specific jobs well: adding or updating content collections, generating index and detail routes, updating layout components, converting static markup to islands, fixing type errors after schema changes, writing frontmatter validation, and moving repeated components into layouts.

Where to watch it closely:

• Content collection schema changes require a full pnpm astro check; otherwise generated types in .astro can be stale.
• Static routes with getStaticPaths must be exported from .astro pages; the agent may forget when copying dynamic route patterns.
• Client directives such as client:load or client:idle on a shared component can add JavaScript to many pages unintentionally.
• Astro frontmatter cannot import server-only Node APIs in static builds unless behind an adapter; watch for accidental fs, path, or process use.
• Content collections with glob() rely on file structure; renaming files without updating queries can produce empty pages at build time.
• Framework islands require the integration installed; an agent may write a React, Preact, or Vue component without checking astro.config.mjs.

Testing and verifying Astro output

Always run pnpm astro check before build, and pnpm build before merging. The agent can run these commands itself, but you should review the output. astro check catches type errors in templates and frontmatter, including content collection schema mismatches. pnpm build verifies static route generation, island bundling, and that getStaticPaths returned expected paths. If the repo has a test script, run it after build changes.

After a build, inspect dist/ for generated HTML and _astro/ for bundled islands. If the project has an adapter, run the preview command and hit a few routes before accepting the change.

Parallel agents on an Astro repo with AgentVera

On an Astro project, AgentVera helps when one agent updates content collection schemas while another refactors islands or fixes static build warnings. It runs real CLI agents in separate git worktrees, so parallel work does not overwrite the same .astro files. Automatic code review after each turn catches Astro-specific mistakes such as a missing getStaticPaths export or a schema change that breaks getCollection calls, and checkpoints let you undo a bad edit quickly. Token budgets prevent long build and debug loops from exhausting your limit. For more, see How to run multiple Claude Code agents in parallel.

Final notes on Claude Code and Astro

Claude Code is most useful on Astro projects when you give it a focused CLAUDE.md, use plan mode for complex changes, and verify with astro check and pnpm build. Keep an eye on content collection types, static path exports, and island client directives. With those guardrails, it handles repetitive Astro work reliably.