Claude Code spinnt nach einer Config-Änderung, so findest du die Ursache

Es lief alles. Dann hast du einen Hook ergänzt, eine Skill installiert, einen neuen MCP-Server eingetragen, und auf einmal hakt Claude Code. Tools werden nicht geladen, der Start dauert ewig, ein Prompt wird komisch beantwortet oder die Session bricht ab. Und du weißt nicht mehr, welche von deinen zehn Änderungen der letzten Woche es war. Das ist der nervigste Fehlertyp, weil du kein klares Symptom hast, nur das Gefühl dass irgendwas in deinem Setup faul ist.

Seit Version 2.1.169 gibt es dafür ein eingebautes Werkzeug, das genau dieses Problem löst. Der Safe-Mode. Er startet Claude Code mit allen Anpassungen abgeschaltet, und ab da arbeitest du dich Schicht für Schicht zurück. Das ist dieselbe Methode wie der abgesicherte Modus bei Windows, nur für dein CLI. Ich gehe die zehn Schritte durch, mit denen du in zwanzig Minuten weißt, was kaputt ist.

1. Erst mal die Version checken

Safe-Mode gibt es ab Claude Code 2.1.169. Wenn deine Version älter ist, fehlt das Flag und du musst die alte Holzhammer-Methode nehmen (Config-Files von Hand wegschieben). Pruef zuerst:

claude --version

Bist du drunter, update vorher. Wie das sauber geht, steht im Playbook Claude Code Update-Strategie. Danach kommst du hierher zurück.

2. Im Safe-Mode starten

Das ist der eine Befehl, um den sich alles dreht:

claude --safe-mode

Alternativ als Environment-Variable, falls du es für eine ganze Shell-Session setzen willst:

CLAUDE_CODE_SAFE_MODE=1 claude

Safe-Mode schaltet alle deine Anpassungen ab. Konkret: deine CLAUDE.md, alle Plugins, alle Skills, alle Hooks und alle MCP-Server. Du bekommst ein nacktes Claude Code, so wie es frisch nach der Installation laufen würde. Nichts von deinem eigenen Kram ist aktiv.

3. Den Fehler im Safe-Mode reproduzieren

Jetzt machst du genau das, was vorher schiefging. Derselbe Prompt, dasselbe File, derselbe Bash-Befehl. Zwei Ausgänge sind möglich, und beide sagen dir was.

Wenn der Fehler im Safe-Mode weg ist, dann liegt es an einer deiner Anpassungen. Gut, das ist der häufige Fall, und ab Schritt 4 grenzt du ein welche. Wenn der Fehler auch im Safe-Mode bleibt, dann liegt es nicht an deiner Config, sondern an Claude Code selbst, an deiner Installation oder an deinem Netzwerk. Dann springst du direkt zu Schritt 9.

4. Eine Schicht nach der anderen, nicht alles auf einmal

Der Reflex ist jetzt, alles gleichzeitig wieder anzuschalten und zu gucken. Mach das nicht. Dann bist du wieder genau da wo du angefangen hast und weißt wieder nichts. Die Reihenfolge die ich nehme geht von außen nach innen, also von dem was am leichtesten kaputtgeht zu dem was am seltensten schuld ist:

MCP-Server, dann Hooks, dann Skills, dann Plugins, dann CLAUDE.md. Nach jeder Schicht testest du erneut. In dem Moment wo der Fehler wieder auftaucht, hast du deinen Verursacher.

5. Mit den MCP-Servern anfangen

MCP-Server sind die häufigste Fehlerquelle, weil sie externe Prozesse starten, Tokens brauchen und über das Netz reden. Starte Claude Code normal, aber mit nur den MCP-Servern aktiv die du verdächtigst. Wenn du viele hast, kommentier in deiner MCP-Config erst alle bis auf einen aus und arbeite dich hoch.

Wenn der Fehler bei einem bestimmten Server zurückkommt, hast du ihn. Was dann zu tun ist, steht detailliert im Playbook MCP debuggen wenn nichts geht. Oft ist es ein abgelaufenes Token oder ein Server der gar nicht startet.

6. Dann die Hooks

Hooks feuern bei Tool-Aufrufen und können eine Session blockieren, wenn ein Hook-Script einen Fehler wirft oder hängt. Schalte deine Hooks einzeln wieder ein. Ein Hook der mit Exit-Code 2 abbricht, blockt die Aktion, das ist gewollt, aber ein Hook mit einem Bug im Script blockt eventuell alles.

