{
"id": "ai-rules-for-static-site-performance",
"type": "rules",
"category": "rules",
"locale": "zh",
"url": "/zh/rules/ai-rules-for-static-site-performance",
"title": "静态网站性能的AI编码规则",
"description": "用于静态网站性能的AGENTS.md规则，强制执行核心网页指标、图片优化、字体加载，并防止代理发送阻塞渲染的资源。",
"tools": [
"Cursor",
"Claude Code",
"Codex",
"Windsurf"
],
"stack": [
"Astro",
"Next.js",
"TypeScript",
"Tailwind"
],
"tags": [
"agents-md",
"astro",
"nextjs",
"tailwind",
"seo",
"conventions"
],
"difficulty": null,
"updated": "2026-06-08",
"markdown": "将其放入仓库根目录，命名为 `AGENTS.md`。性能规则对于AI生成的代码尤为重要，因为代理会优化正确性，但很少考虑包大小、阻塞渲染的资源或布局偏移，除非有明确指示。\n\n## AGENTS.md\n\n```md title=\"AGENTS.md\"\n# Project Rules — Static Site Performance\n\n## Core Web Vitals targets\n- LCP (Largest Contentful Paint): < 2.5 s on a simulated 4G mobile connection.\n- CLS (Cumulative Layout Shift): < 0.1. All images, ads, and embeds must have\n explicit `width` and `height` attributes (or `aspect-ratio` CSS) to reserve space.\n- FID / INP (Interaction to Next Paint): < 200 ms. Minimise main-thread JavaScript.\n- These are not aspirational — they are definition-of-done criteria for any page change.\n\n## Images — highest impact\n- Never use bare `` tags. Use the framework's image component:\n - Astro: `` from `astro:assets`\n - Next.js: `` from `next/image`\n- Serve images in WebP or AVIF. No JPEG/PNG without a `` element with\n a next-gen format source.\n- Hero images (above the fold) must use `loading=\"eager\"` and `fetchpriority=\"high\"`.\n All other images use `loading=\"lazy\"` (the default in the framework image components).\n- Never inline large base64-encoded images in HTML or CSS. Images above 2 KB should\n be served as separate files and cached by the CDN.\n- Always provide `alt` text. Decorative images use `alt=\"\"`. Informational images\n describe their content in under 125 characters.\n\n## Fonts\n- Fonts must be self-hosted (from `public/fonts/` or via the framework's font module).\n Never load fonts from Google Fonts in production — it adds a cross-origin DNS lookup\n and blocks rendering on slow connections.\n- Use `font-display: swap` in all `@font-face` declarations.\n- Preload only the primary font file (the weight used for body text):\n ``.\n Preloading every weight defeats the purpose.\n- Limit to 2 font families per site (e.g. one for headings, one for body). Every\n additional font family is an additional blocking resource.\n\n## JavaScript — bundle discipline\n- Every JS file added to the `` must have `defer` or `async`. No synchronous\n scripts in `` — they block HTML parsing.\n- Third-party scripts (analytics, chat widgets, consent banners) must be loaded after\n the page is interactive. Use `type=\"module\"` + dynamic `import()` or the framework's\n `client:idle` / `strategy=\"lazyOnload\"` equivalents.\n- Do not add a JavaScript dependency for something that can be done in CSS or HTML.\n Parallax, smooth scroll, sticky headers, and CSS animations do not need JavaScript.\n- Run `bundlephobia.com` or check `npx bundlephobia ` before adding any\n new npm package. Document the gzipped size in the PR description.\n\n## CSS\n- Tailwind CSS purges unused classes at build time — this is the correct approach.\n Do not add a global CSS file that imports every utility class from a library.\n- Never use `@import url(...)` inside a CSS file for non-local resources. This is\n a render-blocking network request.\n- Critical above-the-fold CSS may be inlined in `