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 10 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)

10 dérives typiques à repérer

La colonne du milieu est la seule qui compte au moment où vous êtes dans la session : elle décrit ce que vous voyez à l'écran, pas ce que vous supposez. Les cinq premières lignes sont des dérives de conduite (l'agent avance mal), les cinq dernières des dérives de résultat (l'agent produit du code qu'il ne faut pas garder). Les secondes coûtent plus cher parce qu'elles passent inaperçues jusqu'à la relecture du diff, et deux d'entre elles ne se voient que dans les fichiers que l'on ne relit pas : tests/ et pyproject.toml.

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

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

Démarre une nouvelle conversation avec un contexte vide. À 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 ; la conversation précédente n'est pas détruite, elle reste accessible avec /resume. Passer un nom en argument (/clear enquete-health) l'étiquette dans le sélecteur de /resume, ce qui rend le retour en arrière praticable.

Étape 1 : arrêter proprement avec Esc

Esc coupe l'action en cours, il n'annule rien de ce qui a déjà été écrit sur le disque. C'est un arrêt, pas un retour en arrière : les fichiers déjà modifiés le restent, et c'est l'étape 5 qui s'en occupe. L'intérêt d'interrompre tôt est de figer l'état avant qu'il ne s'étende à d'autres fichiers, puis de demander un diagnostic sans autoriser de nouvelle modification, ce que fait la dernière ligne du prompt ci-dessous.

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

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.

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

/compact remplace l'historique de la conversation par un résumé, ce qui libère du contexte mais fait perdre le détail. Le risque n'est donc pas de perdre du code, c'est de perdre une contrainte posée quarante messages plus tôt et que le résumé n'a pas jugée importante. D'où l'étape 2 ci-dessous : relire ce que le résumé a retenu au lieu d'enchaîner directement. /compact accepte aussi des consignes de focalisation directement dans la commande, ce qui évite l'aller-retour de l'étape 3.

Lancez la commande
```
/compact
```
Relisez le résumé proposé

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

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.

Vérifiez l'état Git avant de repartir
Fenêtre de terminal
```
git status
git diff
```
Annulez les modifications non voulues (voir étape 5)

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.

Regardez l'état
Fenêtre de terminal
```
git status
git diff
```
Annulez un fichier spécifique
Fenêtre de terminal
```
git restore app/main.py
```
Ou annulez tout le working tree non commité
Fenêtre de terminal
```
git restore .
```
Relancez les validations pour vérifier
Fenêtre de terminal
```
uv run ruff check .
uv run pytest -q
```

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 restore <fichier> produise un conflit quand le fichier a changé entre-temps. Procédure simple :

Listez les fichiers en conflit
Fenêtre de terminal
```
git status
```
Ouvrez chaque fichier et résolvez les marqueurs <<<<<<<, =======, >>>>>>>
Ajoutez la résolution
Fenêtre de terminal
```
git add <fichier>
```
Relancez le rituel
Fenêtre de terminal
```
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 démarre une nouvelle conversation sans quitter le CLI ; la précédente reste récupérable avec /resume. Quitter complètement (Ctrl+D ou /exit, dont /quit est l'alias) rend la main au terminal. La différence pratique est faible côté données, puisque dans les deux cas rien n'est perdu : elle porte surtout sur le coût de reprise, immédiat avec /clear, de quelques secondes de relance avec /exit.

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

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

Ce tableau est fait pour être consulté pendant une session qui dérape, quand vous n'avez pas le temps de relire le guide. Il reprend les lignes précédentes dans l'ordre de gravité croissante : les quatre premières se règlent dans la conversation, les quatre suivantes touchent au dépôt Git. Le passage de l'une à l'autre moitié est le moment où vous devez vérifier git status avant d'agir.

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 restore <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`

Erreurs fréquentes

Ces quatre situations ont la même racine : on applique la bonne manœuvre avec une formulation trop vague. Un recadrage poli, un résumé non guidé, un git restore . sans cible, un prompt qui ne dit pas ce qui est interdit produisent tous le même effet, l'agent repart dans la direction qu'il avait déjà prise. La colonne de droite se lit donc comme une consigne de précision, pas comme une commande de plus.

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 un `git restore <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

Checklist de fin de guide

Ces cinq points se vérifient en pratiquant, pas en relisant. Rejouez une session sur lab-claude en provoquant volontairement une dérive (demandez une modification hors périmètre, puis interrompez) : si vous enchaînez Esc, recadrage, git restore et validations sans rouvrir cette page, le guide a servi.

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