Les Checkpoints
À l'issue de cette leçon, le stagiaire comprend ce qu'est un checkpoint dans Claude Code, sait en créer manuellement avant une action risquée, et restaurer un état précédent en cas de besoin.
Le filet de sécurité de Claude Code
Travailler avec un agent qui modifie vos fichiers suppose un mécanisme de retour en arrière fiable. C'est le rôle des checkpoints dans Claude Code : des instantanés automatiques de l'état de vos fichiers, pris avant chaque action modifiante, conservés localement, restaurables en une commande.
L'analogie : un point de sauvegarde automatique dans un jeu vidéo. Vous explorez librement sachant que vous pouvez revenir au dernier checkpoint à tout moment. Si Claude fait quelque chose d'inattendu, vous ne perdez pas plus de quelques minutes de travail.
Checkpoints automatiques vs manuels
Automatiques
Claude crée un checkpoint avant chaque action modifiante : édition de fichier, exécution de commande shell, création de dossier. Aucune action de votre part. Labels descriptifs : « avant write src/auth.ts ».
Manuels — commande /checkpoint
Vous créez un checkpoint à un moment précis avec un label de votre choix : /checkpoint avant-refacto-auth. À utiliser avant toute action que vous identifiez comme risquée.
Avantages des checkpoints
Locaux, instantanés, ne nécessitent pas Git. Idéal pour les sessions exploratoires où vous n'avez pas envie de polluer l'historique Git avec des commits intermédiaires.
Complémentaires à Git
Les checkpoints ne remplacent pas Git. Git = partagé et durable. Checkpoints = locaux et éphémères. Les deux sont complémentaires : Git pour les jalons publics, checkpoints pour l'exploration.
Trois commandes essentielles
Trois commandes couvrent tous les besoins de gestion des checkpoints. Aucune n'est complexe ; toutes méritent d'être connues par cœur.
/checkpoint [label] # Créer manuellement un checkpoint # Label optionnel : si vide, label par défaut /checkpoints # Lister les checkpoints disponibles # Affiche ID, date, label, fichiers concernés /restore [id] # Restaurer un état # Demande confirmation avant restauration
La commande /restore sans ID restaure le checkpoint le plus récent. Pour cibler un checkpoint précis, lister d'abord avec /checkpoints, identifier l'ID, puis /restore ckp_a3f9c2.
Quand créer un checkpoint manuel
Les checkpoints automatiques couvrent 90 % des besoins. Les checkpoints manuels sont à créer dans quatre situations précises où l'automatique peut être insuffisant :
Avant un refacto multi-fichiers
Refactoring touchant 3+ fichiers liés. Le checkpoint manuel encadre toute la séquence et permet de revenir d'un coup si l'ensemble ne tient pas.
Avant une migration
Migration de version (Python 3.10 → 3.12, Node 18 → 20), changement de dépendance majeure. Le risque de casse est élevé.
Avant une suppression
Suppression de fichier, de dossier, de section de code. Les checkpoints sauvent les suppressions involontaires aussi bien que volontaires regrettées.
Avant un test exploratoire
Quand vous voulez voir « ce que ça donne si on essaie X ». Le checkpoint vous laisse explorer sans engagement. Restauration trivial si X est une mauvaise idée.
Trois secondes pour /checkpoint avec un label clair (par exemple « avant-refacto-auth »), des heures économisées si la modification tourne mal. Le coût de l'oubli est asymétrique : nul si tout se passe bien, énorme si ça plante.
Où sont stockés les checkpoints
Les checkpoints sont stockés localement dans .claude/checkpoints/ à la racine du projet. Votre disque, votre contrôle. Ils ne sont pas dans Git (le dossier est généralement dans .gitignore), pas dans le cloud, pas accessibles par Anthropic.
Cela a deux conséquences :
- Les checkpoints ne sont pas partagés en équipe. Si vous travaillez en collaboration, les checkpoints sont propres à chaque machine. Pour partager un état avec un collègue, passez par Git.
- Les checkpoints peuvent occuper de l'espace disque. Sur les gros projets, le dossier
.claude/checkpoints/peut grossir vite. Voir la rétention ci-dessous.
Rétention et nettoyage
Par défaut, Claude Code conserve les checkpoints pendant 7 jours, puis purge automatiquement les plus anciens. La durée est configurable dans ~/.claude/settings.json ou via /config.
Quand ajuster la rétention
- Allonger si vous travaillez par sprints longs et voulez pouvoir revenir 2-3 semaines en arrière
- Raccourcir si l'espace disque est contraint ou si vous générez beaucoup de checkpoints éphémères
- Désactiver n'est pas recommandé : c'est un filet de sécurité gratuit côté performance
Pour les checkpoints critiques que vous voulez conserver indéfiniment, le bon réflexe est de faire un commit Git à ce moment-là. Les checkpoints sont pour le court terme ; Git pour le long terme.
Créer et restaurer un checkpoint manuel
Lors de votre prochaine session Claude Code, créez au moins un checkpoint manuel avec /checkpoint avant une action que vous identifiez comme un peu risquée. Listez vos checkpoints avec /checkpoints. Pour bien comprendre la mécanique, forcez-vous à restaurer une fois avec /restore — même si vous savez que vous n'auriez pas eu besoin de le faire. C'est le seul moyen d'avoir confiance dans le filet de sécurité.
Cet exercice est à conserver dans votre dossier de stagiaire. Il n'est pas évalué mais il est tracé.
- docs.claude.com — Claude Code Checkpointing documentation officielle des checkpoints, commandes et configuration
Vous savez créer, lister et restaurer des checkpoints dans Claude Code, et identifier quand les utiliser ?