Versionner le travail de l'IA
Les personnes qui itèrent avec l'IA perdent de bonnes versions : une régénération les écrase, une annulation va trop loin, ou la conversation dérive. Cette compétence fait de chaque changement une version numérotée qui reste jusqu'à ce que l'utilisateur la supprime, afin qu'il puisse voir, comparer et revenir à n'importe quel état antérieur.
Les trois règles
- Chaque changement obtient une version. Une demande utilisateur qui modifie des fichiers équivaut à une version, sauvegardée à la fin de ce tour, avant votre réponse. Sauvegarder par demande, et non par édition de fichier, rend l'historique lisible.
- Revenir en arrière ne supprime jamais une version. Seul le script écrit dans
.ai-versions/. Ne modifiez, déplacez ou supprimez jamais quoi que ce soit dans ce dossier, même si on vous demande de faire du ménage. Orientez plutôt l'utilisateur versbackup. - Revenir en arrière est une nouvelle version. Restaurez avec le script ; ne reconstruisez jamais un ancien travail de mémoire. Une restauration est sauvegardée comme une nouvelle version, afin de pouvoir être annulée aussi.
Le script choisit chaque numéro de version. Ne devinez jamais un numéro ; rapportez celui que le script imprime.
Choisissez le mode une fois par projet
- Vous pouvez exécuter des commandes et éditer des fichiers (Claude Code, Cursor, Codex, Windsurf, Copilot, Gemini CLI, Replit Agent, claude.ai avec exécution de code) : utilisez le mode fichiers ci-dessous.
- Le projet contient
.github/workflows/ai-versions.yml: il utilise la couche GitHub. N'exécutez pasinit. Au lieu de cela, pour chaque changement, écrasez.ai-versions/pending.json, et pour revenir en arrière, écrivez.ai-versions/restore.json. Les deux sont décrits dans assets/rules/github-layer-rules.md. - Vous ne pouvez pas exécuter de commandes (une simple conversation) : suivez references/chat-mode.md.
- L'utilisateur construit dans Lovable, Bolt ou v0 (Bolt et v0 sont en bêta : pas encore testés en direct), ou Figma Make et demande comment versionner là-bas : lisez references/app-builders.md.
Mode fichiers
Le script est scripts/aiv.py dans le dossier de cette compétence (le dossier qui contient ce SKILL.md). Appelez-le par son chemin complet et pointez-le vers le projet avec --root :
python3 "<dossier de cette compétence>/scripts/aiv.py" --root "<dossier du projet>" <commande>
# Windows : utilisez py au lieu de python3
Après init, chaque projet possède également sa propre copie, donc depuis le dossier du projet, python3 .ai-versions/aiv.py <commande> fonctionne de la même manière. Ci-dessous, aiv désigne l'une ou l'autre forme. Si Python n'est pas installé, dites à l'utilisateur qu'il est nécessaire (python.org) et utilisez le mode chat jusqu'à ce qu'il le soit.
Démarrage
Avant votre première modification dans un projet sans .ai-versions/, exécutez init. Il sauvegarde les fichiers actuels en tant que v1.0.0, afin que l'utilisateur puisse toujours revenir à l'état d'avant votre intervention.
Si le dossier contient plus que le projet (un bac à sable, un dossier personnel, un dossier Téléchargements), limitez-le : init --only poster.html assets/. init refuse les dossiers de plus de 5 000 fichiers, car cela signifie généralement qu'il s'agit du mauvais dossier.
Après chaque changement
aiv save --bump minor --summary "Ajout d'une section tarifs avec 3 formules" \
--reason "Nouvelle section ; mise en page et style inchangés" --prompt "ajouter tarifs avec 3 formules"
--bump | Affiché à l'utilisateur comme | Quand |
|---|---|---|
patch | Petite retouche | Mêmes fonctionnalités, petit ajustement : texte, couleur, espacement, taille, une petite correction |
minor | Nouvelle fonctionnalité | Quelque chose de nouveau, même direction : une section, une page, un composant, une fonctionnalité |
major | Grand changement | La direction a changé : refonte, nouvelle mise en page, nouveau système de style, suppression d'une fonctionnalité |
Une demande avec plusieurs changements prend le niveau le plus élevé. En cas d'hésitation entre deux niveaux : prenez le niveau inférieur et mentionnez-le dans --reason. Les cas particuliers (documents, refontes, mises à jour de contenu) sont dans references/bump-levels.md.
Rédigez --summary pour l'utilisateur, pas pour un développeur : « Agrandi l'image du héros », pas « Mise à jour de Hero.tsx ». Mettez la demande de l'utilisateur, raccourcie à une ligne, dans --prompt.
Terminez ensuite votre réponse par une ligne, par exemple : Sauvegardé v1.3.0 (Nouvelle fonctionnalité) : Ajout d'une section tarifs avec 3 formules.
Si save indique que les fichiers correspondent exactement à une version antérieure, il enregistre la sauvegarde comme un retour à cette version. Dites à l'utilisateur ce qui s'est passé.
Quand l'utilisateur demande
| L'utilisateur dit | Exécutez | Ensuite |
|---|---|---|
| « afficher les versions », « historique » | list | Affichez un petit tableau. Pour une chronologie visuelle, exécutez view et partagez le fichier HTML qu'il écrit. |
| « ce qui a changé dans v1.3.0 » | diff v1.3.0^ v1.3.0 | Expliquez en termes simples. vX^ signifie la version avant vX. |
| « compare v1.2 et v2.0 » | diff v1.2.0 v2.0.0 --stat, puis sans --stat pour les détails | Dites ce qui a changé, ce qui s'est amélioré, ce qui s'est dégradé. Si vous pouvez restituer le travail (HTML, images), montrez les deux côte à côte. |
| « revenir à v1.2.0 », « annuler ça » | restore v1.2.0, ou restore prev pour annuler | Puis effectuez l'étape ci-dessous. |
| « récupérer seulement l'ancien en-tête », « ancien design mais garder le nouveau texte » | restore v1.2.0 --path <fichiers> | Seuls ces fichiers changent ; cela est sauvegardé comme une Petite retouche. |
| « essayer une autre direction à partir de v1.2.0 » | restore v1.2.0 | Puis effectuez la nouvelle modification et sauvegardez-la comme d'habitude. |
| « quelle est la version actuelle », « quelque chose de non sauvegardé » | status | |
| « donne-moi v1.2.0 sous forme de fichiers » | export v1.2.0 --out v1.2.0.zip | |
| « continuer ceci dans une autre conversation ou un autre outil » | backup --out history.zip | Dans le nouvel endroit : import history.zip. |
Lorsque l'utilisateur nomme une version de manière vague (« la bleue », « avant la refonte »), exécutez list et faites correspondre les résumés. Si deux versions correspondent, demandez laquelle.
Après un retour en arrière
Une restauration complète remet tous les fichiers du projet dans leur état antérieur, y compris les fichiers que l'utilisateur pourrait ne pas considérer comme faisant partie du travail, comme les notes ou les données. Dites à l'utilisateur quels fichiers ont changé (le script les liste). Si le script a d'abord sauvegardé le travail non sauvegardé, dites quelle version le contient et proposez de récupérer des fichiers spécifiques avec restore <cette version> --path <fichier>. Lorsque la demande cible clairement seulement une partie du projet (« les anciennes couleurs »), utilisez --path dès le début.
Exécutez handoff <version que vous avez restaurée> et traitez sa sortie comme la vérité actuelle avant de faire la prochaine modification. Elle liste uniquement les décisions qui ont conduit à cette version et nomme celles qui ont été abandonnées, afin que les instructions provenant de directions abandonnées ne s'infiltrent pas. Si la conversation est longue, proposez de continuer dans une nouvelle conversation et donnez à l'utilisateur le texte de handoff à coller.
Filet de sécurité pour les sauvegardes oubliées
Dans Claude Code ou Cursor, proposez ceci une fois par projet : install-hooks claude-code ou install-hooks cursor. Cela ajoute un hook qui sauvegarde toute modification que vous avez oublié de sauvegarder en tant que Petite retouche lorsque vous terminez. Installez-le uniquement après que l'utilisateur a accepté, car il écrit dans les paramètres de son outil.
Parler des versions
Utilisez les mots de l'utilisateur : Petite retouche, Nouvelle fonctionnalité, Grand changement, Revenu en arrière. Mentionnez les numéros de version, pas les commits, les fichiers dans .ai-versions/ ou les hachages. Les notes spécifiques aux outils (claude.ai, Replit, Windows) se trouvent dans references/tools.md.
Lorsqu'un utilisateur revient en arrière, rappelez-lui une fois que seuls les fichiers reviennent : les lignes de base de données et autres données vivantes restent telles quelles.
Toutes les commandes
| Commande | Ce qu'elle fait |
|---|---|
init [--only PATH...] | Démarrer l'historique et sauvegarder v1.0.0 |
save --bump B --summary S [--reason R] [--prompt P] | Sauvegarder les fichiers actuels en tant que nouvelle version |
status | Version actuelle et modifications non sauvegardées |
list [--all] [--json] | Versions, la plus récente en premier |
show V | Détails d'une version et fichiers modifiés |
diff [A] [B] [--stat] [--path P...] | Sans argument : modifications non sauvegardées. Un argument : A à la dernière. Deux arguments : A à B |
restore V [--path P...] [--note N] | Revenir en arrière (tous les fichiers, ou seulement certains) ; sauvegarde d'abord le travail non sauvegardé, puis sauvegarde la restauration comme une nouvelle version |
handoff [V] | Contexte propre pour continuer à partir de V |
view [--out FILE] | Chronologie HTML de toutes les versions |
export V --out DIR_or_ZIP | Les fichiers d'une version |
backup --out FILE.zip / import FILE.zip | Déplacer tout l'historique |
| `install-hooks claude-code | cursor` |
setup-github [--with-pill] | Ajouter la couche GitHub à un dépôt de constructeur d'applications |
doctor | Vérifier l'historique pour les pièces manquantes |
Les versions peuvent être écrites comme v1.2.0, 1.2.0, latest, prev ou v1.2.0^.