Diagnostic et récupération

Quand Claude tourne en rond

Une boucle survient lorsque Claude répète la même approche sans succès : il retente la même commande, réécrit le même fichier, ou s'excuse avant de reproduire exactement la même erreur. Reconnaître une boucle rapidement permet d'économiser des tokens (les unités de texte que le modèle traite) et d'éviter d'aggraver les erreurs.

La sortie la plus rapide est un changement de périmètre : plutôt que de demander à Claude de réparer l'ensemble défaillant, isolez le plus petit élément qui doit d'abord fonctionner. Donnez à Claude un seul fichier, une seule fonction, ou un seul message d'erreur plutôt que le contexte complet. Un périmètre plus étroit signifie moins de variables et un chemin plus court vers une réponse correcte.

Lorsque restreindre le périmètre ne suffit pas, changez complètement d'approche. Indiquez explicitement à Claude quelle stratégie abandonner et quoi essayer à la place. Des formules comme /clear dans Claude Code (qui réinitialise le contexte de la conversation) ou l'ouverture d'une nouvelle session empêchent les tentatives précédentes ayant échoué d'influencer les suivantes.

• Utilisez /clear pour effacer la conversation et repartir de zéro sans perdre vos fichiers.
• Collez uniquement l'erreur ou le bloc de code pertinent, pas l'intégralité du projet.
• Énoncez la contrainte explicitement : Do not touch file X. Focus only on function Y.
• Demandez à Claude d'expliquer son plan avant d'agir : Describe your approach in one paragraph, then wait.

Récupérer après une mauvaise modification

Claude Code modifie les fichiers directement sur le disque. Si un changement casse quelque chose, il faut agir vite avant que le contexte grossisse et que l'état d'origine devienne difficile à retrouver. Les deux principales voies de récupération sont le retour arrière via git (quand votre projet utilise git, un système de contrôle de version qui suit chaque modification de fichier) et l'annulation manuelle (quand ce n'est pas le cas).

Quand git est disponible, ces commandes couvrent la plupart des situations :

• Voir ce qui a changé : /git diff dans Claude Code, ou git diff dans un terminal. Cela montre chaque ligne ajoutée ou supprimée depuis le dernier point de sauvegarde (appelé commit).
• Annuler tous les changements non commités : git checkout -- . (le point signifiant "tous les fichiers") remet chaque fichier suivi à l'état du dernier commit. Les nouveaux fichiers non suivis ne sont pas touchés.
• Restaurer un seul fichier : git checkout -- path/to/file.js restaure uniquement ce fichier.
• Annuler le dernier commit en conservant les modifications en attente : git reset --soft HEAD~1. À utiliser quand le commit a eu lieu mais que le code est encore incorrect.
• Annuler le dernier commit et supprimer complètement les modifications : git reset --hard HEAD~1. Cette opération est destructive : les changements sont perdus.

S'il n'y a pas d'historique git, les options sont plus limitées. Claude Code conserve une transcription de la session, vous pouvez donc lui demander de réafficher le contenu original d'un fichier qu'il a modifié, puis le coller à nouveau. Pour les fichiers critiques, la meilleure habitude est d'exécuter cp important.js important.js.bak avant de démarrer une longue session d'édition.

Vous pouvez aussi demander directement à Claude Code : "Annule la dernière modification de config.js" ou "Reviens en arrière sur tous tes changements de cette session." Claude Code utilisera git en coulisse quand c'est possible, ou tentera de reconstruire le contenu précédent depuis sa fenêtre de contexte (la mémoire active de la conversation).

Le contexte s'est pollué

Chaque conversation avec Claude se déroule dans une fenêtre de contexte (le bloc de texte que le modèle peut voir à la fois). Lorsqu'une longue session accumule des tentatives échouées, des instructions contradictoires ou des sorties d'outils bruyantes, le modèle commence à privilégier ce mauvais historique et produit de moins bonnes réponses. C'est ce qu'on appelle la pollution de contexte.

Claude Code vous offre trois niveaux d'intervention, du moins au plus perturbateur :

• Compact (/compact) : résume la conversation jusqu'à présent en un court digest, conserve ce résumé dans le contexte et libère de l'espace. Utilisez ceci quand la session est encore productive mais commence à être longue.
• Clear (/clear) : efface tout l'historique de conversation mais conserve vos fichiers de travail et la session Claude Code ouverte. Utilisez ceci quand le contexte induit activement Claude en erreur mais que vous souhaitez rester dans le même projet.
• Nouveau départ (fermer et rouvrir Claude Code, ou démarrer un nouveau chat) : supprime tout l'état de session. Utilisez ceci quand même un contexte effacé entraîne de mauvaises hypothèses provenant des fichiers ouverts ou de l'état des outils.

