Claude Code CLI : erreurs courantes et recadrage en session

Même avec un bon prompt, un CLAUDE.md et un rituel de validation, certaines sessions partent en vrille : Claude boucle sur la même erreur, modifie plus de fichiers que demandé, ou enchaîne sur un plan que vous n’avez pas validé. Ce guide vous donne les manœuvres de reprise de contrôle à connaître : arrêter net, compacter, recadrer, ou annuler proprement. Toutes se pratiquent sur lab-claude.

Ce que vous allez apprendre

• Repérer 9 dérives typiques d’une session Claude Code
• Appliquer un arbre de décision de recadrage
• Utiliser Esc, /compact, /clear au bon moment
• Formuler un recadrage court et ferme qui tient
• Annuler une modification avec Git sans perdre le reste
• Gérer les conflits Git après un git restore
• Savoir quand quitter la session plutôt que /clear
• Retrouver une décision perdue après un reset contexte

Pourquoi le recadrage est une compétence à part entière

Reprendre une session dérivée, ce n’est pas échouer. C’est la moitié du travail d’un agent. Les deux pièges classiques :

• Laisser dériver “encore une tentative” : le contexte se dégrade, l’agent insiste sur la mauvaise piste
• Tout réinitialiser à la moindre friction : vous perdez l’état utile déjà chargé

La bonne réponse est souvent un geste précis et court, pas une refonte.

Prérequis

• lab-claude opérationnel avec CLAUDE.md en place
• Rituel plan / diff / validations appliqué (voir mode plan, diff et validations)
• Dépôt lab-claude sous contrôle Git propre (git status clean au début)

9 dérives typiques à repérer

Dérive	Signal visible	Manœuvre recommandée
Claude ignore le périmètre	Diff touche des fichiers hors scope	Recadrage court + rejet du diff
Boucle sur la même erreur	Plusieurs tentatives sur le même symptôme	Esc, reformuler l’hypothèse
Plan qui s’allonge	Plan à 7+ étapes alors que vous avez demandé 3	Recadrer vers plan plus court
Session qui bavarde	Réponses longues, peu d’action	/compact pour resserrer le contexte
Contexte dégradé	Claude oublie des éléments posés tôt	/clear et repartir avec un prompt structuré
Confiance excessive	Claude affirme “c’est bon” sans preuve	Exiger la sortie de pytest + ruff
Tests désactivés	Un test passe parce qu’il a été marqué skip	Relire le diff ligne à ligne sur tests/
Edit massif	Un seul prompt déclenche 10 fichiers modifiés	Esc, git restore, réduire le périmètre
Hallucination d’API	Méthode ou paramètre qui n’existe pas	Recadrer : “cite le fichier source ou dis que tu ne sais pas”
Dépendance silencieuse	pyproject.toml modifié sans mention	Refuser le diff, interdire l’ajout sans validation

Glissez pour voir

Identifier la dérive avant d’agir évite d’appliquer la mauvaise manœuvre.

Arbre de décision : quelle manœuvre appliquer

Quand une session dérive, suivez cet ordre. La règle d’or : commencer par le geste le moins destructeur.

Dérive détectée
 │
 ├─ Action en cours ? ──── oui ──> Esc
 │                                   │
 │                                   v
 │                               Diagnostic court
 │
 ├─ Diff hors périmètre ? ─ oui ──> Refuser + recadrage
 │
 ├─ Fichiers modifiés à tort ?
 │        │
 │        oui ──> git stash (sécuriser) ──> git restore ciblé
 │                                              │
 │                                              v
 │                                         ruff + pytest
 │
 ├─ Session longue mais utile ? ─ oui ──> /compact
 │                                          │
 │                                          v
 │                                      Rappeler périmètre
 │
 └─ Contexte irrécupérable ? ──── oui ──> /clear OU quitter la session
                                            │
                                            v
                                       Prompt structuré

