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