Claude Code Plan Mode: Refactoring mit Design-Review zuerst

Viele Entwicklerinnen und Entwickler starten mit Claude Code immer gleich: Aufgabe einfügen, laufen lassen, Diff prüfen. Für kleine Änderungen klappt das gut, doch sobald mehrere Dateien betroffen sind, bricht der Ansatz ein. 

Jede unbegleitete Entscheidung, die Claude trifft, mag für sich genommen oft richtig sein. Aber der Effekt summiert sich: Wenn du z. B. 80% Trefferquote pro Entscheidung annimmst und es in einem Feature 20 Entscheidungspunkte gibt, sinkt die Erfolgswahrscheinlichkeit durch 0.8^20 auf rund 1%.

Der Plan Mode ändert die Gleichung durch eine Nur-Lesen-Phase. Du zwingst Claude, den Code zu lesen, offene Fragen zu stellen und einen Plan zu erstellen, den du prüfst, bevor auch nur eine Datei angefasst wird. 

In diesem Tutorial gehen wir diesen Workflow anhand einer unaufgeräumten FastAPI-Blog-API Schritt für Schritt durch. Wir behandeln die Explore-Plan-Execute-Schleife, die Planbearbeitung mit Strg+G und das Skalieren größerer Refactorings mit Agent Teams. 

Unser Tutorial zu Best Practices mit Claude Code beleuchtet das Problem der sich aufaddierenden Fehler ausführlicher. Die Claude Code 2.1 Anleitung hilft dir bei Installation und Features, falls du Unterstützung beim Setup brauchst.

Mehr über die Modelle hinter Claude Code erfährst du in unseren Guides zu Claude Sonnet 4.6 und Opus 4.6 oder im Kurs Introduction to Claude Models.

Was ist der Claude Code Plan Mode?

Der Plan Mode sperrt Claude in einen Nur-Lesen-Zustand. Es kann Dateien lesen, die Codebasis durchsuchen und dir Fragen stellen, aber jeder Versuch, Dateien zu schreiben, Code zu ändern oder Shell-Befehle auszuführen, wird abgelehnt. Bitte es im Plan Mode um „nur diesen einen schnellen Fix“ und es rührt sich nicht.

Du kannst ihn auf vier Arten aktivieren:

• Shift+Tab zweimal im Eingabefeld wechselt zwischen Normal-, Auto-Accept- und Plan Mode

• Der /plan-Befehl aktiviert den Plan Mode bis zum erneuten Wechsel

• Das CLI-Flag --permission-mode plan startet eine neue Session im Plan Mode

• Ein Eintrag permissions.defaultMode in settings.json setzt den Plan Mode als dauerhaften Standard

Sobald Claude einen Plan erstellt hat, speichert es ihn als Markdown-Datei unter ~/.claude/plans/ mit einem zufällig generierten Namen (z. B. dreamy-orbiting-quokka.md). 

Die Datei ist ein überprüfbarer Vertrag: Sie bleibt über Sessions hinweg erhalten, überlebt sowohl /clear als auch Kontext-Komprimierung und nichts wird umgesetzt, bevor du es freigibst. Beachte: Der Plan selbst bleibt bestehen, aber nach einer Kontext-Komprimierung kann Claude ihn gelegentlich „verlieren“, bis du es ausdrücklich anweist, den Plan erneut zu lesen.

Wenn du Pläne für die Versionsverwaltung direkt im Projekt ablegen willst, setze plansDirectory in settings.json auf einen projektrelativen Pfad wie ./plans.

Projektrelative Pläne eröffnen Workflows, die ~/.claude/plans/ nicht abbilden kann:

• Plan-Diffs in Pull Requests prüfen, bevor jemand mit dem Coding beginnt
• Anmerkungen über Sessions hinweg mitnehmen, ohne auf Kontext-Komprimierung angewiesen zu sein
• Die Markdown-Datei als lebende Spezifikation behandeln, die mehrere Teammitglieder direkt bearbeiten

Für langfristige Refactorings oder mehrteilige Arbeiten gibt dir eine versionsverwaltete Plan-Datei mehr Kontrolle als nur Strg+G allein.

Einen Explore-Plan-Execute-Workflow mit Claude Code umsetzen

Damit klar wird, wie die drei Phasen zusammenspielen, refaktorisieren wir ein fastapi-blog-api-Repo. Es enthält keine Tests und drei Dateien, die jeweils zu viel erledigen: 