Lisez l’arbre de haut en bas : vous n’appliquez /clear qu’après avoir tenté Esc, un recadrage, et /compact.

Les 3 commandes de reprise à connaître

Esc — arrêter Claude en cours

Interrompt immédiatement l’action en cours (recherche, modification, exécution). À utiliser dès que vous voyez Claude partir dans une direction qui ne convient pas : inutile d’attendre la fin.

/compact — compresser le contexte

Résume la session en gardant l’essentiel, libère de la fenêtre de contexte. À utiliser quand la session est longue mais que vous voulez continuer avec les mêmes objectifs.

/clear — repartir propre

Remet la session à zéro. À utiliser quand le contexte est trop dégradé et qu’aucun résumé ne sauverait la suite. Vous conservez votre CLAUDE.md, les fichiers du projet et votre historique Git.

Ordre préférentiel

Essayez d’abord Esc + recadrage. Si ça ne suffit pas, /compact. /clear seulement si vraiment le contexte est irrécupérable.

Étape 1 : arrêter proprement avec Esc

1. Dès que vous voyez une dérive en cours, appuyez sur Esc

2. Posez un diagnostic court

   Stop. Explique en 3 points ce que tu étais en train de faire
   et pourquoi tu as pris cette direction.
   Ne modifie rien.

3. Décidez : recadrer dans la session actuelle ou compacter/effacer

Étape 2 : formuler un recadrage court et ferme

Un recadrage efficace est bref, directif et rappelle le périmètre.

Exemple type :

Stop. Tu sors du périmètre.
Travaille uniquement sur app/main.py et tests/test_health.py.
Propose un plan en 3 étapes maximum.
N'exécute rien tant que je n'ai pas validé.

À éviter :

Non, ce n'est pas exactement ce que je voulais, peut-être qu'on pourrait...

La politesse est bien, mais elle dilue la consigne. Soyez précis avant d’être gentil.

Étape 3 : compacter quand la session est longue mais encore utile

1. Lancez la commande

   /compact

2. Relisez le résumé proposé

   Vérifiez qu’il conserve : objectif, périmètre, décisions déjà prises, fichiers déjà touchés.

3. Ajustez si nécessaire

   Ajoute au résumé : le périmètre est limité à app/main.py et tests/test_health.py.

Étape 4 : repartir propre avec /clear

Utilisez /clear quand au moins deux de ces signaux sont réunis : Claude se contredit, il oublie des règles posées, il insiste sur une mauvaise piste malgré le recadrage.

1. Vérifiez l’état Git avant de repartir

   git status
   git diff

2. Annulez les modifications non voulues (voir étape 5)

3. Lancez /clear puis reformulez un prompt structuré

   Lis app/main.py et tests/test_health.py.
   Résume en 6 points le comportement actuel de /health.
   Ne modifie aucun fichier.

Étape 5 : annuler proprement une modification avec Git

Si Claude a modifié des fichiers hors périmètre, n’essayez pas de corriger à la main.

1. Regardez l’état

   git status
   git diff

2. Annulez un fichier spécifique

   git checkout -- app/main.py

3. Ou annulez tout le working tree non commité

   git restore .

4. Relancez les validations pour vérifier

   uv run ruff check .
   uv run pytest -q

Avant d'annuler

Vérifiez qu’aucune modification souhaitée ne sera perdue. git stash permet de mettre en sécurité avant d’essuyer le reste.

Sécuriser avec git stash avant un reset

git restore . écrase les modifications non commitées. Si une partie est utile, mettez-la en sécurité avant :

git stash push -m "avant-recadrage-claude"
git restore .
uv run ruff check .
uv run pytest -q

Vous pouvez ensuite :

• Appliquer les changements sauvegardés : git stash pop
• Lister les sauvegardes : git stash list
• Supprimer définitivement : git stash drop

Réflexe : toujours stash avant restore quand vous hésitez sur ce qui est utile.

Gérer les conflits Git après un reset partiel

