Astro is built around one idea: ship less JavaScript. Islands architecture means only the interactive components hydrate on the client. Everything else is static HTML. It's a framework with strong opinions about what belongs on the server and what belongs on the client.
AI tools don't know those opinions. They know Astro exists. They don't know you're using Astro 4 or 5, whether you're using SSR or static output, which UI framework you've wired up for islands (React, Vue, Svelte, or none), or that adding client:load to every component defeats the entire purpose of using Astro.
The result: generated Astro code that technically works but sends megabytes of JavaScript to the browser, misuses the content collections API, puts server-only code in client components, and generates React patterns in .astro files.
A CLAUDE.md file locks in the context that makes Astro-specific AI generation correct. Here are 13 rules that fix the most common mistakes.
Rule 1: Declare your Astro version, output mode, and UI framework
