mohamed-stifi/repo-walkthrough-video

Vidéo de présentation d'un dépôt de code

L'objectif est une vidéo qu'un membre de l'équipe peut regarder pour comprendre un dépôt : à quoi il sert, comment ses parties s'assemblent, et chaque fonction exécutée en réel, y compris ce qui est cassé aujourd'hui. Deux tâches sont mélangées ici, et elles doivent se produire dans cet ordre :

1. Tester le dépôt en réel. Chaque commande montrée dans la vidéo a vraiment été exécutée et sa sortie lue.
2. Enregistrer comme une histoire. Les chapitres suivent la forme du système, et chacun est commenté.

Une vidéo qui ne montre que des commandes qui réussissent induit l'équipe en erreur. Les échecs que vous trouvez en testant sont souvent la partie la plus précieuse de la vidéo, alors donnez-leur leur propre chapitre de conclusion.

Structure de sortie

Travaillez dans un dossier en dehors du dépôt. L'utilisateur le choisit ; s'il ne le fait pas, utilisez un dossier frère comme <parent-du-repo>/video/, car un chemin racine comme /video est souvent en lecture seule sur macOS.

video/
├── <nom>-walkthrough.mp4    # vidéo complète : chapitres + piste de sous-titres mov_text
├── <nom>-walkthrough.srt    # même narration, également utilisable comme transcription
├── chapters/NN-slug.mp4      # un fichier par chapitre
├── README.md                 # index des chapitres avec heures de début, comment ré-enregistrer
├── src/                      # engine.py, make_readme.py, script.py (+ aides)
├── work/                     # clone(s) jetables du dépôt : chaque commande s'exécute ici
└── build/                    # fichiers intermédiaires (voix par segment, images, clips)

N'exécutez jamais les commandes de démonstration sur la copie de travail de l'utilisateur. Clonez-le dans work/ (git clone <repo> work/<nom>) pour que la vidéo puisse casser des choses intentionnellement (mauvais manifests, fautes injectées) et réinitialiser avec git checkout . && git clean -fd. Si la copie de travail de l'utilisateur a des modifications non commitées, mentionnez-les et laissez-les tranquilles.

Étape 1 : Vérifier les outils, et indiquer à l'utilisateur ce qui manque

which vhs ffmpeg ffprobe jq; python3 -c "import PIL; print(PIL.__version__)"; say -v '?' | head -3

Si quelque chose manque, dites à l'utilisateur quoi installer, et pourquoi, avant de l'installer (brew install vhs ffmpeg jq). Pour Pillow, ne touchez pas au Python système. Exécutez le moteur via uv à la place : uv run --no-project --with pillow python engine.py .... Enveloppez-le dans une fonction shell (py() { uv run --no-project --with pillow python "$@"; }), car une variable contenant la commande ne s'étendra pas comme un seul mot. Il en va de même pour tout ce dont le dépôt a besoin, comme Docker en cours d'exécution, une pile de simulateur, ou des identifiants. Demandez-les à l'utilisateur, et n'inventez jamais un secret. Une voix premium (Réglages Système → Accessibilité → Contenu parlé, par exemple "Ava (Premium)") sonne beaucoup mieux que la Samantha par défaut. Proposez-la, mais ne bloquez pas dessus ; VOICE=... engine.py --force ré-énonce plus tard.

Étape 2 : Comprendre et tester le dépôt avant d'écrire un mot de narration

Lisez le README, la documentation ou les ADRs, les points d'entrée CLI (--help de chaque sous-commande), les marqueurs de test, le Makefile et la configuration CI. Construisez un inventaire de chaque fonction qu'un utilisateur peut exercer : chaque sous-commande CLI, chaque suite de tests, chaque intégration, chaque mode de défaillance contre lequel le code se défend.

Ensuite, exécutez tout cela dans work/, et notez :

