{
"id": "ai-rules-for-static-site-performance",
"type": "rules",
"category": "rules",
"locale": "en",
"url": "/rules/ai-rules-for-static-site-performance",
"title": "AI Coding Rules for Static Site Performance",
"description": "AGENTS.md rules for static site performance that enforce Core Web Vitals, image optimization, font loading, and prevent agents from shipping render-blocking resources.",
"tools": [
"Cursor",
"Claude Code",
"Codex",
"Windsurf"
],
"stack": [
"Astro",
"Next.js",
"TypeScript",
"Tailwind"
],
"tags": [
"agents-md",
"astro",
"nextjs",
"tailwind",
"seo",
"conventions"
],
"difficulty": null,
"updated": "2026-06-08",
"markdown": "Drop this in your repo root as `AGENTS.md`. Performance rules are especially important for AI-generated code because agents optimise for correctness and rarely consider bundle size, render-blocking resources, or layout shift without explicit instruction.\n\n## AGENTS.md\n\n```md title=\"AGENTS.md\"\n# Project Rules — Static Site Performance\n\n## Core Web Vitals targets\n- LCP (Largest Contentful Paint): < 2.5 s on a simulated 4G mobile connection.\n- CLS (Cumulative Layout Shift): < 0.1. All images, ads, and embeds must have\n explicit `width` and `height` attributes (or `aspect-ratio` CSS) to reserve space.\n- FID / INP (Interaction to Next Paint): < 200 ms. Minimise main-thread JavaScript.\n- These are not aspirational — they are definition-of-done criteria for any page change.\n\n## Images — highest impact\n- Never use bare `` tags. Use the framework's image component:\n - Astro: `` from `astro:assets`\n - Next.js: `` from `next/image`\n- Serve images in WebP or AVIF. No JPEG/PNG without a `` element with\n a next-gen format source.\n- Hero images (above the fold) must use `loading=\"eager\"` and `fetchpriority=\"high\"`.\n All other images use `loading=\"lazy\"` (the default in the framework image components).\n- Never inline large base64-encoded images in HTML or CSS. Images above 2 KB should\n be served as separate files and cached by the CDN.\n- Always provide `alt` text. Decorative images use `alt=\"\"`. Informational images\n describe their content in under 125 characters.\n\n## Fonts\n- Fonts must be self-hosted (from `public/fonts/` or via the framework's font module).\n Never load fonts from Google Fonts in production — it adds a cross-origin DNS lookup\n and blocks rendering on slow connections.\n- Use `font-display: swap` in all `@font-face` declarations.\n- Preload only the primary font file (the weight used for body text):\n ``.\n Preloading every weight defeats the purpose.\n- Limit to 2 font families per site (e.g. one for headings, one for body). Every\n additional font family is an additional blocking resource.\n\n## JavaScript — bundle discipline\n- Every JS file added to the `` must have `defer` or `async`. No synchronous\n scripts in `` — they block HTML parsing.\n- Third-party scripts (analytics, chat widgets, consent banners) must be loaded after\n the page is interactive. Use `type=\"module\"` + dynamic `import()` or the framework's\n `client:idle` / `strategy=\"lazyOnload\"` equivalents.\n- Do not add a JavaScript dependency for something that can be done in CSS or HTML.\n Parallax, smooth scroll, sticky headers, and CSS animations do not need JavaScript.\n- Run `bundlephobia.com` or check `npx bundlephobia ` before adding any\n new npm package. Document the gzipped size in the PR description.\n\n## CSS\n- Tailwind CSS purges unused classes at build time — this is the correct approach.\n Do not add a global CSS file that imports every utility class from a library.\n- Never use `@import url(...)` inside a CSS file for non-local resources. This is\n a render-blocking network request.\n- Critical above-the-fold CSS may be inlined in `