• main.py: alle Routen, Inline-Auth-Checks, hart codierte Config, E-Mail-Versand

• models.py: ORM-Modelle, Pydantic-Schemas, Query-Funktionen, Seed-Daten

• utils.py: Passwort-Hashing, JWT-Tokens, S3-Uploads, Markdown-Rendering, Caching, Ratelimiting, CSV-Export

Phase 1: Kontext sammeln, bevor irgendetwas passiert

Starte die Aufgabe im Plan Mode (klone das GitHub-Repo zuerst lokal). Die erste Eingabe sollte Claude sagen, was du willst, und es anweisen, die relevanten Dateien zu lesen:

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.Bereitgestellt von

Claude delegiert die Codebasis-Recherche an einen eingebauten Subagenten mit Nur-Lesen-Werkzeugen. Er hat alle drei Dateien gelesen, die Imports nachverfolgt und über AskUserQuestion Unklarheiten adressiert. 

Die Fragen betrafen ein paar grundlegende Entscheidungen:

• Architekturtiefe (flache Router vs. vollwertige Service-Layer)
• Umgang mit hart codierter Konfiguration
• Ob ungenutzte Utility-Funktionen entfernt oder behalten werden sollen
• Welches Testframework zum Einsatz kommt

Diese Fragen sind wichtig. Allein die Architekturfrage wäre ohne menschlichen Input ein Münzwurf gewesen. Claude wählt oft das Muster, das es in den Trainingsdaten am häufigsten gesehen hat – bei FastAPI meist eine flache Router-Struktur. Die Antwort „Service-Layer verwenden“ hat hier eine komplette Re-Refaktorisierung später erspart.

Wenn du ein Referenzprojekt mit der Zielarchitektur hast, verlinke es in deiner Eingabe. Claude erstellt bessere Pläne, wenn es sich an einem funktionierenden Beispiel orientieren kann statt an abstrakten Beschreibungen.

Bevor du einen Plan akzeptierst, prüfe Folgendes: Beziehen sich Claudes Fragen auf konkrete Funktionen und Details auf Zeilenebene oder nur auf Dateinamen? Wenn es nach „dem Auth-System“ fragt, aber nie verify_jwt_token oder die Middleware-Kette in main.py erwähnt, hat es eher überflogen als gelesen. Dränge es zu sorgfältiger Lektüre, bevor du zu Phase 2 wechselst.

Phase 2: Den Plan erzeugen und überarbeiten

Nachdem du Claudes Fragen beantwortet hast, generiert es automatisch einen Plan. Eine separate Eingabe ist nicht nötig. Der Plan wird in ~/.claude/plans/ gespeichert und enthält: 

• Kontextzusammenfassung
• Zielverzeichnisstruktur
• Schritt-für-Schritt-Implementierungsreihenfolge
• Verifikationssektion mit Befehlen, um das Refactoring zu bestätigen

Bevor du entscheidest, wie es weitergeht, drücke Strg+G, um den Plan in deinem Standardeditor zu öffnen (gesteuert von $EDITOR). Alternativ öffnest du die aktive Plan-Datei direkt mit /plan open.

An dieser Stelle zahlt sich der Plan Mode aus. Du kannst Schritte mit Inline-Notizen versehen, Schritte löschen, denen du widersprichst, die Reihenfolge anpassen und speichern. Claude übernimmt jede Änderung, sobald du ins Terminal zurückkehrst.

Für den Blog-API-Plan könnten Anmerkungen so aussehen:

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.pyBereitgestellt von

Bei komplexen Plänen reicht ein Strg+G-Durchgang oft nicht. Annotiere, kehre zurück, sag zu Claude „arbeite alle Anmerkungen im Plan ein, noch nichts umsetzen“, prüfe die überarbeitete Fassung und drücke erneut Strg+G. Jede Runde beseitigt Unklarheiten, die sonst zu Fehlentscheidungen in der Implementierung würden.

Sobald der Vertrag passt, bietet dir Claude mehrere Optionen: 

1. Am Plan arbeiten und den Kontext leeren (gut, wenn die Session „abgenutzt“ ist), 
2. Arbeiten ohne Leeren (um den Gesprächsverlauf zu behalten) oder 
3. Weiter über den Plan sprechen. 