Il arrive qu’un git stash pop ou un git checkout -- <fichier> produise un conflit quand le fichier a changé entre-temps. Procédure simple :

1. Listez les fichiers en conflit

   git status

2. Ouvrez chaque fichier et résolvez les marqueurs <<<<<<<, =======, >>>>>>>

3. Ajoutez la résolution

   git add <fichier>

4. Relancez le rituel

   uv run ruff check .
   uv run pytest -q

Si le conflit vient d’un stash, terminez par git stash drop pour nettoyer la pile une fois le conflit résolu.

/clear ou quitter la session : lequel choisir

/clear vide le contexte mais garde la session ouverte (historique accessible via /resume). Quitter complètement (Ctrl+D ou /exit) ferme tout.

Situation	Choix recommandé
Contexte dégradé mais même tâche	/clear + prompt structuré
Changement complet de tâche ou de projet	Quitter et relancer claude
Longue session dont vous voulez pouvoir revenir	Quitter (puis claude --resume si utile)
Vous n’êtes pas sûr de pouvoir sauver le contexte	Quitter et repartir propre

Glissez pour voir

Règle pratique : quand vous hésitez, quittez. Relancer une session prend 2 secondes, et le CLAUDE.md du projet se recharge automatiquement.

Retrouver une décision perdue après un reset

Après /clear ou un redémarrage, les décisions prises dans la conversation disparaissent, mais les traces persistantes restent :

• Le diff Git montre ce qui a été réellement modifié : git diff HEAD~1
• L’historique de commits raconte la progression : git log --oneline -20
• Les fichiers du projet (notamment CLAUDE.md si vous y avez enregistré une règle)
• L’historique de la session si vous relancez avec claude --resume

Bonne pratique pour limiter la perte : si une décision doit survivre à un /clear, elle doit atterrir quelque part de persistant (commit, CLAUDE.md, ou note en clair dans un fichier du projet).

Tableau récapitulatif des manœuvres

Situation	Geste immédiat
Claude part sur une mauvaise piste	Esc + prompt de diagnostic
Diff hors périmètre proposé	Refuser + recadrage court
Session longue mais encore utile	/compact
Contexte irrécupérable, même tâche	/clear + prompt structuré
Changement de tâche complet	Quitter + relancer claude
Fichiers modifiés à tort	git checkout -- <fichier>
Multiples fichiers impactés	git stash puis git restore . + vérif ruff + pytest
Conflit après stash pop	Résoudre marqueurs + git add + rituel
Décision à préserver	La commit ou l’écrire dans CLAUDE.md

Glissez pour voir

Erreurs fréquentes

Symptôme	Cause probable	Correction
Recadrage sans effet	Formulation trop longue ou polie	Raccourcir, commencer par Stop.
/compact perd le périmètre	Résumé trop générique	Ajouter un post-compact rappelant les fichiers cibles
Modifications perdues utiles	git restore trop large	Préférer git checkout -- fichier ciblé ou git stash
Boucle sur la même erreur après /clear	Même prompt flou	Reformuler avec objectif + périmètre + contrainte + validation

Glissez pour voir

Checklist de fin de guide

• Je reconnais au moins 3 dérives sans hésiter
• Je sais quand utiliser Esc, /compact, /clear
• Je formule un recadrage court commençant par Stop.
• Je sais annuler une modification ciblée avec Git
• Je relance ruff + pytest après chaque annulation

À retenir

• Une session dérivée n’est pas un échec, c’est un signal à traiter
• Priorisez : Esc + recadrage > /compact > /clear
• Git est votre filet de sécurité : utilisez-le avant de reprompter
• Un bon recadrage est bref, précis et directif

Prochaines étapes

settings.json avancé Durcir les garde-fous avec des permissions projet partagées

Mode plan, diff et validations Revoir le rituel qui prévient la plupart des dérives

Configurer CLAUDE.md Renforcer les garde-fous persistants du projet

×

📖 Voir la documentation →