Une bonne règle empirique : si vous vous retrouvez à ré-expliquer quelque chose que vous avez déjà dit trois messages plus tôt, commencez par compacter. Si Claude se contredit ou ignore une contrainte que vous avez définie, utilisez clear. Si le modèle semble halluciner le contenu de fichiers ou des résultats d'outils, repartez de zéro et relisez explicitement les fichiers pertinents.

Une API incorrecte ou obsolète

Claude est entraîné sur un instantané figé du monde. Quand vous lui demandez d'appeler une API (une interface de programmation, le contrat qui définit comment deux programmes communiquent), il peut générer du code correspondant à une version plus ancienne de cette API. C'est ce qu'on appelle un appel halluciné ou obsolète : le code paraît plausible mais échouera à l'exécution parce que l'endpoint, le nom du paramètre ou l'en-tête requis n'existe plus.

Le schéma d'échec est généralement l'un des suivants :

• Un statut HTTP 404 (non trouvé) ou 410 (supprimé), indiquant que le chemin URL a été retiré.
• Un 422 ou 400 (non traitable / mauvaise requête), indiquant qu'un champ obligatoire a changé de nom ou qu'un champ déprécié a été rejeté.
• Une erreur d'authentification (401/403) parce que le format du token ou la clé d'en-tête a changé (par exemple, certaines API sont passées de Authorization: Token ... à Authorization: Bearer ...).
• Un résultat erroné silencieux quand un ancien champ optionnel est désormais ignoré et qu'un nouveau champ obligatoire n'a jamais été envoyé.

