Johan409IA/skills

Project Docs

Aide à créer et à maintenir à jour l'ensemble de la documentation d'un projet logiciel, en suivant une structure fixe et une relation définie entre AGENTS.md et MEMORY.md. Utilisez cette compétence à chaque fois que l'utilisateur souhaite une documentation générée de zéro, rafraîchie après des modifications ou maintenue cohérente entre les fichiers.

Structure cible

Tout projet géré par cette compétence doit converger vers cette organisation :

mon-projet/
├── README.md          # qu'est-ce que c'est, comment l'exécuter
├── AGENTS.md           # règles et instructions pour les agents
├── MEMORY.md            # décisions en vigueur et ce qui a été abandonné
├── CHANGELOG.md          # ce qui a changé entre les versions
├── DESIGN.md             # système de design visuel (uniquement s'il y a une IHM)
└── docs/
    ├── architecture.md
    ├── plans/            # plans des agents, un par fichier
    └── (OpenAPI + Scalar servi depuis l'API dans /docs)

Si le projet possède déjà certains de ces fichiers, lisez-les d'abord et mettez-les à jour sur place — n'écrasez pas aveuglément. Si un fichier manque, créez-le en suivant le modèle correspondant ci-dessous.

Workflow

1. Inventoriez ce qui existe. Listez la racine du projet et docs/ pour voir quels fichiers sont déjà présents. Lisez intégralement les éventuels AGENTS.md/MEMORY.md/CHANGELOG.md/README.md/docs/architecture.md existants — ils sont conçus pour être courts.
2. Déterminez le périmètre. Si l'utilisateur nomme un fichier précis (« mets à jour le CHANGELOG »), concentrez-vous dessus, mais vérifiez quand même si ce changement doit se répercuter dans MEMORY.md ou AGENTS.md (voir la règle de propagation ci-dessous). Si l'utilisateur dit quelque chose de général comme « documente mon projet » ou « mets à jour la documentation », parcourez chaque fichier de la structure ci-dessus.
3. Collectez les faits nécessaires à partir du code source lui-même (manifestes de paquets, points d'entrée, scripts, routes, commits récents) plutôt que de deviner. N'inventez pas de commandes, de détails de pile technique ou de points d'accès — vérifiez-les en lisant le code ou les fichiers de configuration.
4. Écrivez ou mettez à jour chaque fichier en utilisant le modèle de référence correspondant. Respectez les limites de taille strictes de AGENTS.md (~30-40 lignes) et MEMORY.md (~50 lignes) — ce sont des contraintes structurelles, pas des suggestions, car les agents relisent ces fichiers à chaque session et des versions trop longues cessent d'être utiles.
5. Faites un rapport indiquant quels fichiers ont été créés vs. mis à jour, et signalez tout ce que vous n'avez pas pu vérifier (par exemple « je n'ai pas trouvé de commande de test, confirme-la »).

Les documents

README.md

Répond à la question « qu'est-ce que c'est et comment l'exécuter » pour un humain. Voir references/readme-template.md. Extrayez les commandes d'exécution/installation/test directement des scripts réels du projet (package.json, Makefile, pyproject.toml, etc.) — ne devinez jamais les noms de commandes.

AGENTS.md

Instructions pour les agents de codage travaillant dans ce dépôt. Voir references/agents-template.md pour les sections exactes et leur ordre. Limite stricte : ~30-40 lignes au total. S'il est déjà plus long, votre travail lors de la mise à jour consiste autant à réduire qu'à ajouter — déplacez tout ce qui ressemble à une décision transitoire ou à une note de travail en cours dans MEMORY.md à la place, et ne conservez ici que les règles durables.

MEMORY.md

Mémoire de session à session : ce qui est vrai en ce moment, pourquoi les décisions clés ont été prises, ce qui a été essayé et rejeté, la suite. Voir references/memory-template.md. Limite stricte : ~50 lignes. Lors de la mise à jour, élaguez activement — supprimez ou compressez les entrées qui ne sont plus pertinentes plutôt que de laisser le fichier grossir indéfiniment.

Relation entre AGENTS.md et MEMORY.md (c'est la convention centrale — appliquez-la correctement) :

• AGENTS.md doit contenir une courte section « Mémoire » ordonnant aux agents de lire MEMORY.md au début d'une tâche et de le mettre à jour à la fin. Utilisez ce libellé exact comme base, en adaptant uniquement si le projet le formule déjà différemment :

  ## Mémoire
  - Au début, lis `MEMORY.md` pour connaître l'état du projet et les décisions prises.
  - À la fin d'une tâche, mets-le à jour : état actuel, décisions importantes (avec leur pourquoi) et erreurs à éviter.
  - Reste bref (maximum ~50 lignes) : résume ou supprime ce qui n'apporte plus rien.
  - Si quelque chose devient une règle permanente, propose de le déplacer dans `AGENTS.md` plutôt que de le laisser dans la mémoire.
  - Ne stocke jamais de données sensibles (clés, jetons, données personnelles).
  

• La section « Limites » de AGENTS.md doit inclure ✅ Toujours : mettre à jour MEMORY.md après chaque tâche.
• Règle de propagation : MEMORY.md contient ce qui est vrai pour le moment — état actuel, décisions avec leur raisonnement, leçons apprises, prochaines étapes. AGENTS.md contient ce qui est vrai toujours — règles permanentes, conventions, pile technique, limites. Lorsque quelque chose dans MEMORY.md cesse d'être une décision ponctuelle et devient une règle permanente (par exemple « nous avons décidé de ne jamais utiliser X » devient « n'utilise jamais X, point final »), remontez-le dans AGENTS.md et supprimez-le de MEMORY.md. Lors de la mise à jour de l'un ou l'autre fichier, vérifiez toujours si cette promotion doit avoir lieu.
• N'écrivez jamais de secrets, jetons ou données personnelles dans l'un ou l'autre fichier.

CHANGELOG.md

Répond à la question « ce qui a changé entre les versions. » Suivez la convention Keep a Changelog (Added/Changed/Fixed/Removed sous chaque version, la plus récente en haut, avec une section Unreleased en haut pour le travail en cours). Voir references/changelog-template.md. Lors de la mise à jour, ajoutez des entrées sous Unreleased au fur et à mesure du travail, et ne créez une nouvelle section de version datée que lorsque l'utilisateur indique une publication.

DESIGN.md

Répond à la question « à quoi ça ressemble et comment l'interface doit-elle être construite » — le système de design visuel, lu par les agents qui génèrent l'interface. Il se trouve à la racine du projet (pas dans docs/), à côté de AGENTS.md. Il suit le format ouvert Google Stitch DESIGN.md (spécification : github.com/google-labs-code/design.md, actuellement alpha). Voir references/design-template.md pour le modèle et une explication de chaque bloc.

• Uniquement pour les projets avec une interface utilisateur (web, mobile, desktop). Si le projet est une API/CLI/bibliothèque pure sans interface, ne le créez pas et mentionnez-le dans le rapport.
• Deux couches : un front-matter YAML avec des jetons lisibles par machine (colors, typography, rounded, spacing, components) — ce sont les valeurs normatives — plus un corps markdown qui explique le pourquoi. Les jetons disent quoi ; la prose dit quand et pourquoi et fait référence aux jetons par leur nom au lieu de répéter les codes hexadécimaux.
• L'ordre des sections est fixe : Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts. Conservez ces en-têtes en anglais exactement comme écrits (les outils les correspondent par nom ; les alias Brand & Style, Layout & Spacing et Elevation sont également acceptés) et écrivez la prose dans la langue du projet. Les sections peuvent être omises mais pas réordonnées, et un en-tête dupliqué est une erreur. Des sections supplémentaires (par exemple Iconography & Imagery, Motion, Accessibility) sont autorisées — placez-les toujours après Do's and Don'ts.
• Prenez les valeurs du code, ne les inventez jamais : configuration Tailwind, variables CSS (:root, globals.css), fichiers de thème de bibliothèque d'interface, polices chargées, exportations de jetons Figma/DTCG. Si le projet a une interface mais pas d'identité visuelle définie, proposez des valeurs et signalez-les dans le rapport comme « proposé, à confirmer ».
• Si un DESIGN.md existe déjà, lisez-le et mettez-le à jour sur place — ne l'écrasez jamais silencieusement. Maintenez les jetons synchronisés avec le code lorsque les couleurs, polices ou espacements changent.
• Pas de limite de ligne stricte (c'est un document de référence comme docs/architecture.md), mais gardez chaque section ciblée : 3 à 6 puces ou un court paragraphe.
• Validez : si Node est disponible, exécutez npx @google/design.md lint DESIGN.md et corrigez les erreurs (broken-ref) et les avertissements raisonnables (missing-primary, contrast-ratio, section-order) ; sinon, dites à l'utilisateur la commande.
• Si AGENTS.md existe et ne mentionne pas DESIGN.md, suggérez à l'utilisateur (ne l'appliquez pas vous-même) d'ajouter une ligne pour que les agents d'interface lisent DESIGN.md avant de générer une interface — gardez à l'esprit la limite de ~30-40 lignes de AGENTS.md.

docs/architecture.md

Répond à la question « comment c'est construit » — composants, flux de données, décisions de conception clés et leur pourquoi, contraintes notables. Voir references/architecture-template.md. C'est le seul document qui peut être plus long que les autres car c'est un document de référence, pas quelque chose relu à chaque session — mais privilégiez quand même les schémas et les sections courtes plutôt que de longs textes. Utilisez un diagramme mermaid pour la vue principale des composants/flux de données lorsque cela aide.

docs/plans/

Lorsqu'un agent produit un plan pour une tâche non triviale (un plan de mise en œuvre en plusieurs étapes, un plan de migration, un plan de refactorisation), enregistrez-le ici dans son propre fichier au lieu de le laisser uniquement dans le chat. Créez le répertoire s'il n'existe pas. Nommez les fichiers AAAA-MM-JJ-court-titre.md (par exemple 2026-10-03-ajouter-webhook-paiement.md) pour qu'ils se trient chronologiquement. Chaque fichier de plan doit être autonome : objectif, approche, étapes, questions ouvertes. Ne supprimez pas les anciens plans une fois terminés — ils constituent un historique ; si le projet souhaite un marqueur « terminé », ajoutez une note de statut d'une ligne en haut du fichier au lieu de le supprimer.

Documentation API — OpenAPI + Scalar

Il ne s'agit pas d'un fichier markdown statique — elle est servie en direct depuis l'API, généralement sur une route /docs ou /reference via le rendu de référence API de Scalar lisant une spécification OpenAPI. Lorsqu'on vous demande de configurer ou mettre à jour la documentation API :

1. Vérifiez si le projet génère déjà une spécification OpenAPI (décorateurs/annotations du framework, un fichier openapi.yaml/openapi.json, ou une bibliothèque de génération de spécification déjà dans les dépendances).
2. Si la spécification existe mais n'est pas encore servie via Scalar, intégrez le middleware/gestionnaire Scalar pour le framework du projet (Scalar a des intégrations officielles pour la plupart des frameworks backend courants — vérifiez les noms de paquets/API actuels plutôt que de supposer, car cet écosystème évolue rapidement) et montez-le sur /docs.
3. Si aucune spécification n'existe encore, générez-en une à partir des routes/gestionnaires existants (la plupart des frameworks ont une bibliothèque qui dérive OpenAPI des définitions de routes/types — préférez cela à l'écriture manuelle de YAML) avant d'intégrer Scalar.
4. Ne maintenez jamais à la main un énorme fichier OpenAPI YAML statique si le framework peut le dériver du code — cela devient immédiatement obsolète. Préférez la génération code-first.
5. Notez l'URL /docs dans README.md une fois qu'elle est configurée, afin que les humains sachent où la trouver.

Liste de contrôle avant de terminer

• AGENTS.md fait ≤ ~40 lignes et comporte une section « Mémoire » pointant vers MEMORY.md
• MEMORY.md fait ≤ ~50 lignes et rien de permanent n'y traîne qui devrait être dans AGENTS.md
• Les commandes de README.md ont été vérifiées par rapport à la configuration réelle du projet, pas supposées
• CHANGELOG.md suit le format Keep a Changelog avec une section Unreleased
• DESIGN.md (uniquement si le projet a une interface) se trouve à la racine du projet, ses jetons correspondent au code réel, les sections suivent l'ordre canonique et npx @google/design.md lint DESIGN.md ne signale aucune erreur
• docs/architecture.md reflète la structure actuelle, pas une version obsolète
• Les nouveaux plans d'agent sont enregistrés sous docs/plans/ avec un nom de fichier daté
• Rien de sensible (clés, jetons, données personnelles) n'a été écrit dans aucun document