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.

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

# 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 `<img>` tags. Use the framework's image component:
  - Astro: `<Image />` from `astro:assets`
  - Next.js: `<Image />` from `next/image`
- Serve images in WebP or AVIF. No JPEG/PNG without a `<picture>` 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):
  `<link rel="preload" as="font" type="font/woff2" crossorigin>`.
  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 `<head>` must have `defer` or `async`. No synchronous
  scripts in `<head>` — 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 <package>` 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 `<style>` in the `<head>`. Non-critical
  CSS must be loaded asynchronously (`rel="preload" as="style"` + `onload` swap trick
  or the framework's equivalent).

## HTML and document structure
- Set `<meta name="viewport" content="width=device-width, initial-scale=1">` on
  every page. Missing this causes mobile browsers to render at desktop width.
- Use `<link rel="preconnect">` for essential third-party origins (CDNs, API hosts)
  that are always needed on page load. Limit to 3 or fewer origins.
- Minify HTML output. Astro and Next.js do this by default — do not disable it.

## Definition of done
- `astro build` or `next build` completes without warnings.
- Lighthouse performance score ≥ 90 on mobile for any changed page.
- No `<img>` tags without `width`/`height` (CLS protection).
- No render-blocking `<script>` in `<head>`.
- `web-vitals` test (`npx unlighthouse --site localhost:4321`) shows LCP < 2.5 s.

Why these rules

Images with explicit dimensions (CLS prevention) is the most commonly missed performance rule in AI-generated code. Agents that write <img src="..."> without width and height attributes cause the page to reflow when the image loads, producing CLS scores that can tank a site’s ranking. The fix is mechanical — always provide dimensions — but agents omit it unless explicitly told.
Self-hosted fonts eliminates a render-blocking cross-origin request that consistently delays LCP by 200–400 ms on typical connections. Agents default to Google Fonts <link> tags from familiarity — they are fine for development but are measurably slower than self-hosted fonts with font-display: swap.

Good fit

Public-facing static sites, marketing pages, blogs, and documentation where Core Web Vitals directly affect search ranking and user conversion.

Not a fit

Internal dashboards or authenticated applications where users are on reliable connections and SEO ranking is irrelevant — the performance constraints are real but the business impact is lower.

AI Coding Rules for Static Site Performance

AGENTS.md

Why these rules

Good fit

Not a fit

Related