Règles de codage IA pour les performances des sites statiques

Règles AGENTS.md pour les performances des sites statiques qui imposent les Core Web Vitals, l'optimisation des images, le chargement des polices, et empêchent les agents d'envoyer des ressources bloquant le rendu.

Placez ce fichier dans la racine de votre dépôt sous le nom AGENTS.md. Les règles de performance sont particulièrement importantes pour le code généré par IA car les agents optimisent pour l’exactitude et tiennent rarement compte de la taille du bundle, des ressources bloquant le rendu ou du décalage de mise en page sans instruction explicite.

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.

Pourquoi ces règles

Images avec dimensions explicites (prévention CLS) est la règle de performance la plus souvent oubliée dans le code généré par IA. Les agents qui écrivent <img src="..."> sans attributs width et height provoquent un réaffichage de la page lorsque l’image se charge, produisant des scores CLS qui peuvent faire chuter le classement d’un site. La correction est mécanique — toujours fournir les dimensions — mais les agents l’omettent sauf instruction explicite.
Polices auto-hébergées élimine une requête inter-origine bloquant le rendu qui retarde régulièrement le LCP de 200 à 400 ms sur des connexions typiques. Les agents utilisent par défaut les balises <link> de Google Fonts par habitude — elles sont acceptables pour le développement mais sont sensiblement plus lentes que les polices auto-hébergées avec font-display: swap.

Bon adaptation

Sites statiques publics, pages marketing, blogs et documentation où les Core Web Vitals affectent directement le classement dans les moteurs de recherche et la conversion des utilisateurs.

Pas adapté

Tableaux de bord internes ou applications authentifiées où les utilisateurs ont des connexions fiables et où le classement SEO n’est pas pertinent — les contraintes de performance sont réelles mais l’impact commercial est moindre.

Règles de codage IA pour les performances des sites statiques

AGENTS.md

Pourquoi ces règles

Bon adaptation

Pas adapté

Connexes