Wähle abhängig davon, wie viel Kontext du bereits aufgebaut hast. Wenn du mitten in einer langen Session steckst, verschafft das Leeren Claude ein frisches Fenster für die Ausführung.

Phase 3: Den freigegebenen Plan umsetzen

Wähle eine Arbeitsoption und Claude beginnt Schritt für Schritt mit der Implementierung. Es arbeitet die Schritte ab und hält an, wenn manuelle Eingriffe nötig sind (z. B. interaktive Auth im Terminal) oder wenn der Plan vollständig abgeschlossen ist.

Achte auf Drift. Der Plan sah vor, zuerst die Auth in ein eigenes Modul auszulagern, doch Claude könnte anfangen, Routen und Auth-Logik gleichzeitig zu ziehen, weil es eine Abkürzung wittert. So entsteht schnell eine halb migrierte Codebasis, in der einige Imports noch auf den alten Ort zeigen und andere schon auf den neuen. 

Weitere Signale für Drift: 

• Eine Datei bearbeiten, die im aktuellen Schritt nicht genannt ist
• Stillschweigend eine Architekturentscheidung treffen, die der Plan offen gelassen hat
• Zwei Schritte zusammenziehen, die der Plan bewusst getrennt hält

Wenn Drift auftritt, wechsle mit Shift+Tab zurück in den Plan Mode. Claude liest den aktuellen Dateistand, erstellt einen überarbeiteten Plan für die verbleibenden Schritte, und du prüfst ihn vor der Fortsetzung. Das ist kein Notbehelf. Die meisten Multi-Datei-Refactorings durchlaufen 2–3 Planrevisionen, bevor sie fertig sind.

Für Refactorings, die nicht in eine Session passen, zerlege die Arbeit in aufeinanderfolgende Pläne statt in einen großen. Schließe die Auth-Extraktion in einem eigenen Plan ab, starte dann eine frische Session und plane die Aufteilung der Routen. 

Nutze /rename, um jede Session zu benennen (z. B. „blog-api-auth-extraction“), damit du mit /resume nahtlos weitermachen kannst. Kleinere Pläne halten das Kontextfenster fokussiert und bieten natürliche Checkpoints zwischen den Phasen.

Praktische Strategien für den Claude Code Plan Mode

Nachdem wir den gesamten Prozess einmal durchlaufen haben, schauen wir uns ein paar Best Practices an, damit du das Maximum aus dem Plan Mode herausholst.

Wann du den Plan Mode nutzt (und wann du ihn weglässt)

Nicht jede Aufgabe braucht einen Plan. Einzeilige Fixes, Tippfehlerkorrekturen und isolierte Funktionsupdates sind ohne Planungs-Overhead schneller. Gleiches gilt für mechanische Änderungen wie das Umbenennen einer Variable in einer Datei.

Eine gute Faustregel: Wenn die Änderung drei oder mehr Dateien betrifft oder du sie nicht in einem Satz beschreiben kannst, plane zuerst. Ab etwa drei Dateien beginnen sich Fehler spürbar zu kumulieren, weil jede Datei eigene Entscheidungen mitbringt, die Claude richtig treffen muss.

Aufgaben, die stets vom Plan Mode profitieren:

• Refactorings, die Code zwischen Dateien verschieben oder gemeinsame Schnittstellen umbenennen
• Neue Features, die bestehende Module berühren
• Abhängigkeitsupdates mit Breaking Changes in der API
• Jede Aufgabe, bei der du nicht sicher bist, wie die Codebasis einen speziellen Fall behandelt
• Ideenfindung, bei der du mit Claude iterieren willst, ohne Risiko verfrühter Edits

Schwache Pläne erkennen, bevor sie teuer werden

Ein Plan kann strukturiert wirken und trotzdem schlecht sein. Mit den aktuellen Claude-Code-Versionen sind halluzinierte Dateireferenzen und vage „bei Bedarf aktualisieren“-Schritte selten. Häufiger ist das Problem, dass alle Implementierungsschritte zuerst kommen und „Tests hinzufügen“ ans Ende gerückt wird.

Solche Pläne liefern schlechtere Ergebnisse als erwartet. Ohne Tests während der Umsetzung hat Claude keine Möglichkeit, seine Arbeit mitten in der Session zu verifizieren. Bei der Blog-API bedeutet ein Plan wie „Schritte 1–6: alle Module extrahieren, Schritt 7: Tests schreiben“ sechs Schritte Code ohne Feedbackschleife. 