Wenn ein Hook der Schuldige ist, geh ins Playbook Hooks debuggen wenn nichts feuert. Da ist der umgekehrte Fall (Hook feuert nicht) und der hier (Hook feuert zu viel) beide abgedeckt.

7. Skills, und der Trick mit den gebündelten Skills

Skills werden nur geladen wenn Claude sie für relevant hält, kosten also normal kaum Kontext. Trotzdem kann eine kaputte Skill-Definition Probleme machen. Schalte deine eigenen Skills im .claude/skills/ Verzeichnis einzeln wieder dazu.

Es gibt seit 2.1.169 noch einen Sonderfall. Claude Code bringt eigene gebündelte Skills, Workflows und eingebaute Slash-Commands mit. Wenn du den Verdacht hast dass eine davon stört, kannst du sie mit einer Einstellung verstecken, ohne deine eigenen anzutasten:

{
  "disableBundledSkills": true
}

Oder als Environment-Variable CLAUDE_CODE_DISABLE_BUNDLED_SKILLS=1. Wenn der Fehler damit verschwindet, lag es an einer mitgelieferten Skill und nicht an deiner. Mehr zum Trigger-Verhalten im Playbook Skill-Trigger-Debugging.

8. Plugins und CLAUDE.md zuletzt

Plugins ziehen oft Hooks, Skills und MCP-Server in einem Paket mit, deswegen kommen sie spät. Aktivier sie einzeln. Ein Plugin aus einer fremden ZIP oder URL ist ein guter Verdächtiger, gerade wenn du es frisch installiert hast.

Bleibt am Ende die CLAUDE.md. Die macht selten harten Ärger, aber sie kann Claude in eine Richtung schubsen die du nicht wolltest, oder sie ist so lang geworden dass sie den halben Kontext frisst. Seit Kurzem skaliert die Warnung CLAUDE.md ist zu lang mit dem Kontextfenster des Modells, du bekommst also einen Hinweis wenn sie über die Grenze geht. Wenn das dein Symptom war, kürz sie oder lager Teile in referenzierte Files aus.

9. Wenn der Fehler auch im Safe-Mode bleibt

Dann ist es nicht deine Config. Drei Verdächtige bleiben. Erstens die Installation selbst, ein Update das halb durchlief oder eine kaputte Binary. Ein sauberes Update oder eine Neuinstallation hilft hier oft. Zweitens das Netzwerk, vor allem wenn du hinter einem Proxy oder VPN sitzt oder die API gerade überlastet ist. Drittens ein echter Bug in der Version die du fährst.

Bei Überlast-Fehlern (overloaded) lohnt sich eine Fallback-Modell-Kette, damit Claude Code bei einem ausgelasteten Modell automatisch auf das nächste ausweicht. Wie das geht, steht im Companion-Playbook Fallback-Modelle gegen Overload.

10. Sauber zurücksetzen und dokumentieren

Du hast den Schuldigen. Jetzt nimmst du den Safe-Mode wieder raus und startest normal, mit der einen Änderung gefixt oder rausgenommen. Wichtig, und das vergesse ich selber dauernd: schreib dir kurz auf was es war. Ein abgelaufenes Token, ein Tippfehler im Hook-Pfad, eine Skill die mit einer anderen kollidierte. Beim nächsten Mal sparst du dir damit die ganze Runde, weil du den Verdacht sofort hast.

Safe-Mode ersetzt nicht die feature-spezifischen Debug-Playbooks. Es ist die Stufe davor. Erst grenzt du mit Safe-Mode ein, welche Schicht das Problem hat, dann gehst du mit dem passenden Playbook in die Tiefe. Wer Lust auf das größere Bild hat, dem hilft das Playbook Tool-Sprawl vermeiden, denn die meisten dieser Fehler entstehen schlicht daraus, dass man zu viel auf einmal installiert hat.

Was als nächstes

Wenn dein Fehler ein overloaded oder ein nicht verfügbares Modell war, mach mit Fallback-Modelle gegen Overload weiter. War es ein MCP-Server, dann MCP debuggen wenn nichts geht. Und wenn dich grundsätzlich interessiert, wie du dein Setup so baust dass es weniger oft kaputtgeht, schau in Level 4 Lektion Hooks und Skills.

Source

• Claude Code Changelog, Version 2.1.169 (--safe-mode, CLAUDE_CODE_SAFE_MODE, disableBundledSkills): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• Claude Code Doku: https://code.claude.com/docs/en/changelog