• les commandes exactes qui montrent bien chaque fonctionnalité, avec une sortie courte (filtrez par jq, head, tail, cut -c1-160)
• ce qui échoue, et si c'est un vrai bug ou juste votre environnement (mauvais chemin par défaut, variable d'environnement manquante). Résolvez les problèmes d'environnement dans le clone ou avec des variables d'environnement, et rendez cette correction visible dans la vidéo, car l'équipe les rencontrera aussi.
• comment enfreindre chaque règle de sécurité intentionnellement (un fixture, un sed sur une copie), afin que la vidéo puisse montrer la règle en action

Ces notes deviennent le chapitre des découvertes. Conservez-les sous forme de liste d'éléments concrets numérotés.

Étape 3 : Planifier les chapitres

Suivez le pipeline propre du système, pas la liste des dossiers. Une forme qui a bien fonctionné :

#	Chapitre	Contenu
00	Bienvenue	carte de titre, puis une diapositive "ce que vous allez voir"
01	Vue d'ensemble	un objectif en une phrase, le pipeline sous forme de boîtes et flèches, une scène terminale de la structure du dépôt
02	Configuration	installation, la CLI regroupée par objectif, la suite de tests rapide
…	un chapitre par étape du pipeline	commandes réelles, plus une scène "casser intentionnellement" par règle
…	live / intégration	les vrais services de support, de bout en bout
N-1	Contrats / passation	ce sur quoi les autres équipes comptent
N	Découvertes et prochaines étapes	la liste des découvertes numérotées, puis quoi faire ensuite

Visez 1 à 3 minutes par chapitre et 15 à 25 minutes au total. Un chapitre est une idée ; un segment est un écran plus une narration. Montrez ce plan à l'utilisateur (titres des chapitres et une ligne chacun) avant d'enregistrer.

Étape 4 : Écrire src/script.py

Copiez les scripts fournis dans le dossier vidéo :

mkdir -p video/src && cp <skill-dir>/scripts/{engine.py,make_readme.py,agent.jq} video/src/
cp <skill-dir>/scripts/script_template.py video/src/script.py

