KI-Codierregeln für die Leistung statischer Websites
AGENTS.md-Regeln für die Leistung statischer Websites, die Core Web Vitals, Bildoptimierung, Schriftarteinbindung durchsetzen und verhindern, dass Agenten renderblockierende Ressourcen ausliefern.
CursorClaude CodeCodexWindsurf AstroNext.jsTypeScriptTailwind
Legen Sie dies als AGENTS.md im Stammverzeichnis Ihres Repositorys ab. Leistungsregeln sind besonders wichtig für KI-generierten Code, da Agenten auf Korrektheit optimieren und ohne explizite Anweisung selten Bundle-Größe, renderblockierende Ressourcen oder Layout-Verschiebungen berücksichtigen.
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.Warum diese Regeln
- Bilder mit expliziten Abmessungen (CLS-Verhinderung) ist die am häufigsten übersehene Leistungsregel in KI-generiertem Code. Agenten, die
<img src="...">ohnewidth- undheight-Attribute schreiben, verursachen ein erneutes Layout der Seite, wenn das Bild geladen wird, was zu CLS-Werten führt, die das Ranking einer Website zerstören können. Die Behebung ist mechanisch – stets Abmessungen angeben – aber Agenten lassen sie aus, wenn es nicht explizit angegeben wird. - Selbst gehostete Schriftarten eliminieren eine renderblockierende Cross-Origin-Anfrage, die die LCP bei typischen Verbindungen durchgängig um 200–400 ms verzögert. Agenten verwenden standardmäßig aus Gewohnheit Google Fonts
<link>-Tags – sie sind für die Entwicklung in Ordnung, aber messbar langsamer als selbst gehostete Schriftarten mitfont-display: swap.
Geeignet für
- Öffentliche statische Websites, Marketingseiten, Blogs und Dokumentationen, bei denen Core Web Vitals das Suchranking und die Benutzerkonversion direkt beeinflussen.
Nicht geeignet für
- Interne Dashboards oder authentifizierte Anwendungen, bei denen Benutzer zuverlässige Verbindungen haben und das SEO-Ranking irrelevant ist – die Leistungseinschränkungen sind real, aber die geschäftlichen Auswirkungen sind geringer.