167 lines
9.6 KiB
Markdown
167 lines
9.6 KiB
Markdown
# 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 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 :
|
|
|
|
```json
|
|
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 :
|
|
|
|
```json
|
|
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
|