Tâche Claude Code bloquée : quand arrêter les retries et restaurer l'état
Un protocole pratique pour récupérer une tâche Claude Code bloquée : classifier l'erreur, interrompre la boucle, documenter l'état et relancer proprement.
Les tentatives répétées sans limite sont une cause fréquente de gaspillage de tokens, de dégradation du contexte et de modifications de code abîmées avec Claude Code. Lorsqu'un agent échoue sans cesse sur les mêmes tests, rencontre une variable d'environnement absente ou modifie les mêmes fichiers en boucle, relancer sans signal nouveau ne corrige pas la cause. Cela enferme simplement la session dans une impasse.
La bonne approche consiste à interrompre la boucle tôt, à classifier le problème côté API et côté code, à figer l'état réel du dépôt puis à reprendre la tâche par une vérification déterministe.
1. Classifier les échecs : quand un retry est inutile
Toutes les erreurs ne disparaissent pas en rejouant une commande. Sans diagnostic clair, il est facile de confondre une limite temporaire de l'API avec une boucle logique de l'agent :
Pour éviter de deviner l'origine du problème et de consommer des tokens à l'aveugle, séparez les incidents de l'API externe des défauts de code. Avec le workflow BetterToken pour Claude Code, le Dashboard permet de consulter le statut HTTP, le modèle, le temps de réponse et la consommation exacte de tokens d'entrée, de sortie et de cache. Un timeout de passerelle ou un 429 peut justifier un retry limité. Si l'API répond régulièrement 200 OK alors que l'agent édite en rond, arrêtez immédiatement la session.
2. Protocole de récupération priorisé
Après 2 ou 3 tentatives consécutives sans progrès, suivez cet ordre :
```mermaid
graph TD
A[L'agent est dans une boucle d'erreur] --> B[Étape 1 : arrêter immédiatement avec Ctrl+C]
B --> C[Étape 2 : vérifier le statut et le diff Git]
C --> D[Étape 3 : enregistrer une Recovery Card]
D --> E[Étape 4 : lancer une session propre avec un contrôle]
```
Actions pas à pas :
- Étape 1 : arrêter la session. Interrompez l'exécution avec `Ctrl+C`. Ne laissez pas l'agent consommer davantage de contexte en générant de longues justifications ou des sorties inutiles.
- Étape 2 : inspecter et nettoyer l'état. Vérifiez les fichiers modifiés avec `git status --short`. Si l'agent a produit du code cassé, ne restaurez que les fichiers concernés : `git checkout -- <file>`.
- Étape 3 : classifier la cause. Comparez les métriques API du Dashboard aux journaux d'exécution de l'agent afin de distinguer un incident réseau d'une erreur de raisonnement.
- Étape 4 : enregistrer une Recovery Card structurée.
3. La Recovery Card structurée
Consignez l'état exact de la tâche avant d'ouvrir une nouvelle session de récupération :
```markdown
Recovery Card : échec du service d'import
- Objectif initial : ajouter la validation d'e-mail dans `auth/service.ts`.
- Progression réelle : regex ajoutée, mais le test unitaire `auth_test.go` échoue.
- Cause identifiée : l'agent a tenté de mocker une méthode privée plutôt que l'interface publique.
- État Git : branche `fix/auth-email`, diff valide conservé dans `auth/service.ts`.
- Action suivante pour la session propre : refactoriser le test unitaire avec l'interface publique `AuthClient`.
```
[!IMPORTANT]
Aucun secret dans la fiche : n'insérez jamais de clés API, de tokens d'accès ni de dumps mémoire bruts dans une Recovery Card. Vérifiez la configuration de l'endpoint et la gestion des clés dans la documentation BetterToken pour Claude Code.
4. Reprise réversible et vérification
Pour reprendre sans risque :
- Ouvrez une nouvelle session Claude Code avec une fenêtre de contexte propre.
- Donnez à l'agent uniquement l'objectif de la tâche et le champ « Action suivante » de la Recovery Card.
- Demandez un contrôle étroit : `npm test -- tests/auth.test.ts`.
- Vérifiez que le test ciblé réussit (`Passed`), puis contrôlez le diff final avec `git diff --check`.
Ce protocole transforme une boucle d'agent incontrôlée en point de contrôle explicite et protège à la fois le dépôt et le budget de tokens.
Paiement et rechargement du solde
Le paiement et le rechargement pour l'usage de l'API se gèrent dans votre propre compte BetterToken. BetterToken est un service d'accès à des API de modèles facturé à l'usage ; le solde payé et rechargé ne disparaît pas automatiquement chaque mois. Les moyens de paiement, montants minimums, frais, taux de change et délais de traitement peuvent évoluer : consultez le compte au moment du paiement.
Prix et maîtrise des coûts
La disponibilité des modèles et les tarifs précis sont des informations dynamiques. Avant de décider d'un budget, consultez la page des tarifs BetterToken plutôt que de reprendre des chiffres d'un ancien article. Après un appel de test, le Dashboard permet de rapprocher le modèle, le statut et les tokens d'entrée, de sortie et de cache avec la consommation correspondante.