fernbrook-labs/beginner-reference-book

Créer un livre de référence pour débutants (guide d'introduction)

Crée un guide d'introduction pour un langage de programmation ou un framework, en respectant le même design, les mêmes fonctionnalités et la même approche que les guides d'introduction TypeScript, Rust, Angular et Go déjà réalisés (exemples dans references/examples/). Le résultat se compose de deux éléments :

• Un fichier HTML unique placé sur le bureau (nommé GuideIntroductif[Nom].html, ouvrable en double-cliquant).
• Une page de partage sur claude.ai (non publique, partagée par l'utilisateur via le menu Share). Créée uniquement si l'environnement prend en charge l'outil Artifact (par exemple, Claude Code).

Pour garantir la cohérence du design, l'apparence et le comportement utilisent directement les composants de ce skill (assets/ et scripts/). Ne pas réécrire le CSS ou le JavaScript à chaque fois. Seuls le contenu (manuscrit) et la méthode de vérification spécifique au langage sont à rédiger.

La valeur première du livre de référence réside dans l'exactitude des exemples de code et des résultats présentés. Les exemples de code, les messages d'erreur et les résultats d'exécution doivent impérativement être vérifiés avec le compilateur officiel ou le Playground officiel (ne pas les inventer). Les versions et les descriptions des nouvelles fonctionnalités doivent également être vérifiées dans les notes de version officielles avant d'être rédigées.

Il s'agit d'un travail long, pouvant prendre plusieurs heures. À chaque étape importante, informer l'utilisateur de ce qui est en cours, en une ou deux phrases.

1. Vérifier l'entrée

L'entrée est constituée soit du texte écrit après le nom du skill (souvent ajouté en tant que ARGUMENTS: à la fin du corps de ce skill), soit du nom du langage ou du framework dans la demande de l'utilisateur.

• Lorsqu'aucun nom n'est spécifié : Ne pas commencer le travail. Demander à nouveau : « Pour quel langage de programmation ou framework souhaitez-vous créer un livre de référence ? » (utiliser AskUserQuestion avec jusqu'à 4 suggestions comme Python, Java, React, Vue.js ; une option « Other » permet une saisie libre).
• Lorsque le texte spécifié n'est ni un langage de programmation ni un framework : Expliquer la raison en une phrase et demander à l'utilisateur de saisir à nouveau un langage ou un framework. Vérifier également toute nouvelle saisie et ne pas continuer tant qu'une entrée valide n'est pas fournie.
• Gestion des cas ambigus, des variations d'orthographe ou des spécifications multiples : Les règles et des exemples de formulations sont détaillés dans references/questions.md, section « Méthode de vérification de l'entrée ». En cas de doute, toujours s'y référer.

Dans les environnements où AskUserQuestion n'est pas disponible, poser la même question sous forme de texte et s'arrêter là.

2. Effectuer des recherches préliminaires avant de poser des questions

Afin de rédiger correctement les descriptions des options, vérifier les points suivants avant de poser des questions (cela prend quelques minutes ; ne pas encore télécharger de fichiers volumineux) :

1. Version stable la plus récente et sa date de publication : Vérifier sur le site officiel ou dans les notes de version. Cela sera utilisé pour la mention « Compatible avec [version] » dans le livre.
2. Existence d'un Playground officiel (site officiel fonctionnant dans le navigateur) : Si oui, existe-t-il une interface pour envoyer du code à compiler/exécuter depuis l'extérieur, peut-on ouvrir une URL avec le code inclus, ou s'agit-il d'un système de lien de partage (stockage du code sur le serveur) ?
3. Le langage/framework est-il déjà installé sur la machine ? (vérifier avec python --version, etc.). Si ce n'est pas le cas, quelle est la taille de l'installation temporaire (taille du téléchargement officiel) ?
4. Espace disque disponible (Get-PSDrive C sous PowerShell Windows, df -h /c sous Git Bash, df -h ~ sous macOS/Linux).
5. Règles spécifiques à l'environnement de l'utilisateur (CLAUDE.md, AGENTS.md, etc.). Par exemple, s'il existe une règle « Ne pas toucher aux dossiers synchronisés avec le cloud (OneDrive, etc.) », la respecter de la recherche jusqu'au nettoyage.

Les méthodes de recherche et les options de vérification par langage sont fournies dans references/verification.md.

3. Poser les questions de sélection (comme pour les livres précédents)

Poser les 4 questions suivantes en une seule fois à l'aide d'AskUserQuestion. Utiliser le même format de questions et d'options que pour les livres de référence précédents (les modèles de formulation sont dans references/questions.md). Placer l'option recommandée en tête et la marquer « (Recommandé) ». Dans les environnements sans AskUserQuestion (par exemple, Codex), présenter les 4 questions et leurs options sous forme de liste numérotée (avec la table des matières approximative pour la portée) et attendre la réponse.

1. Public cible : Par exemple, « Expérimenté en JS/TS (Recommandé) », « Débutant en programmation ». Pour les frameworks basés sur TypeScript (Angular, NestJS, etc.), utiliser « Expérimenté en TypeScript (Recommandé) ». Pour les frameworks Python (Django, etc.), utiliser « Expérimenté en Python (Recommandé) ». Adapter en fonction de la cible.
2. Portée : « Uniquement les bases (court, 8-9 chapitres) », « Bases + fonctionnalités courantes (Recommandé, 12-14 chapitres) », « Jusqu'aux fonctionnalités avancées (long, 16-18 chapitres) ». Pour chaque option, afficher un aperçu de la table des matières.
3. Format : « Même forme que précédemment (Recommandé) » = un fichier HTML sur le bureau + une page de partage, avec des quiz de fin de chapitre, un bouton de copie de code, un suivi des chapitres lus et une recherche par mot-clé. Autres options : « Fichier HTML uniquement », « Choisir les fonctionnalités ». Dans les environnements où une page de partage ne peut pas être créée (pas d'outil Artifact), l'option « Même forme que précédemment » se limite au fichier HTML. Dans ce cas, ne pas proposer « Fichier HTML uniquement » et ne pas mentionner la page de partage dans la description.
4. Méthode de vérification : Lister uniquement les méthodes possibles en fonction des recherches préliminaires. Par exemple : « Vérification via le Playground officiel », « Vérification après installation temporaire », « Vérification avec [nom] déjà installé ». Si l'espace disque est limité, recommander une méthode qui n'installe rien sur la machine.

En fonction des réponses, une seule question supplémentaire peut être posée.

• « Choisir les fonctionnalités » → Demander une sélection multiple parmi : quiz de fin de chapitre, bouton de copie de code, case à cocher pour les chapitres lus, glossaire, recherche par mot-clé.
• Si le Playground utilisé pour la vérification utilise un système de « lien de partage » (comme Go Playground, qui sauvegarde le code sur un serveur et crée un lien), demander : « Créer un lien de partage » ou « Copier et coller ». Les liens de partage sont publics et ne peuvent pas être supprimés ; obtenir impérativement l'accord de l'utilisateur. Les Playgrounds qui intègrent le code dans l'URL (Rust, TypeScript) ne sauvegardent pas de données, donc ne pas poser cette question.

Toutes les options sélectionnées doivent être respectées dans la suite du travail. Ne pas poser deux fois la même question.

4. Établir le plan

1. Définir la table des matières (voir references/writing-guide.md). Chaque chapitre doit pouvoir être lu en environ 10 minutes. Pour un langage, le dernier chapitre doit être « Comment lire les erreurs courantes ». Les tables des matières des 4 livres précédents sont dans references/past-books.md.
2. Rédiger le fichier spec.json (les éléments et un exemple sont dans references/book-spec.md). Inclure le nom de couverture, la version, le public cible, les titres des chapitres, le langage du code, la méthode d'ouverture du Playground, la couleur de la marque, etc.
3. Couleur de la marque : Utiliser la couleur officielle de la marque du langage ou du framework. Le script scripts/make_palette.mjs génère des couleurs claires et sombres à partir d'une seule couleur et vérifie le contraste pour garantir la lisibilité du texte (appelé automatiquement par new_book.mjs).

5. Créer le modèle et rédiger le manuscrit

1. Le dossier de travail doit être créé dans un dossier temporaire de la session (scratchpad de Claude Code, etc. ; sinon, créer un nouveau dossier dans le dossier temporaire du système d'exploitation). Ne pas le créer dans un dossier synchronisé avec le cloud (OneDrive, etc.).
2. Créer le modèle : node <chemin_vers_ce_skill>/scripts/new_book.mjs <dossier_du_livre> --spec spec.json
   • Cela génère book.json, palette.json, src/body.html et src/ja-errors.json.
   • La table des matières, la couverture, le mode d'emploi, les cadres des chapitres, les cadres des quiz et les cadres des annexes sont déjà présents dans src/body.html. Toutes les balises <!-- TODO … --> doivent être remplacées (sinon, l'assemblage signalera une erreur).
3. Avant de commencer à rédiger, lire les exemples. Le dossier references/examples/ contient des extraits de manuscrits des 4 livres précédents (couverture, mode d'emploi, un chapitre représentatif, le chapitre sur les erreurs, les annexes) qui ont été assemblés et vérifiés avec les composants de ce skill. À l'aide du tableau dans references/examples/README.md, choisir 1 ou 2 livres proches de la cible et lire leur body.html (par exemple, pour un langage, go et rust ; pour un framework basé sur TypeScript, angular et typescript). Il est plus efficace de voir des exemples concrets pour harmoniser le ton, la profondeur des explications, la taille des sections, la présentation des exemples de code et la granularité des quiz, plutôt que de lire des règles abstraites. Cependant, ne copier que le style d'écriture ; toujours revérifier les faits (versions, fonctionnalités, etc.). Ne pas recopier les phrases des exemples en changeant simplement quelques mots.
4. Rédiger le manuscrit. Suivre les consignes de references/components.md pour le HTML des composants (encadrés, tableaux, procédures, quiz, titres d'erreurs, etc.), de references/code-blocks.md pour la présentation des exemples de code, et de references/writing-guide.md pour le style d'écriture. Comme il y a de nombreux chapitres, il est conseillé d'écrire quelques chapitres, puis de les assembler et de les vérifier, et ainsi de suite.

6. Vérifier les exemples de code

node <chemin_vers_ce_skill>/scripts/build.mjs extract <dossier_du_livre>   # Exporte les exemples de code dans work/
node <chemin_vers_ce_skill>/scripts/checkers/go-playground.mjs <dossier_du_livre>   # Script de vérification adapté au langage (voir tableau ci-dessous)
node <chemin_vers_ce_skill>/scripts/build.mjs render <dossier_du_livre>    # Crée le HTML avec les résultats dans dist/

Script de vérification	Quand l'utiliser
checkers/go-playground.mjs	Go. Compilation, exécution, go vet, gofmt sur le Go Playground officiel. --share crée un lien de partage.
checkers/rust-playground.mjs	Rust. Compilation, exécution, infos de type sur le Rust Playground officiel.
checkers/typescript-local.mjs	TypeScript/JavaScript. TypeScript installé temporairement : erreurs (avec traduction officielle en japonais), bulles d'info, exécution.
checkers/local-command.mjs	Python, Java, C#, etc. Vérification/exécution avec une commande locale (ou installée temporairement).

Pour les langages ou frameworks non listés ici (comme Angular, où l'on souhaite afficher le rendu à l'écran), créer un nouveau script de vérification qui produit un résultat au même format (work/results.json). Le format du résultat est décrit dans references/code-blocks.md, les principes de création et les exemples passés dans references/verification.md.

• Corriger jusqu'à ce que render affiche « Aucune correction requise : ». Pour les exemples qui doivent produire des erreurs, ajouter // ❌ sur la ligne (et // ⚠ pour les avertissements) ; cela permet de vérifier à chaque assemblage que l'erreur attendue se produit.
• Lire dist/report.txt et vérifier que les messages d'erreur, les résultats d'exécution et les affichages de type correspondent aux explications du texte.
• Les installations temporaires doivent être placées uniquement dans le dossier temporaire de la session, et le cache doit également y être dirigé (voir references/verification.md).

7. Vérification visuelle

Exécuter scripts/test_guide.py. Ce script sert dist/ sur un port spécifié de 127.0.0.1.

python <chemin_vers_ce_skill>/scripts/test_guide.py --book <livre> --port 8770 --search "<mot_présent_dans_le_texte>"

• Nécessite Python avec Playwright et Chromium. Si ce n'est pas installé, demander à l'utilisateur la permission de les installer (quelques centaines de Mo). Si l'installation est impossible, ignorer cette vérification et le mentionner dans le rapport.
• Corriger jusqu'à ce que tous les tests soient réussis. Ensuite, examiner visuellement les captures d'écran dans <livre>/shots/ (couverture, mode d'emploi, chaque chapitre, aide-mémoire, mode sombre, mobile) pour détecter tout débordement, couleur illisible ou problème de mise en page.
• Vérifier également que les liens externes du texte s'ouvrent correctement et que les liens vers le Playground fonctionnent (pour l'un d'entre eux, l'ouvrir et exécuter le code pour confirmer).

8. Livrer et nettoyer

1. Si un lien de partage doit être créé, le faire après la finalisation du contenu (avec --share), puis vérifier que tous les liens ouvrent le bon code.
2. Copier dist/full.html sur le bureau de l'utilisateur (sous Windows : C:\Users\<utilisateur>\Desktop, sous macOS : ~/Desktop) sous le nom GuideIntroductif[Nom].html. Si un fichier du même nom existe déjà, ne pas écraser et demander à l'utilisateur.
3. Si le format inclut une page de partage et que l'environnement prend en charge l'outil Artifact, appeler quickstart, puis publier dist/artifact.html (icône : book, description : une phrase en japonais). Informer l'utilisateur que la page publiée est non publique et que le partage se fait via le menu Share. Si l'environnement ne le permet pas, ignorer cette étape.
4. Supprimer les installations temporaires, le cache et les captures d'écran. Si le travail a écrit dans un emplacement partagé (cache npm, etc.), vérifier et supprimer uniquement ce qui a été créé.
5. Fournir un rapport en japonais : emplacement du fichier, URL de la page de partage (si créée), contenu (points principaux de la table des matières), éléments vérifiés (nombre), points d'attention (environnements non vérifiés, limitations du Playground, etc.).

Documents de référence

Fichier	Quand le consulter
references/questions.md	Méthode de vérification de l'entrée et format des questions de sélection (modèles de formulation).
references/book-spec.md	Format de spec.json et book.json.
references/writing-guide.md	Règles pour la table des matières, la rédaction et l'exactitude.
references/components.md	Composants HTML du manuscrit.
references/code-blocks.md	Format des exemples de code, attributs et structure des résultats des scripts de vérification.
references/verification.md	Méthodes de vérification par langage, procédure d'installation temporaire et de nettoyage.
references/past-books.md	Tables des matières, couleurs, méthodes de vérification et leçons apprises des 4 livres précédents.
references/examples/README.md	Comment choisir des exemples de manuscrit (extraits des 4 livres). À lire avant de rédiger le manuscrit.