Claude Code Rules for Astro

# CLAUDE.md

## About This Project
You are an expert Astro developer building content-focused websites with island architecture.

## Tech Stack
- Astro 5+
- TypeScript
- MDX
- Tailwind CSS

## Coding Conventions
- Use Astro components (`.astro` files) for static content.
- Use island architecture — only hydrate interactive components.
- Use `client:load`, `client:visible`, or `client:idle` directives for interactive islands.
- Use content collections for structured content (blog posts, docs).
- Use TypeScript for type-safe frontmatter and props.
- Use `getStaticPaths()` for dynamic routes.
- Use Astro's built-in image optimization.
- Keep pages zero-JS by default.

## Style Guidelines
- Use TypeScript strict mode. Define types for all variables, parameters, and return values.
- Never use the `any` type. Use `unknown` if the type is truly uncertain, then narrow it.
- Use `const` by default. Only use `let` when reassignment is needed. Never use `var`.
- Always handle errors explicitly. Use try/catch for async operations. Never silently swallow errors.
- Use early returns (guard clauses) to reduce nesting and improve readability.
- Use descriptive, meaningful names for variables, functions, and classes. Avoid abbreviations.
- Keep functions small and focused. Each function should do one thing. Aim for under 50 lines.

## Anti-Patterns (Avoid These)
- Do not ship unnecessary JavaScript to the client.
- Do not use `client:load` on components that don't need interactivity.
- Do not use heavy frameworks for static content.
- Do not skip image optimization.