{
  "id": "agents-md-for-astro-static-site",
  "type": "rules",
  "category": "rules",
  "locale": "fr",
  "url": "/fr/rules/agents-md-for-astro-static-site",
  "title": "Règles AGENTS.md pour un site statique Astro",
  "description": "Un AGENTS.md prêt à l'emploi pour les sites statiques Astro qui maintient les agents IA dans la pile, évite les dérives SSR et impose les conventions de collecte de contenu.",
  "tools": [
    "Cursor",
    "Claude Code",
    "Codex",
    "Windsurf"
  ],
  "stack": [
    "Astro",
    "TypeScript",
    "Tailwind"
  ],
  "tags": [
    "agents-md",
    "astro",
    "typescript",
    "tailwind",
    "conventions",
    "seo"
  ],
  "difficulty": null,
  "updated": "2026-06-08",
  "markdown": "Placez ceci dans la racine de votre dépôt sous le nom `AGENTS.md`. Les agents ciblant Astro (Cursor, Claude Code, Codex) le lisent automatiquement au démarrage et l'utilisent pour rester conformes aux conventions à chaque session de génération de code.\n\n## AGENTS.md\n\n```md title=\"AGENTS.md\"\n# Project Rules — Astro Static Site\n\n## Stack\n- Astro 5 (static output, `output: \"static\"`). No SSR adapter unless explicitly requested.\n- TypeScript strict mode. All `.astro` component scripts are TypeScript.\n- Tailwind CSS v4. No CSS-in-JS. No inline `style` attributes unless value is truly dynamic.\n- Content managed via Astro Content Collections (Zod schemas in `src/content.config.ts`).\n\n## Hard rules\n- Never switch `output` to `\"server\"` or `\"hybrid\"` — this is a static build.\n- Never add `client:load` to a component that does not require browser interactivity.\n  Prefer `client:idle` or `client:visible` when a client directive is genuinely needed.\n- All content files live in `src/content/<collection>/`. Do not create ad-hoc markdown\n  files outside a defined collection.\n- Frontmatter must match the Zod schema in `src/content.config.ts`. Validate before\n  writing — wrong field names cause build failures, not runtime errors.\n- Images must go through Astro's `<Image />` component or `getImage()` helper.\n  Never use bare `<img>` tags — they bypass optimisation and break CLS scores.\n- Never read environment variables with `import.meta.env` inside a `.ts` utility that\n  may be imported on the client; mark those files with a `// server-only` comment and\n  import them only from `.astro` files or API endpoints.\n- Do not add a dependency without stating the reason. Prefer Astro-native solutions\n  (content collections, view transitions, image optimisation) before reaching for npm.\n\n## Conventions\n- Components live in `src/components/`. Page layouts live in `src/layouts/`.\n  One component per file; file name matches the exported component name.\n- Route pages live under `src/pages/`. Dynamic routes use bracket notation:\n  `src/pages/[slug].astro`. Static paths are generated via `getStaticPaths()`.\n- Shared TypeScript utilities live in `src/lib/`. Import with the `@/` alias\n  (configured in `tsconfig.json`).\n- Tailwind classes follow mobile-first order: base → `sm:` → `md:` → `lg:`.\n  No arbitrary values unless a design token does not exist.\n- Every page component must export a `<meta>` block via the layout that includes\n  `title`, `description`, and Open Graph tags.\n\n## SEO conventions\n- Every `src/pages/*.astro` page must render a canonical `<link rel=\"canonical\">`.\n- Blog / content pages must include `datePublished` and `dateModified` in\n  JSON-LD structured data.\n- Do not create two pages that share the same `<title>` or `<meta name=\"description\">`.\n\n## Definition of done\n- `astro check` passes with zero errors.\n- `astro build` completes without warnings.\n- Lighthouse performance score ≥ 90 on a representative page (run `unlighthouse`).\n- No new `any` types. No unused imports.\n- All new content frontmatter passes the Zod schema (`bun run typecheck`).\n```\n\n## Pourquoi ces règles\n\n- **\"Ne jamais passer la sortie en serveur\"** est la règle la plus efficace pour les sites statiques Astro. Les agents qui découvrent une fonctionnalité manquante suggèrent souvent d'ajouter un adaptateur SSR comme solution rapide — cela change silencieusement la cible de déploiement, casse le cache CDN et ajoute de la latence de démarrage à froid. La règle oblige les agents à résoudre les problèmes dans le paradigme statique.\n- **\"Les images doivent passer par `<Image />`\"** élimine l'erreur IA la plus courante sur les sites de contenu : les balises `<img>` nues qui dégradent les Core Web Vitals. Le pipeline d'images d'Astro gère automatiquement la conversion de format, le `srcset` responsive et le chargement différé — les agents le contournent sauf indication explicite.\n- **La validation du frontmatter avec Zod** détecte les incohérences de schéma au moment de la vérification de type plutôt qu'à la construction ou, pire, en rendant silencieusement des données erronées. Les agents qui écrivent des fichiers markdown hallucinent souvent les noms des champs du frontmatter.\n\n## Bon usage\n\n- Sites marketing, blogs, sites de documentation et sites de contenu axés sur le SEO construits avec Astro et une cible de sortie statique fixe.\n\n## Pas adapté\n\n- Projets Astro utilisant `output: \"server\"` ou `\"hybrid\"` avec un adaptateur edge/SSR — ceux-ci nécessitent un ensemble de règles différent qui autorise `client:load` et les modèles de récupération de données côté serveur."
}