zarazhangrui/codebase-to-course

Que fait codebase-to-course ?

Transformez n'importe quelle base de code en un cours interactif et magnifique. Le résultat est un dossier contenant un styles.css préconstruit, un main.js, des fichiers HTML par module, et un index.html assemblé — ouvrez-le directement dans le navigateur sans aucune configuration (seule dépendance externe : le CDN Google Fonts). Le cours enseigne le fonctionnement du code à travers des modules basés sur le défilement, des visualisations animées, des quiz intégrés et des traductions en français clair du code.

Première utilisation – Bienvenue

Lorsque le skill est déclenché pour la première fois et que l'utilisateur n'a pas encore spécifié de base de code, présentez-vous et expliquez ce que vous faites :

Je peux transformer n'importe quelle base de code en un cours interactif qui explique comment elle fonctionne — aucune connaissance en codage n'est requise.

Il suffit de me pointer vers un projet :

• Un dossier local — par exemple, « transforme ./mon-projet en cours »
• Un lien GitHub — par exemple, « crée un cours à partir de https://github.com/utilisateur/repo »
• Le projet actuel — si vous êtes déjà dans une base de code, dites simplement « transforme ceci en cours »

Je vais parcourir le code, comprendre comment tout s'articule, et générer un magnifique cours HTML d'une seule page avec des diagrammes animés, des explications de code en français clair et des quiz interactifs. Le tout fonctionne dans votre navigateur — aucune installation nécessaire.

Si l'utilisateur fournit un lien GitHub, clonez d'abord le dépôt (git clone <url> /tmp/<nom-du-repo>) avant de commencer l'analyse. S'il dit « cette base de code » ou similaire, utilisez le répertoire de travail actuel.

À qui s'adresse ce cours

L'apprenant cible est un « vibe codeur » — quelqu'un qui construit des logiciels en donnant des instructions en langage naturel à des outils d'IA de codage, sans formation traditionnelle en informatique. Il a peut-être construit ce projet lui-même (sans regarder le code), ou a trouvé un projet open-source intéressant sur GitHub et veut comprendre comment il est construit. Dans les deux cas, il ne comprend pas encore ce qui se passe sous le capot.

Partez du principe qu'il n'a aucune base technique. Chaque concept d'informatique — des variables aux API en passant par les bases de données — doit être expliqué dans un langage simple comme si l'apprenant ne l'avait jamais rencontré. Pas de jargon sans définition. Pas de « comme vous le savez probablement ». Le ton doit être celui d'un ami intelligent qui explique les choses, pas d'un professeur qui fait un cours.

Leurs objectifs sont pratiques, pas académiques :

• Acquérir suffisamment de connaissances techniques pour orienter efficacement les outils de codage IA — prendre de meilleures décisions architecturales et de pile technologique
• Détecter quand l'IA se trompe — repérer les hallucinations, identifier les mauvaises pratiques, savoir quand quelque chose semble anormal
• Intervenir quand l'IA est bloquée — sortir des boucles de bugs, déboguer les problèmes, se débloquer
• Construire des logiciels plus avancés avec une qualité et une fiabilité de niveau production
• Être techniquement à l'aise pour discuter des décisions avec les ingénieurs en toute confiance
• Acquérir le vocabulaire du logiciel — apprendre les termes techniques précis pour décrire les exigences de manière claire et sans ambiguïté aux agents de codage IA (par exemple, savoir dire « paquetage namespace » au lieu de « truc de dossier partagé »)

Ils n'essaient PAS de devenir ingénieurs logiciels. Ils veulent que le codage soit un super-pouvoir qui amplifie ce dans quoi ils sont déjà bons. Ils n'ont pas besoin d'écrire du code à partir de zéro — ils doivent le lire, le comprendre et le diriger.

Pourquoi cette approche fonctionne

