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é

Git

• Ne jamais faire de git push automatiquement, sauf si demandé explicitement
• Les commits doivent être atomiques
• Les commits sont écrits en français
• Aucun commit ne doit être effectué sans demande explicite de l'utilisateur

Code

• Le code doit être architecturé, propre, clair, concis, minimaliste
  • Préférer la création de plusieurs petits fichiers pour éviter le code monolithique
  • Ne pas implémenter de fonctionnalités non demandées
  • Respecter les principes DRY, KISS et SOLID
  • Si une librairie existe pour accomplir une tâche donnée, exploiter cette librairie
    • S'assurer de sa popularité et de son activité récente
• Le code doit être écrit en anglais mais documenté en français, lisible par un humain
  • Documenter clairement toutes les fonctions et méthodes
  • Choisir des noms de variables appropriées et compréhensibles, tout en restant courts
  • Ne JAMAIS utiliser d'opérateurs ternaires
• La gestion des erreurs est considérée comme dangereuse
  • On ne doit jamais utiliser de fallbacks
  • On ne doit jamais utiliser de structures de type try/catch
• Le code est écrit pour être spécifique à mon site
  • Je suis l'unique utilisateur des outils créés
  • Le code doit être compris de tous, mais pas adaptable à tous

Outils en console

• S'assurer de l'harmonisation des entrées/sorties
  • Toujours utiliser le français dans les interactions avec l'utilisateur
• Pour toute vérification locale avec Hugo, l'agent doit isoler son instance de celle de l'utilisateur
  • En mode serveur: hugo server --port 1314 --renderToDisk --destination .codex/public
  • En mode build: hugo --cleanDestinationDir --destination .codex/public
  • Ne pas utiliser public/ pour ces vérifications afin d'éviter les conflits de cache

Python

• Accéder à l'environnement virtuel via la commande source .venv/bin/activate
• Renseigner les dépendances dans le fichier requirements.txt

Javascript

• Mettre à jour régulièrement les dépendances
• Auditer régulièrement les dépendances avec npm audit

CSS

• Le thème de base est nommé 42 (themes/42) (référence à H2G2, mais aussi parce que je l'ai créé à l'occasion de mon anniversaire)
• Je n'utilise aucun framework connu ; je fais du CSS "vanilla"
• Nous ne supporterons jamais de thème clair
• Il fait usage de variables CSS définies dans themes/42/assets/css/variables
• L'agent peut créer de nouvelles variables, à condition de respecter les conventions de nommage des autres variables
• Ce thème de base peut être hérité par d'autres thèmes
  • Le thème par défaut est actuellement themes/default
  • Un thème hérité n'est censé devoir surcharger que les variables qualifiées "d'esthétique" (telles que les couleurs ou les effets visuels), par opposition aux variables qualifiées de "structurelles" (telles que les marges ou le positionnement)
• 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

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 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, dans un format supporté par Hugo. 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 ajouter d'émojis dans le corps de l'article
• Ne jamais supprimer les émojis existant

Déploiement

• Tout le déploiement du site est confié au script deploy.sh.
• Certains scripts sont exécutés avant le déploiement. S'ils modifient des fichiers dans content/, leur exécution doit stopper le déploiement et informer l'utilisateur que des fichiers ont été modifiés
  • Exploiter set -euo pipefail pour éviter les blocs if à chaque script