Module 8 — Mode plan, checkpoints, sessions et worktrees : travailler sans peur

Le module 7 a verrouillé ce que Claude a le droit de faire. Ce module s'occupe de la question d'après : que faire quand Claude fait quelque chose que je ne voulais pas, ou quand je veux essayer deux pistes en parallèle sans que l'une pollue l'autre ? Quatre filets s'empilent :

• Le mode plan empêche d'écrire tant qu'un plan n'est pas validé.
• Les checkpoints rembobinent code et conversation à un point d'avant l'accident.
• Les sessions conservent les conversations pour les reprendre, les nommer, les diviser (/branch) ou les copier en arrière-plan (/fork).
• Les worktrees isolent une session entière dans un checkout git séparé.

Le mode plan : penser avant d'écrire

Le mode plan dit à Claude de rechercher et de proposer des modifications sans les appliquer : Claude lit des fichiers, lance des commandes shell d'exploration, rédige un plan ; les éditions restent bloquées jusqu'à validation (sauf en bypassPermissions).

On entre en plan par Shift+Tab (cycle), /plan (bascule pour un tour), /plan <description> (bascule et démarre la tâche décrite), ou claude --permission-mode plan au lancement. Shift+Tab à nouveau sort sans valider.

Pour les commandes shell pendant la planification : si auto est disponible et useAutoModeDuringPlan actif (défaut), le classifieur juge chaque commande — l'exploration passe, l'écriture est refusée. Sinon chaque commande hors read-only demande, même si l'auto-allow du sandbox est actif. En bypassPermissions, aucun garde.

Quand le plan est prêt, Claude le présente et demande la suite :