Ce skill inverse l'enseignement traditionnel de l'informatique. L'ancien modèle est : mémoriser des concepts pendant des années → construire quelque chose éventuellement → enfin voir l'intérêt (la plupart des gens abandonnent avant l'étape 3). Ce modèle est : construire d'abord → expérimenter le fonctionnement → comprendre maintenant comment ça marche.

L'apprenant a déjà un contexte que les étudiants traditionnels n'ont pas — il a utilisé l'application, il sait ce qu'elle fait, il a peut-être même décrit ses fonctionnalités en langage naturel. Le cours le rejoint là où il est : « Vous connaissez ce bouton sur lequel vous cliquez ? Voici ce qui se passe sous le capot quand vous cliquez dessus. »

Chaque module répond à la question « pourquoi devrais-je m'y intéresser ? » avant « comment ça marche ? » La réponse à « pourquoi devrais-je m'y intéresser ? » est toujours pratique : parce que cette connaissance vous aide à mieux diriger l'IA, à déboguer plus rapidement ou à prendre des décisions architecturales plus intelligentes.

Le résultat basé sur un dossier est intentionnel : séparer le CSS/JS du contenu signifie que l'IA ne régénère jamais le code standard, chaque module est écrit indépendamment (gardant la taille de sortie petite et la qualité élevée), et l'index.html assemblé fonctionne hors ligne sans aucune configuration.

---

Le processus

Phase 1 : Analyse de la base de code

Avant d'écrire le cours HTML, comprenez profondément la base de code. Lisez tous les fichiers clés, tracez les flux de données, identifiez le « casting » (composants/modules principaux) et cartographiez comment ils communiquent. La rigueur ici est payante — plus vous comprenez, meilleur est le cours.

Ce qu'il faut extraire :

• Les principaux « acteurs » (composants, services, modules) et leurs responsabilités
• Le parcours utilisateur principal (ce qui se passe quand quelqu'un utilise l'application de bout en bout)
• Les API clés, les flux de données et les modèles de communication
• Les modèles d'ingénierie astucieux (mise en cache, chargement différé, gestion des erreurs, etc.)
• Les vrais bugs ou pièges (si visibles dans l'historique git ou les commentaires)
• La pile technologique et pourquoi chaque pièce a été choisie

Découvrez ce que fait l'application par vous-même en lisant le README, les points d'entrée principaux et le code de l'interface utilisateur. Ne demandez pas à l'utilisateur d'expliquer le produit — il n'est peut-être pas non plus familier avec lui. Le cours doit commencer par expliquer ce que fait l'application en langage simple (un bref « voici ce que fait ce truc et pourquoi c'est intéressant ») avant de plonger dans son fonctionnement. Le premier module doit commencer par une action utilisateur concrète — « imaginez que vous colliez une URL YouTube et cliquiez sur Analyser — voici ce qui se passe sous le capot. »

Phase 2 : Conception du programme

Structurez le cours en 4 à 6 modules. La plupart des cours nécessitent 4 à 6. N'allez à 7 ou 8 que si la base de code a vraiment autant de concepts distincts à enseigner. Des modules moins nombreux mais meilleurs battent des modules plus nombreux mais plus superficiels.

L'arc commence toujours par ce que l'apprenant sait déjà (le comportement visible par l'utilisateur) et se dirige vers ce qu'il ne sait pas (le code en dessous). Considérez-le comme un zoom avant : commencez large avec l'expérience, puis décollez progressivement les couches.

Position du module	Objectif	Pourquoi c'est important pour un vibe codeur
1	« Voici ce que fait cette application — et ce qui se passe quand vous l'utilisez »	Commencez par le produit (ce qu'il fait, pourquoi c'est intéressant), puis tracez une action utilisateur principale dans le code. Ancre tout dans quelque chose de concret.
2	Rencontrez les acteurs	Connaître les composants qui existent pour pouvoir dire à l'IA « mets cette logique dans X, pas Y »
3	Comment les pièces communiquent	Comprendre le flux de données pour pouvoir déboguer les problèmes de type « ça ne s'affiche pas »
4	Le monde extérieur (API, bases de données)	Savoir ce qui est externe pour évaluer les coûts, les limites de taux et les modes de défaillance
5	Les astuces	Apprendre des modèles (mise en cache, segmentation, gestion des erreurs) pour pouvoir les demander à l'IA
6	Quand les choses cassent	Développer l'intuition de débogage pour pouvoir sortir des boucles de bugs de l'IA
7	La vue d'ensemble	Voir l'architecture complète pour prendre de meilleures décisions sur ce qu'il faut construire ensuite

Ceci est un menu, pas une liste de contrôle. Choisissez les modules qui servent la base de code — un outil CLI simple en nécessite 4, pas 7. Adaptez l'arc à la complexité de la base de code.

Le principe clé : Chaque module doit être lié à une compétence pratique — diriger l'IA, déboguer, prendre des décisions. Si un module n'aide pas l'apprenant à FAIRE quelque chose de mieux, supprimez-le ou reformulez-le jusqu'à ce que ce soit le cas.

Chaque module doit contenir :

• 3 à 6 écrans (sous-sections qui s'enchaînent dans le module)
• Au moins une traduction code-à-français
• Au moins un élément interactif (quiz, visualisation ou animation)
• Un ou deux encadrés « ahah ! » avec des perspectives universelles en informatique
• Une métaphore qui ancre le concept technique dans la vie quotidienne — mais ne réutilisez JAMAIS la même métaphore d'un module à l'autre, et ne revenez JAMAIS par défaut à la métaphore du « restaurant » (trop utilisée). Choisissez des métaphores qui s'adaptent naturellement au concept spécifique. Les meilleures métaphores semblent naturelles pour le concept, pas forcées.

Éléments interactifs obligatoires (chaque cours doit inclure TOUS ces éléments) :

• Animation de chat de groupe — au moins une dans l'ensemble du cours. Ce sont les conversations de style iMessage/WeChat entre les composants. Ce sont l'un des éléments les plus engageants et ils doivent toujours apparaître, même si vous devez encadrer de manière créative le concept d'un module comme une conversation entre acteurs.
• Animation de flux de messages / flux de données — au moins une dans l'ensemble du cours. L'animation de paquets étape par étape entre les acteurs. Si la base de code a un type quelconque de requête/réponse, pipeline de données ou processus en plusieurs étapes, animez-le. Chaque base de code a des données qui circulent quelque part — trouvez-les.
• Blocs de traduction Code ↔ Français — au moins un par module (déjà requis ci-dessus, mais je le répète : c'est non-négociable).
• Quiz — au moins un par module (choix multiples, scénario, glisser-déposer, ou « trouvez le bug » — n'importe quel type de quiz compte).
• Info-bulles de glossaire — sur chaque terme technique, première utilisation par module.

Ces cinq types d'éléments sont l'épine dorsale de chaque cours. D'autres éléments interactifs (diagrammes d'architecture, toggles de couches, cartes de motifs, etc.) sont facultatifs et doivent être ajoutés quand ils conviennent. Mais les cinq ci-dessus doivent TOUJOURS être présents — aucune exception.

Ne SOUMETTEZ PAS le programme pour approbation — construisez-le simplement. L'utilisateur veut un cours, pas un document de planification. Concevez le programme en interne, puis passez directement à la construction. S'il veut des changements, il vous le dira après avoir vu le résultat.

Après avoir conçu le programme, décidez quelle voie de construction utiliser :

• Base de code simple (CLI à usage unique, petite application web, bibliothèque, un point d'entrée clair, 5 modules ou moins) → allez directement à la Phase 3 Séquentielle.
• Base de code complexe (application full-stack, plusieurs services, site riche en contenu, monorepo, ou 6+ modules) → allez d'abord à la Phase 2.5, puis à la Phase 3 Parallèle.

Phase 2.5 : Briefs de module (bases de code complexes uniquement)

Pour les bases de code complexes, rédigez un brief pour chaque module avant d'écrire du HTML. C'est l'étape critique qui permet l'écriture en parallèle — chaque brief donne à un agent tout ce dont il a besoin sans relire la base de code.

Lisez references/module-brief-template.md pour la structure du modèle. Lisez references/content-philosophy.md pour les règles de contenu qui doivent guider la rédaction du brief.

Pour chaque module, écrivez un brief dans nom-du-cours/briefs/0N-titre.md contenant :

• Arc pédagogique (métaphore, accroche d'ouverture, perspective clé)
• Extraits de code pré-extraits (copiés-collés de la base de code avec les chemins de fichiers et les numéros de ligne)
• Liste de contrôle des éléments interactifs avec suffisamment de détails pour les construire
• Quelles sections desquels fichiers de référence l'agent de rédaction doit utiliser
• Ce que couvrent les modules précédent et suivant (pour les transitions)

Les extraits de code sont l'étape critique d'économie de jetons. En les pré-extrayant dans le brief, les agents de rédaction n'ont jamais besoin de lire la base de code du tout.

Phase 3 : Construction du cours

Le résultat du cours est un dossier, pas un seul fichier. Tous les CSS et JS sont des fichiers de référence préconstruits — ne les régénérez jamais. Votre travail consiste à écrire uniquement le contenu HTML.

Structure de sortie :

nom-du-cours/
  styles.css       ← copié textuellement de references/styles.css
  main.js          ← copié textuellement de references/main.js
  _base.html       ← shell personnalisé (titre, couleur d'accent, points de navigation)
  _footer.html     ← copié textuellement de references/_footer.html
  build.sh         ← copié textuellement de references/build.sh
  briefs/          ← briefs de module (bases de code complexes uniquement, peuvent être supprimés après la construction)
  modules/
    01-intro.html
    02-actors.html
    ...
  index.html       ← assemblé par build.sh (ne pas écrire manuellement)

Étape 1 (les deux chemins) : Configuration — Créez le dossier du cours. Copiez ces quatre fichiers textuellement en utilisant Lire + Écrire (ne régénérez pas leur contenu) :

• references/styles.css → nom-du-cours/styles.css
• references/main.js → nom-du-cours/main.js
• references/_footer.html → nom-du-cours/_footer.html
• references/build.sh → nom-du-cours/build.sh

Étape 2 (les deux chemins) : Personnaliser _base.html — Lisez references/_base.html, puis écrivez-le dans nom-du-cours/_base.html avec exactement trois substitutions :

• Les deux instances de COURSE_TITLE → le titre réel du cours
• Les quatre placeholders ACCENT_* → les valeurs de couleur d'accent choisies (choisissez une palette parmi les commentaires dans _base.html)
• NAV_DOTS → un <button class="nav-dot" ...> par module

Étape 3 : Écrire les modules — C'est là que les chemins divergent.

Chemin séquentiel (bases de code simples)

Lisez references/content-philosophy.md et references/gotchas.md. Ensuite, écrivez les modules un par un. Pour chaque module, écrivez nom-du-cours/modules/0N-titre.html contenant uniquement le bloc <section class="module" id="module-N"> et son contenu. N'incluez pas les balises <html>, <head>, <body>, <style> ou <script>.

Lisez references/interactive-elements.md pour les motifs HTML de chaque type d'élément interactif. Lisez references/design-system.md pour les conventions visuelles.

Chemin parallèle (bases de code complexes)

Distribuez les modules à des sous-agents par lots de 3 maximum. Chaque agent reçoit :

• Son brief de module (de nom-du-cours/briefs/)
• references/content-philosophy.md et references/gotchas.md
• Uniquement les sections de references/interactive-elements.md et references/design-system.md listées dans le brief

Chaque agent écrit son(ses) fichier(s) de module dans nom-du-cours/modules/. Les modules courts (3 écrans, un quiz) peuvent être appariés — deux briefs donnés à un seul agent.

Ce que les agents ne reçoivent PAS : la base de code complète (les extraits sont dans le brief), SKILL.md, les briefs des autres modules, ou les sections inutiles des fichiers de référence.

Après que tous les agents ont terminé, effectuez une rapide vérification de cohérence dans le contexte principal : les points de navigation correspondent aux modules, les transitions entre les modules sont cohérentes, pas de changements de ton évidents.

Étape 4 (les deux chemins) : Assemblage — Exécutez build.sh depuis le dossier du cours :

cd nom-du-cours && bash build.sh

Cela produit index.html. Ouvrez-le dans le navigateur.

Règles critiques :

• Ne régénérez jamais styles.css ou main.js — copiez toujours depuis