Claude-Code-Task hängt fest: Wann du Retries stoppst und den Zustand wiederherstellst
Ein praktisches Protokoll für festgefahrene Claude-Code-Tasks: Fehler einordnen, Schleifen abbrechen, Git-Zustand sichern und mit einem klaren Prüfschritt fortsetzen.
Unbegrenzte Wiederholungsversuche sind bei der Arbeit mit Claude Code eine häufige Ursache für unnötigen Tokenverbrauch, verschlechterten Kontext und beschädigte Änderungen. Wenn ein Agent immer wieder an denselben Tests scheitert, Umgebungsvariablen fehlen oder dieselben Dateien in einer Schleife bearbeitet werden, löst ein erneuter Versuch ohne neues Signal die Ursache nicht. Er führt die Sitzung nur tiefer in eine Sackgasse.
Die richtige Strategie ist, die Schleife früh zu unterbrechen, Fehler auf API- und Codeebene einzuordnen, den tatsächlichen Repository-Zustand festzuhalten und die Aufgabe über einen deterministischen Prüfschritt wieder aufzunehmen.
1. Fehlerarten einordnen: Wann ein Retry nichts bringt
Nicht jeder Fehler verschwindet durch einen weiteren Befehlslauf. Ohne klare Diagnose verwechselt man vorübergehende Netzwerk- oder Rate-Limit-Probleme leicht mit logischen Schleifen des Agenten:
Um nicht über Ursachen zu raten und Tokens blind zu verbrauchen, trenne Probleme eines externen API-Aufrufs von Codefehlern. Im BetterToken-Workflow für Claude Code kannst du im Dashboard HTTP-Status, Modell, Antwortzeit sowie Verbrauch für Eingabe-, Ausgabe- und Cache-Tokens prüfen. Liefert die API einen Gateway-Timeout oder 429, ist ein begrenzter Retry plausibel. Liefert sie zuverlässig 200 OK, während der Agent kreisförmig editiert, beende die Sitzung sofort.
2. Priorisiertes Wiederherstellungsprotokoll
Wenn ein Agent 2–3 aufeinanderfolgende Versuche ohne Fortschritt gemacht hat, arbeite diese Reihenfolge ab:
```mermaid
graph TD
A[Agent steckt in einer Fehlerschleife] --> B[Schritt 1: Mit Ctrl+C sofort stoppen]
B --> C[Schritt 2: Git-Status und Diff prüfen]
C --> D[Schritt 3: Recovery Card speichern]
D --> E[Schritt 4: Saubere Sitzung mit Prüfschritt starten]
```
Schritt für Schritt:
- Schritt 1: Sitzung beenden. Unterbrich den Lauf mit `Ctrl+C`. Lass den Agenten nicht weiter Kontext für lange Erklärungen oder zusätzliche Ausgaben verbrauchen.
- Schritt 2: Zustand prüfen und bereinigen. Prüfe geänderte Dateien mit `git status --short`. Hat der Agent defekten Code erzeugt, setze ausschließlich die beschädigten Dateien zurück: `git checkout -- <file>`.
- Schritt 3: Ursache klassifizieren. Vergleiche die API-Metriken im Dashboard mit den Ausführungsprotokollen des Agenten und trenne Netzwerkfehler von einem Logikfehler.
- Schritt 4: Eine strukturierte Recovery Card sichern.
3. Die strukturierte Recovery Card
Halte den genauen Aufgabenzustand fest, bevor du eine neue Wiederherstellungssitzung startest:
```markdown
Recovery Card: Fehler im Import-Service
- Ursprüngliches Ziel: E-Mail-Validierung in `auth/service.ts` ergänzen.
- Tatsächlicher Fortschritt: Regex ergänzt, aber der Unit-Test `auth_test.go` schlägt fehl.
- Ursache: Der Agent wollte eine private Methode statt der öffentlichen Schnittstelle mocken.
- Git-Zustand: Branch `fix/auth-email`, gültiger Diff in `auth/service.ts` bleibt erhalten.
- Nächste Aktion für die saubere Sitzung: Unit-Test über die öffentliche Schnittstelle `AuthClient` überarbeiten.
```
[!IMPORTANT]
Keine Geheimnisse speichern: Schreibe niemals API-Schlüssel, Zugangstokens oder rohe Speicherauszüge in eine Recovery Card. Prüfe Endpoint-Konfiguration und Schlüsselverwaltung in der BetterToken-Dokumentation für Claude Code.
4. Reversible Wiederherstellung und Prüfung
So setzt du die Arbeit sicher fort:
- Starte eine neue Claude-Code-Sitzung mit einem sauberen Kontextfenster.
- Übergib dem Agenten nur das Aufgabenziel und das Feld „Nächste Aktion“ aus der Recovery Card.
- Fordere einen eng begrenzten Prüflauf an: `npm test -- tests/auth.test.ts`.
- Stelle sicher, dass der Zieltest besteht (`Passed`), und prüfe anschließend den finalen Diff mit `git diff --check`.
Dieses Protokoll macht aus einer außer Kontrolle geratenen Agentenschleife einen nachvollziehbaren Kontrollpunkt und schützt Codebasis und Tokenbudget.
Zahlung und Aufladen des Guthabens
Für API-Nutzung werden Aufladen und Zahlung im eigenen BetterToken-Konto verwaltet. BetterToken ist ein nutzungsbasiertes Modell-API-Angebot; bezahltes, aufgeladenes Guthaben verfällt nicht monatlich. Verfügbare Zahlungswege, Mindestbeträge, Gebühren, Wechselkurse und Bearbeitungszeiten können sich ändern und sind im Konto zum Zeitpunkt der Zahlung maßgeblich.
Preise und Kosten kontrollieren
Modellverfügbarkeit und konkrete Preise sind dynamisch. Prüfe sie vor einer Kostenentscheidung auf der BetterToken-Preisseite, statt feste Werte aus einem alten Artikel zu übernehmen. Nach einem Testaufruf kannst du im Dashboard Modell, Status sowie Eingabe-, Ausgabe- und Cache-Token samt zugehörigem Verbrauch abgleichen.