Astro Context Guide for AI Coding (llms.txt + Rules + MCP)
The web framework for content-driven websites. Zero-JS by default, islands architecture, and markdown-first.
1. Astro Official llms.txt & Clean Markdown Documentation
Official Docs MapFeed this clean, token-efficient Markdown documentation directly to Antigravity, Cursor, or Claude Code to prevent hallucinations and outdated API syntax.
# Standard llms.txt Index Endpoint
https://docs.astro.build/llms.txt
# Comprehensive Documentation Bundle
https://docs.astro.build/llms-full.txt
Estimated Token Footprint: ~27k tokens (Fits smoothly inside standard 128k/1M context windows)
2. Production-Ready Astro Cursor Rules (.cursorrules & .mdc)
Astro Islands architecture, Content Collections, and hybrid rendering rules. Save this into .cursor/rules/astro.mdc in your project repository.
// Astro Best Practices
- Ship zero client-side JavaScript by default; hydrate UI with client:load / client:visible only when necessary.
- Define content schemas with defineCollection and zod in src/content/config.ts.
- Use Astro's built-in Image and Picture components for automatic WebP/AVIF asset optimization.
- Prefer static site generation (SSG) for content pages; use hybrid SSR only for authenticated routes.3. Astro Antigravity & Claude Code System Instructions
Add this concise instruction block to your workspace .gemini/rules or project system prompt.
// Context Anchor for Astro
When writing code for Astro, refer directly to the verified specifications at https://docs.astro.build/llms.txt.
Follow strict error-handling and avoid deprecated API calls.5. Troubleshooting: Common Astro AI Coding Issues & Fixes
Frequently reported errors when LLMs generate Astro code without proper context:
⚠️ Proactive Fix: Fix: Hydration mismatch happens when interactive components depend on window or localStorage during SSR.
6. Best Used With (Astro Architecture Combos)
Engineers building with Astro frequently combine these complementary developer frameworks: