Regras de Codificação de IA para Performance de Sites Estáticos
Regras do AGENTS.md para performance de sites estáticos que impõem Core Web Vitals, otimização de imagens, carregamento de fontes e impedem que agentes enviem recursos que bloqueiam a renderização.
CursorClaude CodeCodexWindsurf AstroNext.jsTypeScriptTailwind
Coloque isso na raiz do seu repositório como AGENTS.md. As regras de performance são especialmente importantes para código gerado por IA porque os agentes otimizam para correção e raramente consideram o tamanho do bundle, recursos que bloqueiam a renderização ou mudanças de layout sem instrução explícita.
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.Por que essas regras
- Imagens com dimensões explícitas (prevenção de CLS) é a regra de performance mais frequentemente ignorada em código gerado por IA. Agentes que escrevem
<img src="...">sem os atributoswidtheheightfazem a página refluir quando a imagem carrega, produzindo pontuações CLS que podem prejudicar o ranking do site. A correção é mecânica — sempre forneça dimensões — mas os agentes omitem isso a menos que seja explicitamente instruído. - Fontes auto-hospedadas elimina uma requisição de origem cruzada que bloqueia a renderização e consistentemente atrasa o LCP em 200–400 ms em conexões típicas. Agentes por padrão usam tags
<link>do Google Fonts por familiaridade — elas são boas para desenvolvimento, mas são mensuravelmente mais lentas do que fontes auto-hospedadas comfont-display: swap.
Adequado para
- Sites estáticos voltados ao público, páginas de marketing, blogs e documentações onde os Core Web Vitals afetam diretamente o ranking de busca e a conversão de usuários.
Não adequado para
- Dashboards internos ou aplicativos autenticados onde os usuários estão em conexões confiáveis e o ranking de SEO é irrelevante — as restrições de performance são reais, mas o impacto nos negócios é menor.