La solution est toujours la même : ancrer Claude dans la spécification réelle et actuelle avant de lui demander d'écrire ou de déboguer l'appel. Vous pouvez coller la section pertinente de la documentation officielle directement dans votre prompt, ou pointer Claude Code vers le fichier OpenAPI (description lisible par machine de l'API) en direct avec /fetch. Ne faites jamais confiance à Claude pour connaître une API tierce sans source.

Dans Claude Code (l'agent de codage en ligne de commande et IDE), le flux de travail est le suivant : reproduire l'erreur, collecter la réponse HTTP brute, récupérer la documentation actuelle, puis demander à Claude de comparer son code généré avec la spécification réelle et de ne corriger que ce qui a changé. Gardez la correction chirurgicale pour éviter d'introduire de nouveaux bugs.

Vous obtenez une erreur 429

Une erreur 429 signifie "Trop de requetes." L'API (Application Programming Interface, la passerelle que Claude Code utilise pour atteindre Claude) a une limite de débit : un plafond sur le nombre de tokens (morceaux de texte) que vous pouvez envoyer ou recevoir dans une fenêtre de temps donnée. Atteindre ce plafond fait rebondir chaque requête avec un 429 jusqu'à ce que la fenêtre se réinitialise.

Claude Code signale les erreurs 429 par un message d'erreur rouge dans le terminal. Le message inclut généralement une valeur d'en-tête Retry-After, vous indiquant exactement combien de secondes attendre. Si vous êtes sur un plan gratuit ou de niveau 1, la fenêtre est généralement d'une minute ; sur les niveaux supérieurs, les limites s'appliquent aussi par heure et par jour.

Causes courantes des erreurs 429 dans une session Claude Code :

• Exécuter un workflow multi-agents ou parallèle qui déclenche de nombreux appels simultanés
• Utiliser la réflexion étendue (valeur élevée de budget_tokens) sur des prompts répétés, ce qui consomme des tokens rapidement
• Des scripts en boucle (comme /loop ou une automatisation personnalisée) sans délai entre les itérations
• Un contexte de grande base de code lu intégralement à chaque tour au lieu de façon incrémentielle

Pour éviter les erreurs 429 : lisez les fichiers de façon incrémentielle avec offset et limit, utilisez le prompt caching (préfixez les parties stables de votre contexte pour qu'elles ne soient pas refacturées à chaque tour), abaissez max_tokens quand vous n'avez pas besoin de longues réponses, et ajoutez une courte pause entre les appels automatisés. Pour les travaux par lots importants, passez à la Batch API, qui a une limite de débit séparée, bien plus élevée, et un rabais de 50 % sur les coûts.

Une commande bloquée

Un processus bloqué est un processus qui a cessé de progresser sans pour autant se terminer. Dans Claude Code, cela se produit généralement quand une commande shell attend indéfiniment une saisie, qu'une requête réseau expire silencieusement, ou qu'une tâche en arrière-plan remplit un tampon. Savoir faire la différence entre "lent" et "vraiment bloqué" vous évite d'interrompre un travail qui a simplement besoin de plus de temps.

La solution la plus rapide est Ctrl+C, qui envoie un signal d'interruption au processus de premier plan. Si le terminal lui-même est gelé, appuyez sur Ctrl+C deux fois rapidement. Claude Code annulera l'appel d'outil en cours et vous rendra le contrôle sans perdre le contexte de la conversation.

Pour les commandes susceptibles de durer longtemps, lancez-les en tant que tâches en arrière-plan en ajoutant run_in_background: true dans les paramètres de l'outil, ou suffixez la commande shell avec &. Vous recevrez une notification à la fin de la tâche au lieu d'attendre de façon bloquante.

• Ctrl+C : interrompt et annule l'appel d'outil actif.
• préfixe timeout : encadrez les commandes risquées avec timeout 30 <commande> pour les arrêter automatiquement après N secondes.
• indicateur background : utilisez run_in_background pour les compilations longues, les serveurs ou les suites de tests.
• /stop : la commande slash de Claude Code (les commandes slash commencent par /) qui arrête une boucle d'agent en cours sans fermer la session.

Annuler des modifications en toute sécurité

Git offre plusieurs niveaux d'annulation, chacun adapté à une situation différente. L'essentiel est de savoir lequel utiliser pour récupérer ce dont vous avez besoin sans rien perdre d'autre.

git restore supprime les modifications non validées dans votre répertoire de travail. Exécutez git restore path/to/file.js pour annuler les changements non sauvegardés dans ce fichier et le ramener à son dernier état commité. Ajoutez l'option --staged pour retirer un fichier de la zone de préparation sans toucher aux modifications sur le disque : git restore --staged path/to/file.js.

git checkout (syntaxe plus ancienne, encore largement utilisée) peut faire la même chose pour un fichier unique : git checkout -- path/to/file.js. Il permet aussi de sauter vers un commit ou une branche spécifique, ce qui est utile pour inspecter un état antérieur sans effacer votre travail actuel.

Quand vous pensez avoir perdu un commit, git reflog est votre filet de sécurité. Le reflog (abrégé de "reference log") enregistre chaque position vers laquelle HEAD a pointé, y compris les commits "supprimés" par un reset ou un rebase. Flux de récupération habituel :

• Exécutez git reflog pour lister les positions récentes de HEAD avec leurs hachages courts.
• Trouvez le hachage juste avant que les choses aient mal tourné.
• Créez une nouvelle branche à partir de lui : git checkout -b recovery abc1234.
• Fusionnez ou faites un cherry-pick de ce dont vous avez besoin dans votre branche principale.

Quand repartir de zéro

Une session Claude Code accumule du contexte (l'historique complet des messages, des appels d'outils et des lectures de fichiers conservés en mémoire). Lorsque ce contexte devient périmé, contradictoire ou simplement trop volumineux, poursuivre la session consomme plus de tokens et produit de moins bons résultats qu'ouvrir une nouvelle session.

Repérez ces signaux indiquant que vouloir sauver la session est la mauvaise décision :

• Boucles répétitives : Claude continue de proposer la même correction défectueuse alors que vous l'avez déjà rejetée.
• Confusion de contexte : Claude fait référence à un ancien chemin de fichier, à une variable supprimée ou à un plan que vous avez explicitement annulé.
• Pression sur les tokens : les réponses deviennent laconiques, sautent des étapes ou vous avertissent que la fenêtre de contexte est presque pleine.
• Échecs d'outils en cascade : trois appels d'outils consécutifs ou plus échouent pour des raisons sans rapport, ce qui signale que l'état de la session est corrompu plutôt que le code lui-même.

Repartir de zéro ne signifie pas perdre votre travail. Les résumés compressés vous permettent de transporter les décisions essentielles dans la nouvelle session sans le bruit parasite. Utilisez /compact avant de quitter pour comprimer la conversation, puis copiez le résumé au début de votre prochaine session.

La règle pratique : si vous avez passé plus de temps à vous battre contre la session qu'à écrire du code, réinitialisez. Une session propre avec un prompt de passation bien rédigé (un court paragraphe décrivant ce qui a été fait et ce qui vient ensuite) est plus rapide que de maintenir en vie une session défaillante.