Ein besserer Plan setzt auf Testgetriebene Entwicklung (TDD) und verzahnt Tests und Implementierung: Schreibe Tests für auth/, bevor du die Auth-Funktionen herausziehst, bestätige, dass sie bestehen, schreibe dann Tests für posts/, bevor du die Routen extrahierst. Jeder bestandene Test gibt Claude ein klares Signal, dass das Refactoring auf Kurs ist. 

Wenn du TDD-Konventionen in deiner CLAUDE.md festhältst, nimmt Claude Testschritte standardmäßig auf. Claude Code Hooks können diese Regeln automatisiert durchsetzen, indem sie Validierungsskripte ausführen, die die Planqualität vor der Freigabe prüfen.

Große Refactorings mit Agent Teams skalieren

Pläne, die sieben oder mehr Dateien betreffen, verlieren an Qualität, weil das Kontextfenster während der Ausführung vollläuft. Die Blog-API erreicht diesen Punkt, wenn man Routen, Modelle, Services, Config, Tests und die neue Verzeichnisstruktur mitzählt.

Agent Teams ist ein experimentelles Feature, das diese Arbeit auf mehrere Claude-Code-Instanzen verteilt. Eine Session agiert als Team Lead, während Teammitglieder jeweils ihr eigenes, unabhängiges Kontextfenster erhalten. 

Für die Blog-API könntest du in drei Teammitglieder aufteilen: eines für die Extraktion der Routen, eines für Datenbank- und Modellebene und eines für die Testabdeckung. Der Lead weist Aufgaben zu, Teammitglieder übernehmen und erledigen sie, und blockierte Aufgaben (wie „Imports aktualisieren“ abhängig von „Module extrahieren“) werden automatisch freigegeben, sobald Abhängigkeiten fertig sind. 

Der gleiche Zuschnitt funktioniert auch über Repositories hinweg: Wenn deine API von einer Shared Library abhängt, kann ein Teammitglied die Library refaktorisieren, während ein anderes die Nutzung in der API anpasst.

Die beste Einstellung für den Plan Mode: Planfreigabe für Teammitglieder verpflichtend machen. Sage dem Lead: „Starte drei Teammitglieder für das Blog-API-Refactoring. Verlange Planfreigabe, bevor sie Änderungen vornehmen.“ 

1. Jedes Teammitglied plant im Nur-Lesen-Modus
2. Der Lead prüft und genehmigt oder lehnt mit Feedback ab
3. Nur freigegebene Pläne werden ausgeführt

Du kannst das Urteil des Leads steuern, indem du Kriterien vorgibst: „Nur Pläne genehmigen, die Testabdeckung enthalten“ oder „Pläne ablehnen, die das DB-Schema direkt ändern.“ Aktiviere Agent Teams, indem du "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" in den settings.json env-Block aufnimmst.

Für einfachere Parallelisierung ohne Experimental-Flag kannst du mit Git-Worktrees separate Plan-Mode-Sessions auf unterschiedlichen Branches fahren, die jeweils ihren eigenen Plan unabhängig abarbeiten.

Wenn eine lange Session eine Kontext-Komprimierung durchläuft, sollen Teammitglieder ihre Plan-Dateien gezielt erneut öffnen und lesen, um Drift zu vermeiden.

Das Claude-Code-Plugins-Tutorial behandelt weitere Muster zum Managen mehrphasiger Arbeit.

Fazit

Der Wert des Plan Mode lässt sich auf eines verdichten: Review vor Ausführung. Jede Runde Annotationen, jede Frage, die Claude stellt statt zu raten, eliminiert eine Entscheidung, die sonst falsch ausgefallen wäre. 

Starte bei deiner nächsten Änderung über mehrere Dateien im Plan Mode, und überarbeite den Plan mit Strg+G, bevor du Schreibzugriff gibst. Für CLAUDE.md-Konfiguration, Kontext-Management und Hook-basierte Leitplanken knüpft das Best-Practices-Tutorial an dieses hier an. 

Für einen größeren Überblick über KI-unterstütztes Coden empfehle ich unseren Skill Track AI for Software Engineering. Er vermittelt dir die Grundlagen und gibt dir praktische Erfahrung mit ähnlichen Tools wie GitHub Copilot, Windsurf oder Replit.