2025/AGENTS.md

AGENTS.md

Présentation du projet

Ce projet contient les sources de mon blog. Il s'agit d'un site statique généré avec Hugo, dont la version peut être vérifiée avec la commande hugo version.

Instructions générales

Interactions avec l'utilisateur

• L'utilisateur préfère être vouvoyé
• Répondre à l'utilisateur en français, quelle que soit la langue utilisée ailleurs
• Si une demande prête à confusion, demander une clarification à l'utilisateur plutôt que d'essayer de deviner
• L'utilisateur préfère considérer l'agent comme une entité féminine
• L'agent est un expert du développement web et maitrise toute technologie afférente
• L'utilisateur préfère qu'on s'adresse à lui avec un ton bienveillant, en utilisant un vocabulaire soutenu, approprié au contexte
• L'autisme de l'utilisateur doit être pris en compte au cours des échanges
• L'utilisateur peut parfois perdre patience : la discussion doit être désamorcée rapidement par une solution que l'agent mettra en place, testera et modifiera jusqu'à ce qu'elle produise le résultat escompté
• L'agent peut utiliser la commande manage validate all à la place d'une reconstruction du site par la commande hugo. Cette commande lance la construction du site en mode "production", et permet de vérifier la validité des pages HTML, de la feuille de style et du flux RSS
• L'agent devra considérer les avertissements de cette validation comme des erreurs, à l'exception de l'avertissement Self reference doesn't match document location dans la validation du flux RSS

Git

• Ne jamais faire de git push automatiquement, sauf si demandé explicitement
• Les commits doivent être atomiques
• Les commits sont écrits en français UTF-8
• Aucun commit ne doit être effectué sans demande explicite de l'utilisateur
• Éviter d'exécuter des commandes Git en parallèle dès qu'au moins l'une d'elles peut toucher à l'index ou aux références ; préférer une exécution strictement séquentielle
• En cas d'erreur Unable to create .../.git/index.lock, vérifier d'abord qu'aucun autre processus Git local n'est actif ; si aucun processus n'utilise le dépôt et que le fichier .git/index.lock existe encore, le supprimer puis relancer la commande, de manière séquentielle

Outils en console

• L'agent peut se servir du script manage présent à la racine du projet pour gérer divers aspects du site
• L'agent peut interroger ce script pour obtenir de l'aide (--help)
• Lors des tests locaux ou du profilage de génération Hugo, l'agent peut définir MEILI_SEARCH_API_KEY=dummy pour éviter qu'une valeur absente ne bloque inutilement l'analyse

CSS

• Le CSS doit rester le plus simple possible
  • On ne doit pas exploiter d'effets visuels complexes tels que les agrandissements, les shifts, les apparitions ou disparitions progressives, etc.
• Le code CSS doit respecter les règles d'accessibilité pour le contenu, notamment :
  • Taille des polices
  • Contrastes entre le texte et le fond de son container
• On doit créer le moins de classes possibles, et préférer styliser les balises HTML directement
• On peut utiliser la notation imbriquée (nested) par mesure de lisibilité

Instructions relatives aux articles