script.py contient tous les mots et toutes les commandes. engine.py les transforme en vidéo. Lisez references/script-format.md pour le schéma complet des segments, les mises en page des diapositives et le style de narration. scripts/script_template.py montre chaque type de segment avec un exemple fonctionnel ; construisez le reste des chapitres dans la même forme (l'étape 3 donne le plan des chapitres).

Règles de narration les plus importantes :

• Écrivez pour l'oreille : phrases courtes, pas de markdown, et épeler les acronymes que la voix prononce mal ("M C P", "C L I"), ou ajoutez-les à SPOKEN dans script.py.
• Dites ce que le spectateur doit regarder ("Regardez les compétences : zéro"). La voix et l'image doivent correspondre, donc si vous modifiez la sortie d'une commande (un compteur, un facteur de vitesse), corrigez aussi la phrase.
• Les légendes (la barre inférieure d'une scène terminale) sont une ligne qui énonce le point, avec du code entre backticks.

Étape 5 : Pré-exécution, puis enregistrement

cd video/src                          # `py` = Python avec Pillow (voir Étape 1)
py engine.py --dry                    # exécute chaque commande terminale en bash simple et imprime la sortie, pas de vidéo
py engine.py --dry --only 04          # un chapitre
py engine.py --only 04                # enregistrer un chapitre (retour rapide sur le rendu)
py engine.py                          # tout ce qui manque ou a changé, puis assembler la vidéo complète
py engine.py --only 07 --reuse-terms  # garder les clips VHS, refaire seulement la voix et les images (corrections de narration)
py make_readme.py                     # écrit README.md avec l'index des chapitres

Faites toujours une pré-exécution d'abord. Cela prend des minutes au lieu d'une heure, et attrape chaque commande qui erre, se bloque ou imprime trop. Enregistrez d'abord un chapitre et regardez les images avant la construction complète :

ffmpeg -v error -ss 20 -i chapters/04-*.mp4 -frames:v 1 build/check.png   # puis Lisez le PNG

Une construction complète prend du temps (environ 40 minutes pour 21 minutes de vidéo). Exécutez-la en arrière-plan et attendez son avis de fin plutôt que de la surveiller. Les chapitres sont mis en cache par un hash de leur script, donc ré-exécuter ne reconstruit que ce qui a changé.

Étape 6 : Vérifier et remettre

ffprobe -v error -show_chapters -show_streams -of compact video/<nom>-walkthrough.mp4 | head -40

Vérifiez ce qui suit :

• la durée
• 1920×1080 h264, aac, et un flux de sous-titres mov_text
• un marqueur de chapitre par chapitre
• des images d'échantillon de quelques chapitres : pas de texte débordant des boîtes, légendes dans les deux lignes

Ensuite, indiquez à l'utilisateur les chemins exacts du MP4, du dossier chapters/, du SRT et du README. Ajoutez comment l'ouvrir (open video/<nom>-walkthrough.mp4 ; QuickTime ou VLC affichent les menus des chapitres et des sous-titres) et la liste des découvertes. Mentionnez les conteneurs ou services que vous avez laissés en cours, et comment les arrêter.

Pièges déjà résolus (gardez-les à l'esprit lors de l'édition du moteur)

• Shells en sandbox : vhs, Docker, les caches de uv et say échouent souvent sous un sandbox de commandes ("Operation not permitted", erreurs de socket Docker). Ces commandes doivent s'exécuter en dehors. open est aussi bloqué, donc donnez la commande à l'utilisateur pour qu'il l'exécute lui-même.
• Chutes de trames VHS : le 50 ips par défaut chute des trames sur les longues scènes. Le moteur utilise Set Framerate 15.
• Output de VHS doit être un simple nom de fichier. Exécutez vhs avec cwd défini sur le dossier de sortie.
• Les chaînes VHS n'ont pas d'échappements. Le guillemet de json.dumps casse les séquences d'échappement PS1. Utilisez q() dans le moteur, qui choisit un délimiteur ", ' ou ` que le texte ne contient pas.
• Wait se bloque si le motif ne correspond pas à l'invite. Le moteur définit un PS1 qui se termine par $ et utilise WaitPattern /[>$]$/. Les commandes qui impriment une dernière ligne se terminant par $ ou > peuvent terminer une attente trop tôt, donc ajoutez une pause là.
• Scènes de longue durée (un agent AI, une exécution de pipeline) : définissez "speedup": True sur le segment. Le moteur accélère le clip approximativement à la longueur de la narration et timbre accéléré ×N.N dans l'en-tête, donc dites qu'il est accéléré.
• Débordement de texte sur les diapositives : wrap() mesure les blocs de code dans la police monospace. Gardez les corps de boîtes courts, et divisez les longs chemins sur deux lignes.
• Boucles d'attente : une boucle pgrep -f <motif> se correspond à elle-même. Attendez plutôt sur un PID ou un fichier.
• Hooks avant ("before": [...] sur un chapitre) préparent l'état : réinitialiser un conteneur de base de données, déclencher un pipeline, injecter une faute. Mettez l'annulation (réinitialisation, désinjection) dans le même chapitre, afin qu'une reconstruction d'un chapitre ne laisse jamais la plateforme cassée.
• Secrets nécessaires par la démonstration vont dans un fichier ignoré par git dans le clone (par exemple dev-vault.env). Ne montrez jamais leurs valeurs à l'écran, et ne les commitez jamais.

Montrer un agent AI au travail (optionnel)

Si le dépôt construit ou configure un agent, la scène la plus forte est l'agent diagnostiquant une vraie faute injectée. Exécutez-le sans affichage avec une sortie stream-json, et formatez le flux avec le agent.jq fourni (une ligne par appel d'outil, puis la réponse) :

claude -p "<question>" --output-format stream-json --verbose | jq -rj -f /chemin/vers/video/src/agent.jq

Marquez ce segment "speedup": True, et réinitialisez la faute ensuite dans le même chapitre.