• Yes, and use auto mode — approuve et passe en auto (devient Yes, auto-accept edits si auto n'est pas dispo, ou Yes, and switch to BYPASS PERMISSIONS si la session a été lancée avec ce mode).
• Yes, manually approve edits — approuve et revient en Manual pour valider chaque édition.
• No, keep planning — reste en plan pour retravailler.

Ctrl+G ouvre le plan dans votre éditeur externe avant de trancher ; si showClearContextOnPlanAccept est activé, une option approuve et vide le contexte de planification. Accepter un plan donne à la session un titre généré à partir du plan.

Pour rendre le plan par défaut dans un projet : permissions.defaultMode: "plan" dans .claude/settings.json. L'extension VS Code lit claudeCode.initialPermissionMode en settings utilisateur à la place. La commande /ultraplan (envoi vers une session web) a été retirée ; utilisez /plan local.

Les checkpoints : rembobiner sans peur

À chaque prompt utilisateur, Claude Code capture l'état des fichiers touchés par ses outils d'édition ; il en garde jusqu'aux 100 plus récents. /rewind (alias /checkpoint, /undo) ou Esc deux fois quand l'input est vide ouvre le menu. Si l'input a du texte, le double Esc le nettoie et le sauve dans l'historique.

Chaque checkpoint propose, selon ce qui a été capturé :

Option	Effet
Restore code and conversation	Rembobine fichiers et conversation.
Restore conversation	Rembobine la conversation, garde le code.
Restore code	Rembobine les fichiers, garde la conversation.
Summarize from here	Compresse la conversation à partir de ce point (libère du contexte).
Summarize up to here	Compresse jusqu'à ce point, garde la suite intacte.

Après un restore de conversation ou « Summarize from here », le prompt original est reposé dans l'input. Pour orienter un résumé, surlignez l'option et tapez dans le champ add context (optional) avant Enter.

Ce qui n'est pas rembobiné : fichiers modifiés par Bash (rm, mv, cp), éditions de sous-agents (sauf skill forkée en foreground avec background: false), changements externes concurrents, symlinks/hardlinks (Claude Code les saute avec Restored the code, but skipped N files). Les snapshots sont purgés après environ 30 jours ; cleanupPeriodDays allonge la rétention. Si un /clear a eu lieu dans le même processus, le menu ajoute une entrée /resume <session-id> (previous session) pour retomber sur la conversation d'avant le clear (v2.1.191+).

Les sessions : nommer, reprendre, dériver

Une session est une conversation liée à un dossier, sauvée en continu sous ~/.claude/projects/<projet>/<session-id>.jsonl (déplaçable via CLAUDE_CONFIG_DIR). Cinq entrées pour la reprendre :

Commande	Effet
claude --continue	Reprend la dernière session interactive du dossier courant.
claude --resume	Ouvre le picker.
claude --resume <id-ou-nom>	Reprend directement (l'ID est cherché dans le projet, ses worktrees, puis tous les autres projets — v2.1.223+).
claude --from-pr <numéro>	Picker filtré sur les sessions liées à cette PR.
/resume	Bascule vers une autre conversation depuis une session active.

Ce qui est restauré : historique complet, modèle, agent (--agent), objectif (/goal), tâches planifiées non expirées, mode de permission (règles subtiles selon la voie d'entrée). Un bypassPermissions d'origine ne se rétablit jamais automatiquement — il faut le repasser au lancement.

Nommez vos sessions. claude -n <nom> au démarrage, /rename <nom> en cours (le nom apparaît sur la barre de prompt), Ctrl+R sur une ligne du picker. Un nom déjà pris reçoit un suffixe du type auth-refactor-graceful-unicorn (v2.1.232+).

Le picker (/resume seul ou claude --resume) : ↑/↓ pour naviguer, Space pour prévisualiser, Ctrl+R pour renommer, Ctrl+A pour élargir à tous les projets, Ctrl+W à tous les worktrees, Ctrl+B pour filtrer sur la branche git. Coller une URL de PR (GitHub/GitLab/Bitbucket) dans la recherche trouve la session qui l'a créée.

Sept commandes pilotent la vie d'une session :

• /clear [nom] — vide le contexte, démarre une nouvelle conversation. Le nom étiquette la précédente dans /resume. Récupérable via le rewind (previous session) tant que le processus tourne. Alias : /reset, /new.
• /branch [nom] — copie la conversation et bascule dedans ; l'originale reste intacte. Les grants « Allow for this session » sont conservés (même processus). Équivalent CLI : claude --continue --fork-session.
• /fork [prompt] — copie la conversation dans une nouvelle session en arrière-plan et vous laisse ici. La copie reçoit l'instruction de créer son propre worktree avant d'éditer.
• /export [fichier] — exporte en texte lisible ; sans argument, dialogue (presse-papiers ou fichier).
• /recap — résumé d'une ligne (400 caractères max). Un recap automatique s'affiche aussi au retour après trois minutes d'absence (désactivable dans /config, Session recap).
• /add-dir <chemin> — élargit l'accès à un dossier (Tab complète). Déclenche les hooks DirectoryAdded. Le .claude/ du dossier ajouté n'est pas découvert.
• /cd <chemin> — déplace la session dans un autre dossier (le transcript suit), à distinguer de /add-dir qui ne fait qu'élargir.
• /diff — ouvre le panneau de diff sur l'arbre de travail, à jour après chaque édition.

Les worktrees : paralléliser sans marcher sur les pieds

Un worktree git est un dossier séparé avec sa propre branche mais partageant le .git du dépôt principal. Une session dans un worktree isole ses éditions : une session code l'auth pendant qu'une autre corrige un bug, sans jamais toucher les mêmes fichiers.

claude --worktree feature-auth

Sans nom, Claude en génère un (bright-running-fox, etc.). Le worktree naît sous .claude/worktrees/<nom>/ sur une branche worktree-<nom> — à ajouter à votre .gitignore. Les runs interactifs exigent la confiance d'espace de travail. En session, Claude peut créer ou entrer un worktree via l'outil EnterWorktree ; toute cible hors de .claude/worktrees/ demande approbation, seul bypassPermissions court-circuite ce garde.

Isolation appliquée par Claude Code — quatre vérifications non désactivables à chaque appel d'outil :

1. Edit, Write, NotebookEdit visant le checkout principal : refusé.
2. Commande Bash/PowerShell/Monitor dont le cwd résout dans le principal : refusée.
3. Commande qui redirige git vers le principal (git -C, GIT_DIR, cd avant git) : refusée.
4. Commande dont la forme ne permet pas de vérifier statiquement où va git : refusée.

Les mêmes règles couvrent chaque sous-agent lancé depuis la session isolée. Le sandbox laisse passer les écritures dans le .git partagé, donc git commit marche.

Paramétrer :

• worktree.baseRef: "fresh" (défaut) branche depuis la branche par défaut du remote ; "head" branche depuis le HEAD local pour porter du travail en cours.
• Brancher depuis une PR : claude --worktree "#1234" (guillemets obligatoires). URL GitHub ou GitLab acceptées.
• .worktreeinclude à la racine du projet (syntaxe .gitignore) copie des fichiers gitignorés — .env, .env.local, config/secrets.json — dans chaque nouveau worktree.
• isolation: worktree dans le frontmatter d'un sous-agent fige son isolation (module 10).

Nettoyage — à la sortie d'une session --worktree, si le worktree est propre et la session sans nom, suppression automatique ; sinon demande. Une balayeuse périodique retire les worktrees de sous-agents et de sessions background plus vieux que cleanupPeriodDays, sauf travail non poussé, lock actif, ou git worktree add manuel.

Fil rouge : refactor du paiement de Kiosque

Vendredi. Karim doit ajouter un second prestataire de paiement à Kiosque derrière un flag, sans casser la démo de lundi. Il ouvre :

claude --worktree paiement-v2

Le worktree naît sur worktree-paiement-v2 depuis main frais (.worktreeinclude a copié .env). Karim tape :

/plan Ajoute un second prestataire de paiement derrière le flag PAY_V2, sans casser l'ancien.

Claude explore app/payments/, écrit un plan de sept étapes. Ctrl+G — Karim reformule l'étape 4 dans son éditeur. Il choisit Yes, manually approve edits. Titre auto : « Ajouter PAY_V2 derrière un flag ».

Trois éditions plus tard, un test casse. Esc deux fois, sélection du prompt d'il y a deux tours, Restore code and conversation. Le prompt original revient dans l'input, il le reformule : « la précédente tentative a cassé les webhooks — commence par le test qui reproduit le bug ». Cette fois ça passe.

En parallèle, Léa explore une alternative dans un second terminal, en partant du travail en cours (worktree.baseRef=head dans son settings.local.json) :

claude --worktree paiement-v2-alt

Elle nomme sa session paiement-alt. À mi-parcours, /branch etage-callback copie la conversation et bascule dedans, l'originale reste dans /resume. Vers 17h, Karim veut interroger Claude sur les tests sans polluer sa session : /fork Écris-moi un tableau des tests d'intégration existants et de leurs zones aveugles. La copie part en arrière-plan (visible dans claude agents), sa session reste sur le refactor.

Lundi, la démo tourne sur main, worktree-paiement-v2 est prêt à merger, paiement-v2-alt est archivé, et /export release-paiement.md capture la conversation clé pour la PR. Trois pistes, zéro conflit sur les fichiers, zéro écrasement.

En résumé

• Mode plan (Shift+Tab, /plan, --permission-mode plan) : bloque les éditions jusqu'à validation. Le classifieur juge les commandes shell si useAutoModeDuringPlan est actif ; Ctrl+G ouvre le plan dans l'éditeur ; approuver donne un titre auto.
• Checkpoints : capture à chaque prompt (100 derniers). /rewind ou Esc+Esc (input vide) proposent restore code / conversation / les deux, ou summarize. Les changements par Bash, sous-agents non foreground-forkés, symlinks et changements externes ne sont pas rembobinés.
• Sessions : --continue, --resume, --from-pr, /resume. Nommez avec -n, /rename. /clear vide, /branch copie et bascule, /fork copie en arrière-plan, /export archive, /recap résume, /add-dir élargit, /cd déplace, /diff montre.
• Worktrees (--worktree <nom> ou EnterWorktree) : chaque session dans un checkout git séparé. worktree.baseRef choisit fresh ou head, --worktree "#1234" branche depuis une PR, .worktreeinclude copie les fichiers gitignorés, isolation: worktree fige un sous-agent, et Claude Code refuse toute écriture qui viserait le checkout principal.

Module suivant : Hooks : automatiser et verrouiller le comportement de Claude — comment intercepter chaque événement (avant/après un outil, un prompt, un edit de settings, la création d'un worktree) pour ajouter validations, mesures et automatismes.