• Utiliser exclusivement les apostrophes (') et les guillemets (") non-typographiques
• Une phrase par ligne
• Ne jamais terminer une ligne par un double-espace
• Utiliser un français UTF-8

Structure du contenu

• Tout le contenu publié réside dans le dossier content/
• Un dossier contenant un fichier index.md est un bundle
• Tous les articles sont des bundles
• Si un dossier ne contient pas de fichier index.md, c'est une section
• Une section ne contenant que des bundles est une section-feuille, autrement appelée thématique
• Un bundle peut contenir :
  • Un ou plusieurs dossiers images, diagrams, sounds, videos, contenant les pièces jointes du bundle
  • Un dossier data, pouvant notamment contenir des métadonnées associées aux pièces jointes

Sections de premier niveau

Collections (content/collections/)

• Les premiers dossiers, enfants directs de content/collections/, désigne une marque proposant des objets que je collecte ; ce sont les dossiers de marque
  • content/collections/lego contient ma collection d'objets LEGO.
• Chaque dossier de marque peut contenir un ou plusieurs dossiers de thèmes
  • content/collections/lego/jurassic-world contient ma collection d'objets LEGO sur le thème de Jurassic World
• Chaque dossier de thème contient un ou plusieurs bundes d'objets de collection, chacun représentant un et un seul objet

Critiques (content/critiques/)

• Contient mes critiques de médias (liste non exhaustive, pouvant évoluer avec le temps) :
  • content/critiques/films pour mes critiques de films
  • content/critiques/series pour mes critiques de séries TV
  • content/critiques/jeux-video pour mes critiques de jeux-vidéo
  • content/critiques/livres pour mes critiques de livres
• Chaque média contient directement un ou plusieurs bundles représentant l'oeuvre critiquée
• Le titre original est utilisé, pas le titre français

Intérêts (content/interets/)

• Articles de fond sur des sujets qui m'intéressent
• Ce dossier contient un sous-dossier par thématique principale
  • astronomie
  • microscopie
  • informatique
  • etc.
• Chaque thématique contient une arborescence structurée en année, mois, jour et bundles
  • Exemple : Si l'on découpe le chemin physique content/interets/electronique/2025/10/21/pilotage-d-un-switch-usb-par-le-wifi, on sait qu'on est dans le bundle pilotage-d-un-switch-usb-par-le-wifi, publié le 21/10/2025 dans la section électronique

Liens intéressants (content/interets/liens-interessants)

• Cette section a le même usage que l'application Shaarli : je m'en sers pour partager avec mes lecteurs mes trouvailles sur Internet
• Chaque lien intéressant est publié sous forme de bundle, avec au minimum un frontmatter renseignant l'attribut links
• Si une description est trouvée, elle est ajoutée dans le corps du fichier index.md
• Je peux éventuellement ajouter un commentaire personnel dans le corps du fichier index.md, mais ce n'est pas systématique

Pièces jointes

• Un bundle peut contenir une ou plusieurs pièces jointes, selon leur type parmi (liste non exhaustive et pouvant évoluer avec le temps) :
  • images
  • videos
  • sounds
  • diagrams
• Chaque pièce jointe peut être accompagnée de métadonnées placées dans le dossier data du bundle
  • Par exemple, l'image {chemin du bundle}/images/1.png peut avoir un fichier de métadonnées placé dans {chemin du bundle}/data/images/1.yaml

Métadonnées

• Un fichier de métadonnées d'une pièce jointe à un bundle est nécessairement au format yaml, doté des attributs suivants :
  • title : Titre du document (utilisé par l'attribut HTML title)
  • description : Description libre ajoutée au document (affiché dans une balise figcaption par exemple)
  • attribution : Si le fichier n'a pas été créé par l'utilisateur
  • prompt : Si le fichier a été généré par l'Intelligence Artificielle, cet attribut doit contenir le prompt utilisé pour le générer
• Aucun attribut de ce fichier n'est requis ; ils peuvent rester vides ou être précédés par le caractère #
• Le fichier de métadonnées n'est pas requis ; s'il existe, il peut être vide

Frontmatter

• Tout fichier index.md doit avoir un frontmatter contenant au moins les attributs suivants :

  • title : Titre que je donne à mon article
  • date : Si possible avec l'heure, mais la majorité de mes articles actuels ne contiennent que la date

• Le frontmatter peut contenir d'autres attributs optionnels, autres que les taxonomies :

  • cover : Chemin vers l'image illustrant l'article. Cette image doit être stockée dans le dossier {chemin du bundle}/images/. Elle sera utilisée pour générer la vignette de l'article, et affichée en en-tête de l'article. Je la désigne par cover, image de couverture, ou image d'en-tête

  • dossier : Plusieurs bundles partageant une même valeur pour l'attribut dossier seront regroupés dans un dossier virtuel tout en résidant physiquement dans leurs dossiers physiques respectifs

    • Exemple : dossier: [ "Exploitation de mes données météo" ]

    • Cet attribut devrait être complété par un attribut weight

      • Par exemple :

      dossier: [ "Exploitation de mes données météo" ]
      weight: 10
      

    • links : Peut contenir un ou plusieurs objets indiquant des liens associés au bundle. Par exemple :

    links:
    - name: Page d'origine
      url: https://openbadgefactory.com/obv3/credentials/f421c3c8ae974fa2191b3482b05f37b4e1bc8c4b
      lang: fr
    

    - Les attributs `name` (titre du document) et `url` sont requis
    - L'attribut `lang` ne doit être renseigné **que** si l'on connait avec certitude la langue du document distant
    

• Le frontmatter doit être séparé du corps de l'article par une ligne vide

Markdown

• Lorsque l'utilisateur demande à être aidé pour la rédaction de ses articles, employer un ton neutre, utiliser un vocabulaire soutenu mais approprié au sujet traité
• Rester neutre, objectif, factuel
• Présenter des sources vérifiables lors de toute affirmation portant sur un concept-clé, sous la forme de liens markdown vers :
  • la Wikipédia en français (ou à défaut, en anglais)
  • une ou plusieurs études scientifiques, si approprié
• Corriger l'attribut date du frontmatter lorsqu'il est renseigné mais incomplet, pour indiquer la date et l'heure courante, au format 2026-03-28 18:04:56. Ne jamais ajouter l'attribut s'il n'existe pas déjà.
• Les sections démarrent toujours au deuxième niveau dans le corps du markdown (##)
• Ne jamais ajouter de numérotation aux sections
• Ne jamais utiliser de caractères comme les emojis dans les sections
• Ne jamais utiliser de séparateurs (--- ou ***)
• Ne jamais ajouter d'émojis dans le corps de l'article
• Ne jamais supprimer les émojis existants