静态网站性能的AI编码规则

用于静态网站性能的AGENTS.md规则，强制执行核心网页指标、图片优化、字体加载，并防止代理发送阻塞渲染的资源。

将其放入仓库根目录，命名为 AGENTS.md。性能规则对于AI生成的代码尤为重要，因为代理会优化正确性，但很少考虑包大小、阻塞渲染的资源或布局偏移，除非有明确指示。

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.

为什么需要这些规则

带显式尺寸的图片（防止CLS） 是AI生成代码中最常被忽略的性能规则。代理在编写 <img src="..."> 时如果不带 width 和 height 属性，会导致页面在图片加载时重新布局，产生可能拖累网站排名的CLS分数。修复方法是机械性的——始终提供尺寸——但除非明确告知，否则代理会忽略。
自托管字体 消除了一个阻塞渲染的跨域请求，该请求在典型连接上通常会使LCP延迟200–400毫秒。代理出于熟悉而默认使用Google Fonts的 <link> 标签——这在开发中没问题，但比带有 font-display: swap 的自托管字体明显更慢。

适用场景

面向公众的静态网站、营销页面、博客和文档，其中Core Web Vitals直接影响搜索排名和用户转化。

不适用场景

内部仪表盘或需要身份验证的应用程序，用户使用可靠连接且SEO排名无关紧要——性能约束是真实存在的，但业务影响较小。

静态网站性能的AI编码规则

AGENTS.md

为什么需要这些规则

适用场景

